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
, andrubocop
.
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:
- 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
docs-gitlab-com
clone. You can runmake clone-docs-projects
to clone any projects you don’t have in that location. - Go to the
docs-gitlab-com
directory. - Run
hugo
, which builds the GitLab Docs site. - 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
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.
Run eslint
tests
Open the
gitlab
directory in a terminal window.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
Open the
gitlab
directory in a terminal window.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
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support