Skip to content
Projects
Groups
Snippets
Help
Loading...
Help
Support
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
G
gitlab-ce
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Issues
0
Issues
0
List
Boards
Labels
Milestones
Merge Requests
0
Merge Requests
0
Analytics
Analytics
Repository
Value Stream
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Commits
Issue Boards
Open sidebar
Boxiang Sun
gitlab-ce
Commits
38c30b3e
Commit
38c30b3e
authored
5 years ago
by
Evan Read
Committed by
Achilleas Pipinellis
5 years ago
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Provide guidance on how docs global navigation should be structured
parent
8d1d7b2f
Changes
2
Show whitespace changes
Inline
Side-by-side
Showing
2 changed files
with
73 additions
and
22 deletions
+73
-22
doc/development/documentation/site_architecture/global_nav.md
...development/documentation/site_architecture/global_nav.md
+68
-19
doc/development/documentation/site_architecture/index.md
doc/development/documentation/site_architecture/index.md
+5
-3
No files found.
doc/development/documentation/site_architecture/global_nav.md
View file @
38c30b3e
...
...
@@ -4,30 +4,74 @@ description: "Learn how GitLab docs' global navigation works and how to add new
# Global navigation
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/merge_requests/362)
in GitLab 11.6.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/merge_requests/362) in GitLab 11.6.
> - [Updated](https://gitlab.com/gitlab-org/gitlab-docs/merge_requests/482) in GitLab 12.1.
> - [Per-project](https://gitlab.com/gitlab-org/gitlab-docs/merge_requests/498) navigation added in GitLab 12.2.
The global nav adds to the left sidebar the ability to
navigate and explore the contents of GitLab's documentation.
Global navigation (the left-most pane in our three pane documentation) provides:
The global nav should be maintained consistent through time to allow the
users to locate their most-visited links easily to facilitate navigation.
Therefore, any updates must be carefully considered by the technical writers.
-
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.
## Adding new items
to the global nav
## Adding new items
To add a new doc to the nav, first and foremost, check with the technical writing team:
All new pages need a new navigation item. Without a navigation, the page becomes "orphaned". That
is:
-
If it's applicable
-
What's the exact position the doc will be added to the nav
-
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.
Once you get their approval and their guidance in regards to the position on the nav,
read trhough this page to understand how it works, and submit a merge request to the
docs site, adding the doc you wish to include in the nav into the
[
global nav data file
](
https://gitlab.com/gitlab-org/gitlab-docs/blob/master/content/_data/global-nav.yaml
)
.
This means the decision to create a new page is a decision to create new navigation item and vice
versa.
Don't forget to ask a technical writer to review your changes before merging.
### 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
](
#data-file
)
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
](
#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
...
...
@@ -55,7 +99,7 @@ To see the improvements planned, check the
[
global nav epic
](
https://gitlab.com/groups/gitlab-com/-/epics/21
)
.
CAUTION:
**Attention!**
**Do not**
[
add items
](
#adding-new-items
-to-the-global-nav
)
to the global nav without
**Do not**
[
add items
](
#adding-new-items
)
to the global nav without
the consent of one of the technical writers.
## Composition
...
...
@@ -70,8 +114,13 @@ the data among the nav in containers properly [styled](#css-classes).
### Data file
The
[
data file
](
https://gitlab.com/gitlab-org/gitlab-docs/blob/master/content/_data/global-nav.yaml
)
is structured in three components: sections, categories, and docs.
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
...
...
This diff is collapsed.
Click to expand it.
doc/development/documentation/site_architecture/index.md
View file @
38c30b3e
...
...
@@ -66,10 +66,12 @@ the GitLab Documentation website.
-
[
Google Analytics
](
https://marketingplatform.google.com/about/analytics/
)
-
[
Google Tag Manager
](
https://developers.google.com/tag-manager/
)
## Global nav
## Global nav
igation
To understand how the global nav (left sidebar) is built, please
read through the
[
global navigation
](
global_nav.md
)
doc.
Read through the global navigation](global_nav.md) documentation to understand:
-
How the global navigation is built.
-
How to add new navigation items.
## Deployment
...
...
This diff is collapsed.
Click to expand it.
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment