mdx-include

What it is and what it does

mdx_include is a Markdown extension that lets you insert the contents of local files or remote URLs directly into your Markdown documents using a simple brace syntax like `{! file.md !}`. It handles recursive inclusion (files can include other files), file slicing by line and column ranges, content caching to avoid re-reading the same file multiple times, and circular inclusion detection. The extension depends on Markdown, rcslice for line/column slicing, and cyclic for circular dependency detection.

The package is motivated by an earlier markdown-include project but adds features like per-inclusion recursion control, indentation preservation, and configurable syntax delimiters. It's designed for documentation workflows where you want to keep content DRY by including shared snippets or examples from source files. Configuration options let you control recursion depth, encoding, caching behavior, and whether to allow local vs. remote includes.

Use it for:

• Include code examples from source files into API documentation, keeping examples in sync with actual code.
• Build modular documentation by including shared sections (e.g., common setup steps) into multiple markdown files.
• Embed test fixtures or sample data files into markdown test reports or guides without manual copy-paste.
• Fetch and embed remote markdown or text files into a local document during build time.
• Slice and include only relevant portions of large files (e.g., a specific function from a source file) using line/column ranges.

Worth the install?

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

A Markdown extension that embeds local or remote files into Markdown documents at specified positions, with support for recursive inclusion, file slicing, and content caching.

Yes, if you need file inclusion in Markdown and can tolerate dormant maintenance. The package is stable and has no known vulnerabilities, but it has not been updated since mid-2022. Install it for documentation tooling where you want to embed local or remote files, but do not expect active support or updates for new Markdown or Python versions.

Install

mdx-include on PyPI

pip install mdx-include

uv add mdx-include

poetry add mdx-include

Installing mdx-include

Before you install

Low install friction with a pure Python wheel. Maintenance is dormant—last release was 2022-07-26 and no commits since 2024-03-16—so expect no active bug fixes or feature updates, though the package is marked Production/Stable.

License in practice

BSD license is permissive, allowing commercial and private use with minimal restrictions. You may use, modify, and distribute this package freely as long as you include the license notice.

Quickstart

import markdown

text = r"{! file.md !}"
md = markdown.Markdown(extensions=['mdx_include'])
html = md.convert(text)

Verify before relying

• Whether Python 2 support (listed in classifiers) is actually maintained or tested given the dormant status since 2022.
• Current compatibility with recent versions of Markdown and its other dependencies (rcslice, cyclic).

Package facts

Evidence: mdx_include-1.4.2-py3-none-any.whl

Keywords: markdown, include, local, remote, file

Tags

More Markup packages