Wikis development guidelines

The wiki functionality in GitLab is based on Gollum 4.x. It’s used in the Gitaly Ruby service, and accessed from the Rails app through Gitaly RPC calls.

Wikis use Git repositories as storage backend, and can be accessed through:

Involved Gems

Some notable gems that are used for wikis are:

ComponentDescriptionGem nameGitLab projectUpstream project
gitlabMarkup renderer, depends on various other gemsgitlab-markupgitlab-org/gitlab-markupgithub/markup

Notes on Gollum

We only use Gollum as a storage abstraction layer, to handle the mapping between wiki page slugs and files in the repository.

When rendering wiki pages, we don’t use Gollum at all and instead go through a custom Banzai pipeline. This adds some wiki-specific markup, such as the Gollum [[link]] syntax.

Because we do not make use of most of the Gollum features, we plan to move away from it entirely at some point. See this epic for reference.

Model classes

The Wiki class is the main abstraction around a wiki repository, it needs to be initialized with a container which can be either a Project or Group:

classDiagram
  Wiki --> ProjectWiki
  Wiki --> GroupWiki

  class Wiki {
    #container
    #repository
  }

  class ProjectWiki {
    #project → #container
  }

  class GroupWiki {
    #group → #container
  }

Some models wrap similar classes from Gitaly and Gollum:

Rails ModelGitaly ClassGollum
WikiGitlab::Git::WikiGollum::Wiki
WikiPageGitlab::Git::WikiPage, Gitlab::Git::WikiPageVersionGollum::Page
Gitlab::Git::WikiFileGollum::File

Only some data is persisted in the database:

ModelDescription
WikiPage::MetaMetadata for wiki pages
WikiPage::SlugCurrent and previous slugs of wiki pages
ProjectRepositoryGitaly storage data for project wikis
GroupWikiRepositoryGitaly storage data for group wikis

Attachments

The web UI uploads attachments through the REST API, which stores the files as commits in the wiki repository.