14 KiB
stage | group | info | description |
---|---|---|---|
none | unassigned | To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers | Learn how GitLab docs' global navigation works and how to add new items. |
Global navigation
- Introduced in GitLab 11.6.
- Updated in GitLab 12.1.
- Per-project navigation added in GitLab 12.2.
Global navigation (the left-most pane in our three pane documentation) provides:
- A high-level grouped view of product features.
- The ability to discover new features by browsing the menu structure.
- A way to allow the reader to focus on product areas.
- The ability to refine landing pages, so they don't have to do all the work of surfacing every page contained within the documentation.
Quick start
To add a topic to the global nav, go to the directory that contains
navigation files
and edit the yaml
file for your product area. You can copy an existing nav entry and
edit it to point to your topic.
The files are:
File | Document | Location |
---|---|---|
charts-nav.yaml |
GitLab cloud native Helm Chart | https://docs.gitlab.com/charts/ |
default-nav.yaml |
GitLab Docs | https://docs.gitlab.com/ee/ |
omnibus-nav.yaml |
Omnibus GitLab Docs | https://docs.gitlab.com/omnibus/ |
runner-nav.yaml |
GitLab Runner Docs | https://docs.gitlab.com/runner/ |
Adding new items
All new pages need a new navigation item. Without a navigation, the page becomes "orphaned". That is:
- The navigation shuts when the page is opened, and the reader loses their place.
- The page doesn't belong in a group with other pages.
This means the decision to create a new page is a decision to create new navigation item and vice versa.
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.
NOTE: Note: 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.
- EE badging is subject to the following:
- Required when linking to an EE-only page.
- Not required when linking to a page that is a mix of CE and EE-only content.
- Required when all sub-items are EE-only. In this case, no sub-items are EE badged.
- Not required when sub-items are a mix of CE and EE-only items. In this case, each item is badged appropriately.
How it works
The global nav has 3 components:
- Section
- Category
- Doc
- Category
The available sections are described on the table below:
Section | Description |
---|---|
User | Documentation for the GitLab's user UI. |
Administrator | Documentation for the GitLab's Admin Area. |
Contributor | Documentation for developing GitLab. |
The majority of the links available on the nav were added according to the UI. The match is not perfect, as for some UI nav items the documentation doesn't apply, and there are also other links to help the new users to discover the documentation. The docs under Administration are ordered alphabetically for clarity.
To see the improvements planned, check the global nav epic.
NOTE: Note: Do not add items to the global nav without the consent of one of the technical writers.
Composition
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.
Data file
The data file describes the structure of the navigation for the applicable project. All data files are stored at https://gitlab.com/gitlab-org/gitlab-docs/blob/master/content/_data/ and comprise three components:
- Sections
- Categories
- Docs
Sections
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.
Categories
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.
If a category URL is not present in CE (it's an EE-only document), add the
attribute ee_only: true
below the category link. Example:
- category_title: Category title
category_url: 'category-link'
ee_only: true
If the category links to an external URL, e.g., GitLab Design System,
add the attribute external_url: true
below the category title. Example:
- category_title: GitLab Design System
category_url: 'https://design.gitlab.com'
external_url: true
Docs
Each doc represents the third level of nav links. They must be always added within a category.
Example with one doc link:
- category_title: Category title
category_url: 'category-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.
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'
Whenever a document is only present in EE, add the attribute ee-only: true
below the doc link. Example:
- doc_title: Document 2 title
doc_url: 'doc-2-link'
ee_only: true
If you need to add a document in an external URL, add the attribute external_url
below the doc link:
- doc_title: Document 2 title
doc_url: 'doc-2-link'
external_url: true
All nav links are clickable. If the higher-level link does not have a link
of its own, it must link to its first sub-item link, mimicking GitLab's navigation.
This must be avoided so that we don't have duplicated links nor two .active
links
at the same time.
Example:
- category_title: Operations
category_url: '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: 'user/project/integrations/prometheus_library/'
Syntax
For all components (sections, categories, and docs), respect the indentation and the following syntax rules.
Titles
- Use sentence case, capitalizing feature names.
- There's no need to wrap the titles, unless there's a special char in it. E.g.,
in
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
- As convention, always wrap URLs in single quotes
'url'
. - Always use relative paths against the home of CE and EE. Examples:
- For
https://docs.gitlab.com/ee/README.html
, the relative URL isREADME.html
. - For
https://docs.gitlab.com/ee/user/project/cycle_analytics.html
, the relative URL isuser/project/cycle_analytics.html
.
- For
- For
README.html
files, add the complete pathpath/to/README.html
. - For
index.html
files, use the clean (canonical) URL:path/to/
. - For EE-only docs, use the same relative path, but add the attribute
ee_only: true
below thedoc_url
orcategory_url
, as explained above. This displays an "information" icon on the nav to make the user aware that the feature is EE-only.
CAUTION: Caution:
All links present on the data file must end in .html
, not .md
. Do not
start any relative link with a forward slash /
.
Examples:
- category_title: Issues
category_url: 'user/project/issues/'
# note that the above URL does not start with a slash and
# does not include index.html at the end
docs:
- doc_title: Container Scanning
doc_url: 'user/application_security/container_scanning/'
ee_only: true
# note that the URL above ends in html and, as the
# document is EE-only, the attribute ee_only is set to true.
Layout file (logic)
The layout is fed by the data file, builds the global nav, and is rendered by the default layout.
There are three main considerations on the logic built for the nav:
- Path: first-level directories underneath
docs.gitlab.com/
:https://docs.gitlab.com/ce/
https://docs.gitlab.com/ee/
https://docs.gitlab.com/omnibus/
https://docs.gitlab.com/runner/
https://docs.gitlab.com/*
- EE-only: documentation only available in
/ee/
, not on/ce/
, e.g.:https://docs.gitlab.com/ee/user/group/epics/
https://docs.gitlab.com/ee/user/project/security_dashboard.html
- Default URL: between CE and EE docs, the default is
ee
, therefore, all docs should link to/ee/
unless if on/ce/
linking internally toce
.
Path
To use relative paths in the data file, we defined the variable dir
from the root's first-child directory, which defines the path to build
all the nav links to other pages:
<% dir = @item.identifier.to_s[%r{(?<=/)[^/]+}] %>
For instance, for https://docs.gitlab.com/ee/user/index.html
,
dir
== ee
, and for https://docs.gitlab.com/omnibus/README.html
,
dir
== omnibus
.
Default URL
The default and canonical URL for GitLab documentation is
https://docs.gitlab.com/ee/
, thus, all links
in the docs site should link to /ee/
except when linking
among /ce/
docs themselves.
Therefore, if the user is looking at /ee/
, /omnibus/
,
/runner/
, or any other highest-level dir, the nav should
point to /ee/
docs.
On the other hand, if the user is looking at /ce/
docs,
all the links in the CE nav should link internally to /ce/
files.
<% if dir != 'ce' %>
<a href="/ee/<%= sec[:section_url] %>">...</a>
<% else %>
<a href="/<%= dir %>/<%= sec[:section_url] %>">...</a>
<% end %>
...
<% end %>
This also allows the nav to be displayed on other
highest-level directories (/omnibus/
, /runner/
, etc),
linking them back to /ee/
.
The same logic is applied to all sections (sec[:section_url]
),
categories (cat[:category_url]
), and docs (doc[:doc_url]
) URLs.
ee-only
docs
Docs for features present only in GitLab EE are tagged
in the data file by ee-only
and an icon is displayed on the nav
link indicating that the ee-only
feature is not available in CE.
The ee-only
attribute is available for categories
(<% if cat[:ee_only] %>
)
and docs
(<% if doc[:ee_only] %>
), but not for sections
.
CSS classes
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-0
,
.level-1
, and .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.