Documentation site architecture

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

Documentation site architecture

gitlab-docs项目托管用于生成 GitLab 文档网站的资源库，该资源库已部署到https://docs.gitlab.com . 它使用Nanoc静态站点生成器.

Architecture

文档内容的源存储在 GitLab 的各个产品存储库中，而用于从该内容构建文档站点的源位于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 网站：

注意：在 2019 年 9 月，我们转向了一个单一的代码库 ，因此 CE 和 EE 的文档现在完全相同. 出于历史原因，并且为了不破坏整个 Internet 上的任何现有链接，我们仍然维护 CE 文档（ https://docs.gitlab.com/ce/ ），尽管它已从网站中隐藏，现在已成为符号链接到 EE 文档. 如果Pages 支持重定向 ，我们将能够彻底删除它.

Assets

为了提供优化的网站结构，设计和搜索引擎友好的网站以及可发现的文档，我们在 GitLab 文档网站中使用了一些资产.

Libraries

SEO

Global navigation

通读全局导航文档以了解：

  • 全局导航的构建方式.
  • 如何添加新的导航项.

Pipelines

gitlab-docs项目中的管道：

  • 测试对 docs 站点代码的更改.
  • 构建用于各种管道作业的 Docker 映像.
  • 构建和部署文档站点本身.
  • 触发review-docs-deploy作业时生成审阅应用程序.

Rebuild the docs site Docker images

星期一每周一次，运行预定的管道并重建用于各种管道作业（例如docs-lint的 Docker 映像. Docker 映像配置文件位于Dockerfiles 目录中 .

如果您需要立即重建 Docker 映像（必须具有维护者级别权限）：

注意：如果更改 dockerfile 配置并重建映像，则可以在gitlab主存储库以及gitlab-docs中gitlab-docs . 首先创建一个具有不同名称的映像，然后对其进行测试，以确保您不会中断管道.

  1. 在gitlab-docs ，转到 CI / CD>管道 .
  2. 单击运行管道按钮.
  3. 看到新的管道正在运行. 构建图像的工作在第一阶段，即build-images . 您可以单击管道编号以查看较大的管道​​图，或单击迷你管道图中的第一（ build-images ）阶段以公开构建图像的作业.
  4. 点击播放 （ ）按钮旁边的要重建的图像.
    • 通常，您不需要重建image:gitlab-docs-base映像，因为它很少更改. 如果确实需要重建，请确保仅在重建完成后才运行image:docs-lint .

Deploy the docs site

计划的管道每隔四个小时就会构建和部署一个文档站点. 管道从主项目的 master 分支中获取当前文档，并使用 Nanoc 进行构建并将其部署到https://docs.gitlab.com .

如果您需要立即构建和部署站点（必须具有维护者级别的权限）：

  1. 在gitlab-docs ，转到 CI / CD>时间表 .
  2. For the Build docs.gitlab.com every 4 hours scheduled pipeline, click the play () button.

Using YAML data files

在 Nanoc 中实现类似于Jekyll 数据文件的最简单方法是使用@items变量.

数据文件必须放在content/目录中，然后可以在 ERB 模板中引用它.

假设我们有具有content/_data/versions.yaml文件：

  1. versions:
  2.   - 10.6
  3.   - 10.5
  4.   - 10.4

然后，我们可以像下面这样遍历versions数组：

  1. <% @items['/_data/versions.yaml'][:versions].each do | version | %>
  3. <h3><%= version %></h3>
  5. <% end &>

请注意，数据文件必须具有yaml扩展名（而不是yml ），并且我们使用符号（ :versions ）引用数组.

Bumping versions of CSS and JavaScript

每当content/assets/下的自定义 CSS 和 JavaScript 文件更改时，请确保在最前面更改其版本. 此方法通过清除先前文件的缓存来确保您的更改将生效.

始终使用 Nanoc 包含这些文件的方式，不要在布局中对它们进行硬编码. 例如使用：

  1. <script async type="application/javascript" src="<%= @items['/assets/javascripts/badges.*'].path %>"></script>
  3. <link rel="stylesheet" href="<%= @items['/assets/stylesheets/toc.*'].path %>">

The links pointing to the files should be similar to:

  1. <%= @items['/path/to/assets/file.*'].path %>

然后 Nanoc 将根据Rules定义的内容正确构建和呈现这些链接.

Linking to source files

可以使用名为edit_on_gitlab的助手来链接到页面的源文件. 我们可以链接到简单编辑器和 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

docs 网站使用Algolia DocSearch进行搜索. 它是这样工作的：

  1. GitLab 是DocSearch 程序的成员，该程序是Algolia的免费版 .
  2. Algolia 为 GitLab docs 网站托管DocSearch 配置 ，我们已经共同努力对其进行完善.
  3. 该配置由爬虫每 24 小时进行一次解析，并将DocSearch 索引 存储在Algolia 的服务器上 .
  4. 在文档方面，我们使用了DocSearch 布局 ，除https://docs.gitlab.com/search/使用其自己的布局之外，几乎所有页面上都存在该布局 . 在这些布局中，有一个 JavaScript 代码段，该代码段使用 Algolia 显示结果所需的 API 密钥和索引名称（ gitlab ）来启动 DocSearch.

对于 GitLab 员工：用于访问 Algolia 仪表板的凭据存储在 1Password 中. 如果要接收有关使用情况的每周报告，请搜索标题为Email, Slack, and GitLab Groups and Aliases的 Google 文档，搜索docsearch ，并在电子邮件中添加评论，以添加到获取每周报告的别名中.

Monthly release process (versions)

docs 网站支持版本，每个月我们都会将最新版本添加到列表中. 有关更多信息，请阅读有关每月发布过程的信息 .

Review Apps for documentation merge requests

如果您为 GitLab 文档做出了贡献，请阅读如何使用每个合并请求创建一个 Review App .