sphinx_mdinclude
Markdown extension for Sphinx
Decision gist · record as of 2026-08-14
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.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires Python 3.8 or newer; Sphinx must be installed and configured as your documentation tool.
- 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 · maintenance · safety
permissive license (permissive) — Licensed under MIT (permissive), meaning you can use, modify, and distribute this package freely in both open and closed projects with minimal restrictions.
last release 2024-08-03 (741 days) · last repo commit 2025-04-01 · 22 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 494,808 downloads/mo, #6,345 on PyPI
Alternatives
Verify before relying
pip install sphinx-mdinclude
# In conf.py:
extensions = ['sphinx_mdinclude']
# In your .rst file:
.. mdinclude:: path/to/file.md- 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.
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 on it.
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
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.
Requires Python 3.8 or newer; Sphinx must be installed and configured as your documentation tool.
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.mdVerify 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
| License | permissive license permissive |
| Python support | Supports the current Python release >=3.8 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 4 packagesmistunedocutilspygmentssphinx |
| Maintenance | Aging 741 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 494,808 / month, #6,345 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 4 - BetaFramework :: Sphinx :: ExtensionIntended Audience :: DevelopersLicense :: OSI Approved :: MIT LicenseNatural Language :: EnglishTopic :: Text Processing |
Evidence: sphinx_mdinclude-0.6.2-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “include markdown files in rst”
- sphinx_mdincludeSphinx extension that lets you include and render Markdown files…
- m2r2Converts markdown files with embedded reStructuredText markup to…
- sphinx-substitution-extensionsAdds substitution support to Sphinx directives, allowing variable…
Give your agent the search over MCP, or paste the wish link into any chat.
More Text Processing packages
A drop-in replacement for Python's standard `re` module that adds advanced regex features like nested sets, fuzzy matching, lookaround in conditionals, and full Unicode case-folding while maintaining backward compatibility.
pyparsing provides a library for building text parsers directly in Python code using composable grammar classes, handling quoted strings, whitespace variation, and embedded comments without regex or lex/yacc.
Install it if you need to parse text or define grammars programmatically.
fonttools manipulates font files in multiple formats (TrueType, OpenType, AFM, Type 1, Mac-specific) and includes TTX, a tool to convert fonts to and from XML text format.
Install it if you need to read, write, or manipulate fonts programmatically or via the TTX command-line tool.
Docutils converts plaintext documentation in reStructuredText format into multiple output formats including HTML, XML, and LaTeX using a modular processing system.
RapidFuzz provides fast fuzzy string matching using Levenshtein Distance and related metrics, implemented mostly in C++ with Python bindings for rapid similarity scoring and approximate string matching.
Install it if you need fuzzy string matching; it's a solid replacement for FuzzyWuzzy with better licensing and performance.
tinycss2 parses CSS strings into token and block objects, and generates CSS strings from those objects, following the CSS Syntax Level 3 specification without enforcing specific properties or values.
Install it if your project requires CSS tokenization or syntax manipulation.
See also m2r2 · sphinx-markdown-builder · sphinx-markdown-tables · sphinx-jsonschema · sphinx-substitution-extensions · changelog · recommonmark · sphinx-jinja · sphinxcontrib-youtube · setuptools-markdown