Duolith docs

0085. Editor shells beyond VS Code: LSP4IJ and the TextMate bundle in JetBrains, the HTML tree-sitter grammar elsewhere

  • Status: Proposed
  • Date: 2026-11-14
  • Decided by: integrator (internal only)
  • Planning item: none; editor shells

Context

Every editor should get the language server (duolith-language-server --stdio, decision 0025) and some highlighting, while the shells stay thin (editors/AGENTS.md). There is a TextMate grammar (decision 0023) and no tree-sitter grammar for page files. JetBrains IDEs have two language server clients: the platform's own LSP API and Red Hat's LSP4IJ plugin. Neovim, Helix and Zed highlight with tree-sitter; Sublime Text reads TextMate grammars only as property lists; Emacs has neither.

Decision

  • JetBrains: a Gradle plugin (IntelliJ Platform Gradle Plugin 2) on LSP4IJ, mapping *.duo to the server with a file name pattern. Highlighting is the generated TextMate grammar, handed to the IDE's bundled TextMate plugin through its bundle provider; the .duo file type comes from that bundle and the icon from a file icon provider. The grammar, the language configuration and the icon are copied from editors/grammars and editors/vscode at build time.
  • Neovim, Helix and Zed: the HTML tree-sitter grammar, with one highlights.scm and injections.scm shared by Helix and Zed (a test keeps the two copies equal). Like the TextMate grammar, capitalised tags are components and prefix:name attributes are directives, so no element list is typed by hand. Neovim uses a Vim syntax file by default, which also colours the script block and {expressions} as TypeScript. The server's semantic tokens add colour where the editor supports them.
  • Sublime Text: the TextMate grammar converted to a property list, rule for rule, by editors/others/scripts/sublime-grammar.ts. A test fails when the committed copy is stale.
  • Emacs: duolith-mode, derived from html-mode, and an eglot-server-programs entry.
  • Every shell runs the server on the PATH, resolved to an absolute path from absolute PATH entries, because the server runs in the project's folder and a bare name could pick up a program there (Windows looks in the current folder first). The server installed in a project (node_modules/.bin) matches the project's compiler, but running it runs the project's code, so it needs consent: the JetBrains plugin uses it only in a trusted project; Neovim only with project_server = true and then only after :trust (vim.secure.read) accepts that file, asked again when it changes; Emacs only with duolith-use-project-server set to ask, asking once per project; Helix, Zed and Sublime Text only when the user names it. A page outside any project gets no server in Neovim.

Alternatives considered

OptionWhy not
The platform LSP API in JetBrainsFor the 2024 platform versions we support it is only in JetBrains' commercial IDEs, not in IntelliJ IDEA Community or Android Studio; LSP4IJ runs in all of them, and adds a console showing the server's traffic
A JetBrains file type with its own lexerA second highlighter to keep in step with the language definition; the TextMate bundle is already generated
Write the tree-sitter grammar nowOut of scope for the shells; it belongs to the Syntax context and replaces the HTML grammar in one place when it lands
Ship .sublime-syntaxA conversion that changes the rules (sublime-syntax has its own model); the property list is the same grammar

Consequences

  • Building the JetBrains plugin needs JetBrains' repositories (download.jetbrains.com, www.jetbrains.com, plugins.jetbrains.com, downloads.marketplace.jetbrains.com) besides Maven Central and the Gradle plugin portal. The build skips the cache redirector, and uses the test framework bundled in the IDE, because both would otherwise reach mirrors outside the allowlist.
  • The plugin uses TrustedProjects.isTrusted, which the Plugin Verifier reports as experimental API.
  • With the HTML grammar, tree-sitter editors see the script block and {expressions} as text, and a { handler with => in it can show as a parse error. The language server's diagnostics are unaffected. A Duolith tree-sitter grammar fixes this in one place.
  • Update: that grammar landed (editors/grammars/tree-sitter-duolith, decision 0100), and Helix, Zed and Neovim now use it with its own queries, copied into each shell by pnpm generate; they fetch it from the commit on main that added it. Emacs registers it for treesit-install-language-grammar, and duolith-ts-mode (derived from duolith-mode, so the eglot entry and comment settings carry over) colours, indents and indexes pages with it, with the grammar's captures mapped to font-lock faces and TypeScript and CSS embedded where Emacs has those grammars. Without the grammar, pages stay in duolith-mode.
  • Changing editors/grammars/duolith.tmLanguage.json needs pnpm --filter duolith-editors-others generate for Sublime Text. The other shells read it at build time or not at all.