{"id":24023,"library":"mdformat-front-matters","title":"mdformat-front-matters","description":"An mdformat plugin for formatting YAML, TOML, or JSON front matter in Markdown files. Current version: 2.0.0. Release cadence is irregular; major version bumps when there are breaking changes in mdformat or plugin API.","status":"active","version":"2.0.0","language":"python","source_language":"en","source_url":"https://github.com/butlerx/mdformat-front-matters","tags":["mdformat","plugin","front-matter","yaml","toml","json","markdown"],"install":[{"cmd":"pip install mdformat-front-matters","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Core required dependency","package":"mdformat","optional":false},{"reason":"Required for TOML front matter parsing (Python <3.11)","package":"tomli","optional":true},{"reason":"Used for YAML front matter parsing","package":"pyyaml","optional":true}],"imports":[{"note":"No common mistake—just import the package to register the plugin automatically.","wrong":"","symbol":"mdformat_front_matters","correct":"import mdformat_front_matters"}],"quickstart":{"code":"import mdformat_front_matters\nimport mdformat\n\n# Format a markdown string with YAML front matter\nformatted = mdformat.text('---\\ntitle: My Doc\\n---\\n\\nHello, world!', options={\n    'wrap': 80,\n    'end_of_line': 'lf'\n})\nprint(formatted)","lang":"python","description":"Importing the plugin automatically registers it with mdformat. Then use mdformat.text() or mdformat.file() as usual."},"warnings":[{"fix":"Upgrade Python to 3.10 or higher.","message":"Version 2.0.0 drops support for Python <3.10. Ensure you're using Python 3.10+.","severity":"breaking","affected_versions":"2.0.0+"},{"fix":"Update CLI or API calls to use `prefer_style` instead of `front_matter_style`.","message":"The option --front-matter-style has been renamed to --prefer-style. Old style may be removed in future.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Ensure `import mdformat_front_matters` is called before any mdformat formatting.","message":"Plugin auto-registers on import; if you import it after calling mdformat functions, plugin won't be active.","severity":"gotcha","affected_versions":"all"},{"fix":"Explicitly list plugins in `mdformat` options or control plugin loading order via Python code.","message":"When using with other mdformat plugins, ordering may affect behavior if multiple plugins modify front matter. Check plugin priority.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use `import mdformat_front_matters` without any submodule.","cause":"Incorrect import path: the package is not a module with submodules; just `import mdformat_front_matters` works.","error":"ImportError: cannot import name 'mdformat_front_matters' from 'mdformat_front_matters'"},{"fix":"Use `prefer_style` instead of `front_matter_style` in mdformat options.","cause":"Option name changed in v2.0.0 from `front_matter_style` to `prefer_style`.","error":"mdformat.errors.MdformatConfigError: Unknown option 'front_matter_style'"},{"fix":"Ensure the file path is correct and the file exists.","cause":"mdformat.file() expects a path to an existing file. This is a general mdformat gotcha.","error":"FileNotFoundError: [Errno 2] No such file or directory: '...' (when using mdformat.file())"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}