You want to make changes to the syntax highlighting and don't know where to start and how to see the impact of your changes? This document should get you started.
It's a bit clunky. I apologize. There isn't a whole lot of people who write their own syntax highlighting grammars.
Much like microsoft/TypeScript-TmLanguage, the .tmLanguage
files are maintained in YAML to make them easier to consume and edit by humans.
The *.tmLanguage.json
files are generated by our build and are not maintained manually.
Visual Studio Code only lets you debug extensions, so we'll use theme-check-vscode
for this. Since this repository is a git submodule
of theme-check-vscode
.
- Clone theme-check-vscode.
git clone --recurse-submodules https://github.com/Shopify/theme-check-vscode
NOTE: If you forgot the --recurse-submodules
flag, you can fix it with the following command at the root of the theme-check-vscode
directory:
git submodule update --init --recursive
- Install dependencies
cd theme-check-vscode
yarn install
-
In a terminal, at the root of
theme-check-vscode
, build the extension:cd path/to/theme-check-vscode npm run build
-
Start the YAML->JSON syntax highlighting watcher:
npm run dev:syntax
-
In VS Code, at the root of
theme-check-vscode
, opensrc/extension.js
. -
Press
F5
(or Run > Start Debugging menu option). -
Select the
VS Code Extension Development
option.
-
In the
[Extension Development Host]
window, open thetheme-check-vscode/syntaxes/test
folder. Open any*.liquid
file. -
In the other window, make modifications to any of the language grammar files (the YAML files).
-
In the
[Extension Development Host]
window, hit⌘+R
to refresh.You should see the result of your changes.
-
Repeat step 7-8 until satisfied.
It is highly recommended you setup VS Code's Scope inspector. This will greatly help you debug your changes.
Turns out this is kind of hard to test. The folks at Microsoft have a text-based workflow that involves committing "baseline" outputs for a series of files. We're doing the same here.
- In a terminal, go into the
theme-check-vscode/syntaxes
folder.
cd path/to/theme-check-vscode
cd syntaxes
-
Make changes to any of the YAML files.
-
Generate new traces:
yarn test
-
Inspect the result of the
theme-check-vsode/syntaxes/test/generated/*.baseline.txt
files. -
Look at the diff between your changes and the accepted baselines:
yarn test:diff
-
Repeat step 2–5 until satisfied.
-
Accept and commit the changes as the new baselines.
yarn test:accept
yarn add tests/baselines
-
Official documentation on TextMate language grammars
For when you want to learn more about what the fields are and how they work. You should take an afternoon reading this entire page and taking notes. This is going to go a long way.
-
List of convention for scope names
Don't know what
name
to give to a token so that it gets highlighted properly by default themes? This reference should guide you. -
Visual Studio Code Syntax Highlighting Guide
-
This section is particularly helpful when you want to debug interactively and see the result of your changes.
-
-
Official documentation on TextMate scope selectors
For when you want to understand styling. It's a bit less important.