Markdown API#

@tanstack/highlight/markdown converts Markdown code-fence inputs into rendered block data or HAST. It does not parse Markdown documents.

TanStack Markdown adapter#

TanStackMarkdownHighlighterOptions#

type TanStackMarkdownHighlighterOptions = {
  highlightLines?: ReadonlyArray<number>
  lineNumbers?: boolean
}

TanStackMarkdownHighlighter#

A synchronous callback matching TanStack Markdown's code-highlighter contract without importing @tanstack/markdown.

createTanStackMarkdownHighlighter#

function createTanStackMarkdownHighlighter(
  highlighter: Highlighter,
): TanStackMarkdownHighlighter

Returns escaped inner token markup for a renderer-owned <code> element. Highlighted lines receive th-line--highlighted; unknown languages use the highlighter's configured fallback.

Metadata#

parseCodeDiffNotation#

function parseCodeDiffNotation(code: string): {
  code: string
  decorations: Array<HighlightDecoration>
}

Removes trailing [!code ++] and [!code --] directives and returns th-line--inserted and th-line--deleted decorations for their one-based line numbers. JavaScript-style line and block comments, # line comments, and HTML comments are supported.

Both LF and Windows CRLF line endings are preserved when directives are removed.

CodeFenceMeta#

type CodeFenceMeta = {
  decorations: Array<HighlightDecoration>
  lineNumbers: boolean
  title?: string
}

parseCodeFenceMeta#

function parseCodeFenceMeta(meta?: string | null): CodeFenceMeta

Recognizes title, filename, file, name, lineNumbers, showLineNumbers, shorthand highlighted lines, and named line annotations. Invalid line fragments are ignored. See Annotations.

Quoted values are treated as text, so title="lineNumbers {2}" sets a title without enabling line numbers or highlighting a line. Named annotations require braces, for example ins={2}, and line numbers must be positive safe integers with ascending ranges.

getCodeFenceTitle#

function getCodeFenceTitle(meta?: string | null): string | undefined

Returns the trimmed value of the first title, filename, file, or name assignment. Single-quoted, double-quoted, and unquoted values are accepted.

Fence rendering#

CodeFenceInput#

type CodeFenceInput = {
  code: string
  decorations?: ReadonlyArray<HighlightDecoration>
  lang?: string | null
  lineNumbers?: boolean
  meta?: string | null
  title?: string | null
}

Inline diff notation is converted first, followed by metadata and explicit decorations. Explicit lineNumbers takes precedence over metadata. Explicit title takes precedence when it is non-empty.

HighlightedCodeFence#

RenderedCodeBlockData plus the resolved decorations and lineNumbers.

renderCodeFence#

function renderCodeFence(
  input: CodeFenceInput,
  highlighter: Highlighter,
): HighlightedCodeFence

Parses inline diff notation and metadata, then delegates to the supplied highlighter.

HAST#

HastText#

A HAST-compatible text node with type: 'text' and value.

HastElement#

A HAST-compatible element node with type, tagName, optional properties, and recursive children.

codeFenceToHast#

function codeFenceToHast(
  input: CodeFenceInput,
  highlighter: Highlighter,
): HastElement

Returns a <pre class="th-code th-code--LANG"><code>...</code></pre> HAST tree. A title is exposed as dataTitle on the pre node.

tokensToHast#

function tokensToHast(
  tokens: ReadonlyArray<HighlightToken>,
  lang: string,
  options?: {
    decorations?: ReadonlyArray<HighlightDecoration>
    lineNumbers?: boolean
    title?: string
  },
): HastElement

Renders existing tokens to the same HAST structure without tokenizing code.