sphinx-mdinclude

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.

Features

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 (m2r_parse_relative_links)

Restrictions

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: #

Installation

Python 3.6 or newer is required.

pip install sphinx-mdinclude

Usage

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 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.

License