Duolith docs

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 by crates/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.txt holds the ones that used to differ. Every page in examples/ must parse with no ERROR node; pnpm check enforces 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), between BEGIN GENERATED and END GENERATED lines, so a new element is coloured everywhere by pnpm generate, and check-generated fails 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 a load= 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: .gitattributes maps *.duo to Astro on GitHub (the only grammar GitHub has that reads the --- script block as TypeScript; compared with Svelte and HTML in editors/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 from editors/grammars/linguist/app.gitattributes.
  • Names are placeholders (@placeholder/..., placeholder-tree-sitter-pages) everywhere a registry would see them. **Display names are the placeholder PUBLIC_NAME**: Linguist's language name and its samples/PUBLIC_NAME/ folder, the Rouge title, the highlight.js name, the Shiki displayName and the tree-sitter title. Decision 0010's rename replaces PUBLIC_NAME with 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, the source.duolith scope) and the .duo extension, since editors and fences match on them; the rename changes those too.

Every target and its status

TargetWhereWorks todaySubmissionNeeds Mik
VS Code, Sublime, JetBrains (TextMate)editors/grammars/duolith.tmLanguage.jsonyes (decision 0023)marketplace, separatelythe marketplace accounts (as before)
Neovim (nvim-treesitter)tree-sitter-duolith/as a custom parser, steps in its READMEadd to nvim-treesitter's parser list; a Neovim plugin registry entryyes: nvim-treesitter PR and plugin registry
Helixtree-sitter-duolith/as a [[grammar]] entry, steps in its READMEHelix's languages.toml upstreamyes: Helix PR
Zedtree-sitter-duolith/as a dev extension, steps in its READMEZed extension registryyes: Zed extension registry
Emacs 29+tree-sitter-duolith/grammar installs; no duolith-ts-mode yetnone yetno
tree-sitter grammar packagestree-sitter-duolith/builds as C and WebAssemblynpm, crates.io, the tree-sitter grammar listyes: npm, crates.io and tree-sitter registry names and publishing
GitHublinguist/Astro fallback via .gitattributesLinguist PR, once 2000+ .duo files outside our repositories existyes: Linguist PR, display name, the public grammar repository
GitLabrouge/Svelte fallback via .gitattributesRouge PR, then GitLab's next Rouge upgradeyes: Rouge PR
Shikihighlighters/shiki/yesnpmyes: npm name and publishing
highlight.jshighlighters/highlightjs/yesnpm (third-party language package)yes: npm name and publishing
Prismhighlighters/prism/yesnpm, or a Prism component PRyes: npm name, or the Prism PR
Docs sitetools/release/site/ (not on main)hook documented in highlighters/README.mdnoneno
Monaco, CodeMirror 6nonenononeno (not written)

Nothing in the table has been submitted or published.

Alternatives considered

OptionWhy not
Use tree-sitter-html in Neovim, Helix and ZedScript blocks and {expressions} show as plain text, and --- breaks the tree
Generate highlight.js, Prism and Rouge from the TextMate grammarTheir 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 fallbackNeither reads the script block as TypeScript (screenshots in /mnt/project-files/demo/highlighting/)
Submit to Linguist nowLinguist 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.