HTML Mustache Language Server

A VS Code language server for HTML with Mustache template syntax, powered by tree-sitter.

Features

• Semantic Highlighting - Context-aware syntax highlighting using tree-sitter
• Document Symbols - Outline view showing HTML elements and Mustache sections
• Hover Information - Documentation for HTML tags, attributes, and Mustache constructs
• Folding Ranges - Collapse HTML elements, Mustache sections, and comments

Quick Start

# 1. From the project root, build the WASM parser
tree-sitter build --wasm

# 2. Install LSP dependencies
cd lsp
pnpm install

# 3. Build the LSP
pnpm run build

# 4. Test in VS Code (see below)

Building the WASM Parser

The LSP requires the tree-sitter grammar compiled to WebAssembly. From the project root:

# Make sure tree-sitter CLI is installed
pnpm add -g tree-sitter-cli  # or use the one in this repo's devDependencies

# Build the WASM file (creates tree-sitter-htmlmustache.wasm)
tree-sitter build --wasm

This creates tree-sitter-htmlmustache.wasm in the project root, which the LSP server loads at runtime.

Installing & Building the LSP

cd lsp

# Install all dependencies (client + server)
pnpm install

# Build both client and server
pnpm run build

Development Mode

For active development, use watch mode to auto-rebuild on changes:

pnpm run watch

Testing in VS Code

Option 1: Launch Configuration (Recommended)

1. Open the project root (tree-sitter-htmlmustache/) in VS Code
2. Go to Run and Debug (Cmd+Shift+D)
3. Select "Launch LSP Extension" from the dropdown
4. Press F5

This opens a new VS Code window with the extension loaded. Open any .mustache, .hbs, or .handlebars file to test.

Option 2: Manual

1. Open the lsp/ folder in VS Code
2. Press F5 to launch Extension Development Host
3. In the new window, open a .mustache file

Verifying It Works

Once running, you should see:

• Syntax highlighting for HTML and Mustache constructs
• Outline view (Cmd+Shift+O) showing HTML elements and Mustache sections
• Hover tooltips when hovering over tags, attributes, or Mustache expressions
• Folding arrows for collapsible regions

Troubleshooting

"Failed to load tree-sitter-htmlmustache.wasm"

The WASM file wasn't found. Make sure you built it:

cd /path/to/tree-sitter-htmlmustache
tree-sitter build --wasm
ls *.wasm  # Should show tree-sitter-htmlmustache.wasm

No syntax highlighting

1. Check the Output panel (View > Output) and select "HTML Mustache Language Server"
2. Verify the file has a supported extension (.mustache, .hbs, .handlebars)
3. Make sure semantic highlighting is enabled in VS Code settings

Type errors during build

Run pnpm install from the project root to install dependencies.

Architecture

lsp/
├── client/                 # VS Code extension client
│   └── src/
│       └── extension.ts    # Extension entry point
├── server/                 # Language server
│   └── src/
│       ├── server.ts       # Main LSP server
│       ├── parser.ts       # Tree-sitter integration
│       ├── semanticTokens.ts # Syntax highlighting
│       ├── documentSymbols.ts # Outline view
│       ├── hover.ts        # Hover information
│       └── folding.ts      # Folding ranges
└── package.json            # Extension manifest

How It Works

1. Parsing: Documents are parsed with tree-sitter on open and on every change
2. Caching: Parse trees are cached per-document for efficiency
3. Feature Extraction: Each LSP feature walks the syntax tree to extract information

The server loads tree-sitter-htmlmustache.wasm from the parent directory and uses it to parse documents into syntax trees.

Adding Features

To add a new LSP feature:

1. Create a new file in server/src/ (e.g., completion.ts)
2. Implement the feature using the cached parse tree
3. Register the handler in server.ts
4. Add the capability to the InitializeResult

Related

• tree-sitter-htmlmustache - The tree-sitter grammar
• VS Code LSP Guide
• web-tree-sitter