@tanstack/markdown/skills/docs-features/SKILL.md

A tiny, fast, deterministic Markdown renderer for blogs and documentation.

---
name: 'docs-features'
description: >
  Build documentation metadata with docsMarkdownExtensions, GitHub-style
  callouts, heading collection, comment components, heading/file/package-
  manager/bundler tabs, framework panels, and code-fence metadata. Load when
  authoring or consuming TanStack-style docs syntax and custom-element data
  contracts.
metadata:
  type: core
  library: '@tanstack/markdown'
  library_version: '0.0.13'
requires:
  - 'render-markdown'
sources:
  - 'TanStack/markdown:docs/guides/docs-preset.md'
  - 'TanStack/markdown:docs/reference/extensions.md'
  - 'TanStack/markdown:src/extensions/docs.ts'
  - 'TanStack/markdown:src/extensions/tabs.ts'
  - 'TanStack/markdown:src/extensions/framework.ts'
  - 'TanStack/markdown:src/extensions/headings.ts'
  - 'TanStack/markdown:src/extensions/comment-components.ts'
---

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 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)