archival for VS Code

Language support for archival sites: syntax highlighting for archival's liquid dialect, plus diagnostics for templates, object definitions and objects from the archival binary's built-in language server.

Requirements

The extension drives archival lsp, so the archival binary must be installed, at the version named by archivalMinVersion in package.json or above. Install it with npm i -g archival, cargo binstall archival, or cargo install archival.

It is searched for in this order:

1. the archival.serverPath setting (~ and ${workspaceFolder} are expanded)
2. node_modules/.bin/archival, then node_modules/archival/bin/archival, in the workspace folder
3. archival on PATH
4. ~/.cargo/bin/archival

The server starts only in folders containing an archival.toml or archival_objects.toml, one per workspace folder.

Features

• Highlighting for archival's liquid dialect: {% layout %}, {% include %} and {% render %} with their with / for / as clauses and key: value arguments, {% liquid %} bodies, {% echo %}, and {% # … %} inline comments.
• Template diagnostics from the same parser that builds the site, so a template that reports clean here is one that builds.
• TOML diagnostics for archival.toml, your object definitions, and every object under the objects directory — unknown fields, bad field types and a non-numeric order are only warnings during a build, and errors here.

Only liquid's standard-library filters are available in archival. Shopify's pluralize and date_in_tz are highlighted as unknown because archival's parser rejects them.

Every check runs against the parsers inside the archival binary you have installed, so what this reports is what the archival that builds your site accepts — not what some published schema described at the time it was written.

TOML files

This extension expects a TOML extension alongside it, such as Even Better TOML. VS Code ships no TOML language of its own, and there is no manifest field for a peer extension — extensionDependencies and extensionPack both install what they name — so this is a recommendation rather than a requirement, raised once when you open an archival site without one.

What you get either way:

The two archival does not check itself are the two it has no parser for: their types live in the archival editor, which publishes its schemas through archival rather than owning a parser here. Those come from SchemaStore, which resolves them by filename.

Settings

Run archival: Show Server Output to see what the server is doing, and archival: Restart Language Server after installing or upgrading the binary.

Using this alongside the Liquid extension

This extension claims the liquid language so that it works on its own. So do Liquid and Shopify Liquid. With two enabled, VS Code picks one grammar by load order, so highlighting can differ between reloads, and the Shopify server reports diagnostics about a theme rather than an archival site. Disable one of the two in archival workspaces (Extensions → Disable (Workspace)).

Development

npm install
npm run watch     # rebuild on change; launch the extension with F5
npm test          # typecheck and compare grammar snapshots

Grammar snapshots live beside their sources in test/grammar. Regenerate them with npm run test:grammar:update and read the diff — they are the only thing that catches a grammar regression.

They are generated against a stub text.html.basic, because VS Code ships that grammar but the test runner does not, and an include that fails to resolve silently changes which rule wins. Snapshots therefore show no HTML highlighting.