Use your Mac in Virtual Reality. VR Desktop allows you to create a virtual desktop environment for macOS. Music & Gems - Virtual Reality. A downloadable game for Windows, Linux, and Android. Download Now Name your own price. You will search for The Elusive Musical.
We needed to create an internal knowledge base, preferably based on a wiki-engine. The requirements were:
From my own researching and evaluating, there are very few wikis that meet all the requirements, and out of those Gollum seems to be the best.
Even though it has its own installation guide, for me that wasn’t enough, so here are my guides for Linux and Mac OS, plus some customizing and tweaking.
At first, before discovering Gollum, I actually decided to create my own wiki-engine, as I didn’t like any of the wikis I found by that moment, and even started prototyping it with .NET Core Blazor (server-side variant). But then I took a closer look at Gollum and abandoned the idea.
Gollum has it all:
By the way, Gollum is what is running wikis on GitHub and GitLab, so you can actually clone wikis from there and run them locally on your machine.
The goal is to run Gollum behind NGINX as a reverse proxy, available at http://wiki.your.host.
Install required packages:
and then Gollum gem itself:
Create a user to run the wiki from:
Login as this user and create the wiki folder, initialize the Git repository and set the default commits author:
Note the --bare
option - it is required for users to be able to use this repository as a remote for their local cloned repository, so they could push their commits to it.
Gollum uses Mustache system for templating. If you’d like to customize default wiki layouts by modifying Gollum’s base templates, don’t edit the default ones - make a copy and work with the copies instead:
You’ll also need to set this path in the config.
Create the wiki config:
Create a systemd service:
Why localhost? You guessed it right - because we’ll be running it behind a proper reverse-proxy, such as NGINX, so we don’t want Gollum to expose its port to the network.
Verify that it’s bound to 127.0.0.1
:
You can also try to open http://your.host:4567 - it should fail.
Install and setup NGINX as a reverse proxy:
Now your wiki should be available at http://wiki.your.host. Obviously, first you’d need to add a record for wiki.your.host
in your local DNS server or at your hoster control panel (assuming you already have your.host
domain registered).
In our case we host wiki in the internal network only, so it’s not exposed to the internet, and there is no real need to restrict access to it. However, in your case you might want to protect it with Basic authentication.
Here the goal is to simply run Gollum locally on demand - to preview your local changes before pushing them to the main repository on server.
Install required packages:
Since Mac OS already has system Ruby, you’ll need to “overwrite” it in your ~/.bash_profile
:
Update the environment:
and check the versions:
Try to install Gollum now. In my case it failed:
Here this error is caused by the obsolete libffi library. To fix it, force the required gem, and this time Gollum should install fine:
Make a symlink for Gollum executable somewhere in your PATH
, for example:
Now do the steps described in local editing and try to run your wiki. It might fail with the following error:
That means that you have no web-server in your Ruby. Install some, for example webrick, and then you’ll be able to run the wiki:
The wiki is now available on http://localhost:4567.
Gollum has a web UI for editing, and that would be the easiest option in most cases.
Sadly, there is no authentication out of the box, which is a minor issue in our case, but for others this could be a serious disadvantage. Although, it seems to be possible to hack it in.
So, by default all the changes made via web UI will be authored by the default user from Git repository config on server.
But why edit wiki in web UI, when its content is just plain-text Markdown files in a Git repository? You can work with it as with any other Git repository!
So, every team member can have a local copy of the wiki, author (and sign) their commits and push them to the main repository via SSH. You can even disable editing via web UI, so Git and SSH would be the only way to edit the wiki. How awesome is that.
Create an SSH key on your machine:
Add the wiki host to your SSH config (~/.ssh/config
):
Go the wiki host and add your public key to /home/gollum/.ssh/authorized_keys
.
Now you should be able to clone the wiki repository via SSH. On your local machine go to some /path/to/your/documents/or/whatever
and clone the wiki like this:
Make sure that you have meaningful username and e-mail in your Git config (these values will be used for authoring your changes in the wiki):
The rest is as with any other Git repository: you do some changes, commit them and push to remote.
To run Gollum locally, first install it on your machine, create a config in the root of the wiki repository that you’ve just cloned (no need to commit the local config, and actually add it to .gitignore
) and then:
Now you can open http://localhost:4567 in your browser. Note that it will only render what’s already committed, so if you don’t see changes you’ve made, check if you’ve committed them.
The main purpose of running Gollum locally is to preview your changes and amend local commits before pushing to remote. For example, you’ve committed some changes (did not push them yet), previewed them in browser and decided to do some more changes. To preview new changes you’ll need to commit them too, but instead of making a new commit you can just do this:
That will update your last commit (--amend
), preserving the original commit message (--no-edit
). You can amend your commit countless number of times and push it to the main repository only when you are completely satisfied with the changes.
As already mentioned, you can customize default wiki layouts by editing Gollum templates.
Aside from templates, you can also add your customs CSS and JS. To enable those, make sure your wiki config has the following lines:
Then create custom.css
and custom.js
files in the wiki root. Now you can either write your custom CSS and JS right there, or use them as “importing points” - for example here’s my custom.css
:
and then I do the actual styling in those files.
By the way, even though the pages markup is Markdown, you can just as well use raw HTML blocks. And you can also assign CSS classes to Markdown elements, such as images:
As an example, our main page is mostly done with raw HTML. And thanks to injected custom styles, it nicely adapts to mobile screens:
Also, default Gollum styles define some rather ugly margins for ToC, headers, paragraphs and so on, but you can easily customize that into something nicer like this:
Note that by default both custom.css
and custom.js
are included in the <head>
. If you would like to move your JS code to the end of <body>
, you can do it by modifying the following template: /path/to/gems/gollum-VERSION/lib/gollum/templates/layout.mustache
(or rather a copy of it that you made earlier).
There are certain special files (subpages) that get injected into pages - you can guess where exactly on a page by looking at their names:
_Header.md
_Sidebar.md
_Footer.md
You can use them for injecting some common blocks, such as table of contents (ToC). Here’s my _Header.md
, for instance:
These blocks affect all the pages in the current and nested folders, unless they are “overwritten” on lower levels. For example, I have an archive
folder with its own _Header.md
:
and it has different contents:
so, aside from ToC, all the pages in the archive
folder (and nested folders) will also have a special banner.
Gollum has quite a number of features, and I won’t describe all of them, but I would like to highlight some, as they are easy to overlook:
<<GlobalTOC()>>
macros to the main page and that will generate a list of all the wiki pages (unlike Overview, this will list only content pages)