@tanstack/markdown

# Docs Metadata Contracts All `ComponentNode.properties` values are strings. Values described as JSON are produced with `JSON.stringify`. HTML rendering escapes them as attribute values; DOM `dataset` access returns the decoded string. ## Preset Composition ```ts interface DocsMarkdownOptions { collectHeadings?: boolean | HeadingCollectionOptions } interface HeadingCollectionOptions { skipComponentNames?: ReadonlySet<string> | string[] } ``` `docsMarkdownExtensions()` returns these extensions in order: 1. `calloutsExtension()` 2. `commentComponentsExtension({ transformComponent: transformDocsComponent })` 3. `headingCollectionExtension()` unless `collectHeadings` is `false` An object passed as `collectHeadings` configures heading collection. `true` or an omitted value uses defaults. ## Comment Components Single form: ```md  ``` Block form: ```md  Component body  ``` Names become lowercase. Attribute names preserve their parsed spelling, and every value is a string. Supported values are double-quoted, single-quoted, unquoted, or valueless; a valueless attribute becomes `"true"`. The initial AST shape is: ```ts interface CommentComponentShape { type: 'component' name: string attributes: Record<string, string> children: BlockNode[] } ``` Without a transform-provided `tagName`, HTML uses `md-comment-component`, adds `data-component="<name>"`, and adds `data-attributes="<JSON attributes>"` unless a transform already supplied `data-attributes`. An unmatched block start produces an empty component and consumes only the start line. Its apparent body is parsed normally outside the component. ## Callouts Input: ```md > [!WARNING] Deployment warning > Back up the database first. ``` `KIND` accepts letters only and becomes lowercase. An omitted title becomes title-cased from the kind. The AST contract is: ```ts interface CalloutNode { type: 'callout' kind: string title: string children: BlockNode[] } ``` HTML uses: ```html <div class="markdown-alert markdown-alert-warning"><p class="markdown-alert-title">Deployment warning</p><div class="markdown-alert-content"><p>Back up the database first.</p></div></div> ``` ## Heading Collection The document property is: ```ts interface MarkdownHeading { id: string text: string level: number framework?: string } ``` Only headings with generated IDs are collected. Traversal includes lists, blockquotes, callouts, and components. By default, any subtree inside a component whose `name` is `tabs` is skipped. Passing `skipComponentNames` replaces the default set; include `'tabs'` explicitly when adding more names: ```ts import { docsMarkdownExtensions } from '@tanstack/markdown/extensions/docs' export const extensions = docsMarkdownExtensions({ collectHeadings: { skipComponentNames: ['tabs', 'example'], }, }) ``` Within an `md-framework-panel`, collected nested headings receive the panel's `data-framework` value. ## Tab Metadata ### Shared tab descriptors Heading, file, and bundler tabs set: ```ts interface TabsProperty { 'data-attributes': string } interface TabsMetadata { tabs: Array<{ slug: string name: string }> } ``` Each generated panel is: ```ts interface TabPanelShape { type: 'component' name: 'tab-panel' tagName: 'md-tab-panel' attributes: {} properties: { 'data-tab-slug': string 'data-tab-index': string 'data-content'?: 'code-only' | 'mixed' } children: BlockNode[] } ``` `data-tab-index` is a zero-based integer encoded as a string. ### Heading tabs Missing or unknown `variant` values dispatch to heading tabs. Sections split at the shallowest heading depth found among direct component children. The section heading is removed from panel children. Slugs use the heading ID when present. Otherwise they are lowercase ASCII slugs with non-alphanumeric characters removed, repeated whitespace converted to `-`, repeated hyphens collapsed, and length capped at 64 characters. The fallback is `tab-<one-based-index>`. No headings means the original component is returned. ### File tabs Only direct `code` children become files; other children are discarded when at least one code block exists. Tab descriptors use: ```ts { slug: `file-${zeroBasedIndex}`, name: code.title || code.file || 'Untitled', } ``` The root also sets: ```ts interface FilesMetadata { files: Array<{ title: string code: string language: string }> } interface FileTabsProperties { 'data-attributes': string 'data-files-meta': string } ``` `data-files-meta` is JSON-encoded `FilesMetadata`. `title` falls back through `code.title`, `code.file`, then `"Untitled"`; `language` falls back to `"plaintext"`. Every panel contains its original code node. No direct code children means the original component is returned. ### Package-manager tabs Accepted variants are `package-manager` and `package-managers`. Each nonempty source line uses: ```text framework: package-one package-two ``` Framework names become lowercase. Repeated framework lines append package arrays rather than merging them. The root sets: ```ts interface PackageManagerMetadata { packagesByFramework: Record<string, string[][]> mode: 'install' | 'dev-install' | 'local-install' } interface PackageManagerProperties { 'data-package-manager-meta': string } ``` `data-package-manager-meta` is JSON-encoded `PackageManagerMetadata`. Only `dev-install` and `local-install` are preserved; an omitted, differently cased, or unknown mode resolves after lowercasing to `install`. Successful transformation replaces all children with an empty array and emits no `md-tab-panel` children. No valid `framework: packages` line means the original component is returned. ### Bundler tabs The only supported section names are `vite` and `rsbuild`, matched case-insensitively and emitted in that fixed order when present. Sections split at the shallowest direct heading depth. The root sets: ```ts interface BundlerMetadata { bundlers: Array<'vite' | 'rsbuild'> } interface BundlerTabsProperties { 'data-attributes': string 'data-bundler-meta': string } ``` `data-bundler-meta` is JSON-encoded `BundlerMetadata`. Each panel additionally sets `data-content` to `"code-only"` only when the section has exactly one child and that child is a code block; every other shape uses `"mixed"`. No supported section means the original component is returned. ## Framework Metadata Framework transforms split only on direct level-one headings. A valid root sets: ```ts interface FrameworkMetadata { codeBlocksByFramework: Record< string, Array<{ title: string code: string language: string }> > } interface FrameworkProperties { 'data-available-frameworks': string 'data-framework-meta': string } ``` `data-available-frameworks` is a JSON array of lowercase heading text in source order. `data-framework-meta` is JSON-encoded `FrameworkMetadata`. Only direct code children of each framework section enter `codeBlocksByFramework`; title defaults to `""` and language to `"plaintext"`. Each panel is: ```ts interface FrameworkPanelShape { type: 'component' name: 'framework-panel' tagName: 'md-framework-panel' attributes: {} properties: { 'data-framework': string } children: BlockNode[] } ``` The level-one selector heading is removed. Descendant headings deeper than level one receive the lowercase framework label, including headings nested through blockquotes, callouts, lists, and components. No direct level-one heading means the original component is returned. ## Code Fence Metadata Code metadata is parsed by the core parser, not by `docsMarkdownExtensions`. ````md ```tsx file="app.tsx" framework="React" {2,4-6} export function App() { return <main>Docs</main> } ``` ```` The code node fields are: ```ts interface CodeBlockNode { type: 'code' lang?: string meta?: string title?: string framework?: string file?: string value: string highlightLines?: number[] } ``` - The first language token accepts letters, digits, `_`, `+`, `.`, `#`, and `-`. - `meta` stores the trimmed text after the language. - The first `title=` or `file=` value sets both `title` and `file`. - `framework=` becomes lowercase. - `{2,4-6}` and `lines=2,4-6` produce sorted, unique positive line numbers. - Invalid ranges are ignored, and each individual range expands to at most 1,000 lines. HTML code blocks expose `data-lang`, `data-code-title`, `data-filename`, and `data-framework` when the corresponding values exist. Highlight lines are passed to a configured highlighter; metadata alone does not create token or line markup.