Docs: Add docs-check-links target#1546
Conversation
TomFern
changed the title
docs-check-links targetdocs-check-links target
| docs-check-links: docs-image | ||
| rm -rf $(PWD)/docs/public | ||
| docker run \ | ||
| --rm \ | ||
| --platform $(DOCKER_PLATFORM) \ | ||
| -v $(PWD)/docs/victorialogs:/opt/docs/content/victorialogs \ | ||
| -v $(PWD)/docs/public:/opt/docs/public \ | ||
| --entrypoint /bin/sh \ | ||
| vmdocs-docker-package \ | ||
| -c "yarn install && hugo --minify && yarn run check-links" | ||
| rm -rf $(PWD)/docs/public |
There was a problem hiding this comment.
I don't know how it works, but it generates quite false positives. This solution seems fragile to me. It should work without noise and be reliable in order to be useful.
$ linkinator .
→ crawling .
[#] victoriametrics/stream-aggregation/#data-delay-and-staleness
[0] http://scout.docker.com/v/CVE-2025-61729
[0] http://www.haproxy.org/
[0] http://localhost:8428/vmui/
[0] http://localhost:9428/select/vmui
[#] helm/victoriametrics-k8s-stack/changelog/#v0850
[#] helm/victoriametrics-k8s-stack/changelog/#v0850
[#] victoriametrics-cloud/get-started/quickstart/#about-storage
[#] victoriametrics-cloud/alertmanager-setup-for-deployment/#configure-alerting-rules
[#] victoriametrics-cloud/alertmanager-setup-for-deployment/#configure-alerting-rules
[0] http://scout.docker.com/v/CVE-2025-61729
[0] http://scout.docker.com/v/CVE-2025-61729
[0] http://scout.docker.com/v/CVE-2025-61729
[0] http://scout.docker.com/v/CVE-2025-61729
[#] http://docs.grafana.org/administration/provisioning/#datasources
./
[#] victoriametrics/stream-aggregation/#data-delay-and-staleness
[#] victoriametrics-cloud/get-started/quickstart/#about-storage
[#] victoriametrics-cloud/alertmanager-setup-for-deployment/#configure-alerting-rules
[#] victoriametrics-cloud/alertmanager-setup-for-deployment/#configure-alerting-rules
changelog/
[0] http://scout.docker.com/v/CVE-2025-61729
victoriametrics/integrations/grafana/datasource/
[#] http://docs.grafana.org/administration/provisioning/#datasources
victoriametrics/changelog/changelog_2026/
[0] http://scout.docker.com/v/CVE-2025-61729
victoriametrics/changelog/changelog_2025/
[0] http://scout.docker.com/v/CVE-2025-61729
victoriametrics/changelog/changelog_2022/
[0] http://www.haproxy.org/
guides/getting-started-with-opentelemetry/
[0] http://localhost:8428/vmui/
[0] http://localhost:9428/select/vmui
helm/victoria-metrics-k8s-stack/
[#] helm/victoriametrics-k8s-stack/changelog/#v0850
[#] helm/victoriametrics-k8s-stack/changelog/#v0850
victoriametrics/changelog/
[0] http://scout.docker.com/v/CVE-2025-61729
changelog.html
[0] http://scout.docker.com/v/CVE-2025-61729
ERROR: Detected 15 broken links. Scanned 650 links in 33.718 seconds.
There was a problem hiding this comment.
It builds the hugo site by cloning vmdocs and overwriting the docs folders in this repository. Then it uses linkinator to scan the whole site. So it picks up issues across all documentation, not just VictoriaLogs.
The lines with [#] mean there is a broken anchor. That is, the link works but there is no matching anchor in the page.
The lines with [0] mean the link is broken. In this case I think there could have been a network error on some of the external site. I think we should disable all link checking to external sites. I'll check the config file on vmdocs to see how to disable it.
The correct list of issues should be this (I also need to exclude localhost from the scan)
./
[#] victoriametrics/stream-aggregation/#data-delay-and-staleness
[#] victoriametrics-cloud/get-started/quickstart/#about-storage
[#] victoriametrics-cloud/alertmanager-setup-for-deployment/#configure-alerting-rules
[#] victoriametrics-cloud/alertmanager-setup-for-deployment/#configure-alerting-rules
victoriametrics/integrations/grafana/datasource/
[#] http://docs.grafana.org/administration/provisioning/#datasources
victoriametrics/query-stats/
[#] victoriametrics/style_guide/#proofreading-tools
victoriametrics/style_guide/
[0] http://docs.vicoriametrics.com/victoriametrics/data-ingestion/opentelemetry-collector/
guides/getting-started-with-opentelemetry/
[0] http://localhost:8428/vmui/
[0] http://localhost:9428/select/vmui
helm/victoria-metrics-k8s-stack/
[#] helm/victoriametrics-k8s-stack/changelog/#v0850
[#] helm/victoriametrics-k8s-stack/changelog/#v0850
ERROR: Detected 11 broken links. Scanned 653 links in 32.323 seconds.
There was a problem hiding this comment.
Thanks for explaining. Yes, please go ahead. It's probably better to note in the make command that this excludes external sites and only checks inbound links.
Could we set it up to report on VictoriaLogs only since the PR intention is "check the documentation in this repository"?
Also when I run this command, it creates a docs/public/ dir, which makes the git changes on my local dirty with unrelated changes. It would be great to either remove it or move it to /tmp or any folder that gets ignored.
There was a problem hiding this comment.
Sure, I'll make the changes. Thanks for the feedback. The config is global for all docs because the config files lives in vmdocs. I want to add a docs-check-link target in every repository (VM, VL, VT, etc) that has docs, so we can one day add some automation check in all PRs that deal with docs.
There was a problem hiding this comment.
I also added the same checker on VT here: VictoriaMetrics/VictoriaTraces#194
Let me update the config file first and then see if that clears the issues
checker tool fails.
|
@func25 I updated the link checker config in this PR. Once merged, the new config should take effect for all repositories using the link checker tool. (Update: it has been merged) I also updated the docs/Makefile to do the cleanup even if the checker fails. Previously, when the docker command failed due to broken links, the last line which deleted The correct output of the link checker should now be (once the PR above is merged) I checked and they all seem legitimate broken anchors. Here's the report:
|
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 1 file (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="docs/Makefile">
<violation number="1" location="docs/Makefile:101">
P1: The `exit` command in the `docs-check-links` target never executes — it becomes an argument to `rm -rf`. After a link-check failure, `make docs-check-links` exits with code 0 instead of propagating the failure, so CI or pre-merge hooks won't detect broken links. The fix is a missing `;` (or `&&`) before `exit` to separate it from `rm -rf` as an independent command.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com> Signed-off-by: Pablo (Tomas) Fernandez <46322567+TomFern@users.noreply.github.com>
2 participants
We have a
check-linkstarget in the vmdocs repository. This is a good start but it only detects broken links after changes in docs are merged into master in this repository.It would be nice to have a way to check the documentation in this repository (before creating a PR for instance). This PR introduces a
docs-check-linkstarget to thedocs/Makefile. This lets us see if we have any new broken links in the current branch/PR before merging into main.We've already implemented this on VictoriaMetrics here: VictoriaMetrics/VictoriaMetrics#11121