Liquid (vs code)

A visual studio code extension for the Liquid template language. Includes syntax highlighting support for Liquid code used in HTML, JavaScript CSS, SCSS, Markdown and more. Ships with auto formatting code beautification, advanced snippet auto-completion resolution and respects VS Codes native Intellisense, hover and diagnostic features.

Key Features

• Syntax support for Liquid in CSS, SCSS, JavaScript, Markdown and more!
• Auto formatting and beautification with the powerful PrettyDiff.
• Snippet auto-completion for liquid tags, filters, shopify schema and more!
• Focused support for Jekyll and Shopify liquid variations
• Supports Shopify Section code blocks.

Avoiding extension conflicts

If you're using the Liquid Language Support and/or the Shopify Liquid Template Snippets then it's highly recommended that you either uninstall or disable both of these before using this extension.

Showcase

Table of Contents

• Quickstart
• Commands
• Workspace Settings
• Syntax Support
• Formatting
  • Using .liquidrc rule file
  • Using the workspace setting option
  • Toggle and Status button
  • Tag Associations
  • Ignored Tags
  • Rules
  • Key Binding
• Snippets
• Support
• Changelog

Quickstart

After installing this extension run the Liquid: Generate .liquidrc File command to create a .liquirc rule file in your projects root directory. This file will be used to enforce your code formatting style, refer to the Formatting and Rules section for additional information for customization options. Open any .html, .liquid or .jekyll file and starting coding your project.

Commands

Workspace Settings

{
  // Controls whether formatting is enabled or disabled
  "liquid.format": true,
  // Formatting code style rules
  "liquid.rules": {
    // Ignored tags
    "ignore": [
      {
        "type": "", // Accepts html or liquid
        "begin": "", // The start tag pattern
        "end": "" // the ending tag pattern/name
      }
    ],
    // HTML code style
    "html": {},
    // JavaScript code style (applied to the {% javascript %} tag)
    "js": {},
    // CSS code style (appled to {% style %} and {% stylesheet %} tags)
    "css": {},
    // SCSS code style (applied to the {% stylesheet 'scss' %} tag)
    "scss": {},
    // JSON code style (applied to the {% schema %} tag)
    "json": {}
  }
}

Syntax Support

This extension provides liquid syntax support in various languages by leveraging VS Codes powerful grammar injections feature. Liquid is a template language and thus its grammar should be treated as such and by using grammar injections we don't loose any of VS Codes awesome features like IntelliSense, Auto Complete, Hover and Diagnostics.

Additionally, Liquid code contained in HTML <script> and/or <style> tags also support liquid syntax highlighting.

Supported Languages

If you would like Liquid syntax support for a certain language or file extension please submit a feature request.

HTML Validation

If your <style> and <script> HTML tags contain Liquid syntax consider disabling HTML Validation in editor settings to prevent VS Code from validating these tags and throwing errors:

{
  "html.validate.scripts": false,
  "html.validate.styles": false
}

Formatting

Formatting can be enable/disabled via the command palette and will respect the editor.formatOnSave setting. When Liquid formatting is enabled the extension will format (beautify) any HTML, Liquid or Jekyll file in your workspace as it will assume these files contain Liquid syntax.

Formatting uses a default set of style rules which enforce a consistent coding style. You can customize the format rules and overwrite the defaults using a .liquidrc file or alternatively use the liquid.rules workspace setting option.

Using .liquidrc rule file

Including a .liquid file in the root of your projects workspace is the recommended approach for defining a custom set of formatting code style rules. This approach allows you to easily control formatting options to best fit your code style quirks and share this ruleset across projects and collaborations.

Using the workspace setting option

Rules can also be applied in your User or Workspace settings using the liquid.rules configuration option. Please note that if a .liquidrc is present in your projects root it will run precedence over rules defined in workspace settings. Again, it's recommended you use a .liquidrc file for setting custom rules.

Status bar button

When a HTML, Liquid and Jekyll file is open and active in the editor you will see the Liquid toggle/status button appear on the bottom right hand side of the VS Code status bar. The toggle button will allow you to enable/disable liquid formatting and will notify you when the parser encounters any code errors.

Status Bar Item	Function	Description
	Formatting is enabled	Clicking this status bar in this state will disable formatting
	Formatting is disabled	Clicking the status bar item in this state will enable formatting
	Parsing error was detected	Opens the output panel and provides a hint were error occured (formatting is still enabled in this state)

Tag Association

The are some situations where you may want to apply language formatting to a specific tag. Using the tags property available to each language rule will allow you to apply a formatting code style to a custom defined tag.

Example The below example would apply singluar tag formatting to <source> HTML tags which are used within <picture> elements. The SCSS tag association would apply formatting to content between <style lang="scss"></style> tags.

{
  "html": {
    "tags": [
      {
        "tag": "source",
        "rules": {
          "force_attribute": true
        }
      }
    ]
  },
  "scss": {
    "tags": [
      {
        "type": "html",
        "begin": "style lang=\"scss\"", // <style lang="scss">
        "end": "style" // </style>
      }
    ]
  },
}

Ignoring Tags

Sometimes you may wish to ignore/disable formatting for certain HTML or Liquid tags. The ignore ruleset accepts an array of tags you wish to exclude. Ignored tags must have matching open and close definition tags and are defined using the ignore setting which accepts an array of objects with each object representing the tag to ignore from formatting.

In previous versions of this extension ignored tags were defined using the liquid.formatIgnore setting. This has been deprecated and you must use the new configuration.

Known Issues
Be careful overiding the default ignore tags. Liquid code contained in <script> or <style> tags will cause formatting to fail, hence why these tags are ignored by default.

The whitespace {%- comment -%} tags have trouble parsing if you're not applying whitespace equally, e.g:

<!-- ✅ THIS WILL FORMAT CORRECTLY -->
{%- comment -%}
  Hello World
{%- endcomment -%}

{% comment %}
  Hello World
{% endcomment %}

<!-- ❌ THIS WILL BREAK FORMATTING -->
{%- comment %}
  Hello World
{% endcomment -%}

Notice in the above example the liquid commment tags using whitespace dash -. When the whitespace dash is only used once on either the left or right side it will break formatting. If you decide to remove comments from ignore then you must write all comments with equal whitespace dashes, like the above example.

Please remove the default tags from the ignore array with extereme caution, be aware of what you're doing and how it might effect your code.

Default Ignores

{
  "ignore": [
    {
      "type": "liquid",
      "begin": "comment", // {% comment %} or {%- comment -%}
      "end": "endcomment" // {% endcomment %} or {%- endcomment -%}
    },
    {
      "type": "html",
      "begin": "script", // <script>
      "end": "script" // </script>
    },
    {
      "type": "html",
      "begin": "style", // <style>
      "end": "style" // <style>
    }
  ]
}

All HTML comments (<!-- -->) are ignored by default.

Do not include tag denotations (eg: <, >, </, {%, %}) when defining begin and end capture expressions. The type property defines the denotations of the tag.

Rules

Below is the default code style formatting rules. Generate this file using the Liquid: Generate .liquidrc File command and a file in the root of your project will be created. Alternatively you can use the "liquid.rules" option in your workspace or user settings.

{
  "ignore": [
    {
      "type": "liquid",
      "begin": "comment",
      "end": "endcomment"
    },
    {
      "type": "html",
      "begin": "script",
      "end": "script"
    },
    {
      "type": "html",
      "begin": "style",
      "end": "style"
    }
  ],
  "html": {
    "correct": true,
    "force_attribute": false,
    "preserve": 2,
    "unformatted": false
  },
  "js": {
    "preserve": 1,
    "method_chain": 0,
    "quote_convert": "none",
    "format_array": "indent",
    "format_object": "indent",
    "braces": false,
    "no_semicolon": false,
    "brace_block": true
  },
  "scss": {
    "css_insert_lines": true,
    "preserve": 2,
    "braces": false,
    "brace_block": true
  },
  "css": {
    "css_insert_lines": true,
    "preserve": 2,
    "braces": false,
    "brace_block": true
  },
  "json": {
    "preserve": 0,
    "format_array": "indent",
    "braces": true,
    "no_semicolon": true,
    "brace_block": false
  }
}

Key binding

You can use the Liquid formatter by using the below key binding.

cmd + shift + L -> Format Document

Use ctrl for windows

Custom keybindings
If you don't like the defaults then rebind editor.action.formatDocument in the keyboard shortcuts menu of vscode.

Snippets

Liquid snippets are supported in this extension. The Filter and Tag snippets which have been included were forked from vscode-liquid-snippets. The reason for forking this extension is to avoid conflicts due to the extension dependency it relies on, however additionally the extension includes over 50+ snippet helpers for both Jekyll and Shopify development.

Schema Snippets (Shopify Liquid Variation)

Shopify {% schema %} section snippets are supported when using the schema prefix followed by the input type setting name. The schema snippets inject complete input types and allow you to quickly apply the schema setting.

Support this extension!

This extension brings sufficient support of the Liquid language to VS Code and aims to provide a well integrated IDE experience for developers using all variations of the language. Prior to the release of this extension Liquid support in vscode and text editors in general was extremely limited with developers stuck using outdated and sometimes broken solutions.

Developing this extension has taken a considerable amount of time. For now, this extension is available free of cost but will require a small license fee in the future. To help keep this extension free and open source for as long as possible, please consider supporting its growth and maintainance:

PayPal: Donate
BTC: 35wa8ChA5XvzfFAn5pMiWHWg251xDqxT51

Changelog

Refer to the Changelog for each per-version update and/or fixes.

Currently made with 🖤 by Nikolas Savvidis