Global navigation · Gitlab 中文文档

# Global navigation > 原文：[https://docs.gitlab.com/ee/development/documentation/site_architecture/global_nav.html](https://docs.gitlab.com/ee/development/documentation/site_architecture/global_nav.html) * [Quick start](#quick-start) * [Adding new items](#adding-new-items) * [Where to add](#where-to-add) * [What to add](#what-to-add) * [How it works](#how-it-works) * [Composition](#composition) * [Data file](#data-file) * [Sections](#sections) * [Categories](#categories) * [Docs](#docs) * [Syntax](#syntax) * [Titles](#titles) * [URLs](#urls) * [Layout file (logic)](#layout-file-logic) * [Path](#path) * [Default URL](#default-url) * [`ee-only` docs](#ee-only-docs) * [CSS classes](#css-classes) # Global navigation[](#global-navigation "Permalink") 版本历史 * 在 GitLab 11.6 中[引入](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/362) . * 在 GitLab 12.1 中[更新](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/482) . * 在 GitLab 12.2 中添加了按[项目](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/498)导航. 全局导航（三窗格文档中最左侧的窗格）提供： * 产品功能的高层分组视图. * 通过浏览菜单结构发现新功能的能力. * 一种让读者专注于产品领域的方法. * 能够优化登录页面的功能，因此他们不必完成覆盖文档中包含的每个页面的所有工作. ## Quick start[](#quick-start "Permalink") 要将主题添加到全局导航，请转到包含[导航文件](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/content/_data/)的目录，然后编辑产品区域的`yaml`文件. 您可以复制现有的导航条目并将其编辑以指向您的主题. 这些文件是： | File | Document | Location | | --- | --- | --- | | `charts-nav.yaml` | GitLab 云原生头盔图 | `https://docs.gitlab.com/charts/` | | `default-nav.yaml` | 亚搏体育 app 文件 | `https://docs.gitlab.com/ee/` | | `omnibus-nav.yaml` | Omnibus GitLab Docs | `https://docs.gitlab.com/omnibus/` | | `runner-nav.yaml` | 亚搏体育 app Runner Docs | `https://docs.gitlab.com/runner/` | ## Adding new items[](#adding-new-items "Permalink") 所有新页面都需要一个新的导航项. 如果没有导航，页面将变为"孤立". 那是： * 打开页面时，导航会关闭，并且阅读器会失去位置. * 该页面与其他页面不属于同一组. 这意味着创建新页面的决定就是创建新导航项的决定，反之亦然. ### Where to add[](#where-to-add "Permalink") 文档页面可以说属于以下几类： * GitLab 用户. 这是用于从 Reporter 到 Owner 拥有任何级别权限的用户日常使用 GitLab 的文档. * GitLab 管理员. 这往往是自我管理实例的文档，这些实例需要访问托管 GitLab 的基础架构. * 其他文档. 其中包括针对日常使用 GitLab 的客户以及贡献者的文档. 属于其他组的文档属于此处. 考虑到这些组，以下是应在何处添加新项目的一般规则. * 用户文档： * 组级别功能属于" **组"** . * 项目级功能属于" **项目"** . * 可以将组或项目级别（有时称为"实例级别"）之外的功能放在顶层，但是必须注意不要淹没该顶层空间. 如果可能，可以以某种方式对这些功能进行分组. * 除上述内容外，其他大多数其他用户文档都属于**User** . * 管理文档属于**Administrator** . * 其他文档属于顶层文档，但必须注意不要创建冗长的顶层导航，这会违背它的目的. **注意：**正在逐步推出使所有文档和导航项目都遵循这些原则的方法. ### What to add[](#what-to-add "Permalink") 确定了在哪里添加导航元素之后，下一步就是确定要添加的内容. 需要什么样的机制被[证明以下](#data-file) ，但在原则： * 导航项文本（读者看到的文本）应： * 越短越好. * 要根据具体情况. 很少需要重复父项中的文本. * 避免使用行话或艺术术语，除非无处不在. 例如， **CI**是**持续集成**的可接受替代. * 导航链接必须遵循[数据文件中](#data-file)记录的规则. * EE 徽章受以下条件限制： * 链接到仅 EE 的页面时必需. * 链接到仅包含 CE 和 EE 内容的页面时，不需要. * 当所有子项目均为 EE 专用时为必填项. 在这种情况下，没有子项目带有 EE 标志. * 如果子项目是仅包含 CE 和 EE 的项目，则不需要. 在这种情况下，每个项目都将被适当标记. ## How it works[](#how-it-works "Permalink") 全局导航具有 3 个组成部分： * **Section** * Category * Doc 下表描述了可用的部分： | Section | Description | | --- | --- | | User | GitLab 用户界面的文档. | | Administrator | GitLab 管理区域的文档. | | Contributor | 开发 GitLab 的文档. | 根据用户界面添加了导航上可用的大多数链接. 匹配并不完美，因为某些 UI 导航项不适用于该文档，并且还有其他链接可帮助新用户发现文档. 为了清楚起见，" **管理** "下的文档按字母顺序排列. 要查看计划中的改进，请查看[全局导航史诗](https://gitlab.com/groups/gitlab-com/-/epics/21) . **注意：**未经技术作者之一的同意， **请勿** [将项目添加](#adding-new-items)到全局导航. ## Composition[](#composition "Permalink") 全局导航由两个文件构建： * [Data](#data-file) * [Layout](#layout-file-logic) 数据文件将布局与文档链接一起提供给布局. 该布局在[样式](#css-classes)正确[的](#css-classes)容器中的导航之间组织数据. ### Data file[](#data-file "Permalink") 数据文件描述了适用项目的导航结构. 所有数据文件都存储在[https://gitlab.com/gitlab-org/gitlab-docs/blob/master/content/_data/中，](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/content/_data/)并且包含三个组件： * Sections * Categories * Docs #### Sections[](#sections "Permalink") 每个部分代表较高级别的导航项. 它由标题和 URL 组成： ``` sections: - section_title: Text section_url: 'link' ``` 该部分可以单独使用，也可以包含其中的类别. #### Categories[](#categories "Permalink") 部分中的每个类别都构成了导航的第二级. 它包括类别标题和链接. 它可以单独放置在导航栏中，也可以包含第三级子项目. 具有一个独立类别的部分的示例： ``` - section_title: Section title section_url: 'section-link' section_categories: - category_title: Category title category_url: 'category-link' ``` 具有两个独立类别的部分的示例： ``` - 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' ``` 为了清楚起见，请**始终**在类别之间添加空白行. 如果 CE 中没有类别 URL（这是仅 EE 的文档），请在类别链接下方添加属性`ee_only: true` . 例： ``` - category_title: Category title category_url: 'category-link' ee_only: true ``` 如果类别链接到外部 URL，例如[GitLab Design System](https://design.gitlab.com) ，则在类别标题下添加属性`external_url: true` . 例： ``` - category_title: GitLab Design System category_url: 'https://design.gitlab.com' external_url: true ``` #### Docs[](#docs "Permalink") 每个文档代表导航链接的第三级. 必须始终将它们添加到类别中. 带有一个文档链接的示例： ``` - 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. 多个文档的示例： ``` - 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' ``` 每当仅在 EE 中存在文档时，请在 doc 链接下添加属性`ee-only: true` . 例： ``` - doc_title: Document 2 title doc_url: 'doc-2-link' ee_only: true ``` 如果您需要在外部 URL 中添加文档，请在 doc 链接下面添加属性`external_url` ： ``` - doc_title: Document 2 title doc_url: 'doc-2-link' external_url: true ``` 所有导航链接都是可单击的. 如果上级链接没有自己的链接，则它必须链接到它的第一个子项目链接，模仿 GitLab 的导航. 必须避免这种情况，以便我们不会同时有重复的链接或两个`.active`链接. 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[](#syntax "Permalink") 对于所有组件（节，类别和文档），请**遵循缩进**和以下语法规则. ##### Titles[](#titles "Permalink") * 使用句子大小写，将特征名称大写. * 除非其中有特殊字符，否则无需包装标题. 例如，在`GitLab CI/CD` ，存在`/` ，因此必须将其用引号引起来. 按照惯例，将标题用双引号引起来： `category_title: "GitLab CI/CD"` . ##### URLs[](#urls "Permalink") * 按照惯例，始终将 URL 括在单引号`'url'` . * 始终在 CE 和 EE 的所在地使用相对路径. 例子： * 对于`https://docs.gitlab.com/ee/README.html` ，相对 URL 为`README.html` . * 对于`https://docs.gitlab.com/ee/user/project/cycle_analytics.html` ，相对 URL 是`user/project/cycle_analytics.html` . * 对于`README.html`文件，添加完整路径`path/to/README.html` . * 对于`index.html`文件，请使用干净的（规范的）URL： `path/to/` . * 对于仅限 EE 的文档，请使用相同的相对路径，但在`doc_url`或`category_url`下添加属性`ee_only: true` ，如上所述. 这将在导航上显示一个"信息"图标，以使用户知道该功能仅适用于 EE. **警告：**数据文件上存在的所有链接都必须以`.html`而不是`.md`结尾. 不要以斜杠`/`开头任何相对链接. 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: Service Desk doc_url: 'user/project/service_desk.html' ee_only: false # 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)[](#layout-file-logic "Permalink") [布局](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/global_nav.html)由[数据文件提供](#data-file) ，构建全局导航，并由[默认](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/default.html)布局呈现. 为导航创建的逻辑主要考虑三个方面： * [路径](#path) ： `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/debug/` * `https://docs.gitlab.com/*` * [仅限 EE](#ee-only-docs) ：仅在`/ee/`可用的文档，在`/ce/`不可用，例如： * `https://docs.gitlab.com/ee/user/group/epics/` * `https://docs.gitlab.com/ee/user/project/security_dashboard.html` * [默认 URL](#default-url) ：CE 和 EE 文档之间的[默认 URL](#default-url) ，默认值为`ee` ，因此，除非在`/ce/`内部链接到`ce`否则所有文档都应链接到`/ee/` . #### Path[](#path "Permalink") 要在数据文件中使用相对路径，我们从根的第一个子目录定义了变量`dir` ，该目录定义了构建指向其他页面的所有导航链接的路径： ``` <% dir = @item.identifier.to_s[%r{(?<=/)[^/]+}] %> ``` 例如，对于`https://docs.gitlab.com/ce/user/index.html` ， `dir` = = `ce` ，和`https://docs.gitlab.com/omnibus/README.html` ， `dir` == `omnibus` . #### Default URL[](#default-url "Permalink") GitLab 文档的默认规范 URL 为`https://docs.gitlab.com/ee/` ，因此，文档站点中的所有链接都应链接至`/ee/`除非在`/ce/`文档本身之间进行链接. 因此，如果用户正在查看`/ee/` ， `/omnibus/` ， `/runner/`或任何其他最高级别的目录，则导航栏应指向`/ee/` docs. 另一方面，如果用户正在查看`/ce/` docs，则 CE 导航中的所有链接都应在内部链接到`/ce/`文件. ``` <% if dir != 'ce' %> <a href="/ee/<%= sec[:section_url] %>">...</a> <% else %> <a href="/<%= dir %>/<%= sec[:section_url] %>">...</a> <% end %> ... <% end %> ``` 这也允许导航显示在其他最高级别的目录（ `/omnibus/` ， `/runner/`等）上，并将它们链接回`/ee/` . 相同的逻辑应用于所有节（ `sec[:section_url]` ），类别（ `cat[:category_url]` ）和 docs（ `doc[:doc_url]` ）URL. #### `ee-only` docs[](#ee-only-docs "Permalink") 仅在 gitLab EE 中存在的功能文档在数据文件中被`ee-only`标记，并且在导航链接上显示一个图标，指示`ee-only`功能在 CE 中不可用. `ee-only`属性可用于`categories` （ `<% if cat[:ee_only] %>` ）和`docs` （ `<% if doc[:ee_only] %>` ），但不能用于`sections` . ### CSS classes[](#css-classes "Permalink") 导航在常规`stylesheet.scss` . 要更改其样式，请将它们分组以在团队中更好地发展. URL 组件的独特样式由 CSS 类`.level-0` ， `.level-1`和`.level-2` . 要调整链接的字体大小，填充，颜色等，请使用这些类. 这样，我们保证每个链接的规则都不会与样式表中的其他规则冲突.