mkdocs-macros-includex 0.0.3

Provides the `includex` macro for more flexible includes.

includex

This is a pluglet for mkdocs-macros. It allows to include arbitrary files in mkdocs (similar to snippets or jinja include) with added convenience.

Installation

pip install mkdocs-macros-includex

Usage

In the config (mkdocs.yml) file:

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

Comparison to other tools

snippets (pymdown-extensions)

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:

{% 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.