---
id: mdx-include
version: "1.4.2"
license: BSD
license_treatment: permissive
maintenance: dormant
---

# mdx-include — Python Markdown extension to include local or remote files

License: permissive · Maintenance: dormant · Downloads: 128.8K/mo

## 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 above — 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

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

- License: BSD (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: dormant
- Downloads: 128.8K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

markdown file inclusion extension, include files in markdown, markdown local remote files, markdown content embedding, markdown file slicing, recursive markdown includes, markdown include syntax, markdown-extension, documentation-tooling

[View on SkillFed](https://skillfed.io/packages/mdx-include) · [View on PyPI](https://pypi.org/project/mdx-include/)