---
id: mdformat-front-matters
version: "2.0.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# mdformat-front-matters — An mdformat plugin to format YAML, TOML, or JSON front matter

License: permissive · Maintenance: active · Downloads: 96.5K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 96.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

markdown front matter formatter, mdformat plugin yaml toml json, normalize markdown metadata, front matter normalization, markdown front matter plugin, yaml front matter formatter, mdformat extension, markdown-tooling, static-site-generators

[View on SkillFed](https://skillfed.io/packages/mdformat-front-matters) · [View on PyPI](https://pypi.org/project/mdformat-front-matters/)