Rule order

The fixed order in which the nine polytypo rules run, why each sits where it does, why ranges is off by default, and how options never reorder them.

Updated 21 October 2026 · spec 1.12.0

transform runs nine rules in one fixed order. The order is part of the specification, not an implementation detail, and it is identical in all five runtimes.

The order #

Why the order matters #

Each rule reads the output of the ones before it, so some orderings are required rather than chosen:

• spaces is first so every later rule sees clean spacing.
• ranges runs before dashes. A digit-hyphen-digit shape belongs to ranges alone, whether or not ranges is enabled; dashes never reinterprets it as a parenthetical dash.
• dashes runs before hyphen. By the time hyphen runs, dashes has already declined every hyphen that sits between letters.
• quotes runs before apostrophe. A straight apostrophe can be evidence that a single quote is part of a quotation. quotes uses that evidence first; apostrophe then converts whatever is left.
• nbsp is last so every other rule has settled the characters around the spaces it binds.

The order also underpins idempotency: a rule may create work for a later rule but never for an earlier one.

Examples #

The input holds a digit range and a parenthetical dash. ranges is off, so the range keeps its hyphen while dashes converts the --:

Turning ranges on also converts the range, bound with word joiners, and dashes still handles the rest:

Options and order #

ranges is the only rule that is off by default. A range and a compound label such as Figure 5-10 have the same shape, and telling them apart would need the preceding word, which the rules never read. It is an explicit opt-in.

The rules option switches rules on or off by id. It never reorders them. A disabled rule is removed from the sequence and the rest keep their positions, and the order in which you list ids does not matter. Here dashes is off, so the spaced -- stays while ranges still runs:

Edge cases #

• Rule ids are public API. They appear in the rules option. An unknown id raises POLYTYPO_UNKNOWN_RULE.
• Which rules a locale affects varies. spaces, apostrophe and symbols read no locale data; the others read the fields listed on their pages.

Related #

• Options
• Idempotency
• The span model
• Ranges
• Error codes

Normative text: spec/rules/order.json.