recommonmark: source_suffix '.md' is already registered

[NumesSanguis]

Thank you for keeping m2r alive!

I found this repo through your comment in this issue: miyakogi#51
In that same issue, I asked for a check to be added if .md is already registered. As this issue is also present in m2r2, I would like to ask the same here.

Full issue details:

If in conf.py, you have the following (order is unimportant):

extensions = [
    ...
    # .. mdinclude for Markdown documents
    'm2r2',
    # parse .md documents with sphinx
    'recommonmark',
]

Executing make html will raise the error:

make html
Running Sphinx v3.1.2

abs path: /some/path

Extension error:
source_suffix '.md' is already registered
Makefile:20: recipe for target 'html' failed
make: *** [html] Error 2

A possible solution?

Some modification to the code here?:
https://github.com/CrossNox/m2r2/blob/development/m2r2.py#L663-L667

Or can m2r2 and recommonmark not be used in the same documentation?

Related issues:

• Support for ..include to parse Markdown files (README.md in parent dir) readthedocs/recommonmark#191 (comment)
• Support for files outside Sphinx project (README.md in parent dir) sphinx-doc/sphinx#7000

[CrossNox]

Hello @NumesSanguis, thanks for the issue! I'm gonna try to make some failling tests for this and get it working.
Would it be too much of a hassle to ask for a minimal example to see how you are using each tool?

[NumesSanguis]

Actually I'm not too sure anymore why I tried both in the same project. When I started with the documentation for my project years ago, I started with recommonmark, as this was the recommended approach. However, I wanted to include the README.md outside the docs folder. Recommonmark did not support this, but it was possible with m2r.
So when I added m2r to the requirements, that issue popped-up. Therefore, I guess the use-case is when you are in the middle of switching from recommonmark to m2r2?

Now almost all my documents are .rst, except for the README, which I include like so:

README.md
docs/
  |- README.rst

README.rst:

.. mdinclude:: ../README.md

[hoermannpaul]

I had the same issue, removing recommonmark resolved it.

I guess recommonmark is adding a parser for .md too, thus the problem.

[triggerwaffle]

remove 'recommonmark' from extention array and
add the below code in the bottom of the conf.py
it seems to work fine.

github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/'
def setup(app):
    app.add_config_value('recommonmark_config', {
            'url_resolver': lambda url: github_doc_root + url,
            'auto_toc_tree_section': 'Contents',
            }, True)
    app.add_transform(AutoStructify)

[CrossNox]

I think this can be closed since this is due to recommonmark registering for .md suffix.

[MarionMoseby]

Hey! This issue also pops up when enabling myst_parser, which is needed by sphinx_design. Is there any way of fixing it?

[johentsch]

Hey! This issue also pops up when enabling myst_parser, which is needed by sphinx_design. Is there any way of fixing it?

Also had this issue when adding m2r2 in my conf.py:

extensions = [
    ...,
    "myst_nb", 
    "m2r2",
]

but managed to solve it by changing the order naming m2r2 first.