Closed jgoeders closed 2 years ago
@acomodi @mithro Here is the method I've come up with using myst-parser (new official Markdown processor for Sphinx) to handle all manner of links between top-level Markdown files (eg README.md) and Sphinx documentation (eg /doc/src/), whether they are included in the Sphinx build, or just being viewed on Github.
https://github.com/executablebooks/MyST-Parser/issues/361#issuecomment-1006873840
I'm having issues creating internal documentation links. We are using recommonmark to support markdown files in our sphinx documentation (which is nice), and recommonmark is supposed to support internal links, but I can't get it to work.
For example, if I have a link like:
The link is being converted to an external github link (https://github.com/verilog-to-routing/vtr-verilog-to-routing/blob/master/vtr/get_vtr). I think this is connected to the fix where we wanted to link to files in the root of the Github repo (#1785) but I think something is broken.
@acomodi ?
I figured we must have internal links elsewhere, but the only one I can find lives on line 202 of this page and is broken:
Anyone know a fix to this?
I'm also wondering if others would be interested in moving to the newer myst-parser? recommonmark is now deprecated and myst-parser is the official Sphinx markdown parser.
I would be fine with taking a crack at this if people are interested. We don't have that much markdown documentation, and recommonmark syntax is supposed to be supported, so I don't think it would be too bad to do. Also, the SymbiFlow/sphinxcontrib-markdown-symlinks fix would not be needed since including a file from outside the docs folder is supported in myst.