debian-mirror-gitlab/doc/development/documentation/site_architecture/index.md

239 lines
9.4 KiB
Markdown
Raw Normal View History

2019-02-15 15:39:39 +05:30
---
2021-01-29 00:20:46 +05:30
stage: none
group: unassigned
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2019-02-15 15:39:39 +05:30
---
# Documentation site architecture
2019-12-26 22:10:19 +05:30
The [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) project hosts
the repository which is used to generate the GitLab documentation website and
2021-09-30 23:02:18 +05:30
is deployed to <https://docs.gitlab.com>. It uses the [Nanoc](https://nanoc.app/)
2019-12-26 22:10:19 +05:30
static site generator.
2019-02-15 15:39:39 +05:30
2019-12-26 22:10:19 +05:30
## Architecture
2019-02-15 15:39:39 +05:30
2021-02-22 17:27:13 +05:30
While the source of the documentation content is stored in the repositories for
each GitLab product, the source that is used to build the documentation
2019-12-26 22:10:19 +05:30
site _from that content_ is located at <https://gitlab.com/gitlab-org/gitlab-docs>.
2019-09-30 21:07:59 +05:30
The following diagram illustrates the relationship between the repositories
from where content is sourced, the `gitlab-docs` project, and the published output.
```mermaid
graph LR
2020-04-22 19:07:51 +05:30
A[gitlab/doc]
B[gitlab-runner/docs]
C[omnibus-gitlab/doc]
D[charts/doc]
E[gitlab-docs]
A --> E
B --> E
C --> E
D --> E
E -- Build pipeline --> F
F[docs.gitlab.com]
H[/ee/]
I[/runner/]
J[/omnibus/]
K[/charts/]
F --> H
F --> I
F --> J
F --> K
2019-09-30 21:07:59 +05:30
```
2021-02-22 17:27:13 +05:30
GitLab docs content isn't kept in the `gitlab-docs` repository.
2019-12-26 22:10:19 +05:30
All documentation files are hosted in the respective repository of each
product, and all together are pulled to generate the docs website:
2021-09-04 01:27:46 +05:30
- [GitLab](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc)
2019-12-26 22:10:19 +05:30
- [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/doc)
2021-09-04 01:27:46 +05:30
- [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/main/docs)
2019-12-26 22:10:19 +05:30
- [GitLab Chart](https://gitlab.com/charts/gitlab/tree/master/doc)
2019-02-15 15:39:39 +05:30
## Assets
To provide an optimized site structure, design, and a search-engine friendly
website, along with a discoverable documentation, we use a few assets for
the GitLab Documentation website.
### Libraries
2019-09-30 21:07:59 +05:30
- [Bootstrap 4.3.1 components](https://getbootstrap.com/docs/4.3/components/)
- [Bootstrap 4.3.1 JS](https://getbootstrap.com/docs/4.3/getting-started/javascript/)
- [jQuery](https://jquery.com/) 3.3.1
2019-02-15 15:39:39 +05:30
- [Clipboard JS](https://clipboardjs.com/)
- [Font Awesome 4.7.0](https://fontawesome.com/v4.7.0/icons/)
### SEO
- [Schema.org](https://schema.org/)
- [Google Analytics](https://marketingplatform.google.com/about/analytics/)
- [Google Tag Manager](https://developers.google.com/tag-manager/)
2019-12-04 20:38:33 +05:30
## Global navigation
2019-02-15 15:39:39 +05:30
2019-12-21 20:55:43 +05:30
Read through [the global navigation documentation](global_nav.md) to understand:
2019-12-04 20:38:33 +05:30
- How the global navigation is built.
- How to add new navigation items.
2019-02-15 15:39:39 +05:30
2019-12-26 22:10:19 +05:30
<!--
## Helpers
2019-02-15 15:39:39 +05:30
2019-12-26 22:10:19 +05:30
TBA
-->
2019-02-15 15:39:39 +05:30
2020-04-08 14:13:33 +05:30
## Pipelines
The pipeline in the `gitlab-docs` project:
- Tests changes to the docs site code.
- Builds the Docker images used in various pipeline jobs.
- Builds and deploys the docs site itself.
- Generates the review apps when the `review-docs-deploy` job is triggered.
### Rebuild the docs site Docker images
Once a week on Mondays, a scheduled pipeline runs and rebuilds the Docker images
used in various pipeline jobs, like `docs-lint`. The Docker image configuration files are
2020-06-23 00:09:42 +05:30
located in the [Dockerfiles directory](https://gitlab.com/gitlab-org/gitlab-docs/-/tree/master/dockerfiles).
2020-04-08 14:13:33 +05:30
If you need to rebuild the Docker images immediately (must have maintainer level permissions):
2021-02-22 17:27:13 +05:30
WARNING:
2021-09-04 01:27:46 +05:30
If you change the Dockerfile configuration and rebuild the images, you can break the main
2020-06-23 00:09:42 +05:30
pipeline in the main `gitlab` repository as well as in `gitlab-docs`. Create an image with
2020-04-08 14:13:33 +05:30
a different name first and test it to ensure you do not break the pipelines.
2021-04-17 20:07:23 +05:30
1. In [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs), go to **{rocket}** **CI/CD > Pipelines**.
2021-04-29 21:17:54 +05:30
1. Click the **Run pipeline** button.
2020-04-08 14:13:33 +05:30
1. See that a new pipeline is running. The jobs that build the images are in the first
stage, `build-images`. You can click the pipeline number to see the larger pipeline
graph, or click the first (`build-images`) stage in the mini pipeline graph to
expose the jobs that build the images.
1. Click the **play** (**{play}**) button next to the images you want to rebuild.
- Normally, you do not need to rebuild the `image:gitlab-docs-base` image, as it
rarely changes. If it does need to be rebuilt, be sure to only run `image:docs-lint`
after it is finished rebuilding.
### Deploy the docs site
Every four hours a scheduled pipeline builds and deploys the docs site. The pipeline
2021-09-04 01:27:46 +05:30
fetches the current docs from the main project's main branch, builds it with Nanoc
2020-04-08 14:13:33 +05:30
and deploys it to <https://docs.gitlab.com>.
If you need to build and deploy the site immediately (must have maintainer level permissions):
2021-04-17 20:07:23 +05:30
1. In [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs), go to **{rocket}** **CI/CD > Schedules**.
2020-04-08 14:13:33 +05:30
1. For the `Build docs.gitlab.com every 4 hours` scheduled pipeline, click the **play** (**{play}**) button.
2020-10-24 23:57:45 +05:30
Read more about the [deployment process](deployment_process.md).
2019-12-26 22:10:19 +05:30
## Using YAML data files
2019-02-15 15:39:39 +05:30
2019-12-26 22:10:19 +05:30
The easiest way to achieve something similar to
[Jekyll's data files](https://jekyllrb.com/docs/datafiles/) in Nanoc is by
2021-09-30 23:02:18 +05:30
using the [`@items`](https://nanoc.app/doc/reference/variables/#items-and-layouts)
2019-12-26 22:10:19 +05:30
variable.
2019-02-15 15:39:39 +05:30
2019-12-26 22:10:19 +05:30
The data file must be placed inside the `content/` directory and then it can
be referenced in an ERB template.
2019-02-15 15:39:39 +05:30
2019-12-26 22:10:19 +05:30
Suppose we have the `content/_data/versions.yaml` file with the content:
2019-02-15 15:39:39 +05:30
2019-12-26 22:10:19 +05:30
```yaml
versions:
2020-07-28 23:09:34 +05:30
- 10.6
- 10.5
- 10.4
2019-12-26 22:10:19 +05:30
```
2019-02-15 15:39:39 +05:30
2019-12-26 22:10:19 +05:30
We can then loop over the `versions` array with something like:
2019-02-15 15:39:39 +05:30
2019-12-26 22:10:19 +05:30
```erb
<% @items['/_data/versions.yaml'][:versions].each do | version | %>
2019-02-15 15:39:39 +05:30
2019-12-26 22:10:19 +05:30
<h3><%= version %></h3>
2019-02-15 15:39:39 +05:30
2019-12-26 22:10:19 +05:30
<% end &>
```
Note that the data file must have the `yaml` extension (not `yml`) and that
we reference the array with a symbol (`:versions`).
2020-01-01 13:55:28 +05:30
## Bumping versions of CSS and JavaScript
2019-12-26 22:10:19 +05:30
2020-01-01 13:55:28 +05:30
Whenever the custom CSS and JavaScript files under `content/assets/` change,
2020-06-23 00:09:42 +05:30
make sure to bump their version in the front matter. This method guarantees that
2021-02-22 17:27:13 +05:30
your changes take effect by clearing the cache of previous files.
2019-12-26 22:10:19 +05:30
Always use Nanoc's way of including those files, do not hardcode them in the
layouts. For example use:
```erb
<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:
```erb
<%= @items['/path/to/assets/file.*'].path %>
```
2021-02-22 17:27:13 +05:30
Nanoc then builds and renders those links correctly according with what's
2021-09-04 01:27:46 +05:30
defined in [`Rules`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/Rules).
2019-12-26 22:10:19 +05:30
## Linking to source files
2021-09-04 01:27:46 +05:30
A helper called [`edit_on_gitlab`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/lib/helpers/edit_on_gitlab.rb) can be used
2019-12-26 22:10:19 +05:30
to link to a page's source file. We can link to both the simple editor and the
web IDE. Here's how you can use it in a Nanoc layout:
- Default editor: `<a href="<%= edit_on_gitlab(@item, editor: :simple) %>">Simple editor</a>`
- Web IDE: `<a href="<%= edit_on_gitlab(@item, editor: :webide) %>">Web IDE</a>`
If you don't specify `editor:`, the simple one is used by default.
## Algolia search engine
2020-06-23 00:09:42 +05:30
The docs site uses [Algolia DocSearch](https://community.algolia.com/docsearch/)
2019-12-26 22:10:19 +05:30
for its search function. This is how it works:
2020-06-23 00:09:42 +05:30
1. GitLab is a member of the [DocSearch program](https://community.algolia.com/docsearch/#join-docsearch-program),
2019-12-26 22:10:19 +05:30
which is the free tier of [Algolia](https://www.algolia.com/).
2020-04-22 19:07:51 +05:30
1. Algolia hosts a [DocSearch configuration](https://github.com/algolia/docsearch-configs/blob/master/configs/gitlab.json)
2019-12-26 22:10:19 +05:30
for the GitLab docs site, and we've worked together to refine it.
2020-06-23 00:09:42 +05:30
1. That [configuration](https://community.algolia.com/docsearch/config-file.html) is
2019-12-26 22:10:19 +05:30
parsed by their [crawler](https://community.algolia.com/docsearch/crawler-overview.html)
every 24h and [stores](https://community.algolia.com/docsearch/inside-the-engine.html)
2020-06-23 00:09:42 +05:30
the [DocSearch index](https://community.algolia.com/docsearch/how-do-we-build-an-index.html)
2019-12-26 22:10:19 +05:30
on [Algolia's servers](https://community.algolia.com/docsearch/faq.html#where-is-my-data-hosted%3F).
2021-09-04 01:27:46 +05:30
1. On the docs side, we use a [DocSearch layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/layouts/docsearch.html) which
2019-12-26 22:10:19 +05:30
is present on pretty much every page except <https://docs.gitlab.com/search/>,
2021-09-04 01:27:46 +05:30
which uses its [own layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/layouts/instantsearch.html). In those layouts,
2020-06-23 00:09:42 +05:30
there's a JavaScript snippet which initiates DocSearch by using an API key
2019-12-26 22:10:19 +05:30
and an index name (`gitlab`) that are needed for Algolia to show the results.
2021-01-29 00:20:46 +05:30
### Algolia notes for GitLab team members
2021-04-29 21:17:54 +05:30
If you're a GitLab team member, find credentials for the Algolia dashboard
2020-11-24 15:15:51 +05:30
in the shared [GitLab 1Password account](https://about.gitlab.com/handbook/security/#1password-for-teams).
To receive weekly reports of the search usage, search the Google doc with
2020-04-08 14:13:33 +05:30
title `Email, Slack, and GitLab Groups and Aliases`, search for `docsearch`,
2021-02-22 17:27:13 +05:30
and add a comment with your email to be added to the alias that gets the weekly
2019-12-26 22:10:19 +05:30
reports.
## Monthly release process (versions)
The docs website supports versions and each month we add the latest one to the list.
2021-10-27 15:23:28 +05:30
For more information, read about the [monthly release process](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#monthly-documentation-releases).
2019-12-26 22:10:19 +05:30
## Review Apps for documentation merge requests
If you are contributing to GitLab docs read how to [create a Review App with each
merge request](../index.md#previewing-the-changes-live).