Documentation and UI link tests

For testing:

  • Documentation links to other documentation, we use Lychee and sometimes nanoc.
  • Links to documentation from the GitLab UI, we use haml-lint and eslint .

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:

  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 gitlab-docs clone. You can run make clone-all-docs-projects to clone any projects you don’t have in that location. If you want to update the documentation projects, run make update-all-projects.
  2. Go to the gitlab-docs directory.
  3. Run make internal-links-and-anchors-check, which builds the GitLab Docs site with nanoc and checks links on the built site by using nanoc.

To test documentation links in the GitLab UI locally, you need to run both haml-lint and eslint.

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.