Using Markdown inside ReStructuredText

Short answer: There is no parser for blocks of Markdown that will work inside ReStructuredText, at least not that ReadTheDocs supports. Instead, we can make everything Markdown and embed bits of rst in there to get the referencing and other powerful capabilities Read the Docs uses to create documentation.

Closest that Read the Docs supports is https://github.com/rtfd/recommonmark …their documentation is naturally where you’d expect it: https://recommonmark.readthedocs.io/en/latest/index.html

See in particular: https://recommonmark.readthedocs.io/en/latest/auto_structify.html

There is a project to allow including rst markup and directives in .md files, and convert it all to rst:

https://github.com/miyakogi/m2r

https://miyakogi.github.io/m2r/example.html https://raw.githubusercontent.com/miyakogi/m2r/master/docs/example.md

We could run that locally.

Key tip:

Add options to rebuild ALL files everytime

Without this you may go crazy trying to figure out why a file that links to another file hasn’t picked up the reference after you fix it in the referenced file. The reason is that the referencing file wasn’t changed, so isn’t rebuilt, and so cannot pick up on the correction.

Thanks to this question and answer.

Other approaches

This attempt at listing common syntax between Markdown and rst (or not-so-obtrusive-as-to-be-incompatible syntax) is cool but not what i was looking for: https://gist.github.com/dupuy/1855764

Helpful information:

The issue

Posted: https://github.com/rtfd/readthedocs.org/issues/4412

I think my question can equally be rephrased as: What needs to happen for the latest recommonmark, with updated AutoStructify support, to be deployed on ReadTheDocs.org?

Motivation: Contributors to a couple ReadTheDocs projects i maintain have learned Markdown for use in the GitLab-hosted wikis and issue queues, as well as some familiarity from being on the Internet in the past decade. As much as i’d love to say documentation is in ReStructuredText and that’s that, i cannot do that in good conscience given that i mess up making external links in rst half the time. (I’d use AsciiDoc as advocated in Codewriting if left to my own devices.) Documentation needs to be collaborative, so definitionally i’m not left to my own devices. This means ReadTheDocs, with its excellent infrastructure and trusted reputation. And it means Markdown, so people can easily contribute, including by copy-pasting things worked out in wikis, issues, and pads.

Current status: ReadTheDocs does begrudgingly support Markdown-only documentation, i really really don’t want to give up cross-referencing documents, nor even semantic notes/warnings and everything else Sphinx can provide with ReStructuredText. So i’m super excited that the latest version of Recommonmark offers the ability to have Markdown documents that embed just enough ReStructuredText to do key directives, including document reference labels and admonitions. Unfortunately it is being reported as not in the PyPi package management yet.

The most critical thing is that if someone references a file, for example:

[our values](values.md)

that it gets converted to the link to values.html.

[our values](values) also works, which is absolutely awesome.

This is all working locally! (So long as i install with pip install git+https://github.com/rtfd/recommonmark.git --upgrade).

Does Recommonmark just need to get a new release into pypi? Tag a first release on GitHub? Or is there more to it than that, to get this wonderful new future on ReadTheDocs?

Details

Expected Result

Include a reference in a .md file to another .md file or a the named label using markdown link syntax, correctly determined to be an internal reference by recommommark autostructify.

Actual Result

Broken links, as seen here: https://agaric-documentation.readthedocs.io/en/latest/purpose.html

Working it out

See further updates https://github.com/rtfd/readthedocs.org/issues/4412

from CommonMark import Parser ImportError: cannot import name Parser

Build #7781652 latest (6e2d9e1a0997a0efb305b9382e35804f6bc85185) Build failed git clone –recursive https://gitlab.com/agaric/documentation.git . git checkout –force origin/master git clean -d -f -f git branch -r python2.7 -mvirtualenv –no-site-packages –no-download /home/docs/checkouts/readthedocs.org/user_builds/agaric-documentation/envs/latest python /home/docs/checkouts/readthedocs.org/user_builds/agaric-documentation/envs/latest/bin/pip install –upgrade –cache-dir /home/docs/checkouts/readthedocs.org/user_builds/agaric-documentation/.cache/pip Pygments==2.2.0 setuptools<40 docutils==0.13.1 mock==1.0.1 pillow==2.6.1 alabaster>=0.7,<0.8,!=0.7.5 commonmark==0.5.4 recommonmark==0.4.0 sphinx<1.8 sphinx-rtd-theme<0.5 readthedocs-sphinx-ext<0.6 python /home/docs/checkouts/readthedocs.org/user_builds/agaric-documentation/envs/latest/bin/pip install –exists-action=w –cache-dir /home/docs/checkouts/readthedocs.org/user_builds/agaric-documentation/.cache/pip -r /home/docs/checkouts/readthedocs.org/user_builds/agaric-documentation/checkouts/latest/requirements.txt cat conf.py python /home/docs/checkouts/readthedocs.org/user_builds/agaric-documentation/envs/latest/bin/sphinx-build -T -E -b readthedocs -d _build/doctrees-readthedocs -D language=en . _build/html Running Sphinx v1.7.4

Traceback (most recent call last): File “/home/docs/checkouts/readthedocs.org/user_builds/agaric-documentation/envs/latest/local/lib/python2.7/site-packages/sphinx/cmdline.py”, line 303, in main args.warningiserror, args.tags, args.verbosity, args.jobs) File “/home/docs/checkouts/readthedocs.org/user_builds/agaric-documentation/envs/latest/local/lib/python2.7/site-packages/sphinx/application.py”, line 163, in init confoverrides or {}, self.tags) File “/home/docs/checkouts/readthedocs.org/user_builds/agaric-documentation/envs/latest/local/lib/python2.7/site-packages/sphinx/config.py”, line 167, in init raise ConfigError(CONFIG_ERROR % traceback.format_exc()) ConfigError: There is a programable error in your configuration file:

Traceback (most recent call last): File “/home/docs/checkouts/readthedocs.org/user_builds/agaric-documentation/envs/latest/local/lib/python2.7/site-packages/sphinx/config.py”, line 161, in init execfile_(filename, config) File “/home/docs/checkouts/readthedocs.org/user_builds/agaric-documentation/envs/latest/local/lib/python2.7/site-packages/sphinx/util/pycompat.py”, line 150, in execfile_ exec_(code, globals) File “/home/docs/checkouts/readthedocs.org/user_builds/agaric-documentation/envs/latest/local/lib/python2.7/site-packages/six.py”, line 709, in exec exec(“““exec code in globs, locs”””) File “”, line 1, in File “conf.py”, line 50, in from recommonmark.parser import CommonMarkParser File “/home/docs/checkouts/readthedocs.org/user_builds/agaric-documentation/envs/latest/local/lib/python2.7/site-packages/recommonmark/parser.py”, line 9, in from CommonMark import Parser ImportError: cannot import name Parser

Configuration error: There is a programable error in your configuration file:

Traceback (most recent call last): File “/home/docs/checkouts/readthedocs.org/user_builds/agaric-documentation/envs/latest/local/lib/python2.7/site-packages/sphinx/config.py”, line 161, in init execfile_(filename, config) File “/home/docs/checkouts/readthedocs.org/user_builds/agaric-documentation/envs/latest/local/lib/python2.7/site-packages/sphinx/util/pycompat.py”, line 150, in execfile_ exec_(code, globals) File “/home/docs/checkouts/readthedocs.org/user_builds/agaric-documentation/envs/latest/local/lib/python2.7/site-packages/six.py”, line 709, in exec exec(“““exec code in globs, locs”””) File “”, line 1, in File “conf.py”, line 50, in from recommonmark.parser import CommonMarkParser File “/home/docs/checkouts/readthedocs.org/user_builds/agaric-documentation/envs/latest/local/lib/python2.7/site-packages/recommonmark/parser.py”, line 9, in from CommonMark import Parser ImportError: cannot import name Parser

https://github.com/rtfd/CommonMark-py