markdown-include

What it is and what it does

Markdown-Include is a Markdown extension that adds an include mechanism similar to LaTeX's \input or C's #include preprocessor. It lets you reference external files within Markdown using the {!filename!} syntax, and those files are inserted and processed as part of the document before Markdown rendering. This is useful for breaking large documentation into smaller, reusable pieces and for embedding code snippets or shared content blocks.

The extension supports selective line inclusion (via lines=1 3 8-10 syntax), recursive includes, and heading-depth inheritance so that included files' headings adjust to their context. It depends only on markdown and is configured either programmatically or via MkDocs YAML. The package is marked Production/Stable and has been in use since its first release in 2015, though it has entered a dormant maintenance phase.

Use it for:

• Modularize large documentation projects by splitting content into separate files and including them from a main document.
• Embed code snippets or examples from source files into documentation without manual copy-paste.
• Reuse common sections (e.g., disclaimers, headers, footers) across multiple Markdown documents.
• Build MkDocs sites where documentation is composed from multiple source files with a single base_path.
• Include specific line ranges from files to show only relevant portions of code or configuration.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Adds an include directive to Python-Markdown that lets you embed the contents of other files into Markdown documents, with support for line-range selection and heading-depth adjustment.

Yes, if you need file inclusion in Markdown. The package is stable, has low install friction, no known vulnerabilities, and solves a real problem for modular documentation. The dormant maintenance is a minor concern—monitor compatibility with future markdown releases—but the simple scope suggests it is unlikely to break for routine use.

Install

markdown-include on PyPI

pip install markdown-include

uv add markdown-include

poetry add markdown-include

Installing markdown-include

Before you install

Low friction: pure Python wheel with a single runtime dependency on markdown. Maintenance is dormant—last release was 2023-02-07—but the package is marked Production/Stable and has no known vulnerabilities, so it is unlikely to require active updates for basic use.

License in practice

Licensed under GNU General Public License v3 (GPLv3) (copyleft). Any project that includes this package must comply with GPLv3 terms, including making source code available under the same license if you distribute the combined work.

Quickstart

pip install markdown-include

import markdown
html = markdown.markdown(source, extensions=['markdown_include.include'])

# In Markdown files, use: {!filename!}

Requires Python >=3.7. Requires markdown to be installed as a runtime dependency.

Verify before relying

• Whether the package works correctly with recent versions of markdown beyond version 3.4.
• Whether the dormant maintenance status (last commit 2024-05-10, last release 2023-02-07) poses a risk for future Python or markdown compatibility.

Package facts

Evidence: markdown_include-0.8.1-py3-none-any.whl

Keywords: Markdown, typesetting, include, plugin, extension

Tags

More Python Modules packages