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

#Prettier 3 Plugin

An Antlers formatter is provided as a Prettier 3 plugin. You will need to install and configure Prettier separately from the Antlers Toolbox Visual Studio extension. To install and enable the Antlers plugin for Prettier 3 make sure to install version 2 of the prettier-plugin-antlers package:

1npm install prettier-plugin-antlers@^2 --save-dev

Once the plugin is installed you will need to modify your projects .prettierrc and let Prettier know about the plugin. The following is a sample .prettierrc file which assumes the Tailwind CSS Prettier plugin has also been installed:

 1{
 2    "plugins": [
 3        "prettier-plugin-antlers",
 4        "prettier-plugin-tailwindcss"
 5    ],
 6    "overrides": [
 7        {
 8            "files": [
 9                "*.antlers.html"
10            ],
11            "options": {
12                "parser": "antlers"
13            }
14        }
15    ]
16}

If you are using Visual Studio Code and receive an error stating that there are no formatters available for Antlers after configuring the Prettier extension and plugin, you might need to add Antlers to the list of Prettier's document selectors. Inside your Visual Studio Code's settings.json you can adjust the relevant settings to include the following:

1{
2  "[antlers]": {
3    "editor.defaultFormatter": "esbenp.prettier-vscode"
4  },
5  "prettier.documentSelectors": [
6    "**/*.antlers.html"
7  ]
8}

#Prettier 2 Plugin

If your project still relies on Prettier 2 you must ensure that you install version 1 of the prettier-plugin-antlers plugin.

1npm install prettier-plugin-antlers@^1 --save-dev

Once the plugin is installed you will need to modify your projects .prettierrc and let Prettier know about the plugin. The following is a sample .prettierrc file which assumes the Tailwind CSS Prettier plugin has also been installed:

 1{
 2    "plugins": [
 3        "./node_modules/prettier-plugin-antlers",
 4        "./node_modules/prettier-plugin-tailwindcss"
 5    ],
 6    "overrides": [
 7        {
 8            "files": [
 9                "*.antlers.html"
10            ],
11            "options": {
12                "parser": "antlers"
13            }
14        }
15    ]
16}

#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.