sphinx-mdinclude is a simple Sphinx extension that enables including Markdown documents from within reStructuredText. It provides the `.. mdinclude::` directive, and automatically converts the content of Markdown documents to reStructuredText format. It is a fork of `m2r` and `m2r2`, focused solely on providing a Sphinx extension. The current version is 0.6.2, and it is actively maintained as part of the Omnilib Project, with regular releases addressing compatibility and features.
pip install sphinx-mdincludeVerified import paths — ran on the pinned version, not inferred.
First, add `sphinx_mdinclude` to the `extensions` list in your `conf.py`. Then, within any reStructuredText file (e.g., `index.rst`), use the `.. mdinclude::` directive to embed Markdown content from `.md` files. You can specify a path relative to the current `.rst` file. Options like `:start-line:` and `:end-line:` can be used to include only a portion of the Markdown file.
Ensure Markdown file headings align with the implicit RST heading hierarchy generated by sphinx-mdinclude, or define explicit heading adornments in your RST files that match the expected conversion.
Write content within reStructuredText directives using reStructuredText syntax. If Markdown processing is required within a specific directive, check if the directive explicitly supports it (e.g., via a custom parser or option).
For complex tables requiring specific column alignment, consider using native reStructuredText table directives or alternative Sphinx extensions that provide more advanced table functionalities.
Ensure that image and link paths in included Markdown files are correctly relative to the Sphinx build's expected asset location, or use absolute paths. For images, they often need to be copied to the `_static` directory or a similar location accessible by Sphinx.
Plan for `sphinx-mdinclude` as solely a Sphinx extension; do not expect CLI functionality. For mermaid, use a dedicated Sphinx extension.
Always check the `sphinx-mdinclude` changelog and `install_requires` for specific version compatibility with your Sphinx, Python, Docutils, and Mistune setup. Upgrade dependencies incrementally, testing after each major version bump.