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
*.duoto 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.duofile type comes from that bundle and the icon from a file icon provider. The grammar, the language configuration and the icon are copied fromeditors/grammarsandeditors/vscodeat build time. - Neovim, Helix and Zed: the HTML tree-sitter grammar, with one
highlights.scmandinjections.scmshared by Helix and Zed (a test keeps the two copies equal). Like the TextMate grammar, capitalised tags are components andprefix:nameattributes 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 fromhtml-mode, and aneglot-server-programsentry. - Every shell runs the server on the
PATH, resolved to an absolute path from absolutePATHentries, 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 withproject_server = trueand then only after:trust(vim.secure.read) accepts that file, asked again when it changes; Emacs only withduolith-use-project-serverset toask, 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
| Option | Why not |
|---|---|
| The platform LSP API in JetBrains | For 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 lexer | A second highlighter to keep in step with the language definition; the TextMate bundle is already generated |
| Write the tree-sitter grammar now | Out of scope for the shells; it belongs to the Syntax context and replaces the HTML grammar in one place when it lands |
Ship .sublime-syntax | A 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 bypnpm generate; they fetch it from the commit onmainthat added it. Emacs registers it fortreesit-install-language-grammar, andduolith-ts-mode(derived fromduolith-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 induolith-mode. - Changing
editors/grammars/duolith.tmLanguage.jsonneedspnpm --filter duolith-editors-others generatefor Sublime Text. The other shells read it at build time or not at all.