md-transformer

md-transformer is a powerful tool for dynamic documentation. It allows you to execute code cells, save snippets to files, and include live Python source code directly into your Markdown documents.

It works seamlessly with MkDocs, Zensical, or as a standalone CLI tool.

Documentation: https://md-transformer.readthedocs.io/

Core Features

• 🚀 Live Execution: Run shell commands and include their output in your docs.
• 💾 Snippet Management: Write code in Markdown and automatically save it to files.
• 🐍 Python Integration: Include the source code of any importable Python object.
• 🔧 Extensible: Create your own Markdown transformers using a simple Python API.
• 📦 Multi-Tool Support: Use it as an MkDocs plugin, a Zensical extension, or via the CLI.

Quick Start

1. Save and Execute Python Code

Use the python-code fence to save code to a file, and bash-execute to run it and show the output.

```python-code hello.py
print("Hello from md-transformer!")
```

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

Result:

# hello.py

print("Hello from md-transformer!")

$ python hello.py
Hello from md-transformer!

2. Include Python Source

Include the source code of any function or class using include-python.

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

Result:

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)

Installation

pip install md-transformer

Documentation

For detailed information, please refer to our full documentation:

• 📖 Usage Guide: Detailed integration instructions for MkDocs, Zensical, and the CLI.
• 🛠️ Technical Details: Information on execution environments and object resolution.
• 🧩 Custom Macros: How to extend the tool with your own macros.
• 🔌 API Reference: Full API documentation for developers.

License

This project is licensed under the MIT License.