Sphinx Markdown Include Extension

0.6.2 · active · verified Mon Apr 13

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.

Warnings

gotcha Header levels must be consistent across reStructuredText and included Markdown files. sphinx-mdinclude converts Markdown headings to reStructuredText headings using a fixed scheme (H1: `=`, H2: `-`, H3: `^`, H4: `~`, H5: `"`, H6: `#`). If your parent `.rst` file establishes a different hierarchy before an `.. mdinclude::` directive, the combined document might render incorrectly or produce warnings.
Fix: 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.
gotcha Markdown syntax is generally not processed when nested inside reStructuredText directives. Content within directives (e.g., `.. note::`, `.. code-block::`) should typically be written directly in reStructuredText.
Fix: 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).
gotcha Table column alignment in Markdown files included via `.. mdinclude::` is not supported, as this is a limitation inherited from reStructuredText's table capabilities.
Fix: For complex tables requiring specific column alignment, consider using native reStructuredText table directives or alternative Sphinx extensions that provide more advanced table functionalities.
gotcha Relative paths for images or links within included Markdown files may not resolve correctly in the final Sphinx output if the Markdown file is located outside the main Sphinx source directory (e.g., including `README.md` from the project root).
Fix: 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.
breaking sphinx-mdinclude is a fork of `m2r` and `m2r2` with a focused scope. Version 0.4.0 notably removed the command-line interface (CLI) and mermaid extension support, shifting focus entirely to being a Sphinx extension. Users migrating from `m2r` or `m2r2` should expect these features to be absent.
Fix: Plan for `sphinx-mdinclude` as solely a Sphinx extension; do not expect CLI functionality. For mermaid, use a dedicated Sphinx extension.
breaking Dependency versions for `Sphinx`, `docutils`, and `mistune` have seen breaking changes and pinning adjustments across `sphinx-mdinclude` versions. For example, `mistune` support shifted from `<1.0` to `2.x`, then to `v3` (v0.6.0). Python 3.7 support was dropped in v0.5.4.
Fix: 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.

Install

pip install sphinx-mdinclude Install latest version

Imports

sphinx_mdinclude
```
# In conf.py
extensions = [
    # other extensions,
    'sphinx_mdinclude'
]
```
sphinx-mdinclude is loaded as a Sphinx extension string, not a Python class import.

Quickstart

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.

# conf.py
# Add 'sphinx_mdinclude' to your extensions list
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx_mdinclude'
]

# index.rst (or any .rst file)
My Project Documentation
========================

.. mdinclude:: ../README.md
   :start-line: 1
   :end-line: 10

This section continues with reStructuredText.

.. mdinclude:: introduction.md

view raw JSON →