Wiki, snippets, Pages, Web IDE
Intermediate GitLab UI
Why this matters
Documentation people spend their days deciding where a piece of writing belongs, and GitLab offers four plausible homes. Choosing the wrong one is not fatal, but it costs a migration later. These four features are also the ones you can use without any Git knowledge at all, which makes them the easiest place to start contributing.
Which home for which writing
| Put it in | When |
|---|---|
The repository (docs/, README.md) |
It must be reviewed, versioned with the code, and shipped with a release |
| The wiki | It is context that changes on its own schedule: runbooks, meeting notes, onboarding, decisions |
| An issue | It is about one piece of work, and it will stop mattering when that work is done |
| A snippet | It is a fragment worth sharing but belongs to no project: a command, a config sample, a query |
The dividing question for the first two is review: repository content goes through a merge request and can block a release; wiki content is saved immediately. If a mistake in the text would be a bug, it belongs in the repository.
The wiki
Plan → Wiki. An empty wiki offers Create your first page, whose path must be home. Pages are Markdown by default, they support the same links and images as anywhere else, and the sidebar is generated from the page titles unless a _sidebar page overrides it.
The part people miss: a wiki is its own Git repository, separate from the project's code. Wiki actions → Clone repository gives you the URL, and from then on it behaves like any other repository:
$ git clone git@gitlab.com:northwind-trails/trailguide.wiki.git
$ cd trailguide.wikiThat matters when you want to write ten pages in your editor, restructure a wiki, or search and replace across it. Every web edit is a commit, so the wiki has a full history and each page has a Page history view.
Snippets
A snippet is a small set of files with a URL. Code → Snippets for project snippets, and the Create new (+) menu for personal ones, which are listed on your snippets dashboard.
| Project snippet | Personal snippet | |
|---|---|---|
| Belongs to | The project | You |
| Visibility | Bounded by the project's; a public snippet in a private project stays private | Public or private |
| Good for | A sample config the team keeps re-sending, a reproduction case | Your own commands and notes |
Snippets are version controlled, hold up to 10 files, render Markdown, and can be embedded in an issue or a wiki page. They are the right answer to "can you paste that command again?" and the wrong answer to anything a colleague will need to find in six months.
Pages
GitLab Pages publishes a static website from a project, which is how many teams host documentation. The mechanics are ordinary CI/CD (lesson 9.10):
- A job in
.gitlab-ci.ymlbuilds the site and puts the result in a folder calledpublic. - The job is marked as the Pages deployment, historically by naming it
pages, in current versions by settingpages: true. - The folder is kept as an artifact, and GitLab serves it.
- Deploy → Pages shows the site's URL and its settings, including whether it is public.
pages:
stage: deploy
script:
- mkdocs build --site-dir public
artifacts:
paths:
- publicThe default address follows the namespace: a project owned by the user example is served under example.gitlab.io. Custom domains are configured on the same settings page.
What this means for a writer: your documentation is published by pushing. A merge request to main is a preview-and-review step, and the merge is the publication. That is worth knowing before you ask someone to "put the new page online".
The Web IDE
The Web IDE is a full editor in the browser, built on the same technology as VS Code, generally available since GitLab 18.0. It is not the small single-file editor from lesson 7.8; it opens the whole project, keeps a file tree, searches across files, and commits several changes at once to a branch.
| Open it from | How |
|---|---|
| Anywhere in a project | Press . (full stop) |
| A directory | Code → Open in Web IDE |
| A file | Edit → Open in Web IDE |
| A merge request | Code → Open in Web IDE in the upper right |
Use it when you have a handful of related edits and no clone at hand: fixing five files after a rename, or applying review comments from a borrowed laptop. Use a real clone when you need to run anything, because the Web IDE edits files but does not run your project.
How to do it
The wiki and each snippet are repositories, so the terminal works on them normally:
$ git clone git@gitlab.com:northwind-trails/trailguide.wiki.git
$ cd trailguide.wikiEach page is a Markdown file named after its path, so home.md is the front page. Edit, commit and push as usual; the web wiki updates immediately. There is no merge request step, because the wiki has no protected branches.
Clone the wiki repository like any other and edit it in VS Code, with Markdown preview open. The GitLab Workflow extension can also insert a snippet from the project into the current file, and create a new snippet from a selection.
Clone the wiki repository as a project. IntelliJ renders Markdown in a split preview, which is the main reason to edit a wiki in an IDE rather than the browser.
- Plan → Wiki, then Create your first page or New page; Page history shows every edit as a commit.
- Wiki actions → Clone repository for the URL when you want to work locally.
- Code → Snippets for project snippets; the Create new (+) menu for a personal one.
- Deploy → Pages for the published site's address and settings.
- Press . anywhere in a project to open the Web IDE, then use its Source Control panel to commit to a new branch and start a merge request.
The equivalents are a wiki (also a separate Git repository), gists instead of snippets, GitHub Pages with its own settings page, and github.dev, opened with the same . key. See lesson 10.11.
Common mistakes
- Product documentation in the wiki. No review, no versioning with releases, and it drifts.
- Runbooks in the repository that need a merge request to fix a phone number.
- Treating a snippet as documentation. Snippets are not searchable in the way people expect and nobody inherits them.
- Assuming the wiki cannot be edited locally. It is a Git repository; clone it.
- Expecting the Web IDE to run the project. It edits and commits; it does not execute.
- Editing the Pages site directly. There is no such thing: the site is rebuilt from the repository by a job.
Try it yourself
Goal: use all four, and notice what each one is good at.
- In your practice project, create a wiki page called
homewith three lines about the project. - Clone the wiki repository (Wiki actions → Clone repository), add a second page as a Markdown file locally, commit and push, and refresh the wiki.
- Create a project snippet holding the two commands you use most in this course.
- Open the project's Web IDE with the . key, change two files, and commit them to a new branch from the Source Control panel.
- Note which of the four created a merge request, and which changed something immediately.
Expected result: the wiki has two pages, one written in the browser and one pushed from your clone; a snippet exists; and the Web IDE has produced a branch you can open a merge request from.
Show solution
Only step 4 leads to review. Steps 1 to 3 change something the moment you click save, which is the practical difference between the wiki and snippets on one side and the repository on the other. Choose accordingly: writing that must be right at the moment of a release belongs where review happens.