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-docsgitlab-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 | %>
  2. <h3><%= version %></h3>
  3. <% 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>
  2. <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 .