@tanstack/markdown 0.0.9 → 0.0.11

package/skills/react-rendering/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: 'react-rendering'
+description: >
+  Render Markdown source or a MarkdownDocument with @tanstack/markdown/react
+  using Markdown, renderMarkdownReact, component replacements, and React static
+  SSR. Load for React article components, emitted-tag mappings, pre-parsed
+  documents, custom elements, or renderer parity.
+metadata:
+  type: framework
+  library: '@tanstack/markdown'
+  framework: 'react'
+  library_version: '0.0.10'
+requires:
+  - 'render-markdown'
+sources:
+  - 'TanStack/markdown:docs/guides/react.md'
+  - 'TanStack/markdown:docs/reference/react.md'
+  - 'TanStack/markdown:docs/guides/extensions.md'
+  - 'TanStack/markdown:docs/core-concepts/security.md'
+  - 'TanStack/markdown:src/react.ts'
+  - 'TanStack/markdown:tests/ssr-react.test.tsx'
+---
+
+This skill builds on [render-markdown](../render-markdown/SKILL.md). Read it first for the syntax profile, parser options, AST, and core trust boundaries.
+
+# React Rendering
+
+## Setup
+
+Render source directly and keep the surrounding semantic element in the application:
+
+```tsx
+import { Markdown } from '@tanstack/markdown/react'
+
+export function Article({ source }: { source: string }) {
+  return (
+    <article>
+      <Markdown>{source}</Markdown>
+    </article>
+  )
+}
+```
+
+`Markdown` returns a React fragment. The React adapter requires React 18 or newer.
+
+## Hooks and Components
+
+### Replace emitted links with an application component
+
+```tsx
+import type { ComponentProps } from 'react'
+import { Markdown } from '@tanstack/markdown/react'
+
+function ArticleLink(props: ComponentProps<'a'>) {
+  const external = props.href?.startsWith('http') ?? false
+
+  return (
+    <a
+      {...props}
+      rel={external ? 'noreferrer' : props.rel}
+      target={external ? '_blank' : props.target}
+    />
+  )
+}
+
+export function Article({ source }: { source: string }) {
+  return (
+    <article>
+      <Markdown components={{ a: ArticleLink }}>{source}</Markdown>
+    </article>
+  )
+}
+```
+
+`components` is keyed by emitted intrinsic or custom-element tag names.
+
+### Parse once before repeated React rendering
+
+```tsx
+import { parseMarkdown } from '@tanstack/markdown/parser'
+import { Markdown } from '@tanstack/markdown/react'
+
+const document = parseMarkdown('# Cached article\n\nRendered from an AST.')
+
+export function Article() {
+  return (
+    <article>
+      <Markdown>{document}</Markdown>
+    </article>
+  )
+}
+```
+
+Apply parser options and document transforms when creating the document; renderer options cannot retroactively change its structure.
+
+### Render static React markup on the server
+
+```tsx
+import { renderToStaticMarkup } from 'react-dom/server'
+import { Markdown } from '@tanstack/markdown/react'
+
+const source = '# Server-rendered article'
+
+export const html = renderToStaticMarkup(
+  <article>
+    <Markdown>{source}</Markdown>
+  </article>,
+)
+```
+
+Core static output is tested for structural equivalence with `renderHtml()`.
+
+### Compose through the lower-level node API
+
+```tsx
+import type { ReactNode } from 'react'
+import { parseMarkdown } from '@tanstack/markdown/parser'
+import { renderMarkdownReact } from '@tanstack/markdown/react'
+
+const document = parseMarkdown('# Parsed once')
+
+export function ArticleBody(): ReactNode {
+  return renderMarkdownReact(document)
+}
+```
+
+Use `renderBlockReact` or `renderInlineReact` only when custom tree composition needs individual public AST nodes.
+
+## Common Mistakes
+
+### HIGH Injecting HTML instead of React nodes
+
+Wrong:
+
+```tsx
+import { renderHtml } from '@tanstack/markdown'
+
+export function Article({ source }: { source: string }) {
+  const html = renderHtml(source)
+  return <article dangerouslySetInnerHTML={{ __html: html }} />
+}
+```
+
+Correct:
+
+```tsx
+import { Markdown } from '@tanstack/markdown/react'
+
+export function Article({ source }: { source: string }) {
+  return (
+    <article>
+      <Markdown>{source}</Markdown>
+    </article>
+  )
+}
+```
+
+The HTML-string path bypasses React component replacement and creates an unnecessary trusted-HTML boundary.
+
+Source: `docs/guides/react.md`
+
+### HIGH Mapping AST node names instead of tags
+
+Wrong:
+
+```tsx
+import type { ComponentProps } from 'react'
+import { Markdown } from '@tanstack/markdown/react'
+
+function ArticleLink(props: ComponentProps<'a'>) {
+  return <a {...props} data-navigation="article" />
+}
+
+export function Article() {
+  return (
+    <Markdown components={{ link: ArticleLink }}>
+      {'Read the [guide](/guide).'}
+    </Markdown>
+  )
+}
+```
+
+Correct:
+
+```tsx
+import type { ComponentProps } from 'react'
+import { Markdown } from '@tanstack/markdown/react'
+
+function ArticleLink(props: ComponentProps<'a'>) {
+  return <a {...props} data-navigation="article" />
+}
+
+export function Article() {
+  return (
+    <Markdown components={{ a: ArticleLink }}>
+      {'Read the [guide](/guide).'}
+    </Markdown>
+  )
+}
+```
+
+The map is keyed by emitted tag names such as `a`, not AST discriminants such as `link`.
+
+Source: `docs/guides/react.md`
+
+### HIGH Expecting HTML extension hooks in React
+
+Wrong:
+
+```tsx
+import type { MarkdownExtension } from '@tanstack/markdown'
+import { Markdown } from '@tanstack/markdown/react'
+
+const paragraphHtml: MarkdownExtension = {
+  name: 'paragraph-html',
+  renderHtml(node) {
+    return node.type === 'paragraph'
+      ? '<aside>Rendered only by the HTML renderer</aside>'
+      : undefined
+  },
+}
+
+export function Article() {
+  return <Markdown extensions={[paragraphHtml]}>Ordinary content</Markdown>
+}
+```
+
+Correct:
+
+```tsx
+import type { MarkdownExtension } from '@tanstack/markdown'
+import type { PropsWithChildren } from 'react'
+import { Markdown } from '@tanstack/markdown/react'
+
+const panelExtension: MarkdownExtension = {
+  name: 'panel',
+  transformDocument(document) {
+    return {
+      ...document,
+      children: [
+        {
+          type: 'component',
+          name: 'panel',
+          tagName: 'doc-panel',
+          attributes: {},
+          children: document.children,
+        },
+      ],
+    }
+  },
+}
+
+function Panel({ children }: PropsWithChildren) {
+  return <aside className="documentation-panel">{children}</aside>
+}
+
+export function Article() {
+  return (
+    <Markdown
+      components={{ 'doc-panel': Panel }}
+      extensions={[panelExtension]}
+    >
+      Ordinary content
+    </Markdown>
+  )
+}
+```
+
+`MarkdownExtension.renderHtml` is HTML-specific; portable custom output uses `ComponentNode` and an emitted-tag component mapping.
+
+Source: `docs/guides/extensions.md`
+
+### CRITICAL Enabling raw HTML for untrusted input
+
+Wrong:
+
+```tsx
+import { Markdown } from '@tanstack/markdown/react'
+
+export function UserPost({ source }: { source: string }) {
+  return <Markdown allowHtml>{source}</Markdown>
+}
+```
+
+Correct:
+
+```tsx
+import { Markdown } from '@tanstack/markdown/react'
+
+export function UserPost({ source }: { source: string }) {
+  return <Markdown>{source}</Markdown>
+}
+```
+
+With `allowHtml`, React uses `dangerouslySetInnerHTML`; TanStack Markdown does not sanitize that raw HTML.
+
+Source: `docs/core-concepts/security.md`
+
+### HIGH Tension: renderer parity versus React customization
+
+Core React SSR is tested against `renderHtml()`. React component replacements, raw HTML, highlighter output, and HTML-only extension hooks are application-controlled boundaries outside that parity guarantee.
+
+See also: [custom-extensions](../custom-extensions/SKILL.md) for portable `ComponentNode` output.
+
+## Cross-References
+
+- [render-markdown](../render-markdown/SKILL.md) - shared `MarkdownInput`, parser options, AST behavior, and syntax profile.
+- [custom-extensions](../custom-extensions/SKILL.md) - emit custom tags that React can replace through `components`.
+- [production-pipelines](../production-pipelines/SKILL.md) - audit raw HTML, highlighter output, untrusted content, and SSR boundaries.

package/skills/render-markdown/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: render-markdown
+description: >
+  Parse Markdown with parseMarkdown or parseInline, render HTML with renderHtml,
+  renderDocument, renderBlock, or renderInline, configure frontmatter and
+  heading IDs, and reuse the serializable MarkdownDocument AST. Load for
+  @tanstack/markdown core syntax, parser options, HTML output, references,
+  footnotes, lists, tables, or AST work.
+metadata:
+  type: core
+  library: '@tanstack/markdown'
+  library_version: '0.0.10'
+sources:
+  - 'TanStack/markdown:docs/quick-start.md'
+  - 'TanStack/markdown:docs/core-concepts/document-model.md'
+  - 'TanStack/markdown:docs/core-concepts/parsing.md'
+  - 'TanStack/markdown:docs/core-concepts/rendering.md'
+  - 'TanStack/markdown:docs/core-concepts/syntax-profile.md'
+  - 'TanStack/markdown:src/parser.ts'
+  - 'TanStack/markdown:src/html.ts'
+  - 'TanStack/markdown:src/types.ts'
+---
+
+# Render Markdown
+
+## Setup
+
+Install the framework-neutral package:
+
+```bash
+pnpm add @tanstack/markdown
+```
+
+Render supported Markdown to HTML:
+
+```ts
+import { renderHtml } from '@tanstack/markdown/html'
+
+const source = `# Release notes
+
+- Small browser bundle
+- Serializable AST
+- Safe HTML defaults`
+
+const html = renderHtml(source)
+
+console.log(html)
+```
+
+Use the narrow `@tanstack/markdown/parser` and
+`@tanstack/markdown/html` entry points when the default entry's combined
+exports are unnecessary.
+
+## Core Patterns
+
+### Parse once and render a reusable document
+
+```ts
+import { renderHtml } from '@tanstack/markdown/html'
+import { parseMarkdown } from '@tanstack/markdown/parser'
+import type { MarkdownDocument } from '@tanstack/markdown'
+
+const source = `# Guide
+
+Read the [installation notes](/installation).`
+
+const document = parseMarkdown(source)
+const serialized = JSON.stringify(document)
+const restored = JSON.parse(serialized) as MarkdownDocument
+const html = renderHtml(restored)
+
+console.log(html)
+```
+
+All complete-document renderers accept a source string or an existing
+`MarkdownDocument`; a document input skips parsing.
+
+### Configure frontmatter and heading IDs while parsing
+
+```ts
+import { renderHtml } from '@tanstack/markdown/html'
+import { parseMarkdown } from '@tanstack/markdown/parser'
+
+const source = `---
+title: Installation
+published: true
+---
+
+# Install
+
+## Install`
+
+const document = parseMarkdown(source, {
+  frontmatter: true,
+  headingIds(text, lineIndex) {
+    const slug = text.toLowerCase().replaceAll(' ', '-')
+    return `docs-${lineIndex}-${slug}`
+  },
+})
+
+console.log(document.frontmatter)
+console.log(renderHtml(document))
+```
+
+Frontmatter remains an unparsed string. Heading IDs are generated during
+parsing and are duplicate-safe under the default slugger.
+
+### Add visible heading anchors while rendering
+
+```ts
+import { renderHtml } from '@tanstack/markdown/html'
+import { parseMarkdown } from '@tanstack/markdown/parser'
+
+const document = parseMarkdown('# API')
+
+const html = renderHtml(document, {
+  headingAnchors: {
+    content: '#',
+    className: 'heading-anchor',
+    ariaHidden: true,
+    tabIndex: -1,
+  },
+})
+
+console.log(html)
+```
+
+Heading IDs are a parse concern; visible anchor links are a render concern.
+
+### Parse inline content only when no block context is needed
+
+```ts
+import { parseInline, renderInline } from '@tanstack/markdown'
+
+const nodes = parseInline('Use **stable** APIs and `parseMarkdown`.')
+const html = nodes.map(node => renderInline(node)).join('')
+
+console.log(html)
+```
+
+`parseInline` handles inline syntax only. Use `parseMarkdown` for headings,
+lists, tables, frontmatter, reference definitions, and footnote definitions.
+
+## Behavioral Contracts
+
+- Parsing is synchronous, deterministic, and normalizes line endings.
+- Raw block and inline HTML are recognized only with `allowHtml: true`.
+- Link and image URLs have unsafe executable protocols removed.
+- Tight lists place simple content directly under `<li>`; loose lists retain
+  paragraph wrappers; task checkboxes remain inline with labels.
+- Reference definitions resolve case-insensitively before block parsing.
+- Footnotes render in first-reference order with collision-safe IDs and
+  repeated-reference back links.
+- Code fence metadata is recorded in the AST; highlighting is external.
+- The AST is public but pre-1.0. Regenerate persisted documents when an
+  upgrade changes node contracts.
+
+## Compatibility and Option Timing
+
+TanStack Markdown targets controlled blog and documentation content rather
+than complete CommonMark, GFM, MDX, or arbitrary HTML parsing. Before adding
+syntax, require corpus evidence, regression coverage, renderer parity, and an
+accepted bundle cost. See `production-pipelines/SKILL.md` for compatibility,
+security, highlighting, and size gates.
+
+Parsing fixes the document structure. Apply `frontmatter`, `headingIds`,
+`allowHtml`, parser state, and parser/transform extensions before caching the
+AST. Renderer-only options such as `headingAnchors`, `highlighter`, and
+`codeLineNumbers` may be applied when rendering an existing document.
+
+## Common Mistakes
+
+### HIGH Assuming complete CommonMark or GFM behavior
+
+Wrong:
+
+```ts
+import { renderHtml } from '@tanstack/markdown/html'
+
+const markdownFromAnywhere = `Heading
+===
+
+Visit https://example.com`
+
+const html = renderHtml(markdownFromAnywhere)
+
+console.log(html)
+```
+
+Correct:
+
+```ts
+import { renderHtml } from '@tanstack/markdown/html'
+
+const controlledMarkdown = `# Heading
+
+Visit [example](https://example.com)`
+
+const html = renderHtml(controlledMarkdown)
+
+console.log(html)
+```
+
+Setext headings and automatic URL linking are outside the supported syntax
+profile, so unsupported input can remain literal or have different structure.
+
+Source: `docs/core-concepts/syntax-profile.md`
+
+See also: `production-pipelines/SKILL.md` - compatibility breadth must be
+justified against corpus evidence and the bundle budget.
+
+### MEDIUM Reparsing unchanged content on every render
+
+Wrong:
+
+```ts
+import { renderHtml } from '@tanstack/markdown/html'
+
+const source = '# Cached article'
+
+function renderArticle() {
+  return renderHtml(source)
+}
+
+console.log(renderArticle())
+console.log(renderArticle())
+```
+
+Correct:
+
+```ts
+import { renderHtml } from '@tanstack/markdown/html'
+import { parseMarkdown } from '@tanstack/markdown/parser'
+
+const source = '# Cached article'
+const document = parseMarkdown(source)
+
+function renderArticle() {
+  return renderHtml(document)
+}
+
+console.log(renderArticle())
+console.log(renderArticle())
+```
+
+Complete-document renderers parse string inputs on every call, while a
+`MarkdownDocument` input skips repeated parsing.
+
+Source: `docs/core-concepts/document-model.md`
+
+See also: `production-pipelines/SKILL.md` - parse-ahead caching must preserve
+the parser option and extension set.
+
+### HIGH Applying parser options after parsing
+
+Wrong:
+
+```ts
+import { renderHtml } from '@tanstack/markdown/html'
+import { parseMarkdown } from '@tanstack/markdown/parser'
+
+const document = parseMarkdown('# API')
+const html = renderHtml(document, { headingIds: false })
+
+console.log(html)
+```
+
+Correct:
+
+```ts
+import { renderHtml } from '@tanstack/markdown/html'
+import { parseMarkdown } from '@tanstack/markdown/parser'
+
+const document = parseMarkdown('# API', { headingIds: false })
+const html = renderHtml(document)
+
+console.log(html)
+```
+
+Parse-only options do not retroactively alter a pre-parsed AST.
+
+Source: `docs/reference/html.md`
+
+See also: `custom-extensions/SKILL.md` - parser and transform extensions must
+also be present while creating a cached document.
+
+### MEDIUM Using parseInline for document definitions
+
+Wrong:
+
+```ts
+import { parseInline, renderInline } from '@tanstack/markdown'
+
+const source = `[Guide][guide]
+
+[guide]: /guide`
+
+const html = parseInline(source).map(node => renderInline(node)).join('')
+
+console.log(html)
+```
+
+Correct:
+
+```ts
+import { renderHtml } from '@tanstack/markdown/html'
+import { parseMarkdown } from '@tanstack/markdown/parser'
+
+const source = `[Guide][guide]
+
+[guide]: /guide`
+
+const document = parseMarkdown(source)
+const html = renderHtml(document)
+
+console.log(html)
+```
+
+Standalone inline parsing does not extract document-level reference or
+footnote definitions unless internal parser state is supplied explicitly.
+
+Source: `docs/reference/default-entry.md`
+
+## Related Skills
+
+- `production-pipelines/SKILL.md` - trust boundaries, syntax highlighting,
+  practical compatibility, caching, tests, performance, and bundle budgets.
+- `react-rendering/SKILL.md` - render the same source or AST as React nodes.
+- `octane-rendering/SKILL.md` - render the same source or AST as Octane nodes.
+- `custom-extensions/SKILL.md` - add deterministic parser and renderer hooks.
+- `docs-features/SKILL.md` - use the first-party documentation extensions.
+
+## References
+
+- [AST nodes, parser state, and render options](references/ast-and-options.md)