First of all, I am a big fan of GitLab ❤️
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! 🚀
✅ 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.
✅ 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.
✅ 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 ➡️ Settings ➡️ General ➡️ Visibility, project features, permissions ➡️ 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.
✅ 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.
✅ 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)
✅ 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. 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.
✅ 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 💻
Top comments (0)