Gollum - GitLab, GitHub wikis at home¶
The problem¶
I really like GitLab's wiki setup. It's clean and minimalistic, while exposing all its files in raw format. It's also a plus that everything is versioned in a git repo, so changes can easily be rolled back. But how can I edit this wiki offline with a nice user interface, without needing to edit the raw .md files?
Enter Gollum¶
Gollum is compatible with both GitLab and GitHub's wikis. To edit a GitLab wiki locally, enter your Wiki > hamburger menu > Clone repository (make sure to get a Personal Access Token if not using SSH keys to clone a private Wiki). Then, you can run Gollum locally by either installing it as a Ruby gem, via Docker, etc. I prefer Docker, since it leaves no trace with the --rm flag.
Within the root folder of the wiki repository, run
sudo docker pull gollumwiki/gollum:latest && sudo docker run --rm -p 127.0.0.1:4567:4567 -v $(pwd):/wiki gollumwiki/gollum:latest
latest tag, but oh well. Note that if you're using the fish shell, command substitutions use a plain () instead of $(). Specifying the --rm flag, as mentioned earlier, makes sure that the Docker container and its resources are deleted after you Ctrl+C the running container process.
At this point, point your browser to localhost:4567, and the Gollum interface should pop up.
Warning
Do note that Gollum will only recognize files that have been commited to the git repository, so make sure to commit your changes to files you edit outside of the Gollum interface in order for them to show up in the Gollum web interface.
Alternatives¶
An even easier way to work with Gitlab wikis offline is to just use an IDE like IntelliJ. IntelliJ has excellent Markdown support, and even has table support! Its search feature also eliminates the need to work with a static site indexer like lunrjs.
| This | table |
|---|---|
| was | very |
| easily | made in IntelliJ! |
If you want a web-based editor, I also found Stacks-Editor, Stack Exchange's default Markdown editor with very nice WYSIWYG setup.