mdformat-wiki

Mdformat plugin preserving wikilinks, frontmatter, and index delimiter.

Built for wikis created with plasma-wiki — add it wherever mdformat runs over a wiki maintained by plasma-wiki.

Source: https://github.com/plasma-ai/mdformat-wiki

Package: https://pypi.org/project/mdformat-wiki/

Installation

Install the mdformat-wiki package from PyPI, alongside mdformat:

pip install mdformat-wiki

Use uv tool install mdformat --with mdformat-wiki to install in an isolated environment.

Usage

Once installed, mdformat picks the plugin up automatically and stops disturbing wiki page faces:

• [[...]] wikilinks parse atomically (single line, no nesting) and are never backslash-escaped — including the [[target|label]] pipe form.
• Wikilinks are wrap-atomic: under --wrap, the whole [[...]] face moves between lines as one unit, like an inline code span, while the prose around it fills normally.
• YAML frontmatter at the start of a document renders byte-verbatim (fences and content untouched).
• A thematic break written exactly as *** keeps that face; every other break style is normalized as usual.
• ATX headings keep their original inline face verbatim — unbalanced emphasis is never backslash-escaped and an optional closing # sequence survives; setext headings still normalize to ATX.
• An index link-row description ([[target|label]]: text) renders its text verbatim — a bare * or _ (**kwargs, _verb) is never backslash-escaped — while still wrapping under --wrap. A row whose link alone exceeds the width breaks after ]]:, dropping the description to the next line.

pre-commit

Repos that format markdown with a pre-commit hook need one line — add the plugin to the mdformat hook's additional_dependencies:

  - repo: https://github.com/hukkin/mdformat
    rev: 1.0.0
    hooks:
      - id: mdformat
        additional_dependencies: [mdformat-wiki]

If the hook already lists mdformat-frontmatter, remove it — this plugin already renders frontmatter byte-verbatim. Both plugins register a frontmatter renderer, mdformat only warns about the conflict, and whichever the environment discovers first wins: when mdformat-frontmatter wins, it re-serializes the YAML (quoting values, blanking nulls) instead of leaving it untouched.

Footnotes

Baseline mdformat escapes footnote definitions ([^1]: becomes \[^1\]:). If your pages use footnotes, add mdformat-footnote alongside this plugin — the two compose cleanly (definitions relocate to the document bottom, which is semantically neutral).

Development

Install

Run install.sh in the package root. With no environment active it creates and uses a local .venv; with one active (e.g. pyenv) it installs into that environment (editable), without recreating it:

./install.sh --all-extras --groups=test,lint,type

Run ./install.sh --help for all options. Alternatively, run uv sync --all-extras --group test --group lint --group type and uv run pre-commit install to set up the environment manually.

Installing a dependency as editable (e.g. a sibling package) is left to the caller: uv pip install --editable <path>.

Once installed, run tools with uv run <command>, or activate the environment first (source .venv/bin/activate).

Tests

Run the test suite:

pytest .

Linting

Run linters and formatters:

pre-commit run --all-files

License

Licensed under the Apache License 2.0 — see LICENSE.

Copyright © 2026 Plasma AI