This version ships with breaking changes and requires that you to align with new configuration. This is an important update as it will be the last major version release wherein users will need to undertake and apply changes to core configurations in preparation for the Liquify supersede. The next major release of the extension will be Liquify which means all future features will up-streamed to that project.
See this gist for the quick-fix upgrade guide.
Workspace and .liquidrc file settings now use a new definition structure for formatting configuration. There is no backwards compatibility, so you can either update to 4.0.0 or continue using 3.2.2. Below is the breaking changes that ship in this release.
TLDR
No problems fam, see this gist.
The new configurations are expressed using different structures. Depending on how you define settings, be it within a .liquidrc file or from within a .vscode/settings.json file the way to provide beautification rules has changed. See the below examples of the new configuration structures:
For developers who leverage a .liquidrc file for beautification rules, the new structure requires you to nest rules under a format key property.
| OLD CONFIGURATION | NEW CONFIGURATION |
|---|---|
{
// "liquid.format.wrap": 0,
// "liquid.format.crlf": false,
// "liquid.format.endNewLine": false,
// "liquid.format.indentSize": 2,
// "liquid.format.preserveLine": 3,
// "liquid.format.commentIndent": false,
// "liquid.format.preserveComment": false,
// "liquid.format.markup": {},
// "liquid.format.script": {},
// "liquid.format.style": {},
// "liquid.format.json": {},
} |
{
"format": {
"ignore": [],
"wrap": 0,
"wrapFraction": 0,
"crlf": false,
"endNewline": false,
"indentSize": 2,
"preserveLine": 3,
"liquid": {}, // New! Liquid specific format rules
"markup": {},
"json": {},
"style": {},
"script": {}
}
} |
For developers who use workspace settings (.vscode/settings.json) for defining beautification options. You will need to move configuration to the liquid.format.rules object.
| OLD CONFIGURATION | NEW CONFIGURATION |
|---|---|
{
// "liquid.format.wrap": 0,
// "liquid.format.crlf": false,
// "liquid.format.endNewLine": false,
// "liquid.format.indentSize": 2,
// "liquid.format.preserveLine": 3,
// "liquid.format.commentIndent": false,
// "liquid.format.preserveComment": false,
// "liquid.format.markup": {},
// "liquid.format.script": {},
// "liquid.format.style": {},
// "liquid.format.json": {},
} |
{
"liquid.format.rules": {
"ignore": [],
"wrap": 0,
"wrapFraction": 0,
"crlf": false,
"endNewline": false,
"indentSize": 2,
"preserveLine": 3,
"liquid": {},
"markup": {},
"json": {},
"style": {},
"script": {}
}
} |
The liquid.settings.target option is deprecated and no longer supported. Editor settings will default to the workspace .vscode/settings.json file and if one is not present in the project then the global (User Settings JSON) file will be used.
In version v3.0.0 an additional configuration method was made available which allowed you to define formatting rules in a package.json file using a prettify property. As of version 4.0.0 this is no longer supported (nor is Prettify, see Æsthetic replaced Prettify).
Option definitions using package.json files will return in Liquify, but under a different field value.
As per #132 the liquid.format.enable setting is no longer supported. To enable formatting on save within Liquid files, you will need provide Language Specific settings in either your user or workspace settings. Below is the how you enable formatting in v4.0.0:
{
"[liquid]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "sissel.shopify-liquid"
}
}Users have even more essential features available when choosing this extension for Shopify theme development or projects using Liquid. Support for file associated completions are now available. The files option is available to both the .liquidrc or workspace .vscode/settings.json settings. The option can used to provide file path references to project associated files. When you provide references then completion support is made available for the definition applied.
|
Using a |
Using workspace |
|---|---|
{
"engine": "shopify", // set engine to shopify
"files": {
"locales": "", // eg: ./path/en.default.json
"settings": "", // eg: ./path//settings_data.json
"snippets": [], // eg: ["./snippets/*"]
"sections": [], // eg: ["./sections/*"]
}
} |
{
"liquid.engine": "shopify", // set engine to shopify
"liquid.files.locales": "",
"liquid.files.settings": "",
"liquid.files.snippets": [],
"liquid.files.sections": [],
} |
This release provides locale completion support. This is achieved by providing a project relative path to the default locale file used by your theme. When defined, the extension will provide locale completions in translation object token expressions. Locale completions will be triggered in when a quotation character is detected following output token delimiters, eg: {{ ' }} or {{ " }}. In addition, the | t filter will be inserted automatically when none is detected.
This release provides settings_schema.json completion support. This is achieved by providing a project relative path to the location of your settings_data.json file used by your theme. When defined, the extension will provide completions on the settings.* object in Liquid tag and output tokens.
This release provides snippet file completion support. This is achieved by defining project relative path/s to directories that contain snippets or alternatively you can provide globs matches. Snippets will be shown for in {% render '' %} tag and will also allow you to quick open files.
The Prettify project is now shipped under under the module name Æsthetic. Æsthetic replaces Prettify as the core beautification tool used by the extension. Æsthetic is now under an RC version release along with exhausting tests and new features. Test cases against 100+ different code sample structures has brought Æsthetic to a far safer and more controlled level wherein code output respects input intent and changes will take the least most augmentative approach possible to prevent formats happening in unpredictable ways.
Æsthetic provides new beautification rules that expose more fine grained control over how your code is to be beautified. Your .liquidrc file will complain about now deprecated or changed rules. You should consult the Æsthetic Documentation to familiarize yourself with the tool and better understand how each rule will effect code output.
Below are some key features of Æsthetic and what is being shipped in 4.0.0.
Æsthetic has made previous global level rules available on a per-language basis. This means that you are able to use these rules in all supported lexer (liquid, markup, style and script) modes.
commentIndentcommentNewlinepreserveComment
Liquid beautification rules are no longer coupled together with markup and instead can now be defined via a liquid property. This new structure decouples and separates Liquid from markup allowing for more concise control for Liquid specific beautification. There are also several new highly refined formatting options available for Liquid specific beautification.
SEE CHANGES
| OLD CONFIGURATION | NEW CONFIGURATION |
|---|---|
// markup configuration no longer includes liquid
// specific formatting rules. Instead you define those
// rules on a { "liquid": {} } property
{
"markup": {
// "delimiterTrims": "preserve",
// "normalizeSpacing": true,
// "lineBreakSeparator": "before",
// "valueForce": "intent"
"attributeCasing": "preserve",
"attributeSort": false,
"attributeSortList": [],
"correct": false,
"commentIndent": false,
"commentNewline": false,
"forceAttribute": true,
"forceIndent": false,
"forceAttribute": false,
"preserveAttribute": false,
"preserveText": false,
"ignoreScripts": false,
"ignoreStyles": false,
"quoteConvert": "none",
"selfCloseSpace": true
}
} |
{
"liquid": {
"commentIndent": false,
"commentNewline": false,
"delimiterTrims": "preserve",
"ignoreTagList": [],
"lineBreakSeparator": "before",
"normalizeSpacing": true,
"preserveComment": false,
"quoteConvert": "single",
"valueForce": "intent"
},
"markup": {
"attributeCasing": "preserve",
"attributeSort": [],
"commentIndent": false,
"commentNewline": false,
"correct": false,
"forceAttribute": true,
"forceLeadAttribute": false,
"forceIndent": false,
"ignoreScripts": false,
"ignoreStyles": false,
"preserveComment": false,
"preserveAttributes": false,
"preserveText": false,
"quoteConvert": "none",
"selfCloseSpace": true
}
} |
This is a liquid specific rule which accepts a list of tag names to excluded from formatting.
In version 3.2.0 the extension introduced {% schema %} tag completion and validation support. This release improves upon this essential feature now {% schema %} JSON supports snippet completion capabilities.
Schema JSON provided snippet completion which can be invoked with CRTL+SPACE. All section structures are available, with additional ENBF tab-stop support which converts id defined values to Upcase format Labels.
This release now supports all IETF locale completion structures for labels and other translation based properties.
Schema JSON code regions now provide detailed documentation reference in hover and completion descriptions This information is extracted directly from the Shopify documentation.
This release is made possible with the help of these talented folks.
Miguel, who began contributing to this project in v3. Miguel is who you need to thank for making Settings Schema file intelliSense possible and
- Shopify settings_schema fixes
- [4.0] Section & Snippets Autocomplete not working when using config.method = workspace
Big thanks to Dave, who was behind a lot of the architecture and plays a key role in decision making. Have a look at his blog.
- Deprecate liquid.format.enable in favor of editor.formatOnSave and editor.defaultFormatter
- import asset breaking JS syntax highlighting
The work MaxDesign was essential put in the exhaustive tests and use-cases pertaining to formatting was essential to this release.
Thank you to all users of this extension and those who continue to choose it in their development. I have put a lot of hours into this project over the years and will continue to provide developers with the most powerful features available when working with Liquid.
Follow me on Twitter.
@panoply