Formatting

The Antlers formatter is an opinionated formatting tool built on top of js-beautify, and remains compatible with most of the default settings provided by Visual Studio Code.

Configurable Settings

Most Visual Studio Code formatting settings will apply to the Antlers formatter. For a complete list of all HTML formatting options provided by Visual Studio Code check out their documentation at https://code.visualstudio.com/docs/languages/html#_formatting.

The following options are overriden by the Antlers formatter:

  • html.format.extraLiners

Additionally, because of the way Antlers code is formatted within the document, some settings such as parameter wrapping, max line length, etc. may not always be respected. This is intentional behavior at the moment to ensure consistency and formatter reliability.

Formatting Front Matter

The Antlers formatter will attempt to format your template's front matter by default. If the front matter contains syntax errors, the front matter will not be formatted.

To stop the formatter from attempting to format your front matter, disable the following configuration value:

1antlersLanguageServer.formatFrontMatter

Integrating with Prettier

The Antlers formatter is an opinionated standalone formatter that focuses on the organization of your Antlers code, as well as the structure of the entire document. However, if you have the esbenp.prettier-vscode Visual Studio Code Prettier extension available and would like to format your document using this extension first (before the Antlers formatter works on the Antlers code), you can enable the following setting to true (search for "Antlers Format With Prettier First If Available" within the settings UI):

1antlersFormatWithPrettierFirstIfAvailable

Excluding File Extensions

You may disable the Antlers formatter for specific file extensions by providing a list of file extensions in your workspace's settings file. The configuration key to update is antlersLanguageServer.formatterIgnoreExtensions.

By default Antlers Toolbox will not attempt to format Antlers files ending with the xml extension. This default configuration looks like this (you do not need to include the . in the file extension):

1{
2 "antlersLanguageServer.formatterIgnoreExtensions": [
3 "xml"
4 ],
5}

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 tempalte'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.