Skip to main content

Markdown extension for Sphinx

Project description


Sphinx extension for including or writing pages in Markdown format.

version documentation changelog license

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
    • fenced-code block
    • tables
    • footnotes ([^1])
  • Inline- and Block-level rst markups
    • single- and multi-line directives (.. directive::)
    • inline-roles (:code:`print(1)` ...)
    • ref-link (see `ref`_)
    • footnotes ([#fn]_)
    • math extension inspired by recommonmark
  • Sphinx extension
    • add markdown support for sphinx
    • mdinclude directive to include markdown from md or rst files
    • option to parse relative links into ref and doc directives (md_parse_relative_links)


  • 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.
    • H1: =, H2: -, H3: ^, H4: ~, H5: ", H6: #


Python 3.6 or newer is required.

pip install sphinx-mdinclude


In your Sphinx, add the following lines:

extensions = [

Markdown files with the .md extension will be loaded and used by Sphinx, similar to any other .rst files.

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.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx_mdinclude-0.6.1.tar.gz (65.1 kB view hashes)

Uploaded Source

Built Distribution

sphinx_mdinclude-0.6.1-py3-none-any.whl (16.9 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page