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

A MkDocs plugin that includes content from Markdown files or other file types into your documentation using template directives, with support for filtering by delimiters, rewriting relative URLs, and including from remote URLs.

Yes. This is a mature, actively maintained plugin (Production/Stable status, recent release) with low install friction and no known vulnerabilities. It solves a real documentation problem—content reuse—and is widely used. Apache-2.0 license is permissive. Install it if you want to reduce documentation duplication in MkDocs.

Install

mkdocs-include-markdown-plugin on PyPI

pip install mkdocs-include-markdown-plugin

uv add mkdocs-include-markdown-plugin

poetry add mkdocs-include-markdown-plugin

Installing mkdocs-include-markdown-plugin

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-->" %}

Verify before relying

• Whether the plugin handles circular includes or has safeguards against infinite recursion when recursive=true
• Performance characteristics when including many files via glob patterns or from remote URLs
• Compatibility with popular MkDocs themes beyond core MkDocs

Package facts

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

Keywords: includer, markdown, mkdocs, plugin

Tags

More Text Processing packages