- Choose the right words for your navigation entry
- Add a navigation entry
- How it works
- Introduced in GitLab 11.6.
- Updated in GitLab 12.1.
- Per-project navigation added in GitLab 12.2.
- Unified global navigation added in GitLab 13.11.
Global navigation is the left-most pane in the documentation. You can use the “global nav” to browse the content.
Research shows that people use Google to search for GitLab product documentation. When they land on a result, we want them to find topics nearby that are related to the content they’re reading. The global nav provides this information.
At the highest level, our global nav is workflow-based. Navigation needs to help users build a mental model of how to use GitLab. The levels under each of the higher workflow-based topics are the names of features. For example:
Use GitLab (workflow) > Build your application (workflow) > CI/CD (feature) > Pipelines (feature)
While some older sections of the nav are alphabetical, the nav should primarily be workflow-based.
Choose the right words for your navigation entry
Before you add an item to the left nav, choose the parts of speech you want to use.
The nav entry should match the page title. However, if the title is too long, when you shorten the phrase, use either:
- A noun, like Merge requests.
- An active verb, like Install GitLab or Get started with runners.
Use a phrase that clearly indicates what the page is for. For example, Get started is not as helpful as Get started with runners.
Add a navigation entry
To add a topic to the global nav, edit
and add your item.
Without a navigation entry:
- The navigation closes when the page is opened, and the reader loses their place.
- The page isn’t visible in a group with other pages.
Pages you don’t need to add
Exclude these pages from the global nav:
- Legal notices.
- Pages in the
- Pages in the
The following pages should probably be in the global nav, but the technical writers do not actively work to add them:
- Pages in the
- Pages authored by the support team, which are under the
Sometimes pages for deprecated features are not in the global nav, depending on how long ago the feature was deprecated.
All other pages should be in the global nav.
The technical writing team runs a report to determine which pages are not in the nav. The team reviews this list each month.
Where to add
Documentation pages can be said to belong in the following groups:
- GitLab users. This is documentation for day-to-day use of GitLab for users with any level of permissions, from Reporter to Owner.
- GitLab administrators. This tends to be documentation for self-managed instances that requires access to the underlying infrastructure hosting GitLab.
- Other documentation. This includes documentation for customers outside their day-to-day use of GitLab and for contributors. Documentation that doesn’t fit in the other groups belongs here.
With these groups in mind, the following are general rules for where new items should be added.
- User documentation for:
- Group-level features belongs under Groups.
- Project-level features belongs under Projects.
- Features outside a group or project level (sometimes called “instance-level”) can be placed at the top-level, but care must be taken not to overwhelm that top-level space. If possible, such features could be grouped in some way.
- Outside the above, most other miscellaneous user documentation belongs under User.
- Administration documentation belongs under Administrator.
- Other documentation belongs at the top-level, but care must be taken to not create an enormously long top-level navigation, which defeats the purpose of it.
Making all documentation and navigation items adhere to these principles is being progressively rolled out.
What to add
Having decided where to add a navigation element, the next step is deciding what to add. The mechanics of what is required is documented below but, in principle:
- Navigation item text (that which the reader sees) should:
- Be as short as possible.
- Be contextual. It’s rare to need to repeat text from a parent item.
- Avoid jargon or terms of art, unless ubiquitous. For example, CI is an acceptable substitution for Continuous Integration.
- Navigation links must follow the rules documented in the data file.
How it works
The global nav has five levels:
You can view this structure in the
Do not add items to the global nav without the consent of one of the technical writers.
The global nav is built from two files:
The data file feeds the layout with the links to the docs. The layout organizes the data among the nav in containers properly styled.
The data file describes the structure of the navigation for the applicable project. It is stored at https://gitlab.com/gitlab-org/gitlab-docs/blob/main/content/_data/navigation.yaml and comprises of three main components:
Each section represents the higher-level nav item. It’s composed by title and URL:
sections: - section_title: Text section_url: 'link'
The section can stand alone or contain categories within.
Each category within a section composes the second level of the nav. It includes the category title and link. It can stand alone in the nav or contain a third level of sub-items.
Example of section with one stand-alone category:
- section_title: Section title section_url: 'section-link' section_categories: - category_title: Category title category_url: 'category-link'
Example of section with two stand-alone categories:
- section_title: Section title section_url: 'section-link' section_categories: - category_title: Category 1 title category_url: 'category-1-link' - category_title: Category 2 title category_url: 'category-2-link'
For clarity, always add a blank line between categories.
Each doc represents the third, fourth, and fifth level of nav links. They must be always added within a category.
Example with three doc links, one at each level:
- category_title: Category title category_url: 'category-link' docs: - doc_title: Document title doc_url: 'doc-link' docs: - doc_title: Document title doc_url: 'doc-link' docs: - doc_title: Document title doc_url: 'doc-link'
A category supports as many docs as necessary, but, for clarity, try to not overpopulate a category. Also, do not use more than three levels of docs, it is not supported.
Example with multiple docs:
- category_title: Category title category_url: 'category-link' docs: - doc_title: Document 1 title doc_url: 'doc-1-link' - doc_title: Document 2 title doc_url: 'doc-2-link'
If you need to add a document in an external URL, add the attribute
below the doc link:
- doc_title: Document 2 title doc_url: 'doc-2-link' external_url: true
All nav links are selectable. If the higher-level link does not have a link
of its own, it must link to its first sub-item link, mimicking the navigation in GitLab.
This must be avoided so that we don’t have duplicated links nor two
at the same time.
- category_title: Operations category_url: 'ee/user/project/integrations/prometheus_library/' # until we have a link to operations, the first doc link is # repeated in the category link docs: - doc_title: Metrics doc_url: 'ee/user/project/integrations/prometheus_library/'
For all components (sections, categories, and docs), respect the indentation and the following syntax rules.
- Use sentence case, capitalizing feature names.
- There’s no need to wrap the titles, unless there’s a special char in it. For example,
GitLab CI/CD, there’s a
/present, therefore, it must be wrapped in quotes. As convention, wrap the titles in double quotes:
category_title: "GitLab CI/CD".
URLs can be either relative or external, and the following apply:
- All links in the data file must end with
.html(with the exception of
index.htmlfiles), and not
index.htmlfiles, use the clean (canonical) URL:
path/to/. For example,
- Do not start any relative link with a forward slash
- As convention, always wrap URLs in single quotes
- Always use the project prefix depending on which project the link you add
lives in. To find the global nav link, from the full URL remove
If a URL links to an external URL, like the GitLab Design System, add the attribute
external_url: true, for example:
- category_title: GitLab Design System category_url: 'https://design.gitlab.com' external_url: true
Examples of relative URLs:
|Full URL||Global nav URL|
Layout file (logic)
The layout is fed by the data file, builds the global nav, and is rendered by the default layout.
The global nav contains links from all four upstream projects. The global nav URL has a different prefix depending on the documentation file you change.
|Repository||Link prefix||Final URL|
The nav is styled in the general
stylesheet.scss. To change
its styles, keep them grouped for better development among the team.
The URL components have their unique styles set by the CSS classes
.level-2. To adjust the link’s font size, padding, color, etc,
use these classes. This way we guarantee that the rules for each link do not conflict
with other rules in the stylesheets.