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

250 lines
9.9 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]
G[/ce/]
H[/ee/]
I[/runner/]
J[/omnibus/]
K[/charts/]
F --> H
F --> I
F --> J
F --> K
H -- symlink --> G
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)
2021-02-22 17:27:13 +05:30
NOTE:
2020-06-23 00:09:42 +05:30
In September 2019, we [moved towards a single codebase](https://gitlab.com/gitlab-org/gitlab/-/issues/2952),
2019-12-26 22:10:19 +05:30
as such the docs for CE and EE are now identical. For historical reasons and
in order not to break any existing links throughout the internet, we still
maintain the CE docs (`https://docs.gitlab.com/ce/`), although it is hidden
from the website, and is now a symlink to the EE docs. When
2020-06-23 00:09:42 +05:30
[Pages supports redirects](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/24),
2021-02-22 17:27:13 +05:30
we can remove this completely.
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.
For more information, read about the [monthly release process](release_process.md).
## 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).