Skip to content

rc-links.sh

Audit rendered HTML links and local asset references

Browse Docs pages

Overview

Audit rendered HTML links and local asset references

Source: bones/scripts/rc-links.sh.

Usage

rotkeeper.sh links [options]

Options

--root DIR       Rendered directory to scan; defaults to output/
--report FILE    Report destination; defaults to bones/reports/link-report-*.md
--json           Emit machine-readable JSON to stdout (failures with line+excerpt)
--fix-hint       Show suggested fixes for each failure (no auto-fix)
--dry-run        Scan without writing a report
--verbose        Show detailed logs (line numbers + excerpts)
--help, -h       Show this help message
--version, -v    Show script version and quit

Examples

bash rotkeeper.sh links                     # Audit and write report
bash rotkeeper.sh links --fix-hint          # Audit with per-failure hints
bash rotkeeper.sh links --json | jq .       # Machine-readable output

Exit codes

0    No broken links or missing assets found
1    Broken references found, or audit error

Reads and writes

Environment: reads BONES_DIR, CONFIG_DIR, CONTENT_DIR, DRY_RUN, LOG_DIR, LOG_FILE, OUTPUT_DIR, QUIET, REPORT_DIR, ROOT_DIR, SCRIPT_DIR, TMP_DIR, VERBOSE (canonical via rc-env.sh / rk_load_env); overrides RK_OLIVER_BIN, RK_RENDERER, ROTKEEPER_VERSION when set.

Working directory: No CWD assumption — all paths are root-relative via ROOT_DIR/BONES_DIR/CONTENT_DIR/etc. derived from rc-env.sh; helpers rk_canonical_path/rk_canonical_or_raw resolve symlinks/portably.

Inputs and outputs: reads rendered HTML under the selected root and audits local href/src targets, linked assets, and same/cross-page HTML anchors. Writes the selected report under the report boundary or emits JSON according to flags; dry-run scans without publishing a report.

Side effects

Notes

Design

The command runs an embedded Python 3 HTML parser over .html files under the selected output root. It checks anchor and link element href attributes, including stylesheets, and src attributes on scripts, images, sources, video, and audio. Same-page and destination HTML page fragments must match an id or name; parsed pages are reused during the scan.

URLs are split before percent decoding, so encoded # and ? remain part of a filename. Directory targets resolve to index.html. Canonical target paths must remain inside the selected scan root. Failure records include the source page, target, reason, line number, and an excerpt.

Limits

The command does not fetch external URLs or validate CSS imports, srcset, non-HTML asset fragments, or references generated by JavaScript.

Source pages that cannot be read are skipped; an unreadable destination for an HTML fragment is a failure. A successful result covers only the references the parser collected.

The scan root must resolve under OUTPUT_DIR. Selecting a narrower root also makes links outside that subtree failures, even if they stay inside the overall output tree.

Cautions

--report is not boundary-checked despite the script header's report-boundary description. Relative report paths resolve from ROOT_DIR; the command creates parent directories and overwrites an existing report.

JSON mode also writes a short Markdown summary unless --dry-run is active. --fix-hint suggests changes; it does not change pages.

Shared flags such as --dry-run are honored before or after command-specific options. Dry-run scans normally and writes bootstrap logs and temporary results, but does not publish a report. Its result scratch file is removed on exit.

History

[0.5.0] - 2026-07-23