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` . 要調整鏈接的字體大小，填充，顏色等，請使用這些類. 這樣，我們保證每個鏈接的規則都不會與樣式表中的其他規則沖突.