Formatting CLI

The Antlers formatter CLI is an opinionated formatting tool built on top of js-beautify, and is provided as a standalone version of the formatter that ships with the Visual Studio Code extension.

#Installation

The command line Antlers formatter can be installed with npm using the following command:

1npm install antlers-formatter -g

#Format Command

The CLI utility currently only offers a format command. The format command accepts the following options:

Option	Flag	Description
file	--f	The path to the template to format.
dir	--d
output	--out	An optional file path where the formatted results will be saved. When specified, the file (or files in a directory) is not overwritten.
dump	--dd	When specified, no results are saved to disk. Formatted results are displayed within the terminal.
options	--o	An optional file path to a JSON file containing Antlers formatting settings.

To format a single file:

1antlersformat format --f="/path/to/file/to/format.antlers.html"

To format all Antlers files within a directory recursively:

1antlersformat format --d="/path/to/directory/"

#Format Options

When supplying a options file path to the format utility, the provided JSON file can be configured with the following formatting options:

 1{
 2    "htmlOptions": {},
 3    "formatFrontMatter": true,
 4    "insertSpaces": true,
 5    "maxStatementsPerLine": 3,
 6    "tabSize": 4,
 7    "formatExtensions": [
 8        ".antlers.html"
 9    ]
10}

Setting	Description
formatFrontMatter	Controls whether document Front Matter is formatted.
insertSpaces	Controls whether the Antlers formater should insert spaces or tabs.
maxStatementsPerLine	Suggests a maximum number of Antlers statements that should appear on a single line (i.e., {{ test; test += 3; test += 5; }})
tabSize	The number of spaces to use for indentation.
formatExtensions	A list of file extensions that will be formatted when formatting a directory.

The htmlOptions object may be used to set the HTML formatting options used by the Antlers formatter. These settings follow the same rules as the default Visual Studio Code HTML Formatter. The formatter will do its best to respect these settings, but may be unable to under certain circumstances.

• htmlOptions.indentEmptyLines

• htmlOptions.wrapLineLength

• htmlOptions.unformatted

• htmlOptions.indentInnerHtml

• htmlOptions.wrapAttributes

• htmlOptions.wrapAttributesIndentSize

• htmlOptions.preserveNewLines

• htmlOptions.indentHandlebars

• htmlOptions.endWithNewline

• htmlOptions.extraLiners

• htmlOptions.indentScripts

• htmlOptions.unformattedContentDelimiter

#Prevent Formatting of Specific Files

It may be useful to prevent formatting of a specific Antlers template without excluding the file extension entirely. This can be accomplished by adding a special directive to your template's configuration comment.

Note: These configuration comments must be the first item that appears after your template's front matter (if provided). Consider reading through the Template IDE Hints article to learn more about these comments.

To disable formatting, simply add the @format false directive to the template's configuration comment:

 1{{#
 2    @name Example Template
 3    @format false
 4    @description This template will not be formatted by the Antlers formatter.
 5#}}
 6<div class="hidden lg:block lg:col-span-3 xl:col-span-3">
 7    <nav aria-label="Sidebar" class="sticky top-6 divide-y divide-gray-300">
 8        {{ partial:docnav }}
 9    </nav>
10</div>

The Antlers formatter will now ignore this template when a format request is received.