1---
2type: reference, dev
3stage: Create
4group: Editor
5info: 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
6description: "GitLab's development guidelines for Wikis"
7---
8
9# Wikis development guide **(FREE)**
10
11> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227027) in GitLab 13.5.
12
13## Overview
14
15The wiki functionality in GitLab is based on [Gollum 4.x](https://github.com/gollum/gollum/).
16It's used in [Gitaly's](gitaly.md) Ruby service, and accessed from the Rails app through Gitaly RPC calls.
17
18Wikis use Git repositories as storage backend, and can be accessed through:
19
20- The [Web UI](../user/project/wiki/index.md)
21- The [REST API](../api/wikis.md)
22- [Git itself](../user/project/wiki/index.md#create-or-edit-wiki-pages-locally)
23
24[Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2214) in GitLab 13.5, wikis are also available
25for groups, in addition to projects.
26
27## Involved Gems
28
29Some notable gems that are used for wikis are:
30
31| Component     | Description                                    | Gem name                       | GitLab project                                                                                          | Upstream project                                                    |
32|:--------------|:-----------------------------------------------|:-------------------------------|:--------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------|
33| `gitlab`      | Markup renderer, depends on various other gems | `gitlab-markup`                | [`gitlab-org/gitlab-markup`](https://gitlab.com/gitlab-org/gitlab-markup)                               | [`github/markup`](https://github.com/github/markup)                 |
34| `gitaly-ruby` | Main Gollum library                            | `gitlab-gollum-lib`            | [`gitlab-org/gollum-lib`](https://gitlab.com/gitlab-org/gollum-lib)                                     | [`gollum/gollum-lib`](https://github.com/gollum/gollum-lib)         |
35|               | Gollum Git adapter for Rugged                  | `gitlab-gollum-rugged_adapter` | [`gitlab-org/gitlab-gollum-rugged_adapter`](https://gitlab.com/gitlab-org/gitlab-gollum-rugged_adapter) | [`gollum/rugged_adapter`](https://github.com/gollum/rugged_adapter) |
36|               | Rugged (also used in Gitaly itself)            | `rugged`                       | -                                                                                                       | [`libgit2/rugged`](https://github.com/libgit2/rugged)               |
37
38### Notes on Gollum
39
40We only use Gollum as a storage abstraction layer, to handle the mapping between wiki page slugs and files in the repository.
41
42When rendering wiki pages, we don't use Gollum at all and instead go through a
43[custom Banzai pipeline](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/banzai/pipeline/wiki_pipeline.rb).
44This adds some [wiki-specific markup](../user/markdown.md#wiki-specific-markdown), such as Gollum's `[[link]]` syntax.
45
46Because we do not make use of most of Gollum's features, we plan to move away from it entirely at some point.
47[See this epic](https://gitlab.com/groups/gitlab-org/-/epics/2381) for reference.
48
49## Model classes
50
51The `Wiki` class is the main abstraction around a wiki repository, it needs to be initialized
52with a container which can be either a `Project` or `Group`:
53
54```mermaid
55classDiagram
56  Wiki --> ProjectWiki
57  Wiki --> GroupWiki
58
59  class Wiki {
60    #container
61    #repository
62  }
63
64  class ProjectWiki {
65    #project → #container
66  }
67
68  class GroupWiki {
69    #group → #container
70  }
71```
72
73Some models wrap similar classes from Gitaly and Gollum:
74
75| Rails Model | Gitaly Class                                            | Gollum         |
76|:------------|:--------------------------------------------------------|:---------------|
77| `Wiki`      | `Gitlab::Git::Wiki`                                     | `Gollum::Wiki` |
78| `WikiPage`  | `Gitlab::Git::WikiPage`, `Gitlab::Git::WikiPageVersion` | `Gollum::Page` |
79|             | `Gitlab::Git::WikiFile`                                 | `Gollum::File` |
80
81Only some data is persisted in the database:
82
83| Model                 | Description                              |
84|:----------------------|:-----------------------------------------|
85| `WikiPage::Meta`      | Metadata for wiki pages                  |
86| `WikiPage::Slug`      | Current and previous slugs of wiki pages |
87| `ProjectRepository`   | Gitaly storage data for project wikis    |
88| `GroupWikiRepository` | Gitaly storage data for group wikis      |
89
90## Attachments
91
92The web UI uploads attachments through the REST API, which stores the files as commits in the wiki repository.
93
94Prior to GitLab 11.3 attachments were stored outside of the repository, [see this issue](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475).
95
96## Related topics
97
98- [Gollum installation instructions](https://github.com/gollum/gollum/wiki/Installation)
99