Metadata-Version: 2.1
Name: mkdocs-macros-includex
Version: 0.0.6
Summary: Provides the `includex` macro for more flexible includes.
Author-email: Jannis Mainczyk <jmainczyk@gmail.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.7
Provides-Extra: pygments
Requires-Dist: pygments; extra == 'pygments'
Description-Content-Type: text/markdown

# `includex`

[![coverage](https://codecov.io/gh/jannismain/mkdocs-macros-includex/graph/badge.svg?token=852ISA32PH)](https://codecov.io/gh/jannismain/mkdocs-macros-includex) [![code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch)


Use `includex` to **include** *anything* from any file into your markdown documentation.

## Installation

```sh
pip install mkdocs-macros mkdocs-macros-includex
```

## Usage

`includex` can be configured as a **pluglet** for mkdocs-macros in the `mkdocs.yml` configuration file:

```yaml
plugins:
  - search
  - macros:
      modules: ['includex']
```

Then you can use it to dynamically include file content in your documentation

```md
### Versioning

The version number is defined in the `pyproject.toml` file:

{{ includex("pyproject.toml", start_match="[tool.hatch.version]", code=True, lines=2, caption=True) }}
```

which would be rendered as

---

### Versioning

The version number is defined in the `pyproject.toml` file:

```toml
[tool.hatch.version]
path = "includex.py"
```
<div style="text-align: center; font-style: italic;">pyproject.toml, lines 14-15</div>

---

<!-- TODO: Find out which markdown_extensions need to be enabled for which includex features and list them here -->

## Comparison to other tools

### snippets (pymdown-extensions)

**tl;dr**

- use *snippets* if you want to recursively include content
- use *includex* if you want to include content within macros
- use *includex* if you want to include sections without special markers

The main use case this solves over *[snippets][]* is that it includes partial content (i.e. a section or block) from a file as-is (i.e. without the need for special markers).

Snippets partially supports this now since v9.6 added support to include sections by lines.[^snippet-lines]
Further, v9.7 added to support to sections by name, given that they are marked as such using a special marker comment.[^snippet-sections]

What includex does additionally is to match the start and end of blocks and include them without the need for any markers or line numbers.
While this makes the documentation more prone to break, e.g., when the line that is being matched is changed in a way that it no longer matches, it supports some additional use-cases and requires less custom syntax.

*Snippets* is implemented as a preprocessor, while *includex* is implemented as a [mkdocs-macros][] pluglet. This means that snippets are evaluated earlier than *includex* and prohibits *snippets* to work with other macros, like this:

```jinja
{% for file in get_files("docs/") %}
{{ includex(file) }}
{% endfor %}
```

However, sections included using `includex` are not evaluated themselves, so `includex` cannot be nested (yet). If you need nested includes, use `snippets` instead.

<!-- TODO: nesting includes with snippets vs. includex? -->

<!-- ### mkdocs-include-markdown-plugin -->

[mkdocs-macros]: https://mkdocs-macros-plugin.readthedocs.io/
[snippets]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
[^snippet-lines]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippet-lines
[^snippet-sections]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippet-sections
[jinja include]: https://jinja.palletsprojects.com/en/3.1.x/templates/#include
