gitlab-org--gitlab-foss/doc/development/wikis.md

type	stage	group	info	description
reference, dev	Create	Editor	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments	GitLab's development guidelines for Wikis

Wikis development guide (FREE)

Introduced in GitLab 13.5.

Overview

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

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

• The Web UI
• The REST API
• Git itself

Introduced in GitLab 13.5, wikis are also available for groups, in addition to projects.

Involved Gems

Some notable gems that are used for wikis are:

Component	Description	Gem name	GitLab project	Upstream project
gitlab	Markup renderer, depends on various other gems	gitlab-markup	gitlab-org/gitlab-markup	github/markup
gitaly-ruby	Main Gollum library	gitlab-gollum-lib	gitlab-org/gollum-lib	gollum/gollum-lib
	Gollum Git adapter for Rugged	gitlab-gollum-rugged_adapter	gitlab-org/gitlab-gollum-rugged_adapter	gollum/rugged_adapter
	Rugged (also used in Gitaly itself)	rugged	-	libgit2/rugged

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 Gollum's [[link]] syntax.

Because we do not make use of most of Gollum's 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 Model	Gitaly Class	Gollum
Wiki	Gitlab::Git::Wiki	Gollum::Wiki
WikiPage	Gitlab::Git::WikiPage, Gitlab::Git::WikiPageVersion	Gollum::Page
	Gitlab::Git::WikiFile	Gollum::File

Only some data is persisted in the database:

Model	Description
WikiPage::Meta	Metadata for wiki pages
WikiPage::Slug	Current and previous slugs of wiki pages
ProjectRepository	Gitaly storage data for project wikis
GroupWikiRepository	Gitaly 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.

Prior to GitLab 11.3 attachments were stored outside of the repository, see this issue.