A remark plugin that applies polytypo to the prose of a Markdown or MDX document: locale-correct quotes, dashes, ellipses, apostrophes and no-break spaces. Code, URLs, MDX expressions, JSX attributes and ESM are not touched.
npm install remark-polytypoESM only. Requires Node.js 20 or newer and unified 11 (remark 15).
import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkStringify from "remark-stringify";
import remarkPolytypo from "remark-polytypo";
const file = await unified()
.use(remarkParse)
.use(remarkPolytypo, { locale: "de-DE", dialect: "commonmark" })
.use(remarkStringify)
.process('Sie sagte "es ist *gut*" -- sicher...');
String(file);
// Sie sagte „es ist *gut*“ – sicher…import { compile } from "@mdx-js/mdx";
import remarkPolytypo from "remark-polytypo";
await compile(source, {
remarkPlugins: [[remarkPolytypo, { locale: "en-GB", dialect: "mdx" }]],
});@astrojs/mdx has an extendMarkdownConfig option that defaults to true: MDX inherits the
project's markdown configuration (Astro's MDX integration guide). A plugin configured there
therefore also runs on .mdx files with the same options, and .md and .mdx need different
dialect values. In @astrojs/mdx 8.1.1 the integration accepts extendMarkdownConfig and
remarkPlugins, and marks remarkPlugins as deprecated in favour of
unified({ remarkPlugins }) from @astrojs/markdown-remark used as markdown.processor. Check the
Astro documentation for your version before choosing where to list the plugin.
The Next.js MDX guide says that with Turbopack plugins are named as strings, with serializable options:
// next.config.mjs
import createMDX from "@next/mdx";
const withMDX = createMDX({
options: {
remarkPlugins: [["remark-polytypo", { locale: "en-GB", dialect: "mdx" }]],
},
});
export default withMDX({ pageExtensions: ["js", "jsx", "md", "mdx", "ts", "tsx"] });locale and dialect are required. There is no default for either and nothing is detected.
| Option | Type | Description |
|---|---|---|
locale |
string |
A polytypo locale id such as en-GB, de-DE, fr, ru. An unknown locale throws. |
dialect |
"commonmark" or "mdx" |
How polytypo reads the document. Use mdx for .mdx files and commonmark (CommonMark plus GFM) for .md. |
rules |
Partial<Record<RuleId, boolean>> |
Turns single rules on or off. ranges is off by default. |
narrowNbsp |
"narrow" or "nbsp" |
Emit U+00A0 instead of U+202F where a rule would insert the narrow no-break space. |
frontmatterKeys |
string[] |
YAML frontmatter keys whose values are prose. Without it the frontmatter is left alone. It needs remark-frontmatter (see below). |
The options are polytypo's own, validated by polytypo; a PolytypoError and its code reach you
unchanged. The mode, keys and protect options do not exist here. Values are static: there is
no function form.
The plugin reads the file's source text, runs polytypo's markdown mode over it, and parses the
source and the result with the processor's own parser. It copies the differences into the tree you
are already working with: text values, image and imageReference alt text, and the
frontmatter yaml value when frontmatterKeys is set. Nothing else in the tree changes, and
file.value is not modified.
Changes are matched to nodes by their source position, and a node is only changed if its value is still the one the parser produced. So:
- Put the plugin first. It needs the source and an unmodified tree. If an earlier plugin rewrites text (smart quotes, for example), that text is no longer matched.
- Frontmatter is a
yamlnode only whenremark-frontmatteris in the pipeline. Without it the frontmatter is parsed as Markdown andfrontmatterKeyshas no useful meaning.
Anything the plugin cannot apply safely is left as it was, and a message is added to file.messages
(source remark-polytypo):
ruleId |
Meaning |
|---|---|
dropped-change |
polytypo changed text that lives in a node other than prose, for example raw HTML, inlineMath (remark-math) or an MDX expression. That one change is dropped; the text around it is carried. |
left-unchanged |
polytypo's result would change a node in a way that can move the boundary of the surrounding text (a link whose address would end differently, for instance). The unit described below is left unchanged. |
unmatched-edit |
Some node of a unit no longer matches the source: an earlier plugin changed it, or the parser gave it no position. The unit is left unchanged. |
frontmatter-not-parsed |
frontmatterKeys is set and the document starts with a frontmatter block, but the tree has no yaml node. Add remark-frontmatter before this plugin. |
The unit. Quote pairing and spacing reach across blocks, so the plugin carries text in units, all or nothing. A unit is one paragraph, heading or table cell, except that everything inside a blockquote, a list or a footnote definition is one unit together with the outermost such container around it. If any part of a unit is left unchanged, so is the whole unit. Other paragraphs of the document are decided on their own.
These cases stop the build with an error:
no-source: the file has no source text (for exampleprocessor.run(tree)without a file).tree-shape: the document parses to a different tree after typography, at a level above a paragraph, heading or table cell. A change inside one of those isleft-unchangedinstead.reparse: the typeset text does not parse with the processor's parser, which usually meansdialectdoes not match the parser (commonmarkfor an MDX document, for instance).- A
PolytypoErrorfrom polytypo, such asPOLYTYPO_UNKNOWN_LOCALEor, for an MDX document that does not parse,POLYTYPO_MALFORMED_INPUT.
How each rule works, the locale list and the playground are at polytypo.dev. The engine is polytypo.
MIT