sphinx_mdinclude

What it is and what it does

sphinx-mdinclude is a Sphinx extension that bridges Markdown and reStructuredText by providing an `mdinclude` directive to embed Markdown files into RST documentation. It converts Markdown syntax—including tables, fenced code blocks, footnotes, and inline HTML—into equivalent reStructuredText markup that Sphinx can render. The package is a focused fork focused only on providing a Sphinx extension.

You add it to your Sphinx `conf.py` extensions list, and then use the `.. mdinclude::` directive to pull in `.md` files alongside your existing `.rst` documentation. It also supports parsing relative links into Sphinx ref and doc directives. The conversion is automatic, so you write Markdown naturally and let the extension handle the translation.

Use it for:

• Include a project's README.md directly in Sphinx docs without manually rewriting it in reStructuredText.
• Mix Markdown and RST source files in the same Sphinx documentation build.
• Embed Markdown-formatted content (tables, code blocks, footnotes) into RST pages via the mdinclude directive.
• Maintain documentation in Markdown while using Sphinx as the build and hosting system.
• Convert Markdown fragments to RST markup for inclusion in larger RST documents.

Worth the install?

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

Sphinx extension that lets you include and render Markdown files within reStructuredText documentation, converting Markdown to reStructuredText format on the fly.

Yes, if you need to include Markdown files in a Sphinx documentation project. The extension is stable, has low install friction, carries no security vulnerabilities, and solves a real workflow problem—mixing Markdown and RST sources. Maintenance is aging, so monitor the repository for any incompatibilities with future Sphinx versions.

Install

sphinx-mdinclude on PyPI

pip install sphinx-mdinclude

uv add sphinx-mdinclude

poetry add sphinx-mdinclude

Installing sphinx_mdinclude

Before you install

Low friction install with four straightforward runtime dependencies (mistune, docutils, pygments, sphinx). Maintenance is aging—last release was in 2024—but the repository remains active and unarchived, suggesting the extension is stable enough for its narrow scope.

License in practice

Licensed under MIT (permissive), meaning you can use, modify, and distribute this package freely in both open and closed projects with minimal restrictions.

Quickstart

pip install sphinx-mdinclude

# In conf.py:
extensions = ['sphinx_mdinclude']

# In your .rst file:
.. mdinclude:: path/to/file.md

Requires Python 3.8 or newer; Sphinx must be installed and configured as your documentation tool.

Verify before relying

• Whether relative link parsing (md_parse_relative_links option) works reliably across all Sphinx versions.
• How well the package handles complex Markdown syntax beyond the documented feature set.
• Whether the aging maintenance status signals stability or abandonment risk for future Sphinx compatibility.

Package facts

Evidence: sphinx_mdinclude-0.6.2-py3-none-any.whl

Keywords: Markdown, reStructuredText, sphinx-extension

Tags

More Text Processing packages