Skip to content

Latest commit

 

History

History
80 lines (59 loc) · 2.96 KB

README.md

File metadata and controls

80 lines (59 loc) · 2.96 KB
Raw

sphinx-mdinclude

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.

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 (md_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

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.