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) .