Skip to content

About

polytypo — normalize typography for JavaScript/TypeScript (quotes, dashes, ellipses, no-break spaces). Issues: github.com/polytypo/polytypo/issues

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

polytypo

polytypo

npm version CI npm downloads jsDelivr hits License: MIT

Locale-correct quotes, dashes, ellipses, apostrophes, symbols and no-break spaces —
one portable spec, designed for byte-identical output across runtimes.

Try it live, no install: polytypo.dev

This is the JavaScript/TypeScript implementation. The full spec — all locales, all rules, worked examples in each — lives in polytypo/polytypo. The browser playground runs this exact package, compiled to a browser bundle — paste your own text to try it against any locale before installing anything.

Install

npm install polytypo

Usage

import { transform } from "polytypo/text";

transform(`She said, "it's fine" -- but I wasn't sure...`, { locale: "en-US" });
// She said, “it’s fine”—but I wasn’t sure…

Same input, one locale changed — quotes, dash spacing and all follow the target locale, not a single hardcoded style:

transform(`Sie sagte: "Alles gut" -- aber ich war mir nicht sicher...`, { locale: "de-DE" });
// Sie sagte: „Alles gut“ – aber ich war mir nicht sicher…

Import the entry for the mode you use. Each subpath entry defaults mode to itself and loads only the parsers that mode needs:

Entry Parsers it loads
polytypo/text none
polytypo/html parse5
polytypo/markdown parse5, micromark and its GFM, frontmatter and MDX extensions
polytypo/yaml none
polytypo all of the above

HTML and Markdown are first-class modes, not an afterthought — tags, attributes and fenced code are left alone; only text content is touched:

import { transform } from "polytypo/html";

transform(`<a title="test... wait">Wait... she said "go on."</a>`, { locale: "en-US" });
// <a title="test... wait">Wait… she said “go on.”</a>

html mode leaves ten elements alone, with everything inside them: code, pre, kbd, samp, var, script, style, textarea, svg and math. If you walk a document with a parser of your own, read the list instead of copying it. It is a frozen array, exported from polytypo/html and polytypo:

import { SKIPPED_ELEMENTS } from "polytypo/html";

yaml mode is the one that asks something of you, and it asks for a reason. YAML is a data format with prose in some of it, so you name the keys whose values are prose; there is no default and no guess:

import { transform } from "polytypo/yaml";

transform("summary: Rates -- all of them...\nrun: git diff -- a--b\n", {
  locale: "en-US",
  keys: ["summary"],
});
// summary: Rates—all of them…
// run: git diff -- a--b

Nothing in YAML's syntax separates a sentence from a shell script: description holds one and run holds the other, spelled identically. Without keys the same document comes back with if ! rewritten as if!. Quoting, indentation, anchors and a block scalar's chomping indicator are never decoded and rewritten — the file is located, not re-emitted — so the trailing newlines of a |+ block come back exactly as you wrote them.

In markdown mode the skipped regions are the dialect's own structural ones, not whatever looks like code. CommonMark counts an indented block as code at four spaces; at two it is an ordinary paragraph, so a JSON sample indented by two comes back with curly quotes — valid JSON in, invalid JSON out, and nothing in the return value says so. MDX has no indented code blocks at all, so there even four spaces is prose and a brace in it is a JSX expression: the same sample throws POLYTYPO_MALFORMED_INPUT instead. A fence or a code span is the one marker that means code in both dialects.

Frontmatter is skipped whole by default, delimiters included — it is a machine-read block, and fr would put a narrow no-break space in front of the colon of every field in it. On a site whose frontmatter carries the headline that leaves the most visible string on the page untouched, so name the keys you want processed:

import { transform } from "polytypo/markdown";

transform(
  `---\ntitle: He said "hello" once\nslug: "he-said-hello"\n---\n\nThe body was typeset all along.\n`,
  { locale: "en-US", dialect: "commonmark", frontmatterKeys: ["title"] },
);
// ---
// title: He said “hello” once
// slug: "he-said-hello"
// ---
//
// The body was typeset all along.

Without the option nothing in the block changes, and a key you do not name never does. The block is read with the same scanner yaml mode uses, so it refuses the same constructs — a single-quoted scalar containing '' among them, which is how an apostrophe is written inside single quotes, so title: 'It''s a test' comes back untouched. Double-quoted and plain scalars have no such limit. The block is also processed separately from the body, which shows up in exactly one place: an unbalanced quotation mark in title cannot pair with a mark in your first paragraph.

text mode takes a protect option for strings with holes in them, such as template literals or ICU messages: ranges of the input that are never edited and that the rules read as content. Offsets are Unicode code points, [start, end), ascending and non-overlapping:

import { transform } from "polytypo/text";

transform("${x} - Rules", { locale: "en-US", protect: [{ start: 0, end: 4 }] });
// ${x}—Rules

Text next to a hole converts less than the same text would unsplit, never more: a character polytypo would insert beside the hole is not written. A hole containing a line break counts as a line break to the rules. A malformed list throws POLYTYPO_INVALID_OPTION, and so does a non-empty list in html, markdown or yaml mode. An empty list is the same as no option. Running the output through again is a fixed point only if you move the ranges to where the edits left them; transform does not return them. analyze() takes the same option.

analyze() runs the same pipeline and reports what it would do instead of doing it — one record per edit, each with the rule that made it and code-point offsets into the input you passed (into the document, in html, markdown and yaml mode, not into a span):

import { analyze } from "polytypo";

analyze(`Wait... "really"?`, { locale: "en-US" });
// [ { ruleId: "ellipsis", start: 4, end: 7, before: "...", after: "…" },
//   { ruleId: "quotes",   start: 8, end: 9, before: `"`,   after: "“" }, … ]

It is a report, not a patch. The list is empty exactly when transform would return the input unchanged, and every ruleId is a rule that was enabled for that call — but two rules may touch the same original range (French spaces deletes the space before : and nbsp puts a no-break one back), so replaying the list is not guaranteed to reproduce the output. Call transform for the text. Full contract: spec/rules/analyze.md.

The aggregate polytypo entry defaults mode to "text" and is the one to use when the mode is chosen at runtime. locale has no default anywhere and must always be passed explicitly — there is no silent fallback to English.

Licence

MIT. See LICENSE.

About

polytypo — normalize typography for JavaScript/TypeScript (quotes, dashes, ellipses, no-break spaces). Issues: github.com/polytypo/polytypo/issues

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages