mdformat-frontmatter

2.0.10 · active · verified Mon Apr 13

An `mdformat` plugin for ensuring that YAML front-matter is respected and formatted within Markdown files. It supports YAML front matter typically used by tools like Jekyll. The current version is 2.0.10, and it maintains an active release cadence with regular updates and fixes.

Warnings

gotcha mdformat-frontmatter explicitly supports only YAML front matter. If you require formatting for TOML or JSON front matter, consider alternative plugins like `mdformat-front-matters` (with an 's').
Fix: Ensure your front matter is strictly YAML. For other formats, use a different plugin.
gotcha Incorrectly formed YAML front matter blocks may lead to unexpected behavior or formatting issues. The plugin's primary objective is to allow properly formed YAML headers to pass through.
Fix: Always ensure your front matter adheres to valid YAML syntax and structure.
breaking The formatting style produced by `mdformat` (and thus its plugins) can change between versions. This may lead to inconsistent output if `mdformat` itself is not pinned.
Fix: Pin the version of `mdformat` in your project dependencies (e.g., `mdformat==1.0.0`) to ensure consistent formatting results across environments and builds.
gotcha Prior to v2.0.7, `ruamel.yaml`'s default line-breaking behavior could introduce unexpected wraps within front matter. This was fixed in v2.0.7 to ensure `ruamel.yaml` does not wrap lines.
Fix: Upgrade to `mdformat-frontmatter` version 2.0.7 or newer to benefit from the fix that ensures `ruamel.yaml` does not wrap lines in front matter.

Install

pip install mdformat mdformat-frontmatter Install with mdformat

Imports

mdformat_frontmatter
```
This is a plugin that mdformat auto-detects upon installation. No direct import statement for `mdformat_frontmatter` is typically needed by the end-user to apply its formatting functionality.
```
mdformat plugins are usually enabled by simply being installed in the environment where mdformat is run. For programmatic use, mdformat.text or mdformat.file will automatically use installed plugins.

Quickstart

Install `mdformat` and `mdformat-frontmatter`, then use `mdformat` via its CLI or Python API. The plugin will automatically format YAML front matter.

import mdformat
import os

# Example Markdown with YAML front matter
markdown_content = '''---
title: My Document
date: 2026-04-13
---

# Hello, world!

This is some content below the front matter.
'''.strip()

# Format the content (mdformat auto-detects installed plugins)
formatted_content = mdformat.text(markdown_content)

print("Original content:\n" + markdown_content)
print("\nFormatted content:\n" + formatted_content)

# CLI usage (assuming mdformat and mdformat-frontmatter are installed):
# echo -e "---\ntitle: My Document\n---\n\n# Hello" | mdformat -

view raw JSON →