Docs lint passes if a relative link starts with /doc
Summary
This started with https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/24339 where a broken link was introduced, but the lint checker never caught it. It also passed on master!
I accidentally stumbled upon this while working on https://gitlab.com/gitlab-com/gitlab-docs/issues/310, where I found some pipelines failing due to a failing link (in particular https://gitlab.com/gl-docsteam-new/gitlab-docs/-/jobs/150057449). This is irrelevant, but thanks to the broken link I was able to catch another bug in the docs site, so thanks!
How the docs link checker works
We have to first understand how the dead link checker works. Let's take for example the actual change of the MR that introduced the broken link.
In doc/user/project/integrations/slack.md
, we have the link:
[the logs](/doc/administration/logs.md#productionlog)
In .gitlab-ci.yml
the docs-lint job does the following:
script:
- mv doc/ /tmp/gitlab-docs/content/
- cd /tmp/gitlab-docs
# Build HTML from Markdown
- bundle exec nanoc
# Check the internal links
- bundle exec nanoc check internal_links
It moves the doc/
dir inside content
where Nanoc is expecting the markdown files to be. It then builds the site and finally checks for the links. If the built website was deployed to production, that would be under docs.gitlab.com/doc
.
The interesting part here is that [the logs](/doc/administration/logs.md#productionlog)
translates to <a href="/doc/administration/logs.html#productionlog>
. So, Nanoc correctly sees this as an existing file!
Locally or in production that would fail since we don't have content/doc
, but content/ce
, and <a href="/doc/administration/logs.html#productionlog>
would not exist.
I had to test with CI and print the contents of the doc before and after it was built https://gitlab.com/gitlab-org/gitlab-ce/-/jobs/150101518 to make sure I wasn't missing something :)
The fix
Edit .gitlab-ci.yml
to use the same paths as we use in production when deploying the docs site.
- mv doc /tmp/gitlab-docs/content/$DOCS_GITLAB_REPO_SUFFIX