mdformat-myst

Common errors

• Error: Unknown plugin: myst

  cause The `mdformat-myst` package is not installed or `mdformat` cannot find it.
  fix Run `pip install mdformat-myst` to ensure the plugin is installed in the same environment as `mdformat`.

• AttributeError: 'RootRenderer' object has no attribute 'render_dollarmath'

  cause This usually indicates an incompatibility between `mdformat-myst` and the core `mdformat` version, or a missing required dependency.
  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`.

• mdformat: error: unrecognized arguments: --plugin myst

  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.
  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.

• SyntaxError: invalid syntax (mdformat_myst.py, line XX)

  cause You are likely running an older Python version than required. `mdformat-myst>=0.2.2` requires Python 3.10+.
  fix Upgrade your Python environment to 3.10 or newer. If you must use an older Python, downgrade `mdformat-myst` to `<0.2.2`.

Warnings

• breaking 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.
  Fix: Upgrade Python to 3.10 or newer. For projects requiring older Python, pin `mdformat-myst<0.2.2`.
• breaking 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`.
  Fix: Ensure `mdformat-gfm` is installed. If manually managing `mdformat` plugins, remove `mdformat-tables` and add `mdformat-gfm`.
• breaking 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.
  Fix: Update your `requirements.txt` or `pyproject.toml` to use `mdformat-front-matters` instead of `mdformat-frontmatter`, ensuring the correct version is installed.
• gotcha 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.
  Fix: Always use `mdformat` as the entry point: `mdformat <file> --plugin myst` or `mdformat.text(..., extensions=('myst',))`.

Install

• pip install mdformat-myst Install latest version

Imports

• mdformat.text

  from mdformat import text

  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.

Quickstart

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`.

import os
from mdformat import text

# Example Markdown with MyST syntax
myst_markdown = """
---
title: MyST Example
author: Me
---

# MyST Title

````{myst-role}
This is a myst role content.
````

$$a^2 + b^2 = c^2$$

:::{note}
This is a MyST directive.
:::
"""

# --- Command Line Usage ---
# For command line, save the content to a file, e.g., 'example.md'
# Then run: mdformat example.md --plugin myst

# --- Python API Usage ---
formatted_text = text(myst_markdown, extensions=("myst",))
print(formatted_text)

# To verify it's formatted by mdformat-myst
# Note: This is a simplified check, actual verification requires inspecting output
assert ':::{note}' in formatted_text or '$a^2 + b^2 = c^2$' in formatted_text, \
    "MyST specific elements should be preserved/formatted."