mkdocs-include-markdown-plugin

What it is and what it does

This plugin extends MkDocs by adding template directives that let you include content from other Markdown files or any file type directly into your documentation. Instead of duplicating content across multiple pages, you write an include directive (like `{% include-markdown "path/to/file.md" %}`) and the plugin pulls that content in at build time. It supports filtering included content by start and end delimiters, rewriting relative URLs so links work in their new location, adjusting heading levels, and including from remote URLs with optional HTTP caching.

The plugin is configured in your mkdocs.yml file and offers many customization options: you can change the directive syntax, set default encoding, control indentation and dedenting behavior, exclude files by pattern, and define the order in which multiple files are included when using glob patterns. It depends on mkdocs and wcmatch for pattern matching, both common and lightweight dependencies.

Use it for

• Keep a single README or license file in your repo root and include it in your documentation without maintaining a copy.
• Build API documentation by including code examples or snippets from your source files, keeping them in sync automatically.
• Compose documentation pages from reusable template fragments stored in an includes directory.
• Include release notes or changelog entries from remote URLs into your site without manual updates.
• Adjust heading levels when including content so it fits correctly into your documentation hierarchy.

Worth the install?

AI-flagged interpretation of the facts on this page. Verify before relying on it.

Install

mkdocs-include-markdown-plugin on PyPI

Before you install

Low friction install with only 2 runtime dependencies (mkdocs and wcmatch). Actively maintained with a recent release; last commit 2026-07-01 and 151 repository stars indicate ongoing support.

License in practice

Licensed under Apache-2.0 (permissive), allowing commercial and private use with minimal restrictions—suitable for most projects.

Quickstart

pip install mkdocs-include-markdown-plugin

# In mkdocs.yml:
plugins:
  - include-markdown

# In your Markdown:
{% include-markdown "../README.md" start="<!--start-->" end="<!--end-->" %}

Package facts

Evidence: mkdocs_include_markdown_plugin-7.3.0-py3-none-any.whl

Tags

More Text Processing packages

See also mkdocs-autorefs · mkdocs-exclude · mkdocs-same-dir · mkdocs-video · mkdocs-redirects · condor-git-config · mkdocs-meta-manager · mdx-include · mkdocs-htmlproofer-plugin · mkdocs-table-reader-plugin