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

stage	group	info
none	unassigned	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

Documentation site architecture

The gitlab-docs project hosts the repository which is used to generate the GitLab documentation website and is deployed to https://docs.gitlab.com. It uses the Nanoc static site generator.

Architecture

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 site from that content is located at https://gitlab.com/gitlab-org/gitlab-docs.

The following diagram illustrates the relationship between the repositories from where content is sourced, the gitlab-docs project, and the published output.

  graph LR
    A[gitlab-org/gitlab/doc]
    B[gitlab-org/gitlab-runner/docs]
    C[gitlab-org/omnibus-gitlab/doc]
    D[gitlab-org/charts/gitlab/doc]
    E[gitlab-org/cloud-native/gitlab-operator/doc]
    Y[gitlab-org/gitlab-docs]
    A --> Y
    B --> Y
    C --> Y
    D --> Y
    E --> Y
    Y -- Build pipeline --> Z
    Z[docs.gitlab.com]
    M[//ee/]
    N[//runner/]
    O[//omnibus/]
    P[//charts/]
    Q[//operator/]
    Z --> M
    Z --> N
    Z --> O
    Z --> P
    Z --> Q

GitLab docs content isn't kept in the gitlab-docs repository. All documentation files are hosted in the respective repository of each product, and all together are pulled to generate the docs website:

• GitLab
• Omnibus GitLab
• GitLab Runner
• GitLab Chart
• GitLab Operator

Learn more about the docs folder structure.

Documentation in other repositories

If you have code and documentation in a repository other than the primary repositories, you should keep the documentation with the code in that repository.

Then you can either:

• Add the repository to the list of products published at https://docs.gitlab.com.
• Add an entry in the global navigation for https://docs.gitlab.com that links to the documentation in that repository. View an example.

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.

External libraries

GitLab Docs is built with a combination of external:

• JavaScript libraries.
• Ruby libraries.

SEO

• Schema.org
• Google Analytics
• Google Tag Manager

Global navigation

Read through the global navigation documentation to understand:

• How the global navigation is built.
• How to add new navigation items.

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 located in the Dockerfiles directory.

If you need to rebuild the Docker images immediately (must have maintainer level permissions):

WARNING: If you change the Dockerfile configuration and rebuild the images, you can break the main pipeline in the main gitlab repository as well as in gitlab-docs. Create an image with a different name first and test it to ensure you do not break the pipelines.

1. In gitlab-docs, go to {rocket} CI/CD > Pipelines.
2. Select Run pipeline.
3. See that a new pipeline is running. The jobs that build the images are in the first stage, build-images. You can select the pipeline number to see the larger pipeline graph, or select the first (build-images) stage in the mini pipeline graph to expose the jobs that build the images.
4. Select 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 fetches the current docs from the main project's main branch, builds it with Nanoc and deploys it to https://docs.gitlab.com.

To build and deploy the site immediately (must have the Maintainer role):

1. In gitlab-docs, go to {rocket} CI/CD > Schedules.
2. For the Build docs.gitlab.com every 4 hours scheduled pipeline, select the play ({play}) button.

Read more about documentation deployments.

Using YAML data files

The easiest way to achieve something similar to Jekyll's data files in Nanoc is by using the @items variable.

The data file must be placed inside the content/ directory and then it can be referenced in an ERB template.

Suppose we have the content/_data/versions.yaml file with the content:

versions:
  - 10.6
  - 10.5
  - 10.4

We can then loop over the versions array with something like:

<% @items['/_data/versions.yaml'][:versions].each do | version | %>

<h3><%= version %></h3>

<% end &>

Note that the data file must have the yaml extension (not yml) and that we reference the array with a symbol (:versions).

Archived documentation banner

A banner is displayed on archived documentation pages with the text This is archived documentation for GitLab. Go to the latest. when either:

• The version of the documentation displayed is not the first version entry in online in content/_data/versions.yaml.
• The documentation was built from the default branch (main).

For example, if the online entries for content/_data/versions.yaml are:

online:
  - "14.4"
  - "14.3"
  - "14.2"

In this case, the archived documentation banner isn't displayed:

• For 14.4, the docs built from the 14.4 branch. The branch name is the first entry in online.
• For 14.5-pre, the docs built from the default project branch (main).

The archived documentation banner is displayed:

• For 14.3.
• For 14.2.
• For any other version.

Bumping versions of CSS and JavaScript

Whenever the custom CSS and JavaScript files under content/assets/ change, make sure to bump their version in the front matter. This method guarantees that your changes take effect by clearing the cache of previous files.

Always use Nanoc's way of including those files, do not hardcode them in the layouts. For example use:

<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 then builds and renders those links correctly according with what's defined in Rules.

Linking to source files

A helper called edit_on_gitlab can be used 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

The docs site uses Algolia DocSearch for its search function.

Learn more in https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/docsearch.md.

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.

Review Apps for documentation merge requests

If you are contributing to GitLab docs read how to create a Review App with each merge request.