Sphinx extension for including or writing pages in Markdown format.
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.
sphinx-mdinclude is a fork of m2r and m2r2, focused only on providing a Sphinx extension.
Basic markdown and some extensions (see below)
inline/block-level raw html
Inline- and Block-level rst markups
single- and multi-line directives (
math extension inspired by recommonmark
add markdown support for sphinx
mdincludedirective to include markdown from md or rst files
option to parse relative links into ref and doc directives (
In the rst’s directives, markdown is not available. Please write in rst.
Column alignment of tables is not supported. (rst does not support this feature)
Heading with overline-and-underline is not supported.
Heading with underline is OK
Rst heading marks are currently hard-coded and unchangeable.
Python 3.6 or newer is required.
pip install sphinx-mdinclude
In your Sphinx
conf.py, add the following lines:
extensions = [ ..., 'sphinx_mdinclude', ]
Markdown files with the
.md extension will be loaded and used by Sphinx, similar to
To include Markdown files within other files, use the
.. mdinclude:: <filename>
directive. This applies the conversion from Markdown to reStructuredText format.
sphinx-mdinclude is copyright Hiroyuki Takagi, CrossNox, and Amethyst Reese,
and licensed under the MIT license. I am providing code in this repository to you
under an open source license. This is my personal repository; the license you receive
to my code is from me and not from my employer. See the LICENSE file for details.