The mkdocs-include-markdown-plugin enhances MkDocs by allowing users to include content from other Markdown files, or parts of files, directly into their pages. It supports various features like fragment inclusion, heading offset, and line ranges. The current version is 7.2.2, with active development and frequent minor releases.
pip install mkdocs-include-markdown-pluginVerified import paths — ran on the pinned version, not inferred.
To use the plugin, first install it. Then, enable it in your `mkdocs.yml` file under the `plugins` section. Create a Markdown file (e.g., `docs/index.md`) and use the `{!include path/to/file.md!}` syntax to embed content from another Markdown file (e.g., `docs/includes/snippet.md`).
Ensure `include-markdown` is listed under the `plugins` section in your `mkdocs.yml`.
Verify the relative path from the *parent* Markdown file to the *included* Markdown file. Use `.` for current directory, `..` for parent directory.
Always use the `{!include ...!}` syntax provided by the plugin for directives. Be mindful of potential conflicts if other plugins or themes also use similar curly bracket syntax.Carefully test `heading-offset` values. A positive offset increases heading levels (e.g., `#` becomes `##`), while a negative offset decreases them. Use `0` for no change.
First, ensure the plugin is installed: `pip install mkdocs-include-markdown-plugin`. Then, add or verify its entry in `mkdocs.yml` under the `plugins` section: ```yaml plugins: - include-markdown ```
If the tag is not intended to be processed by the plugin, escape it using Jinja2's `{% raw %}` and `{% endraw %}` tags to treat its content as literal text:
```markdown
{% raw %}{% some_tag %}{% endraw %}
```Verify the file path. Paths can be relative to the current Markdown file, relative to the `docs_dir`, or absolute. Ensure the file exists and the path is correctly specified, including any necessary `../` for parent directories.
Check for plugin conflicts, especially with `mkdocs-material`'s `offline` plugin (which had known issues). Ensure `mkdocs-include-markdown-plugin` is listed correctly in `mkdocs.yml`. If documenting the directive itself, place the example within a fenced code block (```markdown ... ```) which the plugin is designed to skip.