Documentation site architecture · Gitlab 中文文檔

# Documentation site architecture > 原文：[https://docs.gitlab.com/ee/development/documentation/site_architecture/](https://docs.gitlab.com/ee/development/documentation/site_architecture/) * [Architecture](#architecture) * [Assets](#assets) * [Libraries](#libraries) * [SEO](#seo) * [Global navigation](#global-navigation) * [Pipelines](#pipelines) * [Rebuild the docs site Docker images](#rebuild-the-docs-site-docker-images) * [Deploy the docs site](#deploy-the-docs-site) * [Using YAML data files](#using-yaml-data-files) * [Bumping versions of CSS and JavaScript](#bumping-versions-of-css-and-javascript) * [Linking to source files](#linking-to-source-files) * [Algolia search engine](#algolia-search-engine) * [Monthly release process (versions)](#monthly-release-process-versions) * [Review Apps for documentation merge requests](#review-apps-for-documentation-merge-requests) # Documentation site architecture[](#documentation-site-architecture "Permalink") [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs)項目托管用于生成 GitLab 文檔網站的資源庫，該資源庫已部署到[https://docs.gitlab.com](https://s0docs0gitlab0com.icopy.site) . 它使用[Nanoc](https://nanoc.ws/)靜態站點生成器. ## Architecture[](#architecture "Permalink") 文檔內容的源存儲在 GitLab 的各個產品存儲庫中，而用于*從該內容*構建文檔站點的源位于[https://gitlab.com/gitlab-org/gitlab-docs](https://gitlab.com/gitlab-org/gitlab-docs) . 下圖說明了從中獲取內容的存儲庫， `gitlab-docs`項目和已發布的輸出之間的關系. 圖 LR A [gitlab / doc] B [gitlab-runner / docs] C [omnibus-gitlab / doc] D [charts / doc] E [gitlab-docs] A-> EB-> EC-> ED- -> EE-建立管道-> FF [docs.gitlab.com] G [/ ce /] H [/ ee /] I [/ runner /] J [/ omnibus /] K [/ charts /] F- -> HF-> IF-> JF-> KH-symlink-> G 您不會在`gitlab-docs`存儲庫中找到任何 GitLab 文檔內容. 所有文檔文件都托管在每種產品各自的存儲庫中，并且全部拉在一起以生成 docs 網站： * [GitLab](https://gitlab.com/gitlab-org/gitlab/tree/master/doc) * [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/doc) * [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/tree/master/docs) * [GitLab Chart](https://gitlab.com/charts/gitlab/tree/master/doc) **注意：**在 2019 年 9 月，我們[轉向了一個單一的代碼庫](https://gitlab.com/gitlab-org/gitlab/-/issues/2952) ，因此 CE 和 EE 的文檔現在完全相同. 出于歷史原因，并且為了不破壞整個 Internet 上的任何現有鏈接，我們仍然維護 CE 文檔（ `https://docs.gitlab.com/ce/` ），盡管它已從網站中隱藏，現在已成為符號鏈接到 EE 文檔. 如果[Pages 支持重定向](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/24) ，我們將能夠徹底刪除它. ## Assets[](#assets "Permalink") 為了提供優化的網站結構，設計和搜索引擎友好的網站以及可發現的文檔，我們在 GitLab 文檔網站中使用了一些資產. ### Libraries[](#libraries "Permalink") * [Bootstrap 4.3.1 components](https://s0getbootstrap0com.icopy.site/docs/4.3/components/) * [Bootstrap 4.3.1 JS](https://s0getbootstrap0com.icopy.site/docs/4.3/getting-started/javascript/) * [jQuery](https://jquery.com/) 3.3.1 * [Clipboard JS](https://clipboardjs.com/) * [Font Awesome 4.7.0](https://fontawesome.com/v4.7.0/icons/) ### SEO[](#seo "Permalink") * [Schema.org](https://schema.org/) * [Google Analytics](https://marketingplatform.google.com/about/analytics/) * [Google Tag Manager](https://developers.google.com/tag-manager/) ## Global navigation[](#global-navigation "Permalink") 通讀[全局導航文檔](global_nav.html)以了解： * 全局導航的構建方式. * 如何添加新的導航項. ## Pipelines[](#pipelines "Permalink") `gitlab-docs`項目中的管道： * 測試對 docs 站點代碼的更改. * 構建用于各種管道作業的 Docker 映像. * 構建和部署文檔站點本身. * 觸發`review-docs-deploy`作業時生成審閱應用程序. ### Rebuild the docs site Docker images[](#rebuild-the-docs-site-docker-images "Permalink") 星期一每周一次，運行預定的管道并重建用于各種管道作業（例如`docs-lint`的 Docker 映像. Docker 映像配置文件位于[Dockerfiles 目錄中](https://gitlab.com/gitlab-org/gitlab-docs/-/tree/master/dockerfiles) . 如果您需要立即重建 Docker 映像（必須具有維護者級別權限）： **注意：**如果更改 dockerfile 配置并重建映像，則可以在`gitlab`主存儲庫以及`gitlab-docs`中`gitlab-docs` . 首先創建一個具有不同名稱的映像，然后對其進行測試，以確保您不會中斷管道. 1. 在[`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) ，轉到 **CI / CD>管道** . 2. 單擊**運行管道**按鈕. 3. 看到新的管道正在運行. 構建圖像的工作在第一階段，即`build-images` . 您可以單擊管道編號以查看較大的管道??圖，或單擊迷你管道圖中的第一（ `build-images` ）階段以公開構建圖像的作業. 4. 點擊**播放** （）按鈕旁邊的要重建的圖像. * 通常，您不需要重建`image:gitlab-docs-base`映像，因為它很少更改. 如果確實需要重建，請確保僅在重建完成后才運行`image:docs-lint` . ### Deploy the docs site[](#deploy-the-docs-site "Permalink") 計劃的管道每隔四個小時就會構建和部署一個文檔站點. 管道從主項目的 master 分支中獲取當前文檔，并使用 Nanoc 進行構建并將其部署到[https://docs.gitlab.com](https://s0docs0gitlab0com.icopy.site) . 如果您需要立即構建和部署站點（必須具有維護者級別的權限）： 1. 在[`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) ，轉到 **CI / CD>時間表** . 2. For the `Build docs.gitlab.com every 4 hours` scheduled pipeline, click the **play** () button. ## Using YAML data files[](#using-yaml-data-files "Permalink") 在 Nanoc 中實現類似于[Jekyll 數據文件](https://jekyllrb.com/docs/datafiles/)的最簡單方法是使用[`@items`](https://nanoc.ws/doc/reference/variables/#items-and-layouts)變量. 數據文件必須放在`content/`目錄中，然后可以在 ERB 模板中引用它. 假設我們有具有`content/_data/versions.yaml`文件： ``` versions: - 10.6 - 10.5 - 10.4 ``` 然后，我們可以像下面這樣遍歷`versions`數組： ``` <% @items['/_data/versions.yaml'][:versions].each do | version | %> <h3><%= version %></h3> <% end &> ``` 請注意，數據文件必須具有`yaml`擴展名（而不是`yml` ），并且我們使用符號（ `:versions` ）引用數組. ## Bumping versions of CSS and JavaScript[](#bumping-versions-of-css-and-javascript "Permalink") 每當`content/assets/`下的自定義 CSS 和 JavaScript 文件更改時，請確保在最前面更改其版本. 此方法通過清除先前文件的緩存來確保您的更改將生效. 始終使用 Nanoc 包含這些文件的方式，不要在布局中對它們進行硬編碼. 例如使用： ``` <script async type="application/javascript" src="<%= @items['/assets/javascripts/badges.*'].path %>"></script> <link rel="stylesheet" href="<%= @items['/assets/stylesheets/toc.*'].path %>"> ``` The links pointing to the files should be similar to: ``` <%= @items['/path/to/assets/file.*'].path %> ``` 然后 Nanoc 將根據[`Rules`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/Rules)定義的內容正確構建和呈現這些鏈接. ## Linking to source files[](#linking-to-source-files "Permalink") 可以使用名為[`edit_on_gitlab`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/lib/helpers/edit_on_gitlab.rb)的助手來鏈接到頁面的源文件. 我們可以鏈接到簡單編輯器和 Web IDE. 這是在 Nanoc 布局中使用它的方法： * 默認編輯器： `<a href="<%= edit_on_gitlab(@item, editor: :simple) %>">Simple editor</a>` * Web IDE： `<a href="<%= edit_on_gitlab(@item, editor: :webide) %>">Web IDE</a>` 如果您未指定`editor:` ：，則默認使用簡單的一個. ## Algolia search engine[](#algolia-search-engine "Permalink") docs 網站使用[Algolia DocSearch](https://community.algolia.com/docsearch/)進行搜索. 它是這樣工作的： 1. GitLab 是[DocSearch 程序](https://community.algolia.com/docsearch/#join-docsearch-program)的成員，該[程序](https://community.algolia.com/docsearch/#join-docsearch-program)是[Algolia](https://www.algolia.com/)的免費[版](https://www.algolia.com/) . 2. Algolia 為 GitLab docs 網站托管[DocSearch 配置](https://github.com/algolia/docsearch-configs/blob/master/configs/gitlab.json) ，我們已經共同努力對其進行完善. 3. 該[配置](https://community.algolia.com/docsearch/config-file.html)由[爬蟲](https://community.algolia.com/docsearch/crawler-overview.html)每 24 小時進行一次解析，并將[DocSearch 索引](https://community.algolia.com/docsearch/how-do-we-build-an-index.html) [存儲](https://community.algolia.com/docsearch/inside-the-engine.html)在[Algolia 的服務器上](https://community.algolia.com/docsearch/faq.html#where-is-my-data-hosted?) . 4. 在文檔方面，我們使用了[DocSearch 布局](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/docsearch.html) ，除[https://docs.gitlab.com/search/](https://docs.gitlab.com/search/)使用其[自己的布局](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/instantsearch.html)之外，幾乎所有頁面上都存在該[布局](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/instantsearch.html) . 在這些布局中，有一個 JavaScript 代碼段，該代碼段使用 Algolia 顯示結果所需的 API 密鑰和索引名稱（ `gitlab` ）來啟動 DocSearch. **對于 GitLab 員工：**用于訪問 Algolia 儀表板的憑據存儲在 1Password 中. 如果要接收有關使用情況的每周報告，請搜索標題為`Email, Slack, and GitLab Groups and Aliases`的 Google 文檔，搜索`docsearch` ，并在電子郵件中添加評論，以添加到獲取每周報告的別名中. ## Monthly release process (versions)[](#monthly-release-process-versions "Permalink") docs 網站支持版本，每個月我們都會將最新版本添加到列表中. 有關更多信息，請閱讀有關[每月發布過程的信息](release_process.html) . ## Review Apps for documentation merge requests[](#review-apps-for-documentation-merge-requests "Permalink") 如果您為 GitLab 文檔做出了貢獻，請閱讀如何[使用每個合并請求創建一個 Review App](../index.html#previewing-the-changes-live) .