3

Currently markdown links to other MD docs are working fine (and same with section links within the same document), e.g.:

doc1.md

# Doc 1

See [doc2](./doc2.md) [LINK WORKS] for more details.

doc2.md

# Doc 2

See [section 2](#section-2) [LINK WORKS]

# Section-2

<details>

Issue => Linking to section of another doc (in Sphinx Only)

Linking to a specific section of another doc isn't working, as the html is rendered with an anchor to /doc2.md#section-2 instead of /doc2.html#section-2, which results in a 404. This works fine in VS Code's MD preview, on Github, etc.

** Is this a known issue? If not, how can I fix this?**

doc1.md

# Doc 1

See [section2 of doc2](./doc2.md#section-2) [LINK DOESN'T WORK] for more details.

doc2.md

# Doc 2

See [section 2](#section-2) [LINK WORKS]

# Section-2

<details>

Specs

  • Conda Environment / Python3
  • Sphinx 3.4.3
  • recommonmark 0.7.1

Also, here's a Related Question, but different issue.

mzjn
  • 48,958
  • 13
  • 128
  • 248
Kurtis Jungersen
  • 2,204
  • 1
  • 26
  • 31
  • 1
    Which Sphinx extension are you using to parse Markdown files? MyST? RecommonMark? Other? Anyway, you could change the target to `(./doc2.html#section-2)` or better use [MyST syntax](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#syntax-targets). – Steve Piercy Aug 12 '21 at 13:43
  • 1
    @StevePiercy I'm using recommonmark for parsing markdown (as mentioned in the question). The problem with changing the target to point to `.html` is then these links won't work in Github. My temporary solution is to remove references to sections in other docs and just link to the page, although not 100% ideal. – Kurtis Jungersen Aug 12 '21 at 14:39
  • @StevePiercy also I am looking into MyST now, so thanks for that recommendation! – Kurtis Jungersen Aug 12 '21 at 14:41
  • 1
    Choose one for correct linkage: rendering by GitHub or Sphinx. Cannot do both. – Steve Piercy Aug 12 '21 at 16:59
  • @StevePiercy thanks for the pointer that MyST has special support for labels. I think this would be worth being an answer. – luator Nov 03 '21 at 08:26

0 Answers0