GitLab Wiki Page Tips
Tags: gitlab, wiki, opensource, documentation
Published: 2021-01-29 17:40:03

First of all, I am a big fan of **GitLab** :heart:

I work as a software team leader on an embedded software project. We are using GitLab to manage our software life cycle. GitLab offers hosting our software repositories, a simple issue tracking system, visualized gitflow architectures with different member access permissions, CI/CD support, **wiki support** and more.

When I was writing the wiki pages of our software project, I decided to note down the important tips that I have learned during this process.

Let's start! :rocket:

### **:white_check_mark: Use a Separate GitLab Project to Host Wiki Pages**

Let's say you have multiple software projects inside your GitLab group/subgroup, and you have to prepare common documentation for these software projects. Since *"GitLab Free Plan"* (GitLab Release 13.8) does not support group/subgroup level wikis, we need to find a sensible place to host this wiki. 

Let's create a new project on the same hierarchical level with our software projects. This project will only host common wiki pages for our software projects, nothing more. This solves our common project documentation problem.

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/z99axa4gl8bb5t50z9ef.png)

### **:white_check_mark: Set Homepage of Wiki**

When I start generating wiki pages, one thing bothered me. Why was I seeing the ***"Create New Page"*** screen as the homepage of my wiki? How can I specify an existing page as the homepage of my wiki?

The solution is to create a page named ***home*** (home.md). The default behavior of GitLab is to show the page ***home*** as the homepage of the wiki. Without a ***home*** page, ***"Create New Page"*** screen is always shown to the user.

### **:white_check_mark: Disable Other Features in Wiki Project**

Since our wiki project will only host wiki data, other features that are available on the left sidebar menu can be disabled for the sake of simplicity. 

*Left Sidebar Menu* :arrow_right: *Settings* :arrow_right: *General* :arrow_right: *Visibility, project features, permissions* :arrow_right: ***Issues, Repository, Analytics, Pages and Operations***
can all be disabled.

After disabling, GitLab will automatically show the homepage of wiki (home.md) as the new project homepage.

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/ty7zfa3jpvtdyiwzt20o.png)

### **:white_check_mark: Group Pages Inside Directories**

You can group related wiki pages inside directories. When creating a new page, you can name your page as;

```
Directory/Page
```

and GitLab will create a directory named ***Directory*** and create your ***Page*** inside your ***Directory***.

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/kj7jwhl2k0ixq7xc8j9r.png)

### **:white_check_mark: Edit Right Sidebar**

After finishing all my wiki pages, another thing bothered me. How can I change the order of the wiki page links on the right sidebar? One can desire to order these links according to their priorities or alphabetically. By clicking ***"Edit Sidebar"*** button on the right sidebar, you can create a page named ***_sidebar***. Similar to the ***home*** name, ***_sidebar*** is a special name in GitLab. The contents of ***_sidebar*** page is used to design your custom right sidebar. You can add headers, links, images, basically everything that you can do with a markdown file. An example content of a ***_sidebar*** page is given below. Example pages named ***a-page, b-page and c-page*** will be sorted alphabetically on the right sidebar and the page named ***home*** will be the header page.

```
### [Home](home)

- [A Page](a-page)
- [B Page](b-page)
- [C Page](c-page)

```

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/gxanofogwgpl3u4c5d5x.png)

### **:white_check_mark: Edit Wiki Locally with Gollum**

What if we want to edit our wiki when we are not connected to the GitLab server? Using ***Gollum***, this is also possible. Get installation instructions and more information from [here](https://github.com/gollum/gollum/wiki/Installation). Since every wiki is actually a Git repository, we can clone our wiki to our local computer, start Gollum and edit our wiki locally. When the GitLab server is available again, we can push our changes back to GitLab.

### **:white_check_mark: Last Words**

GitLab Wiki is simple to use if you are familiar with markdown language. Keeping the documentation of your software project outside of your source code repository provides a faster Git experience. To be able to compare older versions of wiki pages with the page history feature is also a plus. In future, I will use GitLab or equivalent wiki pages more often instead of traditional documentation methods.

Thanks for reading :computer: