Menu
Find and fix broken internal 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-internal-links |
| description | Find and fix broken internal links in the docs site using linkchecker |
Find and fix all broken internal 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 to find broken internal links:
docker run --rm --name linkchecker \
-v $PWD:/workdir \
-w /workdir \
--link server:server \
ghcr.io/linkchecker/linkchecker:latest \
http://server:8080 \
-t 4 \
--no-status \
--file-output text/linkcheck-report.txt \
--ignore-url="^https://docs\.giantswarm\.io/.*" \
--ignore-url="^http://server:8080/changes/.*"
Read linkcheck-report.txt. Each link report starts with the term URL and ends with a double line break.
Fix each broken link:
Stop the server:
docker kill server
Report results to the user.
IMPORTANT: Always use the relref shortcode for internal links. When modifying an internal link that was not using relref, convert it to relref syntax.