|
| 1 | +# MD086 - Normalize to ASCII quotes and dashes |
| 2 | + |
| 3 | +Aliases: `normalize-quotes-dashes` |
| 4 | + |
| 5 | +**Disabled by default.** This rule is opt-in: enable it explicitly with |
| 6 | +`extend-enable`. |
| 7 | + |
| 8 | +## What this rule does |
| 9 | + |
| 10 | +This rule detects Unicode quotes and dashes that look like their ASCII equivalents, and replaces them with plain ASCII characters. |
| 11 | + |
| 12 | +By default, it will only replace multiple styles of single and double quotes by their simple ASCII equivalents. |
| 13 | + |
| 14 | +You can optionally enable replacement for dashes. |
| 15 | + |
| 16 | +Characters covered by this rule: |
| 17 | + |
| 18 | +| Unicode Character Name | Character | Codepoint | ASCII Replacement | |
| 19 | +| ------------------------------------------ | --------- | --------- | ----------------- | |
| 20 | +| Modifier Letter Apostrophe | ʼ | U+02BC | ' | |
| 21 | +| Left Single Quotation Mark | ‘ | U+2018 | ' | |
| 22 | +| Right Single Quotation Mark | ’ | U+2019 | ' | |
| 23 | +| Single Low-9 Quotation Mark | ‚ | U+201A | ' | |
| 24 | +| Single High-Reversed-9 Quotation Mark | ‛ | U+201B | ' | |
| 25 | +| Prime | ′ | U+2032 | ' | |
| 26 | +| Left Double Quotation Mark | “ | U+201C | " | |
| 27 | +| Right Double Quotation Mark | ” | U+201D | " | |
| 28 | +| Double Low-9 Quotation Mark | „ | U+201E | " | |
| 29 | +| Double High-Reversed-9 Quotation Mark | ‟ | U+201F | " | |
| 30 | +| Double Prime | ″ | U+2032 | " | |
| 31 | +| Hyphen | ‐ | U+2010 | - | |
| 32 | +| Non-Breaking Hyphen | ‑ | U+2011 | - | |
| 33 | +| Figure Dash | ‒ | U+2012 | - | |
| 34 | +| En Dash | – | U+2013 | - | |
| 35 | +| Em Dash | — | U+2014 | - | |
| 36 | +| Horizontal Bar | ― | U+2015 | - | |
| 37 | + |
| 38 | +This rule checks only prose content and skips: |
| 39 | + |
| 40 | +- fenced code blocks |
| 41 | +- indented code blocks |
| 42 | +- inline code spans |
| 43 | + |
| 44 | +## Why this matters |
| 45 | + |
| 46 | +While more typographically correct, those characters only offer a very marginal readability gain. |
| 47 | + |
| 48 | +Fancy quotes and dashes often come from smart punctuation features or |
| 49 | +copy/paste from rich text sources. These characters can create variability, noisy diffs and |
| 50 | +unexpected behavior in tooling that expects ASCII punctuation. |
| 51 | + |
| 52 | +Bad handling of Unicode characters in editors/IDEs is also a source of "Mojibake", |
| 53 | +which are sequences of strange characters generated by decoding a Unicode-encoded |
| 54 | +character with another charset like ISO-8859-x or CP125x. See MD083 for a rule that |
| 55 | +detects such Mojibake. |
| 56 | + |
| 57 | +Normalizing quotes and dashes to ASCII keeps Markdown content predictable and avoids |
| 58 | +hidden character drift across contributors and platforms. |
| 59 | + |
| 60 | +## Examples |
| 61 | + |
| 62 | +### Incorrect |
| 63 | + |
| 64 | +```text |
| 65 | +It’s “quoted” text with ‛variantsʼ. |
| 66 | +``` |
| 67 | + |
| 68 | +### Correct |
| 69 | + |
| 70 | +```text |
| 71 | +It's "quoted" text with 'variants'. |
| 72 | +``` |
| 73 | + |
| 74 | +### Auto-fix behavior in code |
| 75 | + |
| 76 | +```text |
| 77 | +Prose ’quote’ and `code ’quote’` |
| 78 | +``` |
| 79 | + |
| 80 | +Fixes to: |
| 81 | + |
| 82 | +```text |
| 83 | +Prose 'quote' and `code ’quote’` |
| 84 | +``` |
| 85 | + |
| 86 | +The inline code span is intentionally unchanged. |
| 87 | + |
| 88 | +## Configuration |
| 89 | + |
| 90 | +```toml |
| 91 | +[MD086] |
| 92 | +normalize-quotes = true |
| 93 | +normalize-dashes = false |
| 94 | +allow = [] |
| 95 | +``` |
| 96 | + |
| 97 | +- `normalize-quotes`: if enabled (by default), replace Unicode quotes by simple ASCII ones. |
| 98 | +- `normalize-dashes`: if enabled, replace Unicode dashes by simple ASCII ones. |
| 99 | +- `allow`: A list of codepoints to preserve, written as the direct Unicode character, |
| 100 | + or as `U+XXXX`, `U+XXXXX`, or `U+XXXXXX` (for example `U+2019`). |
| 101 | + Any allowed codepoint is ignored by MD086 and will not be replaced. |
| 102 | + |
| 103 | +Example: |
| 104 | + |
| 105 | +```toml |
| 106 | +[MD086] |
| 107 | +enabled = true |
| 108 | +normalize-quotes = true |
| 109 | +normalize-dashes = true |
| 110 | +allow = ["U+2032", "U+2032"] |
| 111 | +``` |
| 112 | + |
| 113 | +With this configuration, the rule is enabled, quotes and dashes are replaced, |
| 114 | +excepted "prime" `′` and "double prime" `″`. |
0 commit comments