Terminal
Terminal/Skill
Checklist for shipping a Markdown pipeline for blogs, docs, or user content, covering trust boundaries, highlighting, caching, and bundle size.
By TanStack
Works with
npx skills add tanstack/markdown --skill production-pipelinesThis skill builds on render-markdown. Read it first for the supported syntax, AST, parser options, and renderer contracts.
Run every section before deploying a blog, documentation site, or user-content renderer.
Expected:
import { renderHtml } from '@tanstack/markdown/html'
export function renderUntrustedMarkdown(
source: string,
sanitize: (html: string) => string,
): string {
const rendered = renderHtml(source)
return sanitize(rendered)
}
Fail condition: Untrusted input reaches allowHtml, an unaudited extension renderHtml hook, or an unaudited highlighter.
Fix: Separate trusted and untrusted entry points, keep trusted callbacks disabled for untrusted content, and enforce application link, image, and final-HTML policy.
Expected:
import { renderHtml } from '@tanstack/markdown/html'
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'
const highlighter = createHighlighter({ languages: [plaintext, ts] })
export const html = renderHtml('```ts {1}\nconst answer = 42\n```', {
highlighter: createTanStackMarkdownHighlighter(highlighter),
})
Fail condition: The callback returns a complete <pre><code> tree, does not escape source code, or comes from an unreviewed transform.
Fix: Return only escaped markup for the renderer-owned <code> contents, and run highlighting during ingestion, build, or server rendering.
Expected:
MARKDOWN_CORPUS_DIRS=../site/src/blog:../site/docs pnpm run test:corpus
pnpm run corpus:audit:tanstack
pnpm run corpus:audit:external
Fail condition: Adoption relies only on CommonMark examples or a comparison table instead of the site's Markdown.
Fix: Add downstream content directories, preserve practical regressions with focused fixtures, and require renderer and bundle accounting for new syntax.
Expected:
import { renderHtml } from '@tanstack/markdown/html'
import { parseMarkdown } from '@tanstack/markdown/parser'
const source = '# Deterministic\n\n- one\n- two'
const firstDocument = JSON.stringify(parseMarkdown(source))
const secondDocument = JSON.stringify(parseMarkdown(source))
const firstHtml = renderHtml(source)
const secondHtml = renderHtml(source)
if (firstDocument !== secondDocument || firstHtml !== secondHtml) {
throw new Error('Markdown output is nondeterministic')
}
Fail condition: Identical source and options produce different serialized AST or HTML.
Fix: Remove time, randomness, environment state, and unstable ordering from extensions and render callbacks.
Expected:
import type { MarkdownDocument } from '@tanstack/markdown'
import { renderHtml } from '@tanstack/markdown/html'
import { parseMarkdown } from '@tanstack/markdown/parser'
const cache = new Map<string, MarkdownDocument>()
export function renderCachedArticle(key: string, source: string): string {
const cacheKey = `markdown-0.0.13:${key}`
let document = cache.get(cacheKey)
if (!document) {
document = parseMarkdown(source, {
frontmatter: true,
headingIds: true,
})
cache.set(cacheKey, document)
}
return renderHtml(document)
}
Fail condition: Stable content is reparsed per request, or parser options/extensions change after the AST is cached.
Fix: Build the AST with final parse options, version persisted cache keys, invalidate stored ASTs when node contracts change, and use only narrow entry points.
Expected:
pnpm run size
pnpm test -- tests/bundle-size.test.ts
Fail condition: Any measured entry exceeds its checked gzip budget or starts bundling a highlighter.
Fix: Inspect the bundle diff and justify any syntax or dependency cost before adjusting a budget.
Expected:
pnpm run verify
Fail condition: Tests, typechecking, build, docs validation, conformance accounting, sizes, benchmarks, or the npm dry run fail.
Fix: Resolve every gate before publishing, including HTML/React/Octane parity; audit raw HTML, highlighter output, HTML hooks, and component replacements separately.
Wrong:
import { renderHtml } from '@tanstack/markdown/html'
export function renderComment(source: string): string {
return renderHtml(source, { allowHtml: true })
}
Correct:
import { renderHtml } from '@tanstack/markdown/html'
export function renderComment(source: string): string {
return renderHtml(source)
}
allowHtml emits raw nodes and is not a sanitization step.
Source: docs/core-concepts/security.md
Wrong:
import { renderHtml } from '@tanstack/markdown/html'
function escapeCode(code: string): string {
return code.replace(/[&<>]/g, (character) => ({
'&': '&',
'<': '<',
'>': '>',
})[character] ?? character)
}
console.log(renderHtml('```ts\nconst x = 1\n```', {
highlighter: (code) => `<pre><code>${escapeCode(code)}</code></pre>`,
}))
Correct:
import { renderHtml } from '@tanstack/markdown/html'
function escapeCode(code: string): string {
return code.replace(/[&<>]/g, (character) => ({
'&': '&',
'<': '<',
'>': '>',
})[character] ?? character)
}
console.log(renderHtml('```ts\nconst x = 1\n```', {
highlighter: (code) => `<span class="token">${escapeCode(code)}</span>`,
}))
The renderer owns <pre><code>; the callback supplies only the code element's trusted contents.
Source: docs/guides/syntax-highlighting.md
Wrong:
import { renderHtml } from '@tanstack/markdown/html'
const source = '```html\n<img src=x onerror=alert(1)>\n```'
console.log(renderHtml(source, { highlighter: (code) => code }))
Correct:
import { renderHtml } from '@tanstack/markdown/html'
function escapeCode(code: string): string {
return code.replace(/[&<>]/g, (character) => ({
'&': '&',
'<': '<',
'>': '>',
})[character] ?? character)
}
const source = '```html\n<img src=x onerror=alert(1)>\n```'
console.log(renderHtml(source, { highlighter: escapeCode }))
Highlighter output is inserted without further escaping in every renderer.
Source: docs/core-concepts/security.md
Wrong:
import { Markdown } from '@tanstack/markdown/react'
import { tokenize } from '@tanstack/highlight'
export function Article({ source }: { source: string }) {
return <Markdown highlighter={(code) => String(tokenize(code))}>{source}</Markdown>
}
Correct:
import { renderHtml } from '@tanstack/markdown/html'
import type { CodeHighlighter } from '@tanstack/markdown'
export function renderStaticArticle(
source: string,
highlighter: CodeHighlighter,
): string {
return renderHtml(source, { highlighter })
}
Tokenizer runtimes, grammars, and themes can outweigh Markdown parsing and should remain build-time or server-side for static content.
Source: docs/guides/performance.md
Wrong:
import { renderHtml } from '@tanstack/markdown/html'
export function renderForEveryPolicy(source: string): string {
return renderHtml(source)
}
Correct:
import { renderHtml } from '@tanstack/markdown/html'
export function renderWithPolicy(
source: string,
sanitize: (html: string) => string,
): string {
return sanitize(renderHtml(source))
}
Core escaping and protocol filtering do not enforce application-specific outbound-link, image, or final-HTML policy.
Source: docs/core-concepts/security.md
Wrong:
import { renderHtml } from '@tanstack/markdown/html'
export function renderArbitraryMarkdown(source: string): string {
return renderHtml(source)
}
Correct:
import { renderHtml } from '@tanstack/markdown/html'
export function renderControlledDocs(source: string): string {
return renderHtml(source)
}
The package implements a documented docs/blog profile, not complete CommonMark, GFM, MDX, or arbitrary plugin behavior.
Source: docs/core-concepts/syntax-profile.md
Wrong:
import { renderHtml } from '@tanstack/markdown/html'
export function renderRequest(source: string): string {
return renderHtml(source)
}
Correct:
import type { MarkdownDocument } from '@tanstack/markdown'
import { renderHtml } from '@tanstack/markdown/html'
import { parseMarkdown } from '@tanstack/markdown/parser'
export function compile(source: string): MarkdownDocument {
return parseMarkdown(source)
}
export function renderRequest(document: MarkdownDocument): string {
return renderHtml(document)
}
String render inputs parse the complete document, while a cached MarkdownDocument skips that work.
Source: docs/core-concepts/document-model.md
Wrong:
import { renderHtml } from '@tanstack/markdown/html'
export function Article({ source }: { source: string }) {
const html = renderHtml(source)
return <article dangerouslySetInnerHTML={{ __html: html }} />
}
Correct:
import { Markdown } from '@tanstack/markdown/react'
export function Article({ source }: { source: string }) {
return <article><Markdown>{source}</Markdown></article>
}
The HTML string adds a trusted insertion boundary and bypasses React component replacement.
Source: docs/guides/react.md
Wrong:
import { renderHtml } from '@tanstack/markdown/html'
const source = '```ts {1}\nconst answer = 42\n```'
console.log(renderHtml(source))
Correct:
import { renderHtml } from '@tanstack/markdown/html'
function escapeCode(code: string): string {
return code.replace(/[&<>]/g, (character) => ({
'&': '&',
'<': '<',
'>': '>',
})[character] ?? character)
}
const source = '```ts {1}\nconst answer = 42\n```'
console.log(renderHtml(source, { highlighter: escapeCode }))
Fence metadata enters the AST, but token markup requires an external highlighter.
Source: docs/core-concepts/syntax-profile.md
Do not maximize conformance by default. Require target-corpus evidence, renderer coverage, and measured bundle cost before adding syntax.
Do not enable raw HTML, extension HTML, or highlighter markup globally to solve presentation needs. Scope each trusted callback to controlled content.
Build cached ASTs with final parser options and document transforms. Keep required HTML render hooks active when rendering those cached documents.
pnpm run verify passes before release.render-markdown for the supported profile, AST, parser options, and core HTML rendering.docs-features for docs metadata and code-fence behavior.custom-extensions for parser hooks and trusted HTML extension boundaries.react-rendering and octane-rendering for framework component policy and SSR parity.