/doc/development/documentation/site_architecture/global_nav.md
Markdown | 304 lines | 225 code | 79 blank | 0 comment | 0 complexity | 70c2d374f99f73a1e77c22d5047e4bb3 MD5 | raw file
1---
2stage: none
3group: unassigned
4info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
5description: "Learn how GitLab docs' global navigation works and how to add new items."
6---
7
8# Global navigation
9
10> - [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/362) in GitLab 11.6.
11> - [Updated](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/482) in GitLab 12.1.
12> - [Per-project](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/498) navigation added in GitLab 12.2.
13> - [Unified global navigation](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/1482) added in GitLab 13.11.
14
15Global navigation is the left-most pane in the documentation. You can use the
16"global nav" to browse the content.
17
18Research shows that people use Google to search for GitLab product documentation. When they land on a result,
19we want them to find topics nearby that are related to the content they're reading. The global nav provides this information.
20
21At the highest level, our global nav is workflow-based. Navigation needs to help users build a mental model of how to use GitLab.
22The levels under each of the higher workflow-based topics are the names of features.
23For example:
24
25**Use GitLab** (_workflow_) **> Build your application** (_workflow_) **> CI/CD** (_feature_) **> Pipelines** (_feature)
26
27## Choose the right words for your navigation entry
28
29Before you add an item to the left nav, choose the parts of speech you want to use.
30
31The nav entry should match the page title. However, if the title is too long,
32when you shorten the phrase, use either:
33
34- A noun, like **Merge requests**.
35- An active verb, like **Install GitLab** or **Get started with runners**.
36
37Use a phrase that clearly indicates what the page is for. For example, **Get started** is not
38as helpful as **Get started with runners**.
39
40## Add a navigation entry
41
42All topics should be included in the left nav.
43
44To add a topic to the global nav, edit
45[`navigation.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/content/_data/navigation.yaml)
46and add your item.
47
48All new pages need a navigation item. Without a navigation, the page becomes "orphaned." That
49is:
50
51- The navigation shuts when the page is opened, and the reader loses their place.
52- The page doesn't belong in a group with other pages.
53
54This means the decision to create a new page is a decision to create new navigation item and vice
55versa.
56
57### Where to add
58
59Documentation pages can be said to belong in the following groups:
60
61- GitLab users. This is documentation for day-to-day use of GitLab for users with any level
62 of permissions, from Reporter to Owner.
63- GitLab administrators. This tends to be documentation for self-managed instances that requires
64 access to the underlying infrastructure hosting GitLab.
65- Other documentation. This includes documentation for customers outside their day-to-day use of
66 GitLab and for contributors. Documentation that doesn't fit in the other groups belongs here.
67
68With these groups in mind, the following are general rules for where new items should be added.
69
70- User documentation for:
71 - Group-level features belongs under **Groups**.
72 - Project-level features belongs under **Projects**.
73 - Features outside a group or project level (sometimes called "instance-level") can be placed at
74 the top-level, but care must be taken not to overwhelm that top-level space. If possible, such
75 features could be grouped in some way.
76 - Outside the above, most other miscellaneous user documentation belongs under **User**.
77- Administration documentation belongs under **Administrator**.
78- Other documentation belongs at the top-level, but care must be taken to not create an enormously
79 long top-level navigation, which defeats the purpose of it.
80
81Making all documentation and navigation items adhere to these principles is being progressively
82rolled out.
83
84### What to add
85
86Having decided where to add a navigation element, the next step is deciding what to add. The
87mechanics of what is required is [documented below](#data-file) but, in principle:
88
89- Navigation item text (that which the reader sees) should:
90 - Be as short as possible.
91 - Be contextual. It's rare to need to repeat text from a parent item.
92 - Avoid jargon or terms of art, unless ubiquitous. For example, **CI** is an acceptable
93 substitution for **Continuous Integration**.
94- Navigation links must follow the rules documented in the [data file](#data-file).
95
96## How it works
97
98The global nav has five levels:
99
100- Section
101 - Category
102 - Doc
103 - Doc
104 - Doc
105
106You can view this structure in [the navigation.yml file](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/content/_data/navigation.yaml).
107
108**Do not** [add items](#add-a-navigation-entry) to the global nav without
109the consent of one of the technical writers.
110
111## Composition
112
113The global nav is built from two files:
114
115- [Data](#data-file)
116- [Layout](#layout-file-logic)
117
118The data file feeds the layout with the links to the docs. The layout organizes
119the data among the nav in containers properly [styled](#css-classes).
120
121### Data file
122
123The data file describes the structure of the navigation for the applicable project.
124It is stored at <https://gitlab.com/gitlab-org/gitlab-docs/blob/main/content/_data/navigation.yaml>
125and comprises of three main components:
126
127- Sections
128- Categories
129- Docs
130
131#### Sections
132
133Each section represents the higher-level nav item. It's composed by
134title and URL:
135
136```yaml
137sections:
138 - section_title: Text
139 section_url: 'link'
140```
141
142The section can stand alone or contain categories within.
143
144#### Categories
145
146Each category within a section composes the second level of the nav.
147It includes the category title and link. It can stand alone in the nav or contain
148a third level of sub-items.
149
150Example of section with one stand-alone category:
151
152```yaml
153- section_title: Section title
154 section_url: 'section-link'
155 section_categories:
156 - category_title: Category title
157 category_url: 'category-link'
158```
159
160Example of section with two stand-alone categories:
161
162```yaml
163- section_title: Section title
164 section_url: 'section-link'
165 section_categories:
166 - category_title: Category 1 title
167 category_url: 'category-1-link'
168
169 - category_title: Category 2 title
170 category_url: 'category-2-link'
171```
172
173For clarity, **always** add a blank line between categories.
174
175#### Docs
176
177Each doc represents the third, fourth, and fifth level of nav links. They must be always
178added within a category.
179
180Example with three doc links, one at each level:
181
182```yaml
183- category_title: Category title
184 category_url: 'category-link'
185 docs:
186 - doc_title: Document title
187 doc_url: 'doc-link'
188 docs:
189 - doc_title: Document title
190 doc_url: 'doc-link'
191 docs:
192 - doc_title: Document title
193 doc_url: 'doc-link'
194```
195
196A category supports as many docs as necessary, but, for clarity, try to not
197overpopulate a category. Also, do not use more than three levels of docs, it
198is not supported.
199
200Example with multiple docs:
201
202```yaml
203- category_title: Category title
204 category_url: 'category-link'
205 docs:
206 - doc_title: Document 1 title
207 doc_url: 'doc-1-link'
208 - doc_title: Document 2 title
209 doc_url: 'doc-2-link'
210```
211
212If you need to add a document in an external URL, add the attribute `external_url`
213below the doc link:
214
215```yaml
216- doc_title: Document 2 title
217 doc_url: 'doc-2-link'
218 external_url: true
219```
220
221All nav links are clickable. If the higher-level link does not have a link
222of its own, it must link to its first sub-item link, mimicking the navigation in GitLab.
223This must be avoided so that we don't have duplicated links nor two `.active` links
224at the same time.
225
226Example:
227
228```yaml
229- category_title: Operations
230 category_url: 'ee/user/project/integrations/prometheus_library/'
231 # until we have a link to operations, the first doc link is
232 # repeated in the category link
233 docs:
234 - doc_title: Metrics
235 doc_url: 'ee/user/project/integrations/prometheus_library/'
236```
237
238#### Syntax
239
240For all components (sections, categories, and docs), **respect the indentation**
241and the following syntax rules.
242
243##### Titles
244
245- Use sentence case, capitalizing feature names.
246- There's no need to wrap the titles, unless there's a special char in it. For example,
247 in `GitLab CI/CD`, there's a `/` present, therefore, it must be wrapped in quotes.
248 As convention, wrap the titles in double quotes: `category_title: "GitLab CI/CD"`.
249
250##### URLs
251
252URLs can be either relative or external, and the following apply:
253
254- All links in the data file must end with `.html` (with the exception
255 of `index.html` files), and not `.md`.
256- For `index.html` files, use the clean (canonical) URL: `path/to/`. For example, `https://docs.gitlab.com/ee/install/index.html` becomes `ee/install/`.
257- Do not start any relative link with a forward slash `/`.
258- As convention, always wrap URLs in single quotes `'url'`.
259- Always use the project prefix depending on which project the link you add
260 lives in. To find the global nav link, from the full URL remove `https://docs.gitlab.com/`.
261- If a URL links to an external URL, like the [GitLab Design System](https://design.gitlab.com),
262 add the attribute `external_url: true`, for example:
263
264 ```yaml
265 - category_title: GitLab Design System
266 category_url: 'https://design.gitlab.com'
267 external_url: true
268 ```
269
270Examples of relative URLs:
271
272| Full URL | Global nav URL |
273| -------------------------------------------------------------- | ------------------------------------- |
274| `https://docs.gitlab.com/ee/api/avatar.html` | `ee/api/avatar.html` |
275| `https://docs.gitlab.com/ee/install/index.html` | `ee/install/` |
276| `https://docs.gitlab.com/omnibus/settings/database.html` | `omnibus/settings/database.html` |
277| `https://docs.gitlab.com/charts/installation/deployment.html` | `charts/installation/deployment.html` |
278| `https://docs.gitlab.com/runner/install/docker.html` | `runner/install/docker.html` |
279
280### Layout file (logic)
281
282The [layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/layouts/global_nav.html)
283is fed by the [data file](#data-file), builds the global nav, and is rendered by the
284[default](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/layouts/default.html) layout.
285
286The global nav contains links from all [four upstream projects](index.md#architecture).
287The [global nav URL](#urls) has a different prefix depending on the documentation file you change.
288
289| Repository | Link prefix | Final URL |
290|----------------------------------------------------------------|-------------|------------------------------------|
291| <https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc> | `ee/` | `https://docs.gitlab.com/ee/` |
292| <https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/doc> | `omnibus/` | `https://docs.gitlab.com/omnibus/` |
293| <https://gitlab.com/gitlab-org/gitlab-runner/-/tree/main/docs> | `runner/` | `https://docs.gitlab.com/runner/` |
294| <https://gitlab.com/charts/gitlab/tree/master/doc> | `charts/` | `https://docs.gitlab.com/charts/` |
295
296### CSS classes
297
298The nav is styled in the general `stylesheet.scss`. To change
299its styles, keep them grouped for better development among the team.
300
301The URL components have their unique styles set by the CSS classes `.level-0`,
302`.level-1`, and `.level-2`. To adjust the link's font size, padding, color, etc,
303use these classes. This way we guarantee that the rules for each link do not conflict
304 with other rules in the stylesheets.