Markdown, Emmet, and Mermaid
Purpose and Scope
Markdown authoring in VS Code combines a writing workflow, editor-language services, preview customization, and syntax-aware rendering. This page orients contributors and advanced users to the parts visible in the supplied source evidence: general editor language support, bracket handling, inplace value replacement, and Copilot panel grammars for Markdown, LaTeX math, and related languages. The user-facing documentation describes Markdown editing features such as document outline, header navigation, path completions, snippets, and preview extension points, while the repository snippets here show lower-level contracts that make language-aware editing and highlighting possible. Sources: src/vs/editor/common/languages/supports/inplaceReplaceSupport.ts, src/vs/editor/common/languages/supports/languageBracketsConfiguration.ts
Emmet fits into this same authoring story as a built-in expansion experience for markup and stylesheet-like languages. Official VS Code documentation describes Emmet abbreviation expansion, suggestion preview, optional Tab expansion, and settings such as emmet.triggerExpansionOnTab and emmet.showExpandedAbbreviation. The requested source evidence does not expose the bundled Emmet extension internals; instead, it shows the editor services that language features depend on once text is in the editor. For readers, the practical distinction is that Emmet generates structured markup quickly, while Markdown services and preview extensions help navigate, render, and enrich the document after it exists. Sources: src/vs/editor/common/languages/supports/inplaceReplaceSupport.ts, src/vs/editor/common/languages/supports/languageBracketsConfiguration.ts
Relevant Source Files
- src/vs/editor/common/languages/supports/inplaceReplaceSupport.ts — Defines BasicInplaceReplace, a shared editor helper that navigates numeric values and common textual value sets such as true/false and visibility keywords.
- src/vs/editor/common/languages/supports/languageBracketsConfiguration.ts — Builds immutable opening and closing bracket metadata from a language configuration, including colorized bracket-pair handling and bracket regular-expression generation.
- extensions/copilot/src/extension/completions-core/vscode-node/extension/src/panelShared/languages/index.ts — Re-exports panel language grammars, including Markdown plus LaTeX and Markdown math grammars used by Copilot completion panel rendering.
- extensions/copilot/src/extension/completions-core/vscode-node/extension/src/panelShared/languages/javaScriptReact.tmLanguage.ts — Provides JSX/JavaScript React grammar coverage used beside Markdown-like panel content when examples or code blocks are rendered.
- extensions/copilot/src/extension/completions-core/vscode-node/extension/src/panelShared/languages/markdown-latex-combined.tmLanguage.ts — Represents the combined Markdown and LaTeX grammar entry point for panel content that mixes prose and math.
- extensions/copilot/src/extension/completions-core/vscode-node/extension/src/panelShared/languages/md-math.tmLanguage.ts — Defines the markdown-math LanguageInput and TextMate-style patterns for TeX comments, functions, constants, brackets, numbers, and operators.
System-to-Code Mapping
The editor-level files are intentionally language-neutral. BasicInplaceReplace accepts two candidate ranges and text values, tries the first candidate, then tries the second, and returns a replacement range plus value when navigation succeeds. Its numeric path preserves decimal precision by deriving a power-of-ten scale from the current text, refusing to decrement zero into a negative value, and returning null when the text is not a clean number. Its textual path cycles through predefined sets, including lowercase and title-case booleans and common access modifiers. Sources: src/vs/editor/common/languages/supports/inplaceReplaceSupport.ts
LanguageBracketsConfiguration turns a LanguageConfiguration into fast lookup structures for editing features that need bracket knowledge. It filters configured bracket pairs, caches opening and closing bracket kind objects, associates each opener with possible closers, and applies colorized bracket-pair rules. When colorized pairs are not explicitly configured, it uses configured brackets except the angle-bracket pair, because many languages use angle brackets as comparison operators or type syntax. Markdown, embedded HTML, code fences, JSX examples, Mermaid blocks, and math expressions can all benefit from accurate bracket identity when rendered or edited through shared editor infrastructure. Sources: src/vs/editor/common/languages/supports/languageBracketsConfiguration.ts
The Copilot panel language registry shows a second layer of support: syntax highlighting for rendered or previewed content inside a panel. Its index file exports named grammars including javascriptreact, markdownLatexCombined, and markdownMath. That means Markdown-like AI output can be displayed with a grammar that understands ordinary Markdown plus math-oriented regions, while adjacent code examples can use language-specific grammars. This is not the Markdown preview engine itself; it is a panel rendering vocabulary that helps completions and chat-style output remain readable. Sources: extensions/copilot/src/extension/completions-core/vscode-node/extension/src/panelShared/languages/index.ts, extensions/copilot/src/extension/completions-core/vscode-node/extension/src/panelShared/languages/javaScriptReact.tmLanguage.ts, extensions/copilot/src/extension/completions-core/vscode-node/extension/src/panelShared/languages/markdown-latex-combined.tmLanguage.ts
Markdown Preview, Math, and Mermaid Concepts
VS Code's Markdown documentation frames the core workflow around writing and reviewing documents: use the Outline view to inspect the header hierarchy, use symbol navigation to jump to headings in a file or workspace, request snippets while editing, and rely on path completions for links and images. Extension authors can also influence the preview by contributing stylesheets with markdown.previewStyles or by returning an extendMarkdownIt function when a markdown-it plugin is contributed. That preview extension model is where new Markdown syntax and presentation features belong, including diagram-oriented formats such as Mermaid when they are implemented as Markdown preview capabilities.
Math support in the supplied source evidence is most concrete in md-math.tmLanguage.ts. The exported markdownMath LanguageInput has the name markdown-math and the scope text.html.markdown.math. Its repository includes a math pattern collection that recognizes TeX-style line comments, line separators, function calls with braced arguments, constants beginning with backslash, curly and round brackets, numeric constants, and common math operators. These patterns are important because Markdown documents often mix prose with equations; highlighting must identify math tokens without treating the whole document as a programming language. Sources: extensions/copilot/src/extension/completions-core/vscode-node/extension/src/panelShared/languages/md-math.tmLanguage.ts
Mermaid should be understood as diagram syntax that normally lives inside Markdown documents and is rendered by the preview surface rather than by generic editor bracket or inplace-replace code. In practice, authors write fenced diagram blocks near prose, headings, lists, code examples, and math. The source paths here show the reusable layers around that experience: editor language configuration handles pairs and text navigation, preview extension points can add syntax or presentation, and panel grammars can color Markdown-adjacent content shown by AI features. Keeping those layers separate helps contributors avoid placing rendering-specific behavior into low-level editor services.
API Components and Source-Level Contracts
| Component | Public shape visible in source | Behavior to rely on |
|---|---|---|
| BasicInplaceReplace.INSTANCE | Static singleton | Shared inplace replacement provider for numeric and textual navigation. |
| navigateValueSet(range1, text1, range2, text2, up) | Method returning IInplaceReplaceSupportResult or null | Tries the primary range/text first, then a secondary range/text, and reports the exact range to replace. |
| LanguageBracketsConfiguration | Immutable class constructed with languageId and LanguageConfiguration | Produces bracket lookup metadata from bracketPairs and colorizedBracketPairs. |
| getOpeningBracketInfo, getClosingBracketInfo, getBracketInfo | Lookup methods | Resolve known bracket text to opening, closing, or either bracket metadata. |
| getBracketRegExp(options) | Method returning RegExp | Builds a regular expression over all configured opening and closing bracket strings. |
| markdownMath | LanguageInput export | Supplies markdown-math grammar patterns for math highlighting in panel content. |
| markdownLatexCombined | Re-exported grammar | Represents combined Markdown and LaTeX coverage for mixed prose and equation content. |
Authoring Flow
A practical Markdown authoring flow starts with the document structure. Create headings that reflect the intended outline, use the Outline view or symbol navigation to move through that hierarchy, and insert images, links, and code fences with snippets or completions. When the document includes generated markup, Emmet abbreviations can speed up HTML-like fragments before they are embedded in Markdown. When the document includes equations, the math grammar evidence shows why TeX-like commands, braces, constants, and operators need distinct scopes so the rendered panel or preview can remain legible. Sources: extensions/copilot/src/extension/completions-core/vscode-node/extension/src/panelShared/languages/md-math.tmLanguage.ts
For contributors, the main implementation guideline is to preserve boundaries between editing primitives, language grammars, and preview behavior. Bracket handling belongs in language configuration because many features need the same opener/closer model. Inplace replacement belongs in shared editor support because it works across many languages and file types. Markdown preview styling and markdown-it plugins belong at the extension contribution layer described by the official API documentation. Panel-specific grammars belong near the panel renderer so AI completions and code explanations can display mixed Markdown, LaTeX, JSX, and search-result content consistently. Sources: src/vs/editor/common/languages/supports/inplaceReplaceSupport.ts, src/vs/editor/common/languages/supports/languageBracketsConfiguration.ts, extensions/copilot/src/extension/completions-core/vscode-node/extension/src/panelShared/languages/index.ts
Next Steps
If you are using VS Code, start with Markdown editing basics: outline navigation, snippets, path completions, preview, and Emmet expansion settings. If you are extending Markdown, use preview styles for presentation changes and markdown-it plugins for new syntax. If you are contributing to Code - OSS, inspect whether the behavior belongs in a bundled extension, a preview contribution, a grammar, or shared editor infrastructure before changing it. For adjacent documentation, continue with Snippets, Basic Editing, IntelliSense and Code Navigation, and Extension Authoring Overview.