8

I'm trying to convert Markdown files to html using Sphinx but am having trouble getting [links](another.md) to be translated to <a href="another.html">links</a>, rather the extension of the target remains the original .md and appears as <a href="another.md">links</a>.

I've created a simple example...

test.md

[Test link](https://www.stackoverflow.com)

[Another Markdown doc](another.md)

another.md

# Another test markdown

Both files reside in the top level directory and I run sphinx-quickstart to create conf.py, accepting the defaults. I then modify conf.py to have...

from recommonmark.parser import CommonMarkParser
extensions = [
    'sphinx.ext.autodoc',
]
source_suffix = ['.rst', '.md']
source_parsers = {
    '.md': CommonMarkParser,
}

The resulting html files are produced but the link from test.html to another.html is not correct and appears as...

test.html 

...
<p><a class="reference external" href="https://thefloow.com">Test link</a></p>
<p><a class="reference external" href="another.md">A real test</a></p>
...

...and points to another.md rather than another.html. I asked a few days ago and was pointed towards using recommonmark's AutoStructify (see thread here) but that didn't work and on further digging/reading it turns out that enable_auto_doc_ref is now deprecated and .md links are added as :any: and should be handled by Sphinx.

But I don't understand why this isn't working or what I should do to resolve it. Any suggestions would be very much appreciated.

EDIT

Versions are as follows

  • Sphinx 1.8.0
  • recommonmark 0.4.0
slackline
  • 2,295
  • 4
  • 28
  • 43
  • What is the version of sphinx and what is the version of recommonmark? The feature is relatively recent so it is important to know. – Pierre de Buyl Sep 27 '18 at 13:22
  • Apologies for the omission, Sphinx is `1.8.0` whilst recommonmark is `0.4.0`. – slackline Sep 27 '18 at 13:35
  • I'm having similar issues. Were you able to resolve this? I also realized its been deprecated and I can not find any new information of how Sphinx is supposed to "natively" convert the links. I did find an example in Recommonmark's docs of how to generate links (https://github.com/rtfd/recommonmark/blob/master/docs/auto_structify.md). It does seem to work for them with the `API Reference` link but I cannot replicate it. – Marcus Lind Dec 04 '18 at 07:29
  • Scratch my comment about the recommonmark docs, seems like they use `AutoStructify` and the deprecated method to resolve the links. – Marcus Lind Dec 04 '18 at 07:54
  • @MarcusLind no I didn't manage to get this working I'm afraid (slipped down my ToDo list). Please do report back if you work it out. – slackline Dec 05 '18 at 09:22

1 Answers1

2

recommonmark==0.5.0.dev0 solves this problem.

conf.py configuration

extensions = [
    # other
    'recommonmark',
]

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

pip configuration (requirements.txt)

sphinx==1.8.2
# recommonmark==0.5.0.dev0
git+https://github.com/rtfd/recommonmark

Please refer to https://www.sphinx-doc.org/en/master/usage/markdown.html if you need more details.

Dmytro Serdiuk
  • 859
  • 10
  • 20
  • Thanks for the heads up I'll have a look later this week. – slackline Jan 02 '19 at 11:00
  • 1
    This worked. However, when there are relative links to sections in a different Markdown document, For instance, the text "See [here](05-osm-usage.md#fault-management)", translates to "See here". There seems to be a bug in recommonmark. – garciadeblas Jun 07 '21 at 17:15
  • @garciadeblas I'm experiencing that same issue as well - were you able to find a solution? – Kurtis Jungersen Aug 11 '21 at 14:34
  • @garciadeblas I opened [this SO question](https://stackoverflow.com/questions/68744271/sphinx-docs-linking-to-specific-section-of-another-markdown-page) about this. Let me know if you've found a solution, or possibly this should be reported as a bug. – Kurtis Jungersen Aug 11 '21 at 14:49