How can I generate documentation from markdown with double bracket references to other markdown [Obsidian, Sphinx]?

Question

I have an Obsidian vault in version control with a bunch of documentation of my project. These documents have double bracket references to other documents, like:

For more information, see [[Roadmap.md]].

I'd like my documentation hosted and accessible to anyone on my team, including nontechnical people who may not want to install Obsidian. I've tried generating documentation with Sphinx using various configurations of MyST-Parser and Recommonmark, but can't get the cross-references to convert to links in the built docs as I'd hoped.

Is there an easy way to accomplish this?

Answer 1

I'm also extensively using Sphinx & Obsidian for various publications. I find it to be a nice ecosystem for publishing documentation. I was recently hitting the same problem, so I gave a try...

You can install it by running this: pip install --user git+https://github.com/MacqGit/sphinx-obsidian.git@main#egg=sphinx-obsidian

Then, in the Sphinx "conf.py -> extensions" just replace the 'myst_parser' by 'sphinx_obsidian' and run a simple compilation. The '[[ ]]' should be nicely compiled.

Please be indulgent as this is a very first attempt (and the first time that I try to lend help by posting on GitHub ;-). Also, the solution is not that nice because the Myst-Parser/markdown-it implementations do not allow to easily expand the 'mdit_py_plugins' capabilities in the Sphinx environment...

You can get back in touch with me if any trouble...