@codemirror/lang-yaml

@codemirror/lang-yaml adds YAML language support to CodeMirror 6, the extensible in-browser code editor. It wraps the Lezer YAML grammar with CodeMirror’s language extension system, providing syntax highlighting, context-aware indentation for block sequences, mappings, and literal blocks, and code folding for flow collections and multi-line items.

Beyond plain YAML, the package exports a yamlFrontmatter helper that lets any other language (Markdown, JSON, etc.) be wrapped with an optional YAML frontmatter block delimited by triple-dash lines, using CodeMirror’s mixed-language parsing to parse the frontmatter as YAML and the rest of the document with the wrapped language.

What You Get

• yaml() language extension - A single function that returns a LanguageSupport ready to drop into a CodeMirror extensions array.
• Context-aware indentation - Custom indent rules for block sequences, block mappings, block literals, and flow collections so pressing Enter keeps YAML properly aligned.
• Code folding support - Flow mappings/sequences and multi-line block items and literals can be folded via CodeMirror’s foldNodeProp integration.
• yamlFrontmatter() composer - Wrap any other language (e.g. Markdown) with an optional YAML frontmatter block using CodeMirror’s mixed-language parsing.
• Exported yamlLanguage - The underlying LRLanguage instance for advanced use cases like custom language data or further configuration.

Common Use Cases

• Config file editors - Embedding a YAML editor for docker-compose, GitHub Actions, or Kubernetes manifests in a web-based IDE or admin tool.
• Markdown editors with frontmatter - Using yamlFrontmatter to give a Markdown-based CMS or note-taking app correct highlighting for the YAML metadata block at the top of a document.
• In-browser YAML linting/preview tools - Powering a YAML playground or validator that needs accurate parsing, folding, and indentation.
• Static site generator dashboards - Editing YAML data files (e.g. Jekyll/Hugo data/config files) directly in a browser-based content tool.

Under The Hood

Architecture

The package is a thin, single-module wrapper (src/yaml.ts) around a Lezer-generated YAML parser, following the same shape as every other @codemirror/lang-* package: a compiled grammar supplies the parse tree, and the JS layer only attaches CodeMirror-specific behavior. It configures the imported Lezer YAML parser with an indentNodeProp that walks up the syntax tree from the cursor to compute indentation for BlockLiteral, BlockSequence, BlockMapping, and QuotedLiteral/Literal nodes, and a foldNodeProp for FlowMapping/FlowSequence and per-item folding of Item/Pair/BlockLiteral nodes. A second, independent language (frontmatterLanguage) is built from a hand-written Lezer grammar (src/frontmatter.grammar) that recognizes triple-dash delimiter lines, and yamlFrontmatter() composes it with any content language via Lezer’s parseMixed, dispatching FrontmatterContent to the YAML parser and Body to the wrapped language’s parser. There is little that could “break” architecturally since the design surface is two small, declarative language definitions rather than layered application logic.

Tech Stack

Written in TypeScript and built with @codemirror/buildhelper (a shared Rollup-based build tool used across the CodeMirror monorepo family), the package depends directly on @codemirror/autocomplete, @codemirror/language, @codemirror/state, and the @lezer/* parser runtime and highlighting packages. The frontmatter grammar is authored in Lezer’s own grammar DSL (frontmatter.grammar) and compiled to a parser table as part of the build, rather than hand-written token logic. No test runner, bundler config, or application framework ships in the published package itself; distribution is ESM/CJS dual output (dist/index.js and dist/index.cjs) with generated type declarations.

Code Quality

No test files or test directory are present in the repository, so there is no visible automated test coverage for the indentation, folding, or frontmatter-mixing logic. The code is fully typed TypeScript with consistent naming and API shape matching the rest of the @codemirror/lang-* family, and public exports carry /// doc comments that are extracted into the published README’s API reference. Error handling is minimal because the surface area is declarative configuration rather than runtime logic with failure modes; there’s no linter or CI configuration checked into this specific repo.

API Design The public API is extremely small and low-boilerplate: import yaml and call it inside an extensions array to get full YAML support, matching the zero-config convention shared by every @codemirror/lang-* package. Advanced consumers can reach yamlLanguage directly to extend language data or highlighting. The yamlFrontmatter(config) helper is a genuinely reusable composition primitive — it lets any other CodeMirror language be wrapped with optional YAML frontmatter in one call, which is more distinctive than the plain single-language wrappers most sibling lang-* packages provide.