Documentation

Markdown mode

Typeset the prose of a CommonMark or MDX document, leaving code, links, HTML and frontmatter exactly as written.

Updated · spec 1.12.0

markdown mode parses a Markdown document and runs the rules over its prose: paragraphs, headings, list items, table cells and the text of links. Code, link destinations, raw HTML and the frontmatter block are skipped and come back byte for byte.

It has one required option, dialect, because "Markdown" is not one language. It has one optional option, frontmatterKeys, which opens named fields of the frontmatter block to the rules.

Examples #

transform(input, { locale: "en-US", mode: "markdown", dialect: "commonmark" })

Input

# The "new" plan -- v2 He said "wait..." and left. Read [the "docs"](https://example.com/a--b "A -- title"). Use `echo "x"` here.

Output

# The “new” plan—v2 He said “wait…” and left. Read [the “docs”](https://example.com/a--b "A -- title"). Use `echo "x"` here.

The heading and the paragraph are typeset. The link text is prose and is typeset; the link destination and its title are not. The code span is skipped whole.

A fenced block is skipped including its info string and fences:

transform(input, { locale: "en-US", mode: "markdown", dialect: "commonmark" })

Input

Say "hello" first: ```js console.log("hi" -- "there"); ``` Then "goodbye".

Output

Say “hello” first: ```js console.log("hi" -- "there"); ``` Then “goodbye”.

Quotation marks and nesting across markup #

The prose of a document is read as one text, not paragraph by paragraph and not node by node. Emphasis, links and inline code in the middle of a sentence do not break a quotation in two, and a straight quote next to a code span is not mistaken for one that touches it. See Span model.

transform(input, { locale: "en-US", mode: "markdown", dialect: "commonmark" })

Input

"He said *'hi'* loudly," she wrote.

Output

“He said *‘hi’* loudly,” she wrote.

What the mode needs from you #

  • A dialect. dialect has no default and is never detected. Omitting it throws POLYTYPO_INVALID_DIALECT. See Dialects.
  • Nothing else. GFM (tables, strikethrough, task lists, autolink literals) is on in both dialects.

Pages in this section #

  • Dialects: commonmark and mdx, and why the library never guesses
  • Frontmatter: the skipped block, frontmatterKeys, and how the block is located
  • Skip list: everything the mode leaves alone
  • MDX: JSX, expressions and parse errors

Normative text: spec/rules/modes.md (§3.7).

Already using polytypo? Add our badge

Two lines: a script tag and a span. No per-embed network call. Pick a language and a theme, then copy the code into your footer or credits. Embedding notes cover Content Security Policy. Sites with the badge are listed on Sites using polytypo.

<script async src="https://polytypo.dev/badge.js"></script>
<span data-polytypo-lang="en" data-polytypo-theme="light"></span>

Search runs in your browser. Nothing is sent anywhere.