> _punctilio_ (n.): precise observance of formalities.
[](https://github.com/AlexanderMattTurner/punctilio/actions/workflows/test.yml)
[](https://github.com/AlexanderMattTurner/punctilio/actions/workflows/lint.yml)
[](https://github.com/AlexanderMattTurner/punctilio/actions/workflows/coverage-badge.yml)
Pretty good at making your text pretty. The most feature-complete and reliable English typography package. `punctilio` transforms plain ASCII into typographically correct Unicode, even across HTML element boundaries. Try it live at [`turntrout.com/punctilio`](https://turntrout.com/punctilio).
**Smart quotes** · **Em/en dashes** · **Ellipses** · **Math symbols** · **Legal symbols** · **Arrows** · **Primes** · **Fractions** · **Superscripts** · **Ligatures** · **Non-breaking spaces** · **HTML-aware** · **Markdown support** · **Bri’ish, German, and French localisation support**
```typescript
import { transform } from "punctilio";
transform(`"It's a beautiful thing, the destruction of words..." -- 1984`);
// → “It’s a beautiful thing, the destruction of words…”—1984
```
`punctilio` accepts three input formats: text, Markdown, and HTML. Use it as a library, a [CLI](#cli), a [pre-commit hook](#pre-commit), or—for a zero-friction install in any project that already runs Prettier—a [Prettier plugin](#prettier-plugin).
```bash
npm install punctilio
```
## Why punctilio?
As far as I can tell, `punctilio` is the most reliable and feature-complete. I built `punctilio` for [my website](https://turntrout.com/design). I wrote and sharpened the core regexes sporadically over several months, exhaustively testing edge cases. Eventually, I decided to spin off the functionality into its own package.
I tested `punctilio` against [`smartypants`](https://www.npmjs.com/package/smartypants) 0.2.2, [`tipograph`](https://www.npmjs.com/package/tipograph) 0.7.4, [`smartquotes`](https://www.npmjs.com/package/smartquotes) 2.3.2, [`typograf`](https://www.npmjs.com/package/typograf) 7.7.0, and [`retext-smartypants`](https://www.npmjs.com/package/retext-smartypants) 6.2.0.[^python] These other packages have spotty feature coverage and inconsistent impact on text. For example, `smartypants` mishandles quotes after em dashes (though quite hard to see in GitHub’s font) and lacks multiplication sign support.
[^python]: The Python libraries I found were closely related to the JavaScript packages. I tested them and found similar scores, so I don’t include separate Python results.
| Input | `smartypants` | `punctilio` |
| :------------------------------------: | :----------------------------------------: | :---------: |
| 5x5 | 5x5 (✗) | 5×5 (✓) |
My [`benchmark.mjs`](https://github.com/AlexanderMattTurner/punctilio/blob/main/benchmark.mjs) measures how well libraries handle a [wide range of scenarios](https://github.com/AlexanderMattTurner/punctilio/blob/main/benchmark_cases.json). The benchmark normalizes stylistic differences (e.g. non-breaking vs regular space, British vs American dash spacing) for fair comparison.
| Package | Passed (of 160) |
| -------------------: | :-------------- |
| `punctilio` | 158 (99%) |
| `tipograph` | 94 (59%) |
| `smartquotes` | 82 (51%) |
| `smartypants` | 76 (48%) |
| `retext-smartypants` | 74 (46%) |
| `typograf` | 69 (43%) |
_Note on benchmark construction: I assembled the initial cases myself. I then sought out cases where `punctilio` failed and competitors succeeded, and improved `punctilio` to succeed there as well. The benchmark may nonetheless remain biased towards `punctilio`._
| Feature | Example | `punctilio` | `smartypants` | `tipograph` | `smartquotes` | `typograf` |
| -------------------: | :---------------------------------------------------: | :---------: | :-----------: | :---------: | :-----------: | :--------: |
| Smart quotes | "hello" → “hello” | ✓ | ✓ | ✓ | ✓ | ✓ |
| Leading apostrophe | 'Twas → ’Twas | ✓ | ✗ | ✗ | ◐ | ✗ |
| Em dash | -- → — | ✓ | ✓ | ✗ | ✗ | ✓ |
| En dash (ranges) | 1-5 → 1–5 | ✓ | ✗ | ✓ | ✗ | ✗ |
| Minus sign | -5 → −5 | ✓ | ✗ | ✓ | ✗ | ✗ |
| Ellipsis | ... → … | ✓ | ✓ | ✓ | ✗ | ✓ |
| Multiplication | 5x5 → 5×5 | ✓ | ✗ | ✗ | ✗ | ◐ |
| Math symbols | != → ≠ | ✓ | ✗ | ◐ | ✗ | ◐ |
| Legal symbols | (c) 2004 → © 2004 | ✓ | ✗ | ◐ | ✗ | ✓ |
| Arrows | -> → → | ✓ | ✗ | ◐ | ✗ | ◐ |
| Prime marks | 5'10" → 5′10″ | ✓ | ✗ | ✓ | ✓ | ✗ |
| Degrees | 20 C → 20 °C | ✓ | ✗ | ✗ | ✗ | ✓ |
| Fractions | 1/2 → ½ | ✓ | ✗ | ✗ | ✗ | ✓ |
| Superscripts | 2nd → 2ⁿᵈ | ✓ | ✗ | ✗ | ✗ | ✗ |
| English localization | American / British | ✓ | ✗ | ✗ | ✗ | ✗ |
| Ligatures | ?? → ⁇ | ✓ | ✗ | ✓ | ✗ | ✗ |
| Non-English quotes | „Hallo“ | ✓ | ✗ | ✓ | ✗ | ◐ |
| Non-breaking spaces | Chapter 1 | ✓ | ✗ | ✗ | ✗ | ✓ |
### Known limitations of `punctilio`
| Input | Behavior | Why |
| :--- | :--- | :--- |
| `'99 but 5' clearance` | `5'` stays straight | A leading apostrophe and an opening quote are indistinguishable without semantics |
| `Anthropic-Pentagon news cycle` | hyphen stays a hyphen | The relational en dash (“between Anthropic and the Pentagon”) is orthographically identical to a hyphenated proper-noun compound (`Merriam-Webster`, `Sarbanes-Oxley`); telling them apart needs named-entity knowledge, not typography |
## Test suite
Setting aside the benchmark, `punctilio`’s test suite runs at 100% branch coverage with well over a thousand tests, including edge cases derived from competitor libraries ([`smartquotes`](https://github.com/kellym/smartquotes.js), [`retext-smartypants`](https://github.com/retextjs/retext-smartypants), [`typograf`](https://github.com/typograf/typograf)) and the [Standard Ebooks typography manual](https://standardebooks.org/manual/). The 100% figure isn’t hand-maintained: Jest’s `coverageThreshold` requires 100% branches, functions, lines, and statements, CI fails below that, and the coverage badge above is regenerated from the actual coverage report on every push to `main`. I also verify that all transformations are stable when applied multiple times. Uses [`recheck`](https://makenowjust-labs.github.io/recheck/) to statically verify the absence of inefficient RegEx patterns.
## Works with HTML DOMs via boundary-aware views
Perhaps the most innovative feature of the library is that it properly handles DOMs! Other typography libraries take one of two approaches, both with drawbacks.
1. String-based libraries (like [`smartypants`](https://www.npmjs.com/package/smartypants)) transform plain text but are unaware of HTML structure. If you flatten text from `""Wait"` into `"Wait"`, transform the text so that it has smart quotes (`“Wait”`), and then try to convert back—you've lost track of where the `` belongs.
2. AST-based libraries (like [`rehype-retext`](https://github.com/rehypejs/rehype-retext)) process each text node individually, preserving structure but losing cross-node information. A quote that opens inside `"Wait` and closes outside it `"` spans two text nodes. Processed independently, the library can't tell whether the final `"` is opening or closing, because it never sees both at once.
`punctilio` gets the best of both worlds with a _ProseView_: a view over a sequence of text nodes that exposes their concatenated text plus the offsets where one node ends and the next begins.
1. Every pass scans the full concatenated text, so cross-node context (the closing `"` above) is always visible.
2. Passes consult the node boundaries explicitly — a rule can treat a boundary as transparent, as a word boundary, or as a blocker, matching what the markup means.
3. Edits are queued by offset and committed back onto the source text nodes, so the HTML structure is never lost and never has to be re-derived.
For `rehype` / `unified` pipelines, use the built-in plugin which handles all of this automatically:
```typescript
import rehypePunctilio from "punctilio/rehype";
unified()
.use(rehypeParse)
.use(rehypePunctilio)
.use(rehypeStringify)
.process('"Wait..." -- she said
');
// → “Wait…”—she said
// The opening quote inside and the closing quote outside it
// are both resolved correctly across the element boundary.
```
* For Markdown ASTs via `remark`, use `remarkPunctilio` which builds the same boundary-aware views over inline text nodes, or use `transformMarkdown` for a simpler Markdown-to-Markdown pipeline.
* For manual DOM walking, use `collectProseBlocks` from `punctilio/rehype` to find the elements to transform, then `applyPasses` (below) to transform each one. (`proseViewOf` builds a raw `ProseView` over an element’s text nodes if you need to drive `transformView` or a pass yourself.)
### Boundary-aware custom transforms
Your own site-specific regexes can join punctilio’s passes as first-class citizens. `definePass` (root export) wraps a regex and replacement into a pass with the same shape as the built-ins: string in, string out; `ProseView` in, edits committed in place. Each pattern makes an explicit decision about matches that span a node boundary (a word split by ``, say): `skip` them (the safe default), `allow` them, or decide per match with a predicate.
`applyPasses` (from `punctilio/rehype`) then runs built-in and custom passes over an element in order, committing between passes so each sees the previous one’s output—you never touch a `ProseView` directly. An entry may carry its own `shouldSkip`/`shouldSkipText` predicates, applied in addition to the base options for that pass only:
```typescript
import { definePass, hyphenReplace, niceQuotes } from "punctilio";
import { applyPasses } from "punctilio/rehype";
const fahrenheit = definePass(/(?\d+) ?F\b/g, "$ °F"); // $&, $1, $, $$ supported
const fractions = definePass(/\b1\/2\b/g, "½"); // boundary-spanning matches skipped by default
applyPasses(element, [
niceQuotes,
hyphenReplace,
fahrenheit,
{ pass: fractions, shouldSkip: (node) => node.tagName === "a" }, // extra skip set for this pass only
]);
```
Migrating from the v4 marker-character API (`transformElement`, the `separator` option, standalone `primeMarks`)? See the [v5 migration guide](docs/migrating-to-v5.md).
## Options
`punctilio` doesn’t enable all transformations by default. Fractions and degrees tend to match too aggressively (perfectly applying the degree transformation requires semantic meaning). Superscript letters and punctuation ligatures have spotty font support. Furthermore, `ligatures = true` can change the meaning of text by collapsing question and exclamation marks.
```typescript
transform(text, {
punctuationStyle: "american" | "british" | "german" | "french" | "none", // default: 'american'
dashStyle: "american" | "british" | "none", // default: 'american'
symbols: true, // ellipsis, math, legal, arrows
includeArrows: true, // arrow transforms (-> → →); only applies when symbols is true
collapseSpaces: true, // normalize whitespace
fractions: false, // 1/2 → ½
degrees: false, // 20 C → 20 °C
superscript: false, // 1st → 1ˢᵗ
ligatures: false, // ??? → ⁇, ?! → ⁈, !? → ⁉, !!! → !
nbsp: true, // non-breaking spaces (after honorifics, between numbers and units, etc.)
});
```
Markdown sinks (`remarkPunctilio`, `transformMarkdown`, the Prettier plugin, and the CLI for Markdown files) default `nbsp` to `false` instead, because invisible U+00A0 characters in Markdown source files break `grep` and Ctrl+F. Pass `nbsp: true` (or the `--nbsp` CLI flag) to opt in.
The `rehype` plugin accepts additional options. Elements matching any `skipTags` tag name or carrying any `skipClasses` class are left untransformed. The `skipTags` value below is the default; `skipClasses` defaults to `[]`, and the value shown is a common opt-in (add `no-formatting` yourself to skip elements marked with it):
```typescript
rehypePunctilio({
skipTags: ["code", "pre", "script", "style", "kbd", "var", "samp", "template", "math", "svg"], // default
skipClasses: ["no-formatting"], // default: [] — shown here as a common opt-in
transformAllElements: false, // see below
});
```
By default the plugin transforms text only inside a curated allowlist of prose-bearing elements (plus custom elements). Set `transformAllElements: true` to invert the model and transform text inside *every* element except those in `skipTags`/`skipClasses` and the form-value elements `