Skip to content

API Overview ​

SymbolPurposeExecutionCommon gotcha
parseProseMarkdown string → frozen ProseDoc ASTSyncFixed profile: raw HTML, entities, reference links are literal text
renderProseHtmlAST → escaped HTML stringSyncNo heading ids unless headingIds: true
renderProseDomAST → DocumentFragment built with DOM APIsSyncNeeds a DOM; pass the doc, not its blocks
proseToTextAST → plain textSyncLinks keep labels, images keep alt text
proseOutlineHeadings with ids, renderer orderSyncNested headings count in the slug sequence, matching the renderer

Package Entry Point ​

ImportPurpose
@vielzeug/scribeComplete public Scribe API

Functions ​

parseProse(markdown, options?) ​

Parses the fixed GFM-flavored profile (see the Usage Guide) into a frozen ProseDoc. Link/image destinations are policy-checked here: relative URLs always pass, data: always fails, other schemes require membership in options.linkProtocols (default ['http', 'https', 'mailto']). A rejected destination becomes the label/alt text plus a dev-only warning — parsing never throws for a bad URL.

ts
const doc = parseProse('Read the [guide](/scribe/).');
  • Throws ScribeLimitError beyond 200,000 characters or 32 nesting levels.

renderProseHtml(doc, options?) → string ​

Escapes every dynamic value; emits only the fixed tag set. options.headingIds adds unique slug ids matching proseOutline.

renderProseDom(doc, options?) → DocumentFragment ​

DOM construction only (createTextNode/createElement/setAttribute): content can never execute. Requires a browser environment. Same options and id behavior as the string renderer.

proseToText(doc) → string ​

Plain text: blocks separated by blank lines, list markers preserved, links reduced to labels. For notifications, search indexing, and previews.

proseOutline(doc, options?) → readonly ProseOutlineEntry[] ​

Headings as { level, text, id } in document order — the same traversal and slug sequence the renderers use with headingIds, including headings nested in blockquotes and lists. options.maxLevel (1–6) filters entries without shifting the slug sequence, so ids keep matching the rendered document.

Types ​

The AST is public: safe to branch on, cache, and cross worker boundaries (frozen, serializable).

TypePurpose
ProseDoc{ blocks }: the parsed document
ProseBlockUnion of block nodes (paragraph, heading, list …)
ProseInlineUnion of inline nodes (text, link, codeSpan …)
ProseParagraph, ProseHeading, ProseCodeBlock, ProseBlockquote, ProseList, ProseListItem, ProseThematicBreak, ProseTable, ProseTableCellBlock variants
ProseText, ProseCodeSpan, ProseStrong, ProseEmphasis, ProseStrikethrough, ProseLink, ProseImage, ProseSoftBreak, ProseHardBreakInline variants
ProseParseOptions, ProseRenderOptions, ProseOutlineOptionsOption bags
ProseOutlineEntry, ProseHeadingLevel, ProseAlignmentOutline entry, 1–6, table alignment

Errors ​

ErrorThrown byMeaning
ScribeError— (base class)Narrow with instanceof for any scribe failure
ScribeLimitErrorparseProseInput exceeds the size or nesting limit