{"id":5315,"library":"mdformat-frontmatter","title":"mdformat-frontmatter","description":"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.","status":"active","version":"2.0.10","language":"en","source_language":"en","source_url":"https://github.com/butler54/mdformat-frontmatter","tags":["markdown","frontmatter","formatter","plugin","yaml","mdformat"],"install":[{"cmd":"pip install mdformat mdformat-frontmatter","lang":"bash","label":"Install with mdformat"}],"dependencies":[{"reason":"This is a plugin for mdformat, which is its host formatter.","package":"mdformat","optional":false},{"reason":"Used internally for parsing and formatting YAML front matter.","package":"ruamel.yaml","optional":false}],"imports":[{"note":"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.","symbol":"mdformat_frontmatter","correct":"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."}],"quickstart":{"code":"import mdformat\nimport os\n\n# Example Markdown with YAML front matter\nmarkdown_content = '''---\ntitle: My Document\ndate: 2026-04-13\n---\n\n# Hello, world!\n\nThis is some content below the front matter.\n'''.strip()\n\n# Format the content (mdformat auto-detects installed plugins)\nformatted_content = mdformat.text(markdown_content)\n\nprint(\"Original content:\\n\" + markdown_content)\nprint(\"\\nFormatted content:\\n\" + formatted_content)\n\n# CLI usage (assuming mdformat and mdformat-frontmatter are installed):\n# echo -e \"---\\ntitle: My Document\\n---\\n\\n# Hello\" | mdformat -\n","lang":"python","description":"Install `mdformat` and `mdformat-frontmatter`, then use `mdformat` via its CLI or Python API. The plugin will automatically format YAML front matter."},"warnings":[{"fix":"Ensure your front matter is strictly YAML. For other formats, use a different plugin.","message":"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').","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always ensure your front matter adheres to valid YAML syntax and structure.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions, particularly across major/minor `mdformat` updates"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<2.0.7"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}