Commit c2ae255d authored by Markus Koller's avatar Markus Koller

Merge branch 'docs-wiki-architecture' into 'master'

Add development guidelines for wikis

See merge request gitlab-org/gitlab!43558
parents 28207308 64ad72fd
......@@ -66,6 +66,7 @@ exceptions:
- POST
- PUT
- RAM
- REST
- RPC
- RSA
- RSS
......
......@@ -167,6 +167,7 @@ Gitleaks
Gitter
globals
Gmail
Gollum
Google
Gosec
Gradle
......
......@@ -116,6 +116,7 @@ Complementary reads:
- [Code Intelligence](code_intelligence/index.md)
- [Approval Rules](approval_rules.md)
- [Feature categorization](feature_categorization/index.md)
- [Wikis development guide](wikis.md)
## Performance guides
......
---
type: reference, dev
stage: none
group: Development
info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines"
description: "GitLab's development guidelines for Wikis"
---
# Wikis development guide
> [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/),
which is 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/#adding-and-editing-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.
Since 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.
Prior to GitLab 11.3 attachments were stored outside of the repository, [see this issue](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475).
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment