{"id":5495,"library":"sphinx-mdinclude","title":"Sphinx Markdown Include Extension","description":"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.","status":"active","version":"0.6.2","language":"en","source_language":"en","source_url":"https://github.com/omnilib/sphinx-mdinclude","tags":["Sphinx","Markdown","documentation","reStructuredText","extension","docs"],"install":[{"cmd":"pip install sphinx-mdinclude","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core documentation generation framework it extends.","package":"Sphinx","optional":false},{"reason":"Markdown parser used for conversion.","package":"mistune","optional":false},{"reason":"Base reStructuredText parsing library, a core Sphinx dependency.","package":"docutils","optional":false},{"reason":"Used for code block syntax highlighting.","package":"Pygments","optional":false}],"imports":[{"note":"sphinx-mdinclude is loaded as a Sphinx extension string, not a Python class import.","symbol":"sphinx_mdinclude","correct":"# In conf.py\nextensions = [\n    # other extensions,\n    'sphinx_mdinclude'\n]"}],"quickstart":{"code":"# conf.py\n# Add 'sphinx_mdinclude' to your extensions list\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon',\n    'sphinx_mdinclude'\n]\n\n# index.rst (or any .rst file)\nMy Project Documentation\n========================\n\n.. mdinclude:: ../README.md\n   :start-line: 1\n   :end-line: 10\n\nThis section continues with reStructuredText.\n\n.. mdinclude:: introduction.md\n","lang":"python","description":"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."},"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For complex tables requiring specific column alignment, consider using native reStructuredText table directives or alternative Sphinx extensions that provide more advanced table functionalities.","message":"Table column alignment in Markdown files included via `.. mdinclude::` is not supported, as this is a limitation inherited from reStructuredText's table capabilities.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Plan for `sphinx-mdinclude` as solely a Sphinx extension; do not expect CLI functionality. For mermaid, use a dedicated Sphinx extension.","message":"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.","severity":"breaking","affected_versions":"0.4.0 and later"},{"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.","message":"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.","severity":"breaking","affected_versions":"Various versions, consult changelog for specifics (e.g., v0.4.0, v0.5.4, v0.6.0)"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}