Documentation and UI link tests

For testing:

• Relative links between documentation files, we use Lychee.
• Links to documentation from the GitLab UI, we use haml-lint, eslint, and rubocop.

Run the relative link test locally

To run the relative link test locally, you can either:

• Run the link check for a single project that contains documentation.
• Run the link check across entire local copy of the GitLab documentation site.

Check a single project

To check the links on a single project:

1. Install Lychee.
2. Change into the root directory of the project.
3. 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:

1. Make sure you have all the documentation projects cloned in the same directory as your docs-gitlab-com clone. You can run make clone-docs-projects to clone any projects you don’t have in that location.
2. Go to the docs-gitlab-com directory.
3. Run hugo, which builds the GitLab Docs site.
4. Run lychee --offline public to check links.

Run UI link tests locally

To test documentation links from GitLab code files locally, you can run

• haml-lint: For .haml files.
• eslint: For frontend (.js and .vue) files.
• rubocop: For .rb files.

Run haml-lint tests

1. Open the gitlab directory in a terminal window.

2. 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:

1. Open the gitlab directory in a terminal window.

2. Install haml-lint:

   gem install haml_lint

3. 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.

Run eslint tests

1. Open the gitlab directory in a terminal window.

2. Run:

   scripts/frontend/lint_docs_links.mjs

If you receive an error the first time you run this test, run yarn install, which installs the dependencies for GitLab, and try again.

Run rubocop tests

1. Install RuboCop

2. Open the gitlab directory in a terminal window.

3. To run the check on all Ruby files:

   rubocop --only Gitlab/DocumentationLinks/Link

   To run the check on a single Ruby file:

   rubocop --only Gitlab/DocumentationLinks/Link path/to/ruby/file.rb