-
Tests in
lint-doc.sh
- Tests in
docs-lint links
and other jobs - Tests in
ui-docs-links lint
- Install documentation linters
- Run documentation tests locally
- Update linter configuration
- Update linting images
- Configure pre-push hooks
- Disable linting on documentation
- Tool versions used in CI/CD pipelines
- Supported projects
Documentation testing
GitLab documentation is stored in projects with code, and treated like code. To maintain standards and quality of documentation, we use processes similar to those used for code.
Merge requests containing changes to Markdown (.md
) files run these CI/CD jobs:
-
docs-lint markdown
: Runs several types of tests, including:- Documentation content: Vale
- Markdown structure: markdownlint
- Miscellaneous tests:
lint-docs.sh
, includingmermaidlint
for invalid Mermaid charts
-
docs-lint links
: Checks the validity of internal links in the documentation suite. -
ui-docs-links lint
: Checks the validity of links from UI elements, such as files inapp/views
files.
Tests in lint-doc.sh
The tests in
/scripts/lint-doc.sh
look for page content problems that Vale and markdownlint cannot test for.
The docs-lint markdown
job fails if any of these lint-doc.sh
tests fail:
- Curl (
curl
) commands must use long-form options (--header
) instead of short options, like-h
. - Documentation pages must contain front matter indicating ownership of the page.
- Non-standard Unicode space characters (NBSP, NNBSP, ZWSP) must not be used in documentation, because they can cause irregularities in search indexing and grepping.
-
CHANGELOG.md
must not contain duplicate versions. - No files in the
doc/
directory may be executable. - Use
index.md
instead ofREADME.md
. - Directories and filenames must use underscores instead of dashes.
- Directories and filenames must be in lower case.
- Mermaid charts must render without errors.
Mermaid chart linting
- Introduced in GitLab 16.10.
Mermaid builds charts and diagrams from code.
The script (scripts/lint/check_mermaid.mjs
) runs during lint-doc.sh
checks on
all merge requests that contain changes to Markdown files. The script returns an
error if any Markdown files return a Mermaid syntax error.
To help debug your Mermaid charts, use the Mermaid Live Editor.
Tests in docs-lint links
and other jobs
To check for broken links, merge requests containing changes to Markdown (.md
) files run these jobs in their
pipelines:
-
docs-lint links
job in thegitlab
project. For example: https://gitlab.com/gitlab-org/gitlab/-/jobs/7065686331. -
docs-lint links
job in theomnibus-gitlab
project. For example: https://gitlab.com/gitlab-org/omnibus-gitlab/-/jobs/7065337075. -
docs-lint links
job in thegitlab-operator
project. -
docs:lint markdown
job in thegitlab-runner
project, which includes link checking. For example: https://gitlab.com/gitlab-org/gitlab-runner/-/jobs/7056674997. -
check_docs_links
job in thecharts/gitlab
project. For example: https://gitlab.com/gitlab-org/charts/gitlab/-/jobs/7066011619.
These jobs check links, including anchor links, and report any problems. Any link that requires a network connection is skipped.
Tests in ui-docs-links lint
The ui-docs-links lint
job uses haml-lint
to test that all documentation links from
UI elements (app/views
files, for example) link to valid pages and anchors.
Install documentation linters
To help adhere to the documentation style guidelines, and improve the content added to documentation, install documentation linters and integrate them with your code editor. At a minimum, install markdownlint and Vale to match the checks run in build pipelines. Both tools can integrate with your code editor.
Run documentation tests locally
Similar to previewing your changes locally, you can also run documentation tests on your local computer. This has the advantage of:
- Speeding up the feedback loop. You can know of any problems with the changes in your branch without waiting for a CI/CD pipeline to run.
- Lowering costs. Running tests locally is cheaper than running tests on the cloud infrastructure GitLab uses.
It’s important to:
- Keep the tools up-to-date, and match the versions used in our CI/CD pipelines.
- Run linters, documentation link tests, and UI link tests the same way they are run in CI/CD pipelines. It’s important to use same configuration we use in CI/CD pipelines, which can be different than the default configuration of the tool.
Run Vale or markdownlint locally
Installation and configuration instructions for markdownlint and Vale are available.
Run lint-doc.sh
locally
Use a Rake task to run the lint-doc.sh
tests locally.
Prerequisites:
- You have either:
- The required lint tools installed on your computer.
- A working Docker or
containerd
installation, to use an image with these tools pre-installed.
- Go to your
gitlab
directory. -
Run:
rake lint:markdown
To specify a single file or directory you would like to run lint checks for, run:
MD_DOC_PATH=path/to/my_doc.md rake lint:markdown
The output should be similar to:
=> Linting documents at path /path/to/gitlab as <user>...
=> Checking for cURL short options...
=> Checking for CHANGELOG.md duplicate entries...
=> Checking /path/to/gitlab/doc for executable permissions...
=> Checking for new README.md files...
=> Linting markdown style...
=> Linting prose...
✔ 0 errors, 0 warnings and 0 suggestions in 1 file.
✔ Linting passed
Run documentation link tests locally
To run documentation link tests locally, you can either:
- Run a link check for a single project that contains documentation.
- Run a link check across entire local copy of the GitLab documentation site.
Check a single project
To check the links on a single project:
- Install Lychee.
- Change into the root directory of the project.
- Run
lychee --offline --include-fragments <doc_directory>
where<doc_directory>
it the directory that contains documentation to check. For example:lychee --offline --include-fragments doc
.
Check all GitLab Docs site projects
To check links on the entire GitLab documentation site:
- Make sure you have all the documentation projects cloned in the same directory as your
gitlab-docs
clone. You can runmake clone-all-docs-projects
to clone any projects you don’t have in that location. If you want to update the documentation projects, runmake update-all-projects
. - Go to the
gitlab-docs
directory. - Run
make internal-links-and-anchors-check
, which builds the GitLab Docs site withnanoc
and checks links on the built site by usingnanoc
.
Run UI link tests locally
To test documentation links in the GitLab UI locally:
- Open the
gitlab
directory in a terminal window. -
Run:
bundle exec haml-lint -i DocumentationLinks
If you receive an error the first time you run this test, run bundle install
, which
installs the dependencies for GitLab, and try again.
If you don’t want to install all of the dependencies to test the links, you can:
- Open the
gitlab
directory in a terminal window. -
Install
haml-lint
:gem install haml_lint
-
Run:
haml-lint -i DocumentationLinks
If you manually install haml-lint
with this process, it does not update automatically
and you should make sure your version matches the version used by GitLab.
Update linter configuration
Vale and markdownlint configurations are under source control in each project, so updates must be committed to each project individually.
The configuration in the gitlab
project should be treated as the source of truth,
and all updates should first be made there.
On a regular basis, the changes made in gitlab
project to the Vale and markdownlint configuration should be
synchronized to the other projects. In each of the supported projects:
- Create a new branch. Add
docs-
to the beginning or-docs
to the end of the branch name. Some projects use this convention to limit the jobs that run. -
Copy the configuration files from the
gitlab
project. For example, in the root directory of the project, run:# Copy markdownlint configuration file cp ../gitlab/.markdownlint-cli2.yaml . # Remove existing Vale configuration in case some rules have been removed from the GitLab project rm -r docs/.vale/gitlab # Copy gitlab_base Vale configuration files for a project with documentation stored in 'docs' directory cp -r ../gitlab/doc/.vale/gitlab_base docs/.vale
-
If updating
gitlab-runner
,gitlab-omnibus
,charts/gitlab
, orgitlab-operator
, also copy thegitlab-docs
Vale configuration from thegitlab
project. For example, in the root directory of the project, run:# Copy gitlab-docs Vale configuration files for a project with documentation stored in 'docs' directory cp -r ../gitlab/doc/.vale/gitlab_docs docs/.vale
-
Review the diff created for
.markdownlint-cli2.yaml
. For example, run:git diff .markdownlint-cli2.yaml
- Remove any changes that aren’t required. For example,
customRules
is only used in thegitlab
project. -
Review the diffs created for the Vale configuration. For example, run:
git diff docs
- Remove unneeded changes to
RelativeLinks.yml
. This rule is specific to each project. - Remove any
.tmpl
files. These files are only used in thegitlab
project. -
Run
markdownlint-cli2
to check for any violations of the new rules. For example:markdownlint-cli2 docs/**/*.md
-
Run Vale to check for any violations of the new rules. For example:
vale --minAlertLevel error docs
-
Commit the changes to the new branch. Some projects require conventional commits so check the contributing information for the project before committing.
- Submit a merge request for review.
Update linting images
Lint tests run in CI/CD pipelines using images from the
gitlab-docs
container registry.
If a new version of a dependency is released (like a new version of Ruby), we should update the images to use the newer version. Then, we can update the configuration files in each of our documentation projects to point to the new image.
To update the linting images:
- In
gitlab-docs
, open a merge request to update.gitlab-ci.yml
to use the new tooling version. (Example MR) - When merged, start a
Build docker images manually
scheduled pipeline. - Go the pipeline you started, and wait for the relevant
test:image
job to complete, for exampletest:image:docs-lint-markdown
. If the job:- Passes, start the relevant
image:
job, for example,image:docs-lint-markdown
. - Fails, review the test job log and start troubleshooting the issue. The image configuration likely needs some manual tweaks to work with the updated dependency.
- Passes, start the relevant
- After the
image:
job passes, check the job’s log for the name of the new image. (Example job output) - Verify that the new image was added to the container registry.
- Open merge requests to update each of these configuration files to point to the new image.
In each merge request, include a small doc update to trigger the job that uses the image.
- https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/docs.gitlab-ci.yml (Example MR)
- https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/.gitlab/ci/docs.gitlab-ci.yml (Example MR)
- https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/master/gitlab-ci-config/gitlab-com.yml (Example MR)
- https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/.gitlab-ci.yml (Example MR)
- https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/blob/master/.gitlab-ci.yml (Example MR)
- https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/.gitlab/ci/test.gitlab-ci.yml (Example MR)
- In each merge request, check the relevant job output to confirm the updated image was used for the test. (Example job output)
- Assign the merge requests to any technical writer to review and merge.
Configure pre-push hooks
Git pre-push hooks allow Git users to:
- Run tests or other processes before pushing a branch.
- Avoid pushing a branch if failures occur with these tests.
lefthook
is a Git hooks manager. It makes configuring,
installing, and removing Git hooks simpler. Configuration for it is available in the
lefthook.yml
file for the gitlab
project.
To set up lefthook
for documentation linting, see
Pre-push static analysis.
To show Vale errors on push, see Show Vale warnings on push.
Disable linting on documentation
Some, but not all, linting can be disabled on documentation files:
- Vale tests can be disabled for all or part of a file.
-
markdownlint
tests can be disabled for all or part of a file. - Documentation link tests cannot be disabled.
- UI link tests cannot be disabled.
Tool versions used in CI/CD pipelines
You should use linter versions that are the same as those used in our CI/CD pipelines for maximum compatibility with the linting rules we use.
To match the versions of markdownlint-cli2
and vale
used in the GitLab projects, refer to:
- For projects managed with
asdf
, the.tool-versions
file in the project. For example, the.tool-versions
file in thegitlab
project. - The versions used (see
variables:
section) when building theimage:docs-lint-markdown
Docker image containing these tools for CI/CD.
Versions set in these two locations should be the same.
Tool | Version | Command | Additional information |
---|---|---|---|
markdownlint-cli2
| Latest | yarn global add markdownlint-cli2
| None. |
markdownlint-cli2
| Specific | yarn global add markdownlint-cli2@0.8.1
| The @ indicates a specific version, and this example updates the tool to version 0.8.1 .
|
Vale (using asdf )
| Specific | asdf install
| Installs the version of Vale set in .tool-versions file in a project.
|
Vale (other) | Specific | Not applicable. | Binaries can be directly downloaded. |
Vale (using brew )
| Latest | brew update && brew upgrade vale
| This command is for macOS only. |
Supported projects
For the specifics of each test run in our CI/CD pipelines, see the configuration for those tests in the relevant projects:
- https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/docs.gitlab-ci.yml
- https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/.gitlab/ci/docs.gitlab-ci.yml
- https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/master/gitlab-ci-config/gitlab-com.yml
- https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/.gitlab-ci.yml
- https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/blob/master/.gitlab-ci.yml
We also run some documentation tests in these projects:
- GitLab CLI: https://gitlab.com/gitlab-org/cli/-/blob/main/.gitlab-ci.yml
- GitLab Development Kit: https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/.gitlab/ci/test.gitlab-ci.yml
- Gitaly: https://gitlab.com/gitlab-org/gitaly/-/blob/master/.gitlab-ci.yml
- GitLab Duo Plugin for JetBrains: https://gitlab.com/gitlab-org/editor-extensions/gitlab-jetbrains-plugin/-/blob/main/.gitlab-ci.yml
- GitLab Workflow extension for VS Code: https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/blob/main/.gitlab-ci.yml
- GitLab Plugin for Neovim: https://gitlab.com/gitlab-org/editor-extensions/gitlab.vim/-/blob/main/.gitlab-ci.yml
- GitLab Language Server: https://gitlab.com/gitlab-org/editor-extensions/gitlab-lsp/-/blob/main/.gitlab-ci.yml
- GitLab Extension for Visual Studio: https://gitlab.com/gitlab-org/editor-extensions/gitlab-visual-studio-extension/-/blob/main/.gitlab-ci.yml
- AI Gateway: https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/blob/main/.gitlab/ci/lint.gitlab-ci.yml
- Prompt Library: https://gitlab.com/gitlab-org/modelops/ai-model-validation-and-research/ai-evaluation/prompt-library/-/blob/main/.gitlab-ci.yml