Skip to content

Usage

md-transformer supports three primary workflows: as an MkDocs plugin, as a Zensical/Python-Markdown extension, or as a standalone CLI tool.

Integration Methods

MkDocs Plugin

To use it with MkDocs, add it to the plugins section of your mkdocs.yml:

plugins:
  - md-transformer

Zensical / Python-Markdown Extension

To use it with Zensical or any tool that supports python-markdown extensions, add it to your configuration:

zensical.toml: 

[project.markdown_extensions]
"md_transformer.markdown_extension" = {}

python: 

import markdown
html = markdown.markdown(text, extensions=["md_transformer.markdown_extension"])

Command Line Interface

You can also process Markdown files directly:

# Install via uv
uv tool install md-transformer

# Process a file and output to stdout
md-transformer input.md > output.md

# Set a custom line length for wrapped code
md-transformer --max-line-length 80 input.md > output.md

Technical Details

include-python Resolution

The include-python code fence uses standard Python import logic to find objects. The argument must be a fully-qualified name:

  • module.function
  • package.module.Class
  • package.module.Class.method

The object must be importable in the environment where md-transformer is running.

Execution Environment

When running via the CLI or during a documentation build (MkDocs, Zensical), a unique temporary directory is created for each execution. This directory is:

  1. Used as the destination for python-code code fences.
  2. Set as the current working directory for all bash-execute commands.

File Includes

The include tag allows you to pull in the content of external files. The syntax is {% include path/to/file.md %}.

{% include path/to/file.md %}

Technical Details

  • Early Processing: Includes are resolved before the Markdown is parsed into a tree. This means the included content can contain its own code fences, macros, or other md-transformer tags.
  • Path Resolution: Paths are relative to the current working directory where md-transformer is executed.
  • Error Handling: If an included file is not found, a FileNotFoundError will be raised (terminating the build).

Custom Macros

Beyond code fences, md-transformer also supports custom macros that can be expanded within your Markdown text. These are useful for dynamic content that isn't a code block.

MacroExpander

The MacroExpander base class allows you to define your own {% command ... %} tags. To use it, you must create a subclass and implement the expand method:

from md_transformer import MacroExpander, transform_text

class GreetingExpander(MacroExpander):
    command = "hello"

    def expand(self, name):
        return f"Hello, {name}!"

text = "This is a message: {% hello World %}"
transformed = transform_text(text, [GreetingExpander()])
# Result: "This is a message: Hello, World!"

The arguments inside the {% ... %} tags are parsed using shell-like rules, so you can use quotes for arguments with spaces: {% hello "Ms. World" %}.