gitlab-foss/doc/development/documentation/testing/links.md

stage, group, info, description, title

stage	group	info	description	title
none	Documentation Guidelines	For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.	Learn how to contribute to GitLab Documentation.	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

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

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