|
| 1 | +#!/usr/bin/env bash |
| 2 | +# description: Check documentation links for 404s using htmltest, |
| 3 | +# and verify that internal links use Hugo's relref shortcode. |
| 4 | +# |
| 5 | +# Usage: |
| 6 | +# ./hack/check-links.sh # Check only (exits 1 if bare relative links found) |
| 7 | +# ./hack/check-links.sh --fix # Auto-fix bare relative links to use relref, then check |
| 8 | +# |
| 9 | +# This script first checks that markdown files don't use bare relative |
| 10 | +# links (which break in Hugo's nested index.html output), then builds |
| 11 | +# the Hugo docs site and runs htmltest against the generated HTML to |
| 12 | +# detect broken internal and external links. |
| 13 | +set -eufo pipefail |
| 14 | + |
| 15 | +FIX_MODE=false |
| 16 | +if [[ "${1:-}" == "--fix" ]]; then |
| 17 | + FIX_MODE=true |
| 18 | +fi |
| 19 | + |
| 20 | +TOPDIR=$(git rev-parse --show-toplevel) |
| 21 | +TMPDIR=${TOPDIR}/tmp |
| 22 | +HUGO_VERSION=${HUGO_VERSION:-0.146.0} |
| 23 | +HTMLTEST_VERSION=${HTMLTEST_VERSION:-0.17.0} |
| 24 | +HUGO_BIN=${TMPDIR}/hugo/hugo |
| 25 | +HTMLTEST_BIN=${TMPDIR}/htmltest/htmltest |
| 26 | +DOCS_BUILD_DIR=${TMPDIR}/docs-build-test |
| 27 | +DOCS_CONTENT_DIR=${TOPDIR}/docs/content |
| 28 | + |
| 29 | +# --- Step 1: Check (and optionally fix) that internal links use relref shortcode --- |
| 30 | +# Bare relative links like [text](some-page) break when Hugo generates |
| 31 | +# nested index.html files. Authors should use {{< relref "/docs/path" >}}. |
| 32 | +# Excluded from checking: |
| 33 | +# - External URLs (http://, https://) |
| 34 | +# - Anchor-only links (#section) |
| 35 | +# - Links already using relref or other Hugo shortcodes |
| 36 | +# - Image references  |
| 37 | +# - mailto: and tel: links |
| 38 | +# - Absolute paths starting with / (valid Hugo site-root paths) |
| 39 | +# - Lines containing Hugo shortcodes (card, relref, etc.) |
| 40 | +# - Lines with raw HTML (href=) |
| 41 | +if [[ "$FIX_MODE" == "true" ]]; then |
| 42 | + echo "==> Fixing bare relative links to use relref shortcode..." |
| 43 | +else |
| 44 | + echo "==> Checking documentation links use relref shortcode..." |
| 45 | +fi |
| 46 | +relref_count=0 |
| 47 | + |
| 48 | +while IFS= read -r -d '' file; do |
| 49 | + # Compute the directory of this file relative to docs/content/ |
| 50 | + # e.g., docs/content/docs/operations/settings.md -> docs/operations |
| 51 | + file_rel="${file#"${DOCS_CONTENT_DIR}/"}" |
| 52 | + file_dir=$(dirname "$file_rel") |
| 53 | + # Normalize: "." means root of content |
| 54 | + if [[ "$file_dir" == "." ]]; then |
| 55 | + file_dir="" |
| 56 | + fi |
| 57 | + |
| 58 | + if [[ "$FIX_MODE" == "true" ]]; then |
| 59 | + # Use perl to find and replace bare relative links in-place |
| 60 | + # Pass the file's directory so we can compute absolute relref paths |
| 61 | + FILE_DIR="$file_dir" perl -pi -e ' |
| 62 | + BEGIN { $dir = $ENV{FILE_DIR}; } |
| 63 | + # Skip lines with Hugo shortcodes |
| 64 | + next if /\{\{[<%]/; |
| 65 | + # Skip lines with raw HTML href |
| 66 | + next if /href=/; |
| 67 | + # Replace [text](bare-target) but NOT  |
| 68 | + s{(?<!!)\[([^\]]*)\]\(([^)]+)\)}{ |
| 69 | + my ($text, $target) = ($1, $2); |
| 70 | + # Only fix bare relative links |
| 71 | + if ($target =~ m{^https?://} || |
| 72 | + $target =~ m{^#} || |
| 73 | + $target =~ m{^(mailto|tel):} || |
| 74 | + $target =~ m/\{\{/ || |
| 75 | + $target =~ m{^/}) { |
| 76 | + "[$text]($target)"; |
| 77 | + } else { |
| 78 | + # Separate anchor from path |
| 79 | + my ($path, $anchor) = $target =~ m{^([^#]*)(.*)$}; |
| 80 | + # Resolve relative path against file directory |
| 81 | + my $abs; |
| 82 | + if ($dir eq "") { |
| 83 | + $abs = $path; |
| 84 | + } else { |
| 85 | + $abs = "$dir/$path"; |
| 86 | + } |
| 87 | + # Normalize: collapse foo/../bar -> bar |
| 88 | + while ($abs =~ s{[^/]+/\.\./}{}) {} |
| 89 | + $abs =~ s{/\.\./}{/}g; |
| 90 | + # Remove trailing / |
| 91 | + $abs =~ s{/$}{}; |
| 92 | + # Remove .md suffix |
| 93 | + $abs =~ s{\.md$}{}; |
| 94 | + # Prepend / |
| 95 | + $abs = "/$abs" unless $abs =~ m{^/}; |
| 96 | + "[$text]({{< relref \"${abs}${anchor}\" >}})"; |
| 97 | + } |
| 98 | + }ge; |
| 99 | + ' "$file" |
| 100 | + fi |
| 101 | + |
| 102 | + # Now scan the (possibly modified) file for remaining bare relative links |
| 103 | + line_num=0 |
| 104 | + while IFS= read -r line; do |
| 105 | + line_num=$((line_num + 1)) |
| 106 | + |
| 107 | + # Skip lines containing Hugo shortcodes (card, relref, etc.) |
| 108 | + if [[ "$line" =~ \{\{[\<\%] ]]; then |
| 109 | + continue |
| 110 | + fi |
| 111 | + |
| 112 | + # Skip lines with raw HTML tags |
| 113 | + if [[ "$line" =~ href= ]]; then |
| 114 | + continue |
| 115 | + fi |
| 116 | + |
| 117 | + # Skip lines with no markdown link syntax |
| 118 | + if ! [[ "$line" =~ \]\( ]]; then |
| 119 | + continue |
| 120 | + fi |
| 121 | + |
| 122 | + # Extract bare relative link targets using perl |
| 123 | + matches=$(echo "$line" | perl -ne ' |
| 124 | + while (/(?<!!)\[([^\]]*)\]\(([^)]+)\)/g) { |
| 125 | + my $target = $2; |
| 126 | + next if $target =~ m{^https?://}; |
| 127 | + next if $target =~ m{^#}; |
| 128 | + next if $target =~ m{^(mailto|tel):}; |
| 129 | + next if $target =~ m{\{\{}; |
| 130 | + next if $target =~ m{^/}; |
| 131 | + print "$target\n"; |
| 132 | + } |
| 133 | + ' 2>/dev/null || true) |
| 134 | + |
| 135 | + if [[ -n "$matches" ]]; then |
| 136 | + while IFS= read -r target; do |
| 137 | + if [[ "$FIX_MODE" == "true" ]]; then |
| 138 | + echo " WARNING: ${file}:${line_num}: could not auto-fix bare relative link '${target}'" |
| 139 | + else |
| 140 | + echo " ERROR: ${file}:${line_num}: bare relative link '${target}' should use {{< relref >}}" |
| 141 | + fi |
| 142 | + relref_count=$((relref_count + 1)) |
| 143 | + done <<<"$matches" |
| 144 | + fi |
| 145 | + done <"$file" |
| 146 | +done < <(find "$DOCS_CONTENT_DIR" -name '*.md' -print0) |
| 147 | + |
| 148 | +if [[ "$FIX_MODE" == "true" ]]; then |
| 149 | + if [[ $relref_count -gt 0 ]]; then |
| 150 | + echo "" |
| 151 | + echo "WARNING: ${relref_count} link(s) could not be auto-fixed. Please fix manually." |
| 152 | + else |
| 153 | + # Show what changed |
| 154 | + changed=$(git -C "${TOPDIR}" diff --name-only -- docs/content/ 2>/dev/null || true) |
| 155 | + if [[ -n "$changed" ]]; then |
| 156 | + echo " Fixed files:" |
| 157 | + echo "$changed" | while IFS= read -r f; do echo " $f"; done |
| 158 | + echo "" |
| 159 | + echo " Run 'make check-links' to verify the fixes." |
| 160 | + else |
| 161 | + echo " No bare relative links found, nothing to fix." |
| 162 | + fi |
| 163 | + fi |
| 164 | +else |
| 165 | + if [[ $relref_count -gt 0 ]]; then |
| 166 | + echo "" |
| 167 | + echo "Found ${relref_count} bare relative link(s). Use {{< relref \"/docs/path\" >}} instead." |
| 168 | + echo "Run 'make fix-links' to auto-fix them." |
| 169 | + exit 1 |
| 170 | + fi |
| 171 | + echo " All internal documentation links use relref correctly." |
| 172 | +fi |
| 173 | + |
| 174 | +# --- Step 2: Build Hugo site and run htmltest --- |
| 175 | +# Download Hugo if not present |
| 176 | +echo "==> Ensuring Hugo ${HUGO_VERSION} is available..." |
| 177 | +"${TOPDIR}/hack/download-hugo.sh" "${HUGO_VERSION}" "${TMPDIR}/hugo" |
| 178 | + |
| 179 | +# Download htmltest if not present |
| 180 | +echo "==> Ensuring htmltest ${HTMLTEST_VERSION} is available..." |
| 181 | +"${TOPDIR}/hack/download-htmltest.sh" "${HTMLTEST_VERSION}" "${TMPDIR}/htmltest" |
| 182 | + |
| 183 | +# Build Hugo site |
| 184 | +echo "==> Building Hugo documentation site..." |
| 185 | +"${HUGO_BIN}" --gc --minify -s "${TOPDIR}/docs/" -d "${DOCS_BUILD_DIR}" |
| 186 | + |
| 187 | +# Run htmltest |
| 188 | +echo "==> Running htmltest link checker..." |
| 189 | +"${HTMLTEST_BIN}" -c "${TOPDIR}/docs/.htmltest.yml" |
0 commit comments