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 /docs/pages/topics for all markdown files and extracts:

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

2. Finds Topic Links - Scans the entire Juneau source tree 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

Check all topic links

cd /Users/james.bognar/git/juneau
python3 scripts/check-topic-links.py

The script will automatically:

• Scan /docs/pages/topics for topic definitions
• Scan the entire Juneau source tree for topic links
• Report any issues found

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 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