1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
|
---
stage: Create
group: Editor
info: 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
description: "GitLab's development guidelines for Wikis"
---
# Wikis development guide **(FREE)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227027) in GitLab 13.5.
## Overview
The wiki functionality in GitLab is based on [Gollum 4.x](https://github.com/gollum/gollum/).
It's used in [Gitaly's](gitaly.md) 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](../user/project/wiki/index.md)
- The [REST API](../api/wikis.md)
- [Git itself](../user/project/wiki/index.md#create-or-edit-wiki-pages-locally)
[Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2214) 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`](https://gitlab.com/gitlab-org/gitlab-markup) | [`github/markup`](https://github.com/github/markup) |
| `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) |
| | 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) |
| | Rugged (also used in Gitaly itself) | `rugged` | - | [`libgit2/rugged`](https://github.com/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](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/banzai/pipeline/wiki_pipeline.rb).
This adds some [wiki-specific markup](../user/markdown.md#wiki-specific-markdown), 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](https://gitlab.com/groups/gitlab-org/-/epics/2381) 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`:
```mermaid
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.
## Related topics
- [Gollum installation instructions](https://github.com/gollum/gollum/wiki/Installation)
|
