feat: add --normalize-front-matter

[KyleKing]

No description provided.

[coderabbitai]

Walkthrough

This PR extends the front-matter plugin with configurable YAML normalization capabilities. It introduces a new --normalize-front-matter CLI option (with modes: none, minimal, 1.2) and updates the YAML handling implementation to use a RoundTripYAMLHandler that supports mode-specific transformations such as converting YAML 1.1 boolean words (yes/no/on/off) to YAML 1.2 equivalents and normalizing null representations. The public formatter APIs now accept a normalize_mode parameter, and documentation is updated with configuration examples and normalization behavior specifications. Two new test fixtures validate quote preservation and normalization across different modes.

Possibly related PRs

• fix: preserve YAML string quotes by setting preserve_quotes=True #13: Modifies mdformat_front_matters/_formatters.py to preserve YAML string quotes via preserve_quotes=True configuration, overlapping directly with this PR's RoundTripYAMLHandler implementation and ruamel.yaml quote preservation logic.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@mdformat_front_matters/_formatters.py`:
- Around line 58-83: The representer registrations for
_NullNormalizingRepresenter (the add_representer calls for type(None),
SingleQuotedScalarString, and DoubleQuotedScalarString which reference
_represent_as_plain_str) should be co-located with the class: move those
add_representer calls into the class body immediately after its docstring (or
implement __init_subclass__ on _NullNormalizingRepresenter to perform the
registrations at subclass creation), so the registration and the explanatory
docstring live together; ensure the lambda for null and the
_represent_as_plain_str reference remain unchanged and still target the same
tags/types.

In `@tests/format/fixtures/normalization.md`:
- Around line 39-52: The test title "YAML null unchanged under none" is
misleading because input `key: ~` is serialized as `key:` (representation
changed), so either rename the test to reflect that the representation is
normalized (e.g., "YAML null representation normalized (~ -> implicit) under
none") or update the code path that serializes YAML in "none" mode to preserve
`~` by adding a custom null representer in the ruamel.yaml serialization
routine; locate the test string "YAML null unchanged under none" in
normalization.md to change the title, or locate the YAML serializer/normalizer
function that handles "none" mode (the routine that invokes ruamel.yaml dumping)
and add/configure a null representer so `~` is preserved.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 87b5e923-ebf5-46b2-bff9-c5e094d9dc2f

📥 Commits

Reviewing files that changed from the base of the PR and between ee81761 and dd0c453.

📒 Files selected for processing (7)

• AGENTS.md
• README.md
• mdformat_front_matters/_formatters.py
• mdformat_front_matters/plugin.py
• tests/format/fixtures/normalization.md
• tests/format/fixtures/quote_preservation.md
• tests/format/test_format.py