Menu
Find and fix broken external links in the docs site using linkchecker
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Understand and maintain how the CRD reference pages under /reference/platform-api/crd/ are generated — register a new CRD source repo, make sure every published CRD has an example CR, and fix pages that render without an example
Classify documentation pages into their Diátaxis type and propose the diataxis_content_type frontmatter value, flagging pages that mix modes
Create a box on a Miro board for every row in a CSV inventory of pages (e.g. the output of the export-csv skill) — each box shows the page title as a clickable link to its URL, with the navigation path as a subline
Export a CSV inventory of all documentation pages (title, navigation path levels, and public URL) from the frontmatter of every Markdown file under src/content
Assess English readability of documentation pages (Flesch Reading Ease, Flesch-Kincaid grade, Gunning Fog, LIX), excluding generated content
Apply style fixes and run Vale prose linting on modified or added pages
| name | fix-external-links |
| description | Find and fix broken external links in the docs site using linkchecker |
Find and fix all broken external links in the docs site.
Fetch the latest release tag for the docs container image:
az acr repository show-tags \
--name gsoci \
--repository giantswarm/docs \
--orderby time_desc \
--output tsv | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | head -1
Store the tag as the TAG environment variable.
Start the docs server:
docker run -d --rm --name server -p 8080:8080 -P gsoci.azurecr.io/giantswarm/docs:$TAG
Run linkchecker with external link checking enabled:
docker run --rm --name linkchecker \
-v $PWD:/workdir \
-w /workdir \
--link server:server \
ghcr.io/linkchecker/linkchecker:latest \
http://server:8080 \
-t 3 \
--no-status \
--check-extern \
--file-output text/linkcheck-report.txt \
--ignore-url="^https://docs\.giantswarm\.io/.*" \
--ignore-url="^http://server:8080/changes/.*" \
--ignore-url="^https://.*example\.com/.*" \
--ignore-url=".*gigantic\.io.*" \
--ignore-url="^https://my-org\.github\.com/.*" \
--ignore-url="^https://github\.com/giantswarm/giantswarm/.*"
Read linkcheck-report.txt. Each link report starts with the term URL and ends with a double line break.
Analyse each reported link. Skip any:
example.comFix permanent redirects (HTTP 301) — update the URL in the markdown source to point directly to the real target URL ("Real URL" in the report).
For 404 not found errors — search the web for an adequate replacement page. If found, update the link. If not found, leave the link unchanged and note it.
Stop the server:
docker kill server
Report results to the user as Markdown suitable for a GitHub pull request description, in this order: