PageRenderTime 4094ms CodeModel.GetById 33ms RepoModel.GetById 1ms app.codeStats 0ms

/doc/development/documentation/site_architecture/global_nav.md

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