University of Cambridge DTG-Wiki
Raven login

General

tl;dr: A gollum wiki is just a git repository with text files written in one of the supported formats, and other resources like documents and images that are linked in from text.

Gollum is a simple wiki system built on top of Git that also powers the GitHub Wikis. Gollum pages may be edited in a number of ways depending on your needs. You can edit your wiki:

  • On a local clone with your favorite text editor or IDE (changes will be visible after committing & pushing).
  • With the built-in web interface (but see gotchas).
  • With the Gollum Ruby API.

We use a customised version of gollum which we call gollum-dtg. It is just a web-frontend that reads a git repository (bare or working-copy) containing plain text files (and other resources like images or documents), parses and displays them in the form of a wiki.

We have extended gollum to use raven authentication, with authorization based on the rules defined by the gitolite wiki repositories (the permissions set in the gitolite-admin config file for each wiki repository), and we also did some minor design changes to the frontend (mainly branding).

Gollum-dtg parses the configuration file from our git server (gitolite) and considers any repository that starts with wiki/ (as in wiki/dtg, wiki/lc525) - parsing it accordingly and displaying it through the web interface.

Besides the live gollum interface (which is based on the HEAD/master of the repository on our git server) you can clone/branch/edit/merge/push that wiki repository as you please (you can certainly push it to github as a github wiki, or you can have local copies and private branches which are not seen on the web). Feel free to use any git-foo you know.

Also see gollum readme.

Playing with this wiki

  1. You can edit/create pages through the web interface at will.
  2. In order to clone this wiki's repository locally, do
    git clone git@wiki.dtg.cl.cam.ac.uk:wiki/wiki-help
    
    This is a separate git server from the one you normally use for code, but it has been set up to accept the same ssh keys you use for the normal dtg-code one. If you don't have your key added to a ssh-agent, you might have to mention your key in your ssh config, (~/.ssh/config) like this:
    Host wiki.dtg.cl.cam.ac.uk
        IdentityFile ~/.ssh/your-key
    

Creating your own wiki

First, you need to already have a ssh key on the dtg-code git server. If you don't have that, create a public/private key pair with ssh-keygen -t rsa -C "CRSID@cam.ac.uk" and send the public key (.pub) to one of the git admins (lc525, drt24, oc243), requesting access to the git repositories. For the moment, CC that to lc525 as well, because I need to copy the same key to the wiki git server (we'll automate that someday).

Once you get access, you just have to add a repository having a name starting with wiki/ on our wiki gitolite server (wiki.dtg.cl.cam.ac.uk):

  1. Clone gitolite-admin and edit the config file to add a wiki repository and configure its permissions:
      git clone git@wiki.dtg.cl.cam.ac.uk:gitolite-admin
    
  2. Edit the config file to add a new wiki repository and set authorization permissions
      repo	wiki/lc525
          R    =   @dtg
          RW   =   lc525
    
    The name of the repository needs to start with wiki/ in order to be picked up by the gollum instalation
  3. Commit and push changes to the git server:
      git add .
      git commit -m "add: new wiki repository, for lc525"
      git push
    
    You need to visit http://wiki.dtg.cl.cam.ac.uk/list to update the list of wikis
  4. Now your wiki has been created by gitolite. Access it through the web interface or clone it locally:
      git clone git@wiki.dtg.cl.cam.ac.uk:wiki/lc525
    
    For local clones, after editing your wiki, just push to the server and they will become visible through the web interface as well.

Authentication and Authorization

There are two usergroups that are parsed specially by gollum: @all and @raven.

  • @all allows anonymous access
  • @raven requests the user to be raven-authenticated (his actual identity does not matter)
  • the other groups/users are considered as normal.

The permission types which gollum parses are as follows:

  • R read-only
  • RW read/write
  • - deny

You can also set permissions on a per-directory basis. For example, consider the following configuration:

repo	wiki/dtg
	RW lab-internal/ = @dtg @time lc525 
	-  lab-internal/ = @all
	RW internal/     = @dtg lc525
	R  internal/     = @raven
	-  internal/     = @all
	RW	         = @dtg
	R	         = @all

After the permission type (R, RW, -) you may place the directory from your repository that the rule refers to. For example,

  RW lab-internal/ = @dtg @time lc525
means that users from @dtg, @time and lc525 will have RW access to all the wiki files in the lab-internal directory from the repo.

Rules are considered in one pass (gitolite does this as well), so their ordering is important. Start with specific rules (ones that apply to deeper directory hierarchies) and go towards more general rules.

Behind the scenes, when a user in gollum-dtg requests a wiki page, it does so mentioning desired_access (R or W), resource path and username (which is null for anonymous access). The rules that match that user are taken in order, and the following checks take place (this has the same semantics as gitolite authorization, but has been re-implemented - so check out for inconsistencies):

  - preconditions (rule is skipped if not true): 
     rule matches user; 
     rule dir matches requested resource path
    
  - check:
  if rule-is-deny-rule (' - ')
    reject access
  else
    if desired_access matches rule permission
       permit access
    else
       fallthrough (check next rule)
  no more rules? reject access

Wiki Content

There are three special file names: Home, _Sidebar and _Footer. All filenames (including the special ones) should have an extension depending on the markup language used by the file. For example, for Markdown, we would have Home.md and _Sidebar.md (for the other extensions see here)

Home is the page first displayed when the wiki loads.

A _Sidebar file affects all pages in their directory and any subdirectories that do not have a sidebar file of their own. Editing sidebars from the web interface can be done by going in the list of page buttons to Index, choosing the desired _Sidebar file and then clicking on Edit.

Linking

Gollum recognizes the [[...]] syntax for links, and you can link to internal pages, anchors, external URLs, documents and images (either external or in the git repository).

  • to pages: [[link_text|page-name]]
  • to anchors: [[link_text|page-name#anchor-name]] they are automatically generated for section headings (just hover your mouse on top of a section header and you'll see them); the anchor name is the text of the header, with spaces replaced by dashes -.
  • to image inside the wiki git repository: [[repo/path/image.jpg]]

Adding a TOC

In every file, a special directive, _TOC_ placed between double square brackets [[...]] will insert an automatic Table of Contents at that location. An example:

The TOC tag can also be used in the _Footer or _Sidebar files.

For TOCs in _Sidebar files, gollum-dtg adds special code to keep the TOC in view for long scrolling pages (after you scroll beyond the end of the sidebar content, the TOC will pop in view and stay in a fixed position).

Supported Formats

Github recognizes the markup format from the extension of the file, so it is important to get it right:

Typesetting Math

Our installation has MathJax enabled. The math delimiters are:

  • $$ ... $$ for displayed mathematics
  • \$ ... \$ and \( ... \) for in-line mathematics.

For example, typing

   $$ 1+\frac{q^2}{(1-q)}+\frac{q^6}{(1-q)(1-q^2)}+\cdots =
      \prod_{j=0}^{\infty}\frac{1}{(1-q^{5j+2})(1-q^{5j+3})},
      \quad\quad \text{for $|q|<1$}. $$
will get you: $$1 + \frac{q^2}{(1-q)}+\frac{q^6}{(1-q)(1-q^2)}+\cdots = \prod_{j=0}^{\infty}\frac{1}{(1-q^{5j+2})(1-q^{5j+3})}, \quad\quad \text{for $|q|<1$}.$$

You can also right-click on the formula for more MathJax options (for example, to get the LaTeX source in a separate window). Try Math Settings > Zoom Trigger > Hover (and then hover any LaTeX formula).

Printing

We have added custom printing css stylesheets to gollum-dtg. By default, they will remove the sidebar & headers and summarise the links in footnote-style at the end of the printout. If you have any other suggestions, don't forget to make them heard.