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