0100. Page files are highlighted everywhere from two grammars, and nothing is submitted without Mik
- Status: Accepted (Mik, 17 Nov 2026)
- Date: 2026-11-14
- Decided by: Mik (submissions and names); integrator (the layout, internal only)
- Planning item: none
Context
Mik asked for .duo colouring "on GitHub, GitLab, IDEs and everywhere possible". VS Code (and Sublime, JetBrains through TextMate bundles) already use the TextMate grammar generated from the language definition (decision 0023). Everything else uses one of four other mechanisms: tree-sitter (Neovim, Helix, Zed, Emacs 29+), GitHub's Linguist, GitLab's Rouge, and the web libraries docs sites use (Shiki, highlight.js, Prism). Each upstream has its own review, and the public package names are not chosen.
Decision
- Two grammars are the source of truth: the generated TextMate grammar (decision 0023) and a new tree-sitter grammar,
editors/grammars/tree-sitter-duolith/, which reads the outer page syntax bycrates/syntax's rules (an external scanner finds the---fences, the expression end at the balancing brace,</style>, comments, and a<that opens no tag) and injects TypeScript and CSS. The few inputs where its tree still differs are listed in its README under "Known differences";test/corpus/parity.txtholds the ones that used to differ. Every page inexamples/must parse with no ERROR node;pnpm checkenforces it. - The other highlighters are thin: Shiki reuses the TextMate grammar as it is; highlight.js, Prism and Rouge are small hand-written lexers. Their element and flow-element lists, and the tree-sitter highlight query's, are generated from
spec/language/elements.yaml(tools/generate/highlighting.ts), betweenBEGIN GENERATEDandEND GENERATEDlines, so a new element is coloured everywhere bypnpm generate, andcheck-generatedfails CI when one is stale. - Shared colours: element names are tags, flow elements (
show,otherwise,slot,piece) are keywords, capitalised names are components (types or classes), a directive's kind (on:,bind:,class:) is a keyword, an event name is a function, and the tree-sitter query colours aload=attribute as a keyword (it was asked for, but it is not in the language definition yet, so this is only a colour). - Fallbacks until GitHub and GitLab know the language:
.gitattributesmaps*.duoto Astro on GitHub (the only grammar GitHub has that reads the---script block as TypeScript; compared with Svelte and HTML ineditors/grammars/linguist/README.md) and to Rouge's Svelte lexer on GitLab (the fewest error marks of svelte, vue and html). Apps get the same line fromeditors/grammars/linguist/app.gitattributes. - Names are placeholders (
@placeholder/...,placeholder-tree-sitter-pages) everywhere a registry would see them. **Display names are the placeholderPUBLIC_NAME**: Linguist's language name and itssamples/PUBLIC_NAME/folder, the Rouge title, the highlight.jsname, the ShikidisplayNameand the tree-sitter title. Decision 0010's rename replacesPUBLIC_NAMEwith the public name in the same change as everything else. Only two things carry the codename: the language id (duolith, the tree-sitter language name, the Rouge tag, the Shiki id and highlight.js alias, thesource.duolithscope) and the.duoextension, since editors and fences match on them; the rename changes those too.
Every target and its status
| Target | Where | Works today | Submission | Needs Mik |
|---|---|---|---|---|
| VS Code, Sublime, JetBrains (TextMate) | editors/grammars/duolith.tmLanguage.json | yes (decision 0023) | marketplace, separately | the marketplace accounts (as before) |
| Neovim (nvim-treesitter) | tree-sitter-duolith/ | as a custom parser, steps in its README | add to nvim-treesitter's parser list; a Neovim plugin registry entry | yes: nvim-treesitter PR and plugin registry |
| Helix | tree-sitter-duolith/ | as a [[grammar]] entry, steps in its README | Helix's languages.toml upstream | yes: Helix PR |
| Zed | tree-sitter-duolith/ | as a dev extension, steps in its README | Zed extension registry | yes: Zed extension registry |
| Emacs 29+ | tree-sitter-duolith/ | grammar installs; no duolith-ts-mode yet | none yet | no |
| tree-sitter grammar packages | tree-sitter-duolith/ | builds as C and WebAssembly | npm, crates.io, the tree-sitter grammar list | yes: npm, crates.io and tree-sitter registry names and publishing |
| GitHub | linguist/ | Astro fallback via .gitattributes | Linguist PR, once 2000+ .duo files outside our repositories exist | yes: Linguist PR, display name, the public grammar repository |
| GitLab | rouge/ | Svelte fallback via .gitattributes | Rouge PR, then GitLab's next Rouge upgrade | yes: Rouge PR |
| Shiki | highlighters/shiki/ | yes | npm | yes: npm name and publishing |
| highlight.js | highlighters/highlightjs/ | yes | npm (third-party language package) | yes: npm name and publishing |
| Prism | highlighters/prism/ | yes | npm, or a Prism component PR | yes: npm name, or the Prism PR |
| Docs site | tools/release/site/ (not on main) | hook documented in highlighters/README.md | none | no |
| Monaco, CodeMirror 6 | none | no | none | no (not written) |
Nothing in the table has been submitted or published.
Alternatives considered
| Option | Why not |
|---|---|
| Use tree-sitter-html in Neovim, Helix and Zed | Script blocks and {expressions} show as plain text, and --- breaks the tree |
| Generate highlight.js, Prism and Rouge from the TextMate grammar | Their models differ (no begin/end scopes in Prism, Ruby states in Rouge); a converter would be larger than the three lexers |
| Svelte or HTML as the GitHub fallback | Neither reads the script block as TypeScript (screenshots in /mnt/project-files/demo/highlighting/) |
| Submit to Linguist now | Linguist rejects extensions with under 2000 files in a year from many users; the PR would be closed |
Consequences
Adding an element needs pnpm generate, which now also rewrites the word lists in four highlighter files. A change to the page syntax in crates/syntax must be mirrored in tree-sitter-duolith/grammar.js and src/scanner.c (the examples-parse test catches most drift) and in the three lexers. GitHub's language bar shows page files as Astro until Linguist ships the language. CI needs a C compiler for the tree-sitter tests (Ubuntu runners have one) and Ruby with the rouge gem for the Rouge step.
What Mik decided (17 Nov 2026)
Approved, with every submission held until the public name exists (decision 0091), so nothing has to be renamed after it is accepted upstream.