mdformat-front-matters

What it is and what it does

mdformat-front-matters is a plugin that extends mdformat to recognize and normalize front matter (metadata blocks) in Markdown files. It handles three formats: YAML (delimited by `---`), TOML (delimited by `+++`), and JSON (block syntax). The plugin preserves the original key order by default but can sort keys alphabetically with a flag, and it includes a strict mode that fails on invalid front matter rather than silently preserving it.

The package is designed to work zero-configuration once installed alongside mdformat—it auto-registers as a plugin. It depends on mdformat as its host, mdit-py-plugins for Markdown parsing integration, ruamel-yaml for YAML handling, and toml for TOML support. It's intended for developers managing Markdown documents with metadata, particularly in static site generators, documentation systems, or content pipelines where consistent front matter formatting matters.

Use it for:

• Enforce consistent front matter formatting across a documentation site or blog built with a static site generator.
• Validate and normalize YAML front matter in Jekyll, Hugo, or similar Markdown-based projects via pre-commit hooks.
• Sort front matter keys alphabetically in CI/CD pipelines to reduce merge conflicts in version control.
• Fail builds when front matter is malformed using strict mode in automated documentation workflows.
• Normalize mixed YAML/TOML/JSON front matter in heterogeneous Markdown repositories to a single standard format.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A plugin for mdformat that normalizes YAML, TOML, and JSON front matter in Markdown documents, with optional key sorting and strict validation modes.

Yes, if you use mdformat and need to normalize front matter in Markdown files. Install friction is low, dependencies are stable, and the plugin is actively maintained. No known vulnerabilities. MIT license is permissive. The only caveat is that the repository is small and young (first release October 2025), so community adoption and long-term support are not yet proven.

Install

mdformat-front-matters on PyPI

pip install mdformat-front-matters

uv add mdformat-front-matters

poetry add mdformat-front-matters

Installing mdformat-front-matters

Before you install

Low friction install as a pure Python wheel. Active maintenance with recent release (2025-12-04), though repository is small (8 stars). Depends on mdformat and parsing libraries (mdit-py-plugins, ruamel-yaml, toml) that are stable, widely-used packages.

License in practice

MIT license (permissive) means you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart

pip install mdformat mdformat-front-matters

mdformat document.md

# Or with key sorting:
mdformat document.md --sort-front-matter

Requires Python 3.10 or later. mdformat must be installed separately or alongside this plugin.

Verify before relying

• Whether the plugin correctly handles edge cases like malformed front matter in non-strict mode across all three formats.
• Performance characteristics when processing large documents or many files with complex nested front matter structures.

Package facts

Evidence: mdformat_front_matters-2.0.0-py3-none-any.whl

Keywords: markdown, markdown-it, mdformat, mdformat_plugin_template

Tags

More Python Modules packages