Improve link checking for our docs #3022
Conversation
theunrepentantgeek
requested review from
davefellows,
matthchr,
babbageclunk and
super-harsh
as code owners
| @@ -150,7 +150,7 @@ go-install kustomize sigs.k8s.io/kustomize/kustomize/v4@v4.5.7 | |||
|
|
|||
| # for docs site | |||
| go-install hugo -tags extended github.com/gohugoio/hugo@v0.88.1 | |||
| go-install htmltest github.com/wjdp/htmltest@v0.15.0 | |||
| go-install htmltest github.com/theunrepentantgeek/htmltest@latest | |||
There was a problem hiding this comment.
Leave a todo here mentioning the reason and parent repo
There was a problem hiding this comment.
I also created #3024 so we don't lose track of the need to update.
| cmds: | ||
| # Excluding './content/reference/*' path as it contains all auto-generated API docs. | ||
| - find . -type f -name "*.md" -not -path "./content/reference/*" -not -path "./node_modules/*" -print0 | xargs -0 -n1 markdown-link-check -c link-checker.json | ||
| - htmltest |
There was a problem hiding this comment.
how does this work? do we not require to provide any path?
There was a problem hiding this comment.
The task runs in docs/hugo (see line 90) and there's a .htmltest.yml file in that folder that has the rest of the configuration.
Codecov Report
@@ Coverage Diff @@
## main #3022 +/- ##
==========================================
- Coverage 54.20% 54.20% -0.01%
==========================================
Files 1374 1374
Lines 580799 580799
==========================================
- Hits 314813 314801 -12
- Misses 214198 214205 +7
- Partials 51788 51793 +5 |
There was a problem hiding this comment.
LGTM! just a few minors. Also, get rid of link-checker.json file as we don;t use it anymore.
docs/hugo/.htmltest.yml
Outdated
| @@ -1,3 +1,13 @@ | |||
| DirectoryPath: public | |||
| CheckExternal: false | |||
There was a problem hiding this comment.
We do want to check the external links as well?
There was a problem hiding this comment.
I'll do that in a separate PR.
What this PR does / why we need it:
We have been using markdown-link-check but it has some issues specific to our context:
In this PR, we switch to using htmltest to verify the final HTML that's generated, instead of trying to second-guess Hugo.
(Until PR#215 is merged, we're using a private fork. We'll switch once a new version is released.)
Special notes for your reviewer:
Running
htmltestidentified 57 broken links; fixes for those are included in this PR.We don't need to guess at the links generated by Hugo - the built in relref function allows lookup of a page by name and will generate the appropriate link. No path is needed if the name of the page is unique (and ours mostly are). In most cases you can also omit the file extension, but it seems to be necessary in some cases.
How does this PR make you feel:
If applicable: