| Command | Description |
|---|---|
| Liquid: Enable Formatting | Enable Prettify formatting |
| Liquid: Disable Formatting | Disable Prettify formatting |
| Liquid: Format Document | Formats the current document |
| Liquid: Generate .liquidrc (defaults) | Generate a .liquidrc file with default rules |
| Liquid: Generate .liquidrc (recommend) | Generate a .liquidrc file with recommended rules |
| Liquid: Open Output | Open the Liquid output panel |
| Liquid: Restart Extension | Restarts the extension |
| Liquid: Release Notes | Visit the Release notes (opens in browser) |
Workspace Settings
The extension provides various workspace/user settings. The options available to liquid.format can be controlled using a .liquidrc configuration file or alternatively you can define format options via a prettify field in a node package.json file. Take a look at the configuration section for more information.
By default, it is assumed you are using vscode workspace/user settings.
{
// Defined the Liquid variation you are working with
"liquid.engine": "shopify",
// Path location to a rule configuration file (relative to project root)
"liquid.config.baseUrl": ".",
// Controls how extension settings are applied (leave this to workspace)
"liquid.settings.target": "workspace",
// Whether or not to enable tag completions
"liquid.completion.tags": true,
// Whether or not to enable object completions
"liquid.completion.objects": true,
// Whether or not to enable filter completions
"liquid.completion.filters": true,
// Controls whether formatting is enabled or disabled
"liquid.format.enable": true,
// Glob paths to exclude from formatting
"liquid.format.ignore": [],
// Word wrap limit, defaults to the vscode wordWrapColumn
"liquid.format.wrap": 0,
// indentation level, defaults to the vscode tabSize
"liquid.format.indentSize": 2,
// Whether or not documents end with newline, defaults to the vscode renderFinalNewline
"liquid.format.endNewLine": false,
// If a blank new line should be forced above comments
"liquid.format.commentIndent": false,
// The maximum number of consecutive empty lines to retain
"liquid.format.preserveLine": 3,
// Prevent comment reformatting due to option wrap
"liquid.format.preserveComment": false,
// Use Windows (CRLF) format, Unix (LF) format is the default.
"liquid.format.crlf": false,
// HTML, Liquid + HTML code style
"liquid.format.markup": {
// Automatically attempts to correct some sloppiness in code
"correct": false,
// Control the casing of attributes.
"attributeCasing": "preserve",
// Alphanumerically sort HTML attributes from A to Z.
"attributeSort": false,
// Sort attributes according to this list, requires attributeSort to be true
"attributeSortList": [],
// Strip extraneous spacing from Liquid delimiters
"delimiterSpacing": false,
// Whether comments should always start at position 0 or indented to code
"commentNewline": false,
// Force leading attributes onto a newline when using wrap
"forceLeadAttribute": false,
// Will force indentation upon content
"forceIndent": false,
// Whether attributes should be indented each onto their own line
"forceAttribute": false,
// If text in the provided document code should be preserved
"preserveText": true,
// self-closing tags end will end with ' />' instead of '/>'
"selfCloseSpace": false,
// Whether attributes should be preserved
"preserveAttributes": false,
// Quotation character conversion
"quoteConvert": "none"
},
// CSS/SCSS code style
"liquid.format.style": {
// Automatically attempts to correct some sloppiness in code.
"correct": false,
// Whether to apply allman style indentation to braces
"braceAllman": false,
// Sorts CSS Selectors in an alphanumerical order
"sortSelectors": false,
// Sort Selectors in an alphanumerical order
"sortProperties": false,
// Inserts new line characters between every CSS code block
"classPadding": false,
// Whether leading `0s` in CSS values immediately preceding a decimal or removed
"noLeadZero": false,
// If comma separated CSS selectors should present on a single line of code
"selectorList": false
},
// JSON code style
"liquid.format.json": {
// Determines how array indexes should be indented
"arrayFormat": "default",
// Whether to apply allman style indentation to braces
"braceAllman": false,
// Inserts a space after the start and before the end of a container
"bracePadding": false,
// Emulates JSBeautify's brace_style option
"braceStyle": "none",
// Determines if all array indexes should be indented, never indented, or left to the default.
"formatArray": "default",
// Determines if all object keys should be indented, never indented, or left to the default
"objectIndent": "default"
},
// JavaScript, TypeScript code style
"liquid.format.script": {
// Determines how array indexes should be indented
"arrayFormat": "default",
// Automatically attempts to correct some sloppiness in code.
"correct": false,
// Whether to apply allman style indentation to braces
"braceAllman": false,
// Insert line after opening curly braces and before closing curly braces
"braceNewline": false,
// Inserts a space after the start and before the end of a container
"bracePadding": false,
// Emulates JSBeautify's brace_style option
"braceStyle": "none",
// If the colon separating a case's expression (of a switch/case block)
"caseSpace": false,
// Whether the 'else' keyword is forced onto a new line.
"elseNewline": false,
// If there should be a trailing comma in arrays and object
"endComma": "none",
// Determines how array indexes should be indented
"arrayFormat": "default",
// Determines how object keys should be indented
"objectIndent": "default",
// If a space should follow a JavaScript function name
"functionNameSpace": false,
// When to break chained methods and properties onto separate lines
"methodChain": 3,
// If destructured lists in script should never be flattened
"neverFlatten": false,
// If a case statement should receive indentation
"noCaseIndent": false,
// Removes semicolons that would be inserted by ASI
"noSemicolon": false,
// Prevent comment reformatting due to option wrap
"preserveComment": false,
// Quotation character conversion
"quoteConvert": "none",
// Inserts a space following the function keyword for anonymous functions
"functionSpace": false,
// Keep ternary statements on one Line
"ternaryLine": false,
// Merges into consecutive variables into a comma separated list
"variableList": false
}
}
Config Base URL
The liquid.config.baseUrl option can be used to define a relative directory path for resolving config files. The option will only work in projects that use .liquidrc files or define formatting rules in as package.json prettify field (see: Configuration). Consider the following directory layout:
root
├─ .vscode
│ └─ settings.json
├─ docs
│ ├─ .liquidrc.json
│ └─ index.liquid
└─ src
├─ includes
└─ views
By default, when no .liquidrc or package.json file (containing a prettify field) exist in a projects root, it will assume beautification rules have been defined in the .vscode/settings.json workspace file. When no formatting rules are defined in the workspace file then the default Prettify rules will be used. In situations where you need the extension to use a config file that is located outside of the root you can provide a baseUrl to the directory containing a the supported file types.
Targeting the .liquidrc.json file located in docs directory:
{
"liquid.config.baseUrl": "./docs"
}
The baseUrl must point a relative directory not a file. If the directory provided cannot be resolved, root is used.
Settings Target
The liquid.settings.target option is used to determine where the extension writes settings. The default configuration and behavior is to use the .vscode/settings.json workspace file. Though you can target user settings (ie: global) it is highly discouraged to do so and could lead to unexpected issues outside of Liquid projects.
Syntax Support
Liquid syntax highlighting is applied using detailed token captures which extend upon the HTML derivative. The core grammars account for all all token structures available in Liquid and have been developed with theming consideration in mind. Liquid contained within Markdown, YAML and JSON languages are supported using vscode injection grammars and applied in a non-conflicting manner. The injected grammars allow intelliSense capabilities provided by vscode to persist and work without interruption while the base Liquid grammar supports HTML intelliSense features within .liquid extension files in an isolated manner.
Supported Languages
| Language Identifier | Language Alias | Supported Extension | IntelliSense Support |
|---|---|---|---|
| liquid | Liquid | .liquid, or .jekyll | ✓ |
| json | JSON | .json | ✓ |
| yaml | YAML | .yaml | ✓ |
| markdown | Markdown | .md, .md.liquid | ✓ |
| liquid-css | Liquid CSS | .css.liquid | 𐄂 |
| liquid-scss | Liquid SCSS | .scss.liquid, sass.liquid | 𐄂 |
| liquid-javascript | Liquid JavaScript | .js.liquid | 𐄂 |
Grammar Injections
In order to preserve vscode intellisense capabilities the below languages have Liquid grammars injected into them. The grammar injection will allow Liquid code to be highlighted and treated as if the syntax exists as part of the languages.
- JSON
- Yaml
- Markdown
When these languages contain Liquid syntax vscode might complain about invalid code. You should consider disabling validations on these languages when they contain Liquid. Please be aware that in situations where you leverage linters or third party tools that Liquid code will typically be interpreted as invalid. It is up to you to take the necessary steps to disable and prevent such issues from becoming problematic to your development experience.
{
// Disabling JSON validations when it contains Liquid syntax
"json.validate.enable": false,
// Disabling JavaScript validations when it contains Liquid syntax
"javascript.validate.enable": true
}
Liquid in JSON, YAML and Markdown
Liquid tags, comments and object grammars are injected into JSON, YAML and Markdown languages. External language code regions and anything which requires an embedded language (ie: {% schema %}) are excluded. There is no need to use a .liquid suffix on these file names in order for Liquid syntax highlighting as it will work out of the box.
If for any reason the injections become problematic then please report an issue.
Liquid in CSS, SCSS, SASS and JavaScript
Liquid syntax contained in JavaScript, CSS, SCSS, SASS and other supported languages require a .liquid extension suffix be applied on file names. The suffix will associate these languages to a designated grammar, for example:
.css → .css.liquid
.scss → .scss.liquid
.sass → .scss.liquid
.js → .js.liquid
If the required .liquid suffix is problematic to your use case then use file associations. Please note that the language native IntelliSense capabilities are not supported in the suffixed files.
Markdown Codeblock
Liquid markdown embedded code block regions are supported in .md files.
```liquid
{% comment %} Liquid code {% endcomment %}
```
Completions
The extension supports completion capabilities. This is a preview feature and will be improved upon as the extension progresses to Liquify, as such the integration is elementary. Completions are similar to snippets but a little more refined. The completions will be invoked and made available depending on the trigger previous character sequence or trigger.
Tags
Liquid Tag completions are made available by typing the % character.
Objects
Liquid object completions will be invoked within tokens at different points.
Filters
Liquid filter completions are made available by typing the | character.
Formatting
Formatting can be enabled/disabled via the command palette and will respect editor.formatOnSave. When Liquid formatting is enabled the extension will format Liquid and all suffixed *.liquid files with a language supported by Prettify. You can disable beautification by clicking the 💧 emoji icon in the status bar or exclude directories/files from handling using the format.ignore setting.
Formatting options can be defined in a .liquidrc file, package.json prettify field or alternatively you can use the workspace setting options.
Prettify 🎀
Prettify is used to facilitate formatting capabilities by the extension. Prettify is built atop of the late but powerful Sparser lexing algorithm and has since been adapted for refined usage with Liquid and this extension. Prettify exposes a granular set of rules and supports Liquid beautification in various markup, script and style languages.
I actively maintain Prettify and it is currently in a pre-release (beta) stage. The ambition is to eventually have the tool become a competitive alternative to Prettier and disrupt "opinionated" conventions. Prettify was introduced in version 3.0.0 replacing PrettyDiff as the core formatter for this extension. Though Prettify has yet to ship an official release candidate it is stable enough for usage and its adaption fixes previous version defects.
Prettify, once stable enough for the big time will be made available for usage in a separate extension
Setting Default Formatter
In some situations you may have another extension handling formatting and you will need to explicitly define an in-language editor.defaultFormatter within your vscode workspace/user settings. VSCode will typically inform you about this but if for any reason you are unable to get formatting to work, try setting the in-language default formatter.
Be sure to define only the languages you wish to have formatted by the extension. If you don't want Prettify to handle formatting then set the option liquid.format.enable to false.
{
// Enables formatting of .liquid files
"[liquid]": {
"editor.defaultFormatter": "sissel.shopify-liquid",
"editor.formatOnSave": true
},
// Enables formatting of all .js.liquid files
"[liquid-javascript]": {
"editor.defaultFormatter": "sissel.shopify-liquid",
"editor.formatOnSave": false
},
// Enables formatting of all .css.liquid files
"[liquid-css]": {
"editor.defaultFormatter": "sissel.shopify-liquid",
"editor.formatOnSave": false
},
// Enables formatting of all .scss.liquid files
"[liquid-scss]": {
"editor.defaultFormatter": "sissel.shopify-liquid",
"editor.formatOnSave": false
}
}
In addition the above defaults, you can also choose to have Prettify beautify other supported languages. Please note, that when extending to the below languages that Prettify is still in its early stages so results may not be perfect. Liquid syntax contained in any of these languages is supported!
{
// Enables formatting of all .html files
"[html]": {
"editor.defaultFormatter": "sissel.shopify-liquid"
},
// Enables formatting of all .tsx files
"[xml]": {
"editor.defaultFormatter": "sissel.shopify-liquid"
},
// Enables formatting of all .css files
"[css]": {
"editor.defaultFormatter": "sissel.shopify-liquid"
},
// Enables formatting of all .scss files
"[scss]": {
"editor.defaultFormatter": "sissel.shopify-liquid"
},
// Enables formatting of all .sass files
"[sass]": {
"editor.defaultFormatter": "sissel.shopify-liquid"
},
// Enables formatting of all .json files
"[json]": {
"editor.defaultFormatter": "sissel.shopify-liquid"
},
// Enables formatting of all .jsonc files
"[jsonc]": {
"editor.defaultFormatter": "sissel.shopify-liquid"
},
// Enables formatting of all .js files
"[javascript]": {
"editor.defaultFormatter": "sissel.shopify-liquid"
},
// Enables formatting of all .js files
"[typescript]": {
"editor.defaultFormatter": "sissel.shopify-liquid"
},
// Enables formatting of all .jsx files
"[jsx]": {
"editor.defaultFormatter": "sissel.shopify-liquid"
},
// Enables formatting of all .tsx files
"[tsx]": {
"editor.defaultFormatter": "sissel.shopify-liquid"
}
}
Status Bar
When the extension is enabled and a supported file has been opened in the editor you'll see a 💧 emoji appear in the bottom right hand side of the vscode status bar. This is the extensions status bar item and that will allow you to enable/disable formatting (programmatically). It also informs upon ignored files, notifies you when the parser encounters any code errors and is displayed when a .liquid file is opened.
| Status | Command | Action |
|---|---|---|
 |
Enabled | Clicking the status bar item in this state will disable formatting |
 |
Disabled | Clicking the status bar item in this state will enable formatting |
 |
Ignoring | Clicking the status bar item in this state opens the output panel |
 |
Errors | Clicking the status bar item in this state opens the output panel |
Ignoring Code and/or Files
You can skip formatting on files, directories and code input a few different ways. If you are using workspace/user settings for configuration then you can pass a glob list of paths relative to the projects root using the liquid.format.ignore[] option. Folks leveraging the .liquidrc file or package.json prettify field for defining beautification rules can use the ignore[] option.
In addition to path ignores, users can also take advantage of Prettify's inline control comments for skipping blocks of code and files from beautification.
Ignoring Regions
@prettify-ignore-start@prettify-ignore-end
You can also annotate HTML tags with data-prettify-ignore attributes
Ignoring Files
<!-- @prettify-ignore -->{% # @prettify-ignore %}{% comment %} @prettify-ignore {% endcomment %}/* @prettify-ignore */// @prettify-ignore
Warning Inline comment ignores made possible via Prettify might be little flakey until an official release.
Configuration
The extension provides a couple of different ways for users to configure and control capabilities. Depending on how regularly you are working with Liquid should help determine which method is best for you. The .liquidrc file or package.json prettify field method are great option for developers who prefer single point of control for beautification features. Developers who prefer to keep things in the editor (ie: .vscode/settings.json) can use workspace/user settings.
Using workspace settings
Setting configuration using workspace settings is made available on the liquid option. When a .liquidrc file is present in your projects root then that will take precedence over the liquid.format.* options defined in workspace/user settings unless formatting has been disabled (ie: the liquid.format.enable option is set to false).
Refer to Workspace Settings for defaults.
Using the package.json prettify field
In some situations users may prefer to define formatting options within a package.json file. The extension will check package.json files for a prettify field and use any beautification options provided when it is defined. The prettify field only accepts format rules overrides vscode workspace/user settings unless a .liquidrc file is present. When a .liquidrc file is present in your projects root then that will take precedence over over the prettify field and liquid.format.* workspace/user setting.
Using .liquidrc config file
The .liquidrc file allows users to control formatting rules used by the extension. You can only provide formatting configuration in .liquidrc files, it does not accept additional vscode workspace/user settings. This method is typically the easiest way to define per-project configurations and shareable rules. Whenever the extension detects the presence of a .liquidrc file it will behave in accordance and assume a Liquid environment.
The .liquidrc file will be an essential requirement in Liquify (the future release) and the point of control for the Liquify parser, Language Server, Liquid specifications and other features. If you use Liquid a lot, then it a good idea to use this method.
Supported .liquidrc files
Currently, the extension only supports 2 JSON (with comments) file types:
.liquidrc.liquidrc.json
Generating .liquidrc Files
You can generate a .liquidrc file using the Liquid: Generate .liquidrc (defaults) command in the vscode command palette. If you prefer a more refined output then you can generate a file with recommended rules. The recommended rules are best suited to Shopify projects and were helped determined by several talented developers who frequent the Shopify Developers discord server.
Below is the default rules. It is important to note that if the liquid.format.* user/workspace setting contains rules it will be merged with these defaults when the file is generated.
{
"ignore": [],
"wrap": 0,
"commentIndent": true,
"crlf": false,
"indentSize": 2,
"preserveComment": true,
"preserveLine": 2,
"endNewLine": true,
"markup": {
"commentNewline": true,
"forceLeadAttribute": false,
"forceAttribute": false,
"forceIndent": false,
"attributeCasing": "preserve",
"attributeSort": false,
"attributeSortList": [],
"correct": false,
"delimiterSpacing": false,
"preserveAttributes": false,
"preserveText": true,
"quoteConvert": "none",
"selfCloseSpace": false
},
"json": {
"arrayFormat": "default",
"braceAllman": false,
"bracePadding": false,
"objectIndent": "default",
"objectSort": false
},
"style": {
"braceAllman": false,
"classPadding": false,
"sortProperties": false,
"sortSelectors": false,
"selectorList": false,
"comments": false,
"correct": false,
"noLeadZero": false,
"quoteConvert": "none"
},
"script": {
"correct": false,
"arrayFormat": "indent",
"braceAllman": false,
"methodChain": 3,
"caseSpace": true,
"endComma": "never",
"quoteConvert": "single",
"elseNewline": true,
"functionNameSpace": false,
"functionSpace": true,
"ternaryLine": true,
"braceNewline": false,
"bracePadding": true,
"braceStyle": "none",
"neverFlatten": false,
"noCaseIndent": true,
"noSemicolon": false,
"objectIndent": "indent",
"objectSort": false,
"vertical": false,
"variableList": false
}
}
Snippets
Liquid snippets are supported in this extension. The filter and tag snippets provided were originally forked from vscode-liquid-snippets but have since changed a considerable amount.
Tag and Filter Snippets
Snippets made available by this extension leverage tab invoked "choices" for applying filter pipes | and delimiter whitespace dashes - in liquid tokens. In addition to the tags and filter snippets, section schema snippets are also supported which help users to quickly generate settings within Shopify theme {% schema %} tag blocks.
Schema Snippets
Shopify {% schema %} tag snippets are made supported by the extension and can be used to apply the supported settings within the embedded code region. All setting configurations are supported.
Extension Conflicts
If you are using alternative extensions such as the Shopify Liquid or Liquid Languages Support extension then you may run into some issues. The conflicts which may be incurred will be caused because these extensions also target Liquid grammars.
The vscode marketplace has 3 different extensions for Liquid support:
- Liquid
- Liquid Languages Support
- Shopify Liquid
This extension uses the Liquid display name and is considered the official Liquid extension for vscode.
Liquid Languages Support
If you are using or have installed the Liquid Languages Support extension then it is recommended that you either uninstall or disable it. The Liquid Languages Support extension is not maintained and the grammars are mostly obsolete. Using it along side this extension and Shopify Liquid is problematic, boycott it, as it does nothing but increase th editors startup time.
Shopify Liquid
If you are using or have installed Shopify Liquid then you may need to choose (or alternate) between the Shopify Liquid extension and this extension. The Shopify Liquid extension is for Shopify projects (specifically themes) and provides a couple of great features which this extension does not (yet) support.
These capabilities made available by Shopify Liquid are nice but they come with limitations as the extension does not support Windows and its LSP (Language Server) implementation requires Ruby to function making it rather resource heavy and exhaustive on your machine. Though the extra features it provides help in some cases, they are specific to Shopify themes and not much use outside of that.
Capabilities available in the future release (Liquify) support all current features of the Shopify Liquid extension.
Releases
As of v3.0.0 all version releases and changelogs including the distributed VSIX files can be found in Releases. Previous version changelogs can be found in the v2.3.0 branch.
Contributing
Contributions are welcome! This project uses pnpm for package management and is written in TypeScript.
- Ensure pnpm is installed globally
npm i pnpm -g - Leverage
pnpm envif you need to align node versions - Clone this repository
git clone https://github.com/panoply/vscode-liquid.git - Run
pnpm iin the root directory - Run
pnpm devfor development mode
Developing
The project uses tsup for producing the distributed bundle. You can produce a VSIX by running the pnpm build command. The .vscode/launch.json file contains the extension host logic.
pnpm dev # Development in watch mode
pnpm build # Builds extension and packages VSIX
pnpm dry # Prints list of files that are packages into VSIX
Testing
The extension has undergone E2E and capability tests, but it does not leverage the vscode test suite. The extension itself is simple enough where extensive tests are not a matter of necessity. The contained test directory is used when invoking the debugger and extension host. Contained within that directory are various sample files that can be used for validating capabilities, grammars and invocation.
PR's are welcome for test cases, but be aware that the Liquify supersede will make them obsolete in due time.
Acknowledgements
Thanks to these talented folks who's work, ideas, feedback and contributions make this extension possible.
Support
No obligation but coffee is always appreciated.
PayPal: Donate
BTC: 35wa8ChA5XvzfFAn5pMiWHWg251xDqxT51