feat: add --normalize-front-matter

AGENTS.md

@@ -63,15 +63,23 @@ The package implements mdformat's plugin interface with up to four key exports i
 
 ### Configuration Options
 
-Configuration can be passed via:
+All options are independent and composable. Configuration can be passed via:
 
-1. Example CLI arguments: `--cli-argument`
-1. Example TOML config file (`.mdformat.toml`):
+1. CLI arguments: `--sort-front-matter`, `--normalize-front-matter`, `--strict-front-matter`
+1. TOML config file (`.mdformat.toml`):
     ```toml
     [plugin.front_matters]
-    cli_argument = true
+    sort_front_matter = true
+    normalize_front_matter = "minimal"  # or "1.2" or "none"
+    strict_front_matter = true
     ```
-1. API: `mdformat.text(content, extensions={"front_matters"}, options={...})`
+1. API: `mdformat.text(content, extensions={"front_matters"}, options={"plugin": {"front_matters": {...}}})`
+
+Option semantics:
+
+- `sort_front_matter`: Sort keys alphabetically (default: preserve original order)
+- `normalize_front_matter`: YAML only — `"none"` (default) preserves everything; `"minimal"` strips unnecessary quotes, normalizes null (`~` → `null`) and boolean case; `"1.2"` additionally upgrades unquoted YAML 1.1 boolean words (`yes`/`no`/`on`/`off`) to `true`/`false`
+- `strict_front_matter`: Raise on invalid front matter instead of preserving it (default: preserve original content on error)
 
 ### Testing Strategy
 

README.md

@@ -13,7 +13,9 @@ An [mdformat](https://github.com/executablebooks/mdformat) plugin for normalizin
 
 - **Multi-format support**: Handles YAML (`---`), TOML (`+++`), and JSON (`{...}`) front matter
 - **Automatic normalization**: Formats front matter consistently (preserves key order by default, standardized indentation)
+- **Quote preservation**: YAML string quotes (`"double"`, `'single'`, `|` block literal, `>` block folded) are preserved by default
 - **Configurable sorting**: Option to sort keys alphabetically with `--sort-front-matter`
+- **YAML normalization modes**: `--normalize-front-matter {none,minimal,1.2}` — from style-only cleanup to full YAML 1.1 → 1.2 upgrade
 - **Error resilient**: Preserves original content if parsing fails. Will error only if `strict` mode is set
 - **Zero configuration**: Works out of the box with mdformat
 
@@ -102,6 +104,8 @@ pipx inject mdformat mdformat-front-matters
 
 ### Configuration Options
 
+All options are independent and composable — use any combination.
+
 #### Key Sorting
 
 By default, front matter keys preserve their original order. To sort keys alphabetically for consistency, use the `--sort-front-matter` flag.
@@ -114,6 +118,65 @@ mdformat document.md
 mdformat document.md --sort-front-matter
 ```
 
+#### YAML Normalization Modes
+
+Use `--normalize-front-matter` to apply progressively more opinionated YAML normalization. The flag accepts one of three values:
+
+| Mode             | What changes                                                 |
+| ---------------- | ------------------------------------------------------------ |
+| `none` (default) | Nothing — full round-trip, all styles preserved              |
+| `minimal`        | Strip unnecessary quotes + null normalization + boolean case |
+| `1.2`            | Everything in `minimal` + YAML 1.1 boolean word upgrade      |
+
+```sh
+# Default — preserve everything
+mdformat document.md
+
+# Strip quotes, normalize null and boolean casing
+mdformat document.md --normalize-front-matter minimal
+
+# Everything in minimal, plus upgrade YAML 1.1 boolean words
+mdformat document.md --normalize-front-matter 1.2
+```
+
+**`minimal` example:**
+
+```yaml
+# Before
+---
+title: "My Post"
+draft: True
+empty: ~
+---
+
+# After --normalize-front-matter minimal
+---
+title: My Post
+draft: true
+empty: null
+---
+```
+
+**`1.2` example** (additionally converts YAML 1.1 boolean words):
+
+```yaml
+# Before
+---
+draft: yes
+published: no
+label: "yes"
+---
+
+# After --normalize-front-matter 1.2
+---
+draft: true
+published: false
+label: yes
+---
+```
+
+Quotes that are semantically necessary are always preserved — values containing colons, empty strings, etc. Block scalar styles (`|` and `>`) are always preserved. Quoted `"yes"` or `'no'` remain as strings; only unquoted `yes`/`no`/`on`/`off` (and their capitalised variants) are treated as YAML 1.1 booleans. TOML and JSON are unaffected.
+
 #### Strict Mode
 
 Enable strict mode to fail on invalid front matter instead of preserving it. Useful for CI/CD pipelines.
@@ -141,6 +204,29 @@ repos:
           - mdformat-front-matters
 ```
 
+#### Configuration File
+
+All options can be set in `.mdformat.toml` instead of passing CLI flags:
+
+```toml
+[plugin.front_matters]
+sort_front_matter = true
+normalize_front_matter = "minimal"  # or "1.2" or "none"
+strict_front_matter = true
+```
+
+Or via the Python API:
+
+```python
+import mdformat
+
+mdformat.text(
+    content,
+    extensions={"front_matters"},
+    options={"plugin": {"front_matters": {"normalize_front_matter": "minimal"}}},
+)
+```
+
 ## HTML Rendering
 
 To hide Front Matter from generated HTML output, `front_matters_plugin` can be imported from `mdit_plugins`. For more guidance on `MarkdownIt`, see the docs: <https://markdown-it-py.readthedocs.io/en/latest/using.html#the-parser>