Browse documentation offline

[Morwenn]

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 the master 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:

1. Open cpp-sort directory in the command line.
2. gollum --page-file-dir docs --ref <version-tag>
3. Visit 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:

• [x] Make the documentation work with Gollum.
• [x] Ensure that it works as a GitHub wiki.
• [x] If possible make it work when browsing the repository itself.
• [x] If possible, ensure that embedded pictures work everywhere.
• [x] Document it tooling.md, with a example of using Gollum.

[Morwenn]

Conlusions so far:

• Using [Page name](file-name.md) works for in-repo browsing and with Gollum
• Using [Page-name](file-name) works with GitHub wiki and Gollum
• Using [[Page name]] works on GitHub wiki only

Sounds like a case of "commit to repository with .md, sed it away when syncing to the GitHub wiki".

[Morwenn]

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:

• The default links work with Gollum and GitHub repository browsing.
• The job that deploys the documentation to the wiki automatically converts links to a working syntax.
• Documentation file names don't have spaces.

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.