{"id":9932,"library":"mdformat-myst","title":"mdformat-myst","description":"mdformat-myst is a plugin for the mdformat Markdown formatter, providing compatibility with MyST (Markedly Structured Text) Markdown syntax. It enables mdformat to correctly parse and format MyST-specific elements like directives, roles, and math blocks. The current version is 0.3.0, and it follows an active release cadence, frequently updating to support new mdformat features and MyST specifications.","status":"active","version":"0.3.0","language":"en","source_language":"en","source_url":"https://github.com/hukkinj1/mdformat-myst","tags":["markdown","myst","mdformat","formatter","plugin","documentation"],"install":[{"cmd":"pip install mdformat-myst","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency; mdformat-myst is a plugin for mdformat.","package":"mdformat","optional":false},{"reason":"Required for handling MyST front-matter blocks.","package":"mdformat-front-matters","optional":false},{"reason":"Required for handling MyST-compatible tables, replacing mdformat-tables.","package":"mdformat-gfm","optional":false},{"reason":"Required for handling MyST-compatible footnotes.","package":"mdformat-footnote","optional":false}],"imports":[{"note":"mdformat-myst is typically used by passing its name ('myst') as an extension to mdformat, rather than direct import of mdformat-myst itself. The mdformat.text function is the primary programmatic interface.","symbol":"mdformat.text","correct":"from mdformat import text"}],"quickstart":{"code":"import os\nfrom mdformat import text\n\n# Example Markdown with MyST syntax\nmyst_markdown = \"\"\"\n---\ntitle: MyST Example\nauthor: Me\n---\n\n# MyST Title\n\n````{myst-role}\nThis is a myst role content.\n````\n\n$$a^2 + b^2 = c^2$$\n\n:::{note}\nThis is a MyST directive.\n:::\n\"\"\"\n\n# --- Command Line Usage ---\n# For command line, save the content to a file, e.g., 'example.md'\n# Then run: mdformat example.md --plugin myst\n\n# --- Python API Usage ---\nformatted_text = text(myst_markdown, extensions=(\"myst\",))\nprint(formatted_text)\n\n# To verify it's formatted by mdformat-myst\n# Note: This is a simplified check, actual verification requires inspecting output\nassert ':::{note}' in formatted_text or '$a^2 + b^2 = c^2$' in formatted_text, \\\n    \"MyST specific elements should be preserved/formatted.\"\n","lang":"python","description":"To use mdformat-myst, you invoke `mdformat` from the command line or use its Python API, specifying `myst` as an enabled extension or plugin. The plugin automatically integrates with `mdformat` to handle MyST-specific syntax. The example demonstrates programmatic usage; for command line, save the MyST markdown to a file and run `mdformat <file> --plugin myst`."},"warnings":[{"fix":"Upgrade Python to 3.10 or newer. For projects requiring older Python, pin `mdformat-myst<0.2.2`.","message":"Python 3.8 support was dropped in version 0.2.2. Users on Python 3.8 or older will need to upgrade their Python version to 3.10+ or pin mdformat-myst to a version prior to 0.2.2.","severity":"breaking","affected_versions":">=0.2.2"},{"fix":"Ensure `mdformat-gfm` is installed. If manually managing `mdformat` plugins, remove `mdformat-tables` and add `mdformat-gfm`.","message":"In version 0.3.0, the internal dependency for table formatting changed from `mdformat-tables` to `mdformat-gfm`. If your project explicitly relied on `mdformat-tables` for MyST table formatting, you should now ensure `mdformat-gfm` is installed and properly configured if you were not already using it. This is automatically handled if you just `pip install mdformat-myst`.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"Update your `requirements.txt` or `pyproject.toml` to use `mdformat-front-matters` instead of `mdformat-frontmatter`, ensuring the correct version is installed.","message":"Version 0.3.0 replaced `mdformat-frontmatter` with `mdformat-front-matters` for handling front matter. This is a name change of a required dependency. Users with specific pinning of `mdformat-frontmatter` might experience issues.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"Always use `mdformat` as the entry point: `mdformat <file> --plugin myst` or `mdformat.text(..., extensions=('myst',))`.","message":"mdformat-myst is an extension for mdformat; it does not provide a standalone executable. To use it, you must install `mdformat` separately and then invoke `mdformat` with the `--plugin myst` flag or `extensions=('myst',)` in the Python API.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Run `pip install mdformat-myst` to ensure the plugin is installed in the same environment as `mdformat`.","cause":"The `mdformat-myst` package is not installed or `mdformat` cannot find it.","error":"Error: Unknown plugin: myst"},{"fix":"Ensure `mdformat` and all its direct dependencies (e.g., `mdit-py-plugins`) are compatible with your `mdformat-myst` version. Try `pip install --upgrade mdformat mdformat-myst`.","cause":"This usually indicates an incompatibility between `mdformat-myst` and the core `mdformat` version, or a missing required dependency.","error":"AttributeError: 'RootRenderer' object has no attribute 'render_dollarmath'"},{"fix":"Verify `mdformat-myst` is installed and `mdformat` is up-to-date (`pip install --upgrade mdformat mdformat-myst`). Also ensure the correct plugin name `myst` is used.","cause":"This error means mdformat itself is installed, but `mdformat-myst` is not, or the installed `mdformat` version is too old to support the `--plugin` flag or dynamic plugin loading, or the plugin name 'myst' is not recognized.","error":"mdformat: error: unrecognized arguments: --plugin myst"},{"fix":"Upgrade your Python environment to 3.10 or newer. If you must use an older Python, downgrade `mdformat-myst` to `<0.2.2`.","cause":"You are likely running an older Python version than required. `mdformat-myst>=0.2.2` requires Python 3.10+.","error":"SyntaxError: invalid syntax (mdformat_myst.py, line XX)"}]}