Documentation site architecture

Documentation site architecture

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

文档内容的源存储在 GitLab 的各个产品存储库中，而用于从该内容构建文档站点的源位于 .

下图说明了从中获取内容的存储库， 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 文档. 如果 ，我们将能够彻底删除它.

Assets

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

Global navigation

通读以了解：

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

gitlab-docs项目中的管道：

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

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

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

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

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

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

  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 数据文件的最简单方法是使用变量.

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

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

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

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

Bumping versions of CSS and JavaScript

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

The links pointing to the files should be similar to:

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

可以使用名为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 是的成员，该程序是的免费版 .
  2. Algolia 为 GitLab docs 网站托管 ，我们已经共同努力对其进行完善.
  3. 该配置由每 24 小时进行一次解析，并将DocSearch 索引 在Algolia 的服务器上 .

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

Monthly release process (versions)

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

如果您为 GitLab 文档做出了贡献，请阅读如何 .