Closed Morwenn closed 2 years ago
Conlusions so far:
[Page name](file-name.md)
works for in-repo browsing and with Gollum[Page-name](file-name)
works with GitHub wiki and Gollum[[Page name]]
works on GitHub wiki onlySounds like a case of "commit to repository with .md
, sed
it away when syncing to the GitHub wiki".
Due to the inability to find a relative link syntax that works at the same time with Gollum, GitHub Wiki, and GitHub repository browsing, I ended up with the following choices:
Images work just fine on the three platforms, which is great. There are still small rendering issues with Gollum, but nothing that actually hinders navigation too much. If I find a simple solution I will fix them in the future, but otherwise the status quo is satisfying enough.
Since version 1.8.0, the documentation is versioned in the
docs
subdirectory of the main repository, and synchronized with a GitHub Action to the repository's Wiki when commits are pushed on themaster
branch (see issue #157). This makes is possible to browse old versions of the documentation, but so far doing so isn't the smoothest experience under the sun.Ideally it should be possible to use Gollum to browse old versions of the documentation. It shouldn't more complicated than following these few steps:
gollum --page-file-dir docs --ref <version-tag>
http://localhost:4567/Home
This actually kind of works nowadays, but most links to other documentation pages are raw links to the online Wiki on GitHub instead of relative links, which makes local navigation extremely painful. Moreover, the existing relative links break for all kinds of reasons, notably beacause of spaces in page names. The simplest syntax to get everything to work everywhere is likely
[Page name](file-name.md#anchor)
. Additionally, it would be nice if it was possible to browse the documentation directly in the repository itself.This leaves us with the following actions:
tooling.md
, with a example of using Gollum.