Global navigation

原文:https://docs.gitlab.com/ee/development/documentation/site_architecture/global_nav.html

Global navigation

版本历史

  • 在 GitLab 11.6 中引入 .
  • 在 GitLab 12.1 中更新 .
  • 在 GitLab 12.2 中添加了按项目导航.

全局导航(三窗格文档中最左侧的窗格)提供:

  • 产品功能的高层分组视图.
  • 通过浏览菜单结构发现新功能的能力.
  • 一种让读者专注于产品领域的方法.
  • 能够优化登录页面的功能,因此他们不必完成覆盖文档中包含的每个页面的所有工作.

Quick start

要将主题添加到全局导航,请转到包含导航文件的目录,然后编辑产品区域的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

所有新页面都需要一个新的导航项. 如果没有导航,页面将变为”孤立”. 那是:

  • 打开页面时,导航会关闭,并且阅读器会失去位置.
  • 该页面与其他页面不属于同一组.

这意味着创建新页面的决定就是创建新导航项的决定,反之亦然.

Where to add

文档页面可以说属于以下几类:

  • GitLab 用户. 这是用于从 Reporter 到 Owner 拥有任何级别权限的用户日常使用 GitLab 的文档.
  • GitLab 管理员. 这往往是自我管理实例的文档,这些实例需要访问托管 GitLab 的基础架构.
  • 其他文档. 其中包括针对日常使用 GitLab 的客户以及贡献者的文档. 属于其他组的文档属于此处.

考虑到这些组,以下是应在何处添加新项目的一般规则.

  • 用户文档:
    • 组级别功能属于” 组” .
    • 项目级功能属于” 项目” .
    • 可以将组或项目级别(有时称为”实例级别”)之外的功能放在顶层,但是必须注意不要淹没该顶层空间. 如果可能,可以以某种方式对这些功能进行分组.
    • 除上述内容外,其他大多数其他用户文档都属于User .
  • 管理文档属于Administrator .
  • 其他文档属于顶层文档,但必须注意不要创建冗长的顶层导航,这会违背它的目的.

注意:正在逐步推出使所有文档和导航项目都遵循这些原则的方法.

What to add

确定了在哪里添加导航元素之后,下一步就是确定要添加的内容. 需要什么样的机制被证明以下 ,但在原则:

  • 导航项文本(读者看到的文本)应:
    • 越短越好.
    • 要根据具体情况. 很少需要重复父项中的文本.
    • 避免使用行话或艺术术语,除非无处不在. 例如, CI持续集成的可接受替代.
  • 导航链接必须遵循数据文件中记录的规则.
  • EE 徽章受以下条件限制:
    • 链接到仅 EE 的页面时必需.
    • 链接到仅包含 CE 和 EE 内容的页面时,不需要.
    • 当所有子项目均为 EE 专用时为必填项. 在这种情况下,没有子项目带有 EE 标志.
    • 如果子项目是仅包含 CE 和 EE 的项目,则不需要. 在这种情况下,每个项目都将被适当标记.

How it works

全局导航具有 3 个组成部分:

  • Section
    • Category
      • Doc

下表描述了可用的部分:

Section Description
User GitLab 用户界面的文档.
Administrator GitLab 管理区域的文档.
Contributor 开发 GitLab 的文档.

根据用户界面添加了导航上可用的大多数链接. 匹配并不完美,因为某些 UI 导航项不适用于该文档,并且还有其他链接可帮助新用户发现文档. 为了清楚起见,” 管理 “下的文档按字母顺序排列.

要查看计划中的改进,请查看全局导航史诗 .

注意:未经技术作者之一的同意, 请勿 将项目添加到全局导航.

Composition

全局导航由两个文件构建:

数据文件将布局与文档链接一起提供给布局. 该布局在样式正确容器中的导航之间组织数据.

Data file

数据文件描述了适用项目的导航结构. 所有数据文件都存储在https://gitlab.com/gitlab-org/gitlab-docs/blob/master/content/_data/中,并且包含三个组件:

  • Sections
  • Categories
  • Docs

Sections

每个部分代表较高级别的导航项. 它由标题和 URL 组成:

  1. sections:
  2. - section_title: Text
  3. section_url: 'link'

该部分可以单独使用,也可以包含其中的类别.

Categories

部分中的每个类别都构成了导航的第二级. 它包括类别标题和链接. 它可以单独放置在导航栏中,也可以包含第三级子项目.

具有一个独立类别的部分的示例:

  1. - section_title: Section title
  2. section_url: 'section-link'
  3. section_categories:
  4. - category_title: Category title
  5. category_url: 'category-link'

具有两个独立类别的部分的示例:

  1. - section_title: Section title
  2. section_url: 'section-link'
  3. section_categories:
  4. - category_title: Category 1 title
  5. category_url: 'category-1-link'
  6. - category_title: Category 2 title
  7. category_url: 'category-2-link'

为了清楚起见,请始终在类别之间添加空白行.

如果 CE 中没有类别 URL(这是仅 EE 的文档),请在类别链接下方添加属性ee_only: true . 例:

  1. - category_title: Category title
  2. category_url: 'category-link'
  3. ee_only: true

如果类别链接到外部 URL,例如GitLab Design System ,则在类别标题下添加属性external_url: true . 例:

  1. - category_title: GitLab Design System
  2. category_url: 'https://design.gitlab.com'
  3. external_url: true

Docs

每个文档代表导航链接的第三级. 必须始终将它们添加到类别中.

带有一个文档链接的示例:

  1. - category_title: Category title
  2. category_url: 'category-link'
  3. docs:
  4. - doc_title: Document title
  5. doc_url: 'doc-link'

A category supports as many docs as necessary, but, for clarity, try to not overpopulate a category.

多个文档的示例:

  1. - category_title: Category title
  2. category_url: 'category-link'
  3. docs:
  4. - doc_title: Document 1 title
  5. doc_url: 'doc-1-link'
  6. - doc_title: Document 2 title
  7. doc_url: 'doc-2-link'

每当仅在 EE 中存在文档时,请在 doc 链接下添加属性ee-only: true . 例:

  1. - doc_title: Document 2 title
  2. doc_url: 'doc-2-link'
  3. ee_only: true

如果您需要在外部 URL 中添加文档,请在 doc 链接下面添加属性external_url

  1. - doc_title: Document 2 title
  2. doc_url: 'doc-2-link'
  3. external_url: true

所有导航链接都是可单击的. 如果上级链接没有自己的链接,则它必须链接到它的第一个子项目链接,模仿 GitLab 的导航. 必须避免这种情况,以便我们不会同时有重复的链接或两个.active链接.

Example:

  1. - category_title: Operations
  2. category_url: 'user/project/integrations/prometheus_library/'
  3. # until we have a link to operations, the first doc link is
  4. # repeated in the category link
  5. docs:
  6. - doc_title: Metrics
  7. doc_url: 'user/project/integrations/prometheus_library/'

Syntax

对于所有组件(节,类别和文档),请遵循缩进和以下语法规则.

Titles
  • 使用句子大小写,将特征名称大写.
  • 除非其中有特殊字符,否则无需包装标题. 例如,在GitLab CI/CD ,存在/ ,因此必须将其用引号引起来. 按照惯例,将标题用双引号引起来: category_title: "GitLab CI/CD" .
URLs
  • 按照惯例,始终将 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_urlcategory_url下添加属性ee_only: true ,如上所述. 这将在导航上显示一个”信息”图标,以使用户知道该功能仅适用于 EE.

警告:数据文件上存在的所有链接都必须以.html而不是.md结尾. 不要以斜杠/开头任何相对链接.

Examples:

  1. - category_title: Issues
  2. category_url: 'user/project/issues/'
  3. # note that the above URL does not start with a slash and
  4. # does not include index.html at the end
  5. docs:
  6. - doc_title: Service Desk
  7. doc_url: 'user/project/service_desk.html'
  8. ee_only: false
  9. # note that the URL above ends in html and, as the
  10. # document is EE-only, the attribute ee_only is set to true.

Layout file (logic)

布局数据文件提供 ,构建全局导航,并由默认布局呈现.

为导航创建的逻辑主要考虑三个方面:

  • 路径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/可用的文档,在/ce/不可用,例如:
    • https://docs.gitlab.com/ee/user/group/epics/
    • https://docs.gitlab.com/ee/user/project/security_dashboard.html
  • 默认 URL :CE 和 EE 文档之间的默认 URL ,默认值为ee ,因此,除非在/ce/内部链接到ce否则所有文档都应链接到/ee/ .

Path

要在数据文件中使用相对路径,我们从根的第一个子目录定义了变量dir ,该目录定义了构建指向其他页面的所有导航链接的路径:

  1. <% dir = @item.identifier.to_s[%r{(?<=/)[^/]+}] %>

例如,对于https://docs.gitlab.com/ce/user/index.htmldir = = ce ,和https://docs.gitlab.com/omnibus/README.htmldir == omnibus .

Default URL

GitLab 文档的默认规范 URL 为https://docs.gitlab.com/ee/ ,因此,文档站点中的所有链接都应链接至/ee/除非在/ce/文档本身之间进行链接.

因此,如果用户正在查看/ee//omnibus//runner/或任何其他最高级别的目录,则导航栏应指向/ee/ docs.

另一方面,如果用户正在查看/ce/ docs,则 CE 导航中的所有链接都应在内部链接到/ce/文件.

  1. <% if dir != 'ce' %>
  2. <a href="/ee/<%= sec[:section_url] %>">...</a>
  3. <% else %>
  4. <a href="/<%= dir %>/<%= sec[:section_url] %>">...</a>
  5. <% end %>
  6. ...
  7. <% end %>

这也允许导航显示在其他最高级别的目录( /omnibus//runner/等)上,并将它们链接回/ee/ .

相同的逻辑应用于所有节( sec[:section_url] ),类别( cat[:category_url] )和 docs( doc[:doc_url] )URL.

ee-only docs

仅在 gitLab EE 中存在的功能文档在数据文件中被ee-only标记,并且在导航链接上显示一个图标,指示ee-only功能在 CE 中不可用.

ee-only属性可用于categories<% if cat[:ee_only] %> )和docs<% if doc[:ee_only] %> ),但不能用于sections .

CSS classes

导航在常规stylesheet.scss . 要更改其样式,请将它们分组以在团队中更好地发展.

URL 组件的独特样式由 CSS 类.level-0.level-1.level-2 . 要调整链接的字体大小,填充,颜色等,请使用这些类. 这样,我们保证每个链接的规则都不会与样式表中的其他规则冲突.