MkDocs Include Markdown Plugin

7.2.2 · active · verified Mon Apr 13

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.

Warnings

gotcha The plugin must be explicitly enabled in your `mkdocs.yml` file. If you forget to add `plugins: - include-markdown` (or similar for custom configuration), the `{!include ...!}` directives will not be processed and will appear as raw text in your output.
Fix: Ensure `include-markdown` is listed under the `plugins` section in your `mkdocs.yml`.
gotcha Paths specified in `{!include ...!}` directives are relative to the *current* Markdown file where the directive is used, not to the `docs` directory or the project root. Incorrect relative paths will lead to `FileNotFoundError`.
Fix: Verify the relative path from the *parent* Markdown file to the *included* Markdown file. Use `.` for current directory, `..` for parent directory.
gotcha The plugin uses `{!include ...!}` syntax for inclusion. This is distinct from Jinja2-style `{{ include ... }}`. Mixing these or using incorrect syntax will prevent content from being included.
Fix: 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.
gotcha The `heading-offset` argument (e.g., `{!include file.md:heading-offset=1!}`) applies a numeric offset to all headings within the included content. Incorrectly specifying or misunderstanding the offset can lead to unintended heading levels in the final output. While a bug with negative values was fixed in v7.1.7, ensure offsets are logical for your document structure.
Fix: 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.

Install

pip install mkdocs-include-markdown-plugin Install package

Imports

IncludeMarkdownPlugin
```
from mkdocs_include_markdown_plugin.plugin import IncludeMarkdownPlugin
```
This is the internal Python class. For common usage, you enable the plugin via your 'mkdocs.yml' file, not via direct Python import.

Quickstart

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`).

# mkdocs.yml
site_name: My Docs
plugins:
  - include-markdown

# docs/index.md
# This is your main Markdown file
---
# Welcome

This is the main content of my document.

Here's some content included from another file:

{!include includes/snippet.md!}

---

# docs/includes/snippet.md
# This is the file to be included
---
## Included Section

This text comes from 'includes/snippet.md'.

It can contain any Markdown.

view raw JSON →