mdformat-directives

An mdformat plugin for generic directives, the :::name[label]{key="value"} syntax of remark-directive and dokk:

:::note[A title]{kind="info"}
Markdown inside is **formatted**; the fences stay where they are.
:::

::install[dokk[search]]

Without it, mdformat sees ::: as text: it pulls closing fences into lists and reflows the blocks.

Install

pipx install mdformat
pipx inject mdformat mdformat-directives

Use

mdformat docs

• Blocks :::name (three or more colons) are kept, with the Markdown inside formatted. To nest, give the outer block more colons; the count is kept.
• One-line directives ::name[label]{attrs} are kept as written.
• Text directives such as :badge[New]{variant="secondary"} are kept as written, also where another plugin would escape their colon.

Raw blocks

Some blocks hold data, not Markdown, such as .env lines whose columns line up. Keep their body exactly as written in .mdformat.toml:

[plugin.directives]
raw = ["env", "bench"]

or on the command line: mdformat --raw-directives env,bench docs.

Development

uv sync --all-extras
make lint   # ruff fix and format, ty, pytest

Releasing

The version comes from the git tag (hatch-vcs); there is nothing to bump. Push a tag such as v0.1.0 and .github/workflows/release.yml builds the wheel and sdist and tests the wheel. Once the pypi environment is approved, it publishes to PyPI and creates the GitHub release.

Before the first release, on PyPI add a trusted publisher (pending publisher) for this repository, workflow release.yml, environment pypi; on GitHub create the pypi environment with a required reviewer (Settings > Environments).