Skip to main content

check-topic-links.py

check-topic-links.py validates that all documentation topic links in the Juneau source code are correct and point to valid topics with matching titles.

What It Does​

The script performs three main operations:

  1. Extracts Topic Information - Scans pages/topics (relative to the juneau-docs repository root) for all markdown files and extracts:

    • Slug names from the frontmatter
    • Page titles from the frontmatter

  2. Finds Topic Links - Scans the Juneau Java source tree (--juneau-root, default sibling ../master/ then ../juneau/) for links in the format:

    https://juneau.apache.org/docs/topics/SLUG">TITLE</a>

  3. Validates Links - Reports any issues:

    • Title mismatches: Link title doesn't match the actual topic title
    • Unknown slugs: Link points to a topic that doesn't exist

Usage​

cd /path/to/juneau-docs
python3 scripts/check-topic-links.py

The script will automatically:

  • Scan pages/topics for topic definitions
  • Scan the Juneau source tree for topic links (sibling ../master/, falling back to ../juneau/)
  • Report any issues found

Non-sibling layouts (worktrees, custom folder names)​

python3 scripts/check-topic-links.py --juneau-root /path/to/juneau
python3 scripts/check-topic-links.py --docs-root /path/to/juneau-docs --juneau-root /path/to/juneau

--docs-root defaults to the checkout containing the script.

File Types Scanned​

The script checks the following file types:

  • .java - Java source files
  • .md - Markdown files
  • .xml - XML configuration files
  • .properties - Properties files
  • .txt - Text files
  • .adoc - AsciiDoc files
  • .rst - reStructuredText files

Exit Codes​

  • 0 - Success, all links validated
  • 1 - Error occurred or validation issues found

Requirements​

  • Python 3.6 or higher
  • No external Python dependencies (uses only standard library)

Notes​

  • The script requires a sibling ../master/ checkout (the Java tree) alongside juneau-docs
  • The script is typically run as part of build-docs.py
  • It validates both slug names and title text
  • Reports are printed to stdout with file locations and line numbers