How can I get offline documentation?

Traditionally, Xastir's source repository has been full of "README.xxxx" files to document it. These, like the xastir.org wiki, have become difficult to maintain and extremely outdated, which is why we've decided to create the Github wiki.

But some Xastir users still want to have the option of offline documentation so they can consult it when they have no internet access (say, while mobile or working a public service activity where there is no internet).

Fortunately, this is possible using the Github wiki, which is just more files stored at Github under git.

The quick way

Simple clone this wiki using the URL you'll find on the right just below the sidebar, under "Clone this wiki locally":

so you'd copy the url and paste it into a git clone command:

git clone https://github.com/Xastir/Xastir.wiki.git

That's it. You have all the files, including the images, of the wiki and you can read them offline.

But, but, that looks like a bunch of gobbledygook

The files you downloaded are in plain text, but with added "Markdown" to make it render on github. It can be difficult to wade through.

You're in luck, though. Github's wikis are run using a fork of a product named Gollum, and you can actually run a Gollum instance of your own to access your cloned wiki --- you can then use your own computer, with no internet, to view them and use them very much as you would the online version.

Clone the wiki, install Gollum through your system's package manager, then run it as:

gollum /path/to/your/clone/of/Xastir.wiki

Your computer now has a little web server running on port 4567, and you can point your web browser at http://localhost:4567 to view your local files, rendered as a wiki.

You can even edit pages in your clone with Gollum

Gollum provides a web-based wiki editor, and works with Git to update any files you changed. You can use this to contribute to the wiki with a little extra effort.

Github's wiki has diverged from Gollum

This is not an exact rendering of what you'd see on the online wiki, as Github has modified Gollum for its own use and they are not longer strictly compatible --- though the Gollum maintainers try to keep it close.

We've observed that the "details" blocks in the sidebar don't work properly, and a few links in the sidebar don't work (not sure why). But all of the links and images in the pages themselves, including the "details" blocks do render correctly and this is a perfectly usable offline option.