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:
- The Web UI
- The REST API
- Git itself
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 |
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 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
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support