docs-features

This skill builds on [render-markdown](../render-markdown/SKILL.md). Read it first for parser options, AST reuse, rendering, and core trust boundaries. # Docs Features ## Setup Create one extension array and use it for parsing and rendering: ```ts import { renderHtml } from '@tanstack/markdown/html' import { parseMarkdown } from '@tanstack/markdown/parser' import { docsMarkdownExtensions } from '@tanstack/markdown/extensions/docs' const source = `# Deployment > [!TIP] Parse once > Reuse the document for every renderer. ## Install Run the package-manager command for your application.` const extensions = docsMarkdownExtensions() const document = parseMarkdown(source, { extensions }) export const headings = document.headings export const html = renderHtml(document, { extensions, headingAnchors: true, }) ``` The preset composes callouts, transformed comment components, and heading collection. It emits metadata and custom elements; it does not install documentation UI behavior. ## Core Patterns ### Collect headings without selector headings ```ts import { parseMarkdown } from '@tanstack/markdown/parser' import { docsMarkdownExtensions } from '@tanstack/markdown/extensions/docs' const source = `# Guide <!-- ::start:tabs --> ## React React setup ## Solid Solid setup <!-- ::end:tabs --> ## API` const extensions = docsMarkdownExtensions() export const document = parseMarkdown(source, { extensions }) export const headings = document.headings ``` Heading collection defaults to skipping every heading inside a component named `tabs`. Pass `docsMarkdownExtensions({ collectHeadings: false })` to disable collection or an options object with `skipComponentNames` to replace the default skip set. ### Author each tab input shape Heading tabs split at the shallowest heading: ```md <!-- ::start:tabs --> ## React React setup ## Solid Solid setup <!-- ::end:tabs --> ``` File tabs select fenced code blocks and use `title=` or `file=` as labels: ````md <!-- ::start:tabs variant="files" --> ```tsx file="app.tsx" export function App() { return <main>Docs</main> } ``` ```css file="app.css" main { display: block; } ``` <!-- ::end:tabs --> ```` Package-manager tabs consume `framework: package...` lines and shared `package...` lines, then remove their source children after creating metadata: ```md <!-- ::start:tabs variant="package-manager" mode="dev-install" --> react: @tanstack/react-query @tanstack/react-router solid: @tanstack/solid-query @tanstack/solid-router <!-- ::end:tabs --> ``` Bundler tabs accept only Vite and Rsbuild heading sections: ````md <!-- ::start:tabs variant="bundler" --> ## Vite ```ts export default { plugins: [] } ``` ## Rsbuild ```ts export default { plugins: [] } ``` <!-- ::end:tabs --> ```` Every transform returns the original component unchanged when its required structure is absent. See [docs metadata contracts](references/docs-metadata.md) for exact properties and fallback rules. ### Build framework-specific panels ```md <!-- ::start:framework --> # React ## Install ```tsx title="react.tsx" export const framework = 'react' ``` # Solid ## Install ```tsx title="solid.tsx" export const framework = 'solid' ``` <!-- ::end:framework --> ``` Framework blocks require level-one selector headings. They emit `md-framework-panel` children, lowercase framework names, label nested headings, and expose code-block metadata by framework. ### Read component metadata before rendering ```ts import type { ComponentNode } from '@tanstack/markdown' import { parseMarkdown } from '@tanstack/markdown/parser' import { docsMarkdownExtensions } from '@tanstack/markdown/extensions/docs' interface TabDescriptor { slug: string name: string } function isTabsNode(node: unknown): node is ComponentNode { return ( typeof node === 'object' && node !== null && 'type' in node && node.type === 'component' && 'name' in node && node.name === 'tabs' ) } const source = `<!-- ::start:tabs --> ## React React content ## Solid Solid content <!-- ::end:tabs -->` const document = parseMarkdown(source, { extensions: docsMarkdownExtensions(), }) const tabsNode = document.children.find(isTabsNode) const metadata = tabsNode?.properties?.['data-attributes'] export const tabs: TabDescriptor[] = metadata ? (JSON.parse(metadata) as { tabs: TabDescriptor[] }).tabs : [] ``` `ComponentNode.properties` holds strings. JSON-bearing values are serialized into escaped HTML attributes by the HTML renderer and must be parsed by the consuming application. ## Common Mistakes ### HIGH Assuming transformed tabs are interactive Wrong: ```ts import { renderHtml } from '@tanstack/markdown/html' import { docsMarkdownExtensions } from '@tanstack/markdown/extensions/docs' const source = `<!-- ::start:tabs --> ## React React content <!-- ::end:tabs -->` export const interactiveTabs = renderHtml(source, { extensions: docsMarkdownExtensions(), }) ``` Correct: ```ts import type { ComponentNode } from '@tanstack/markdown' import { parseMarkdown } from '@tanstack/markdown/parser' import { docsMarkdownExtensions } from '@tanstack/markdown/extensions/docs' const source = `<!-- ::start:tabs --> ## React React content <!-- ::end:tabs -->` const document = parseMarkdown(source, { extensions: docsMarkdownExtensions(), }) const tabsNode = document.children.find( (node): node is ComponentNode => node.type === 'component' && node.name === 'tabs', ) export const tabPanels = tabsNode?.children.filter( (node): node is ComponentNode => node.type === 'component' && node.tagName === 'md-tab-panel', ) ?? [] ``` The transform supplies a model and custom-element names; the site must bind those values to its own state, controls, and renderer components. Source: `docs/guides/docs-preset.md` ### HIGH Leaving a component block unmatched Wrong: ```ts import { parseMarkdown } from '@tanstack/markdown/parser' import { docsMarkdownExtensions } from '@tanstack/markdown/extensions/docs' const source = `<!-- ::start:tabs --> ## React React content` export const document = parseMarkdown(source, { extensions: docsMarkdownExtensions(), }) ``` Correct: ```ts import { parseMarkdown } from '@tanstack/markdown/parser' import { docsMarkdownExtensions } from '@tanstack/markdown/extensions/docs' const source = `<!-- ::start:tabs --> ## React React content <!-- ::end:tabs -->` export const document = parseMarkdown(source, { extensions: docsMarkdownExtensions(), }) ``` An unmatched start is consumed as an empty component, while the following body remains ordinary Markdown. Source: `src/extensions/comment-components.ts:41-63` ### MEDIUM Passing the wrong tab content shape Wrong: ```ts import { parseMarkdown } from '@tanstack/markdown/parser' import { docsMarkdownExtensions } from '@tanstack/markdown/extensions/docs' const source = `<!-- ::start:tabs variant="files" --> This variant does not turn prose into a file. <!-- ::end:tabs -->` export const document = parseMarkdown(source, { extensions: docsMarkdownExtensions(), }) ``` Correct: ````ts import { parseMarkdown } from '@tanstack/markdown/parser' import { docsMarkdownExtensions } from '@tanstack/markdown/extensions/docs' const source = `<!-- ::start:tabs variant="files" --> \`\`\`ts file="app.ts" export const app = true \`\`\` <!-- ::end:tabs -->` export const document = parseMarkdown(source, { extensions: docsMarkdownExtensions(), }) ```` The file transform silently returns the original component when it finds no direct code-block children; the other variants have similarly specific input contracts. Source: `src/extensions/tabs.ts:16-18` ### MEDIUM Expecting fence metadata to highlight code Wrong: ````ts import { renderHtml } from '@tanstack/markdown/html' const source = `\`\`\`ts file="app.ts" {2} const one = 1 const two = 2 \`\`\`` export const html = renderHtml(source) ```` Correct: ````ts import { createHighlighter } from '@tanstack/highlight/core' import { plaintext } from '@tanstack/highlight/languages/plaintext' import { ts } from '@tanstack/highlight/languages/ts' import { createTanStackMarkdownHighlighter } from '@tanstack/highlight/markdown' import { renderHtml } from '@tanstack/markdown/html' const source = `\`\`\`ts file="app.ts" {2} const one = 1 const two = 2 \`\`\`` const highlighter = createHighlighter({ languages: [plaintext, ts], }) export const html = renderHtml(source, { highlighter: createTanStackMarkdownHighlighter(highlighter), }) ```` Fence metadata populates the AST and highlighter options, but tokenization, themes, and CSS stay outside this package. Source: `docs/core-concepts/syntax-profile.md` ## Boundaries - Docs transforms enrich trusted repository-authored content but do not execute MDX, JSX, or JavaScript expressions. - Highlighter output is trusted HTML. Keep highlighting at build time or on the server and apply the checks in [production-pipelines](../production-pipelines/SKILL.md). - Import individual extension entry points when the complete preset adds unused behavior or bundle cost. - Use [custom-extensions](../custom-extensions/SKILL.md) when built-in comment components or transforms do not express the required deterministic syntax. - Use the React or Octane renderer skill to map emitted tags such as `md-tab-panel` and `md-framework-panel` to framework components. ## References - [Docs metadata contracts](references/docs-metadata.md)