--- id: sphinx-mdinclude version: "0.6.2" license: unclear license_treatment: permissive maintenance: aging --- # sphinx_mdinclude — Markdown extension for Sphinx License: permissive · Maintenance: aging · Downloads: 494.8K/mo ## 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 above — 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 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 - License: not declared (permissive) - Python support: supports_current - Install friction: low - Maintenance: aging - Downloads: 494.8K/month (top 15,000 on PyPI) - Known vulnerabilities: none known ## Tags markdown in sphinx documentation, sphinx markdown extension, include markdown files in rst, convert markdown to restructuredtext, mdinclude directive sphinx, markdown support for sphinx, sphinx documentation markdown, sphinx-extension, markdown-to-rst [View on SkillFed](https://skillfed.io/packages/sphinx-mdinclude) · [View on PyPI](https://pypi.org/project/sphinx-mdinclude/)