About¶

Introduction¶

md-transformer is a tool for MkDocs, Zensical, and a standalone CLI tool to execute code cells and thus create documentation dynamically.

The following code fence

```python-code test.py
print("hello world")
```

will lead to the following output

# test.py

print("hello world")

After that you can execute the script within markdown using

```bash-execute
$ python test.py
```

which will be rendered as follows:

$ python test.py
hello world

Including Python Source Code¶

You can also include the source code of any Python object (function, class, etc.) directly into your documentation using the include-python code fence (see Technical Details for how objects are resolved):

```include-python md_transformer.transformer.transform
```

which will be rendered as follows:

def transform(fh_in, fh_out, transformers, max_line_length=100):
    with MarkdownRenderer(max_line_length=max_line_length) as renderer:
        text = expand_includes(fh_in.read())
        doc = mistletoe.Document(text)
        _transform(doc, list(transformers) + [FixLinebreak()])
        print(renderer.render(doc), file=fh_out)

File Includes¶

You can include the content of external files directly into your documentation using the include tag. The syntax is {% include path/to/file.md %}.

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

This happens before any other transformations, allowing you to include files that themselves contain code fences or other macros.

More Information¶

For more details on how to integrate md-transformer into your projects and technical details on its execution environment, please refer to the Usage guide.

Installation¶

To use the plugin you can install it using pip or uv:

$ pip install md-transformer