1

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?

Toby Manders
  • 47
  • 1
  • 6
  • 1
    Can you pre-process the files, replacing doubled square brackets with single? – Steve Piercy Jun 21 '22 at 09:28
  • 1
    For this reason, I endeavor to use only Wiki Engines following the well-known standards, commonmark or GitHub Flavored Markdown (GFM). However, that's easier said than done. So, I have a custom utility I've developed to pre-process my markdown files, making needed transformations - as @StevePiercy mentioned above. – ScottWelker Jun 30 '22 at 17:13
  • @StevePiercy Indeed I found [obsidian export](https://github.com/zoni/obsidian-export), which is a bit clunky but a fair workaround. I'd love something more elegant that would let me go directly from my vault to static HTML I can host on GH Pages, but alas, "export to standard markdown" has been on [their Trello board](https://trello.com/b/Psqfqp7I/obsidian-roadmap) for years. – Toby Manders Jul 05 '22 at 19:16

1 Answers1

2

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...

Bernard.E
  • 21
  • 3
  • Just realized that the MyST-Parser project has been updated to v.0.18.0 since Jun 07, 2022, so I had to adapt "sphinx-obsidian" code accordingly... – Bernard.E Aug 05 '22 at 16:21