Include my markdown README into Sphinx

user_4533188 0
Viewed 29588

I would like to include my project's README.md into my Sphinx documentation like in Can sphinx link to documents that are not located in directories below the root document? - which is that in the resulting Sphinx html documentation I click on a link in the table of contents on the welcome page and get to the README.md.

For that a document readme_link.rst is created which contains the lines

Readme File
-----------

.. include:: ../../README.md

and I add the line

README <readme_link>

into the toctree of index.rst. Going with that, my README.md is not parsed as Markdown, but just printed onto the page as-is-text.

I thought an alternative idea might be to have a markdown file readme_link.md instead, but there is no way to include files with markdown.

How can I have my README.md parsed as markdown?

(Of course I don't want to rewrite it as .rst.)

Why m2r is not working

I tried to follow Render output from markdown file inside .rst file, but this is not working. My README.md has some headings like

# First heading

some text

## Second heading 1

some text

## Second heading 2

some text

and I get the error WARNING: ../README.md:48: (SEVERE/4) Title level inconsistent:. I understand from What does "Title level inconsistent" mean? that I need to use other symbols - but reading into them I realized that the answer refers to rst symbols. That would mean that my markdown readme actually wasn't transformed into rst.

PS: Someone else who tried something like that is https://muffinresearch.co.uk/selectively-including-parts-readme-rst-in-your-docs/

restructuredtext python-sphinx markdown python
6 Answers

I've installed myst-parser extension and tried to include a Markdown file into a .rst file

.. include:: README.md

It is not being parsed. Added :parser: markdown option, but docutils complains that "recommonmark" extension is not installed. I've found a way to include parsed md file:

.. include:: README.md
   :parser: myst_parser.sphinx_
user_14487230

If you also come across the error TypeError: add_source_parser(), here is the solution:

Using m2r2 instead of m2r. That is,

in the file readme_link.rst, we write

.. mdinclude:: ../README.md

and in the file conf.py we add

extensions = [
    # ...
    'm2r2'
]
# ...

# source_suffix = '.rst'
source_suffix = ['.rst', '.md']
user_139306370

The simplest way is to use MyST-Parser, which happens to be the extension now recommended in Sphinx docs for handling Markdown. No need for m2r.

MyST-Parser allows reStructuredText-style directives to be embedded in Markdown files. We'll use that feature to include your Markdown README.md into a placeholder Markdown file that will then get rendered to HTML.

In conf.py:

extensions = [
    # ...
    "myst_parser"
]

Your readme_link file should then be in Markdown format instead of reStructuredText i.e. create a readme_link.md file containing an include directive:

```{include} ../../README.md
```

This directive simply dumps the contents of README.md into readme_link.md which is itself in Markdown, so there's no need to do any conversion to reStructuredText at this point. readme_link.md will get rendered into HTML along with all other source files thanks to the myst_parser extension.

user_1197750

A rather simplictic solution like

.. literalinclude:: ../README.md

might do the trick for you.

This will not parse the .md file but instead display it as a literal code block.

Depending on your situation that might be an acceptable solution. Good thing is that this does not require (potentially unmaintained) extensions, works on Windows which does not support symlinks, allows you to put the content of the README into an existing .rst file, and does not conflict with the .rst headers. The obvious downside is that no parsing is happening.

user_81251190
Related