diff --git a/doc/development/documentation/testing/index.md b/doc/development/documentation/testing/index.md index 59438ae875876acad9cd58b076c555f5ad8ab371..a600d992d0273558388752801079c3073ff79f22 100644 --- a/doc/development/documentation/testing/index.md +++ b/doc/development/documentation/testing/index.md @@ -52,35 +52,21 @@ error if any Markdown files return a Mermaid syntax error. To help debug your Mermaid charts, use the [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/edit). -## Tests in `docs-lint links` +## Tests in `docs-lint links` and other jobs -Merge requests containing changes to Markdown (`.md`) files run a `docs-lint links` -job, which runs two types of link checks. In both cases, links with destinations -that begin with `http` or `https` are considered external links, and skipped: +To check for broken links, merge requests containing changes to Markdown (`.md`) files run these jobs in their +pipelines: -- `bundle exec nanoc check internal_links`: Tests links to internal pages. -- `bundle exec nanoc check internal_anchors`: Tests links to topic title anchors on internal pages. +- `docs-lint links` job in the `gitlab` project. For example: <https://gitlab.com/gitlab-org/gitlab/-/jobs/7065686331>. +- `docs-lint links` job in the `omnibus-gitlab` project. For example: <https://gitlab.com/gitlab-org/omnibus-gitlab/-/jobs/7065337075>. +- `docs-lint links` job in the `gitlab-operator` project. +- `docs:lint markdown` job in the `gitlab-runner` project, which includes link checking. For example: + <https://gitlab.com/gitlab-org/gitlab-runner/-/jobs/7056674997>. +- `check_docs_links` job in the `charts/gitlab` project. For example: + <https://gitlab.com/gitlab-org/charts/gitlab/-/jobs/7066011619>. -Failures from these tests are displayed at the end of the test results in the **Issues found!** area. -For example, failures in the `internal_anchors` test follow this format: - -```plaintext -[ ERROR ] internal_anchors - Broken anchor detected! - - source file `/tmp/gitlab-docs/public/ee/user/application_security/api_fuzzing/index.html` - - destination `/tmp/gitlab-docs/public/ee/development/code_review.html` - - link `../../../development/code_review.html#review-response-slo` - - anchor `#review-response-slo` -``` - -- **Source file**: The full path to the file containing the error. To find the - file in the `gitlab` repository, replace `/tmp/gitlab-docs/public/ee` with `doc`, and `.html` with `.md`. -- **Destination**: The full path to the file not found by the test. To find the - file in the `gitlab` repository, replace `/tmp/gitlab-docs/public/ee` with `doc`, and `.html` with `.md`. -- **Link**: The actual link the script attempted to find. -- **Anchor**: If present, the topic title anchor the script attempted to find. - -Check for multiple instances of the same broken link on each page reporting an error. -Even if a specific broken link appears multiple times on a page, the test reports it only once. +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` @@ -156,19 +142,30 @@ The output should be similar to: ### Run documentation link tests locally -To test links in the documentation locally: +To run documentation link tests locally, you can either: -1. Go to the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory. -1. Run the following commands: +- Run a link check for a single project that contains documentation. +- Run a link check across entire local copy of the [GitLab documentation site](https://docs.gitlab.com). - ```shell - # Check for broken internal links - bundle exec nanoc check internal_links +#### Check a single project - # Check for broken external links (might take a lot of time to complete). - # This test is allowed to fail, and is run only in the gitlab-docs project CI - bundle exec nanoc check internal_anchors - ``` +To check the links on a single project: + +1. Install [Lychee](https://lychee.cli.rs/installation/). +1. Change into the root directory of the project. +1. 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](https://docs.gitlab.com): + +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`. +1. Go to the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory. +1. 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`. ### Run UI link tests locally