includex
Use includex to include anything from any file into your markdown documentation.
Installation
pip install mkdocs-macros mkdocs-macros-includex
Usage
includex can be configured as a pluglet for mkdocs-macros in the mkdocs.yml configuration file:
plugins:
- search
- macros:
modules: ['includex']
Then you can use it to dynamically include file content in your documentation
### 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:
[tool.hatch.version]
path = "includex.py"
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.1 Further, v9.7 added to support to sections by name, given that they are marked as such using a special marker comment.2
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.
Metadata
Release files for mkdocs-macros-includex 0.0.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mkdocs_macros_includex-0.0.6.tar.gz | 16.0 kB | Without provenance | Details for mkdocs_macros_includex-0.0.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mkdocs_macros_includex-0.0.6-py3-none-any.whl | Python 3 | none | any | Details for mkdocs_macros_includex-0.0.6-py3-none-any.whl |
Total release size: 24.3 kB
Release files / mkdocs_macros_includex-0.0.6.tar.gz
| Download URL | mkdocs_macros_includex-0.0.6.tar.gz |
|---|---|
| Size | 16.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
613fdecc5d1caf86db30662e3bbc42335eeee4e16aad7bd2dbd6b8129fcd8eac
|
|
BLAKE2b-256 checksum How to use checksums |
20a5d430b612d61d0f412ff696bed883e4d4445231553d6da236037cb3ae8142
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
python-httpx/0.24.1
|
Release files / mkdocs_macros_includex-0.0.6-py3-none-any.whl
| Download URL | mkdocs_macros_includex-0.0.6-py3-none-any.whl |
|---|---|
| Size | 8.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
521988166eb78ed52c843ddc787e6b4a0dd365cecd2c320fd87883c6d90d6004
|
|
BLAKE2b-256 checksum How to use checksums |
cb4bb43691a6005eb327e6b8c23bef447abbf124d38457881bee82dc276bbc4d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
python-httpx/0.24.1
|
Security for mkdocs-macros-includex 0.0.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.