Metadata-Version: 2.4
Name: md-transformer
Version: 0.1.0
Summary: A tool for MkDocs and Zensical to execute code cells and create documentation dynamically.
Project-URL: Documentation, https://md-transformer.readthedocs.io/
Project-URL: Repository, https://gitlab.com/uweschmitt/md-transformer
Project-URL: Issues, https://gitlab.com/uweschmitt/md-transformer/-/issues
Author-email: Uwe Schmitt <uwe.schmitt@id.ethz.ch>
License-Expression: MIT
License-File: LICENSE.txt
Keywords: documentation,markdown,mkdocs,python,snippet,zensical
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Documentation
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.11
Requires-Dist: click>=8.1.7
Requires-Dist: mistletoe>=1.4.0
Requires-Dist: mkdocs-awesome-pages-plugin>=2.9.3
Requires-Dist: mkdocs-material>=9.5.42
Requires-Dist: mkdocstrings[python]>=0.26.2
Requires-Dist: zensical>=0.0.2
Description-Content-Type: text/markdown

# md-transformer

[![pipeline](https://gitlab.com/uweschmitt/md-transformer/badges/main/pipeline.svg)](https://gitlab.com/uweschmitt/md-transformer/-/commits/main)
[![coverage](https://gitlab.com/uweschmitt/md-transformer/badges/main/coverage.svg?job=coverage)](https://gitlab.com/uweschmitt/md-transformer/-/commits/main)

`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/](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:**

```python
# hello.py

print("Hello from md-transformer!")
```

```sh
$ 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:**

```python
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

```sh
pip install md-transformer
```

---

## Documentation

For detailed information, please refer to our full documentation:

*   📖 **[Usage Guide](docs/usage.md)**: Detailed integration instructions for MkDocs, Zensical, and
    the CLI.
*   🛠️ **[Technical Details](docs/usage.md#technical-details)**: Information on execution
    environments and object resolution.
*   🧩 **[Custom Macros](docs/usage.md#custom-macros)**: How to extend the tool with your own macros.
*   🔌 **[API Reference](docs/api.md)**: Full API documentation for developers.

## License

This project is licensed under the MIT License.

