Skip to content

Diagnostic Modes

Jump to bottom
William Jacoby edited this page Sep 8, 2026 · 1 revision

Diagnostic Modes

Four flags replace a normal build entirely, doing one focused check instead. Three (-l, -m, -i) run before a real build, against the dump; one (-c) runs after, against an already-generated output/.

Diagnostic modes never touch --exclude-excluded content or overwrite an existing deployment's custom assets — each uses a copy_assets_mode internally ("full", "avatars", or "none") scoped to exactly what it needs, not the full asset-copying pipeline a real generate() run does.

-l, --list-forums 

.venv/bin/python -m generator.generate --dump dump/ --output output/ -l

Prints every forum/category with its forum_id, indented to show nesting — so you know which id(s) to put in an --exclude JSON file. Does not render the site or write anything to --output.

-m, --missing-avatars 

.venv/bin/python -m generator.generate --dump dump/ --output output/ -m
.venv/bin/python -m generator.generate --dump dump/ --output output/ -m --avatar-overrides output/avatar_overrides.json

Resolves avatars the same way a real generate() run does (local files, remote fetches, any existing --avatar-overrides), then lists every user whose avatar still doesn't resolve to anything and writes a starter --avatar-overrides template for them. Does not render the site — only assets/avatars/ gets populated, since that's what's needed to check resolution against.

The generated template is written to output/avatar_overrides.json — or output/avatar_overrides.new.json when --avatar-overrides was already supplied, so re-running -m after filling some entries in doesn't silently overwrite your hand-edited file.

-i, --check-images 

.venv/bin/python -m generator.generate --dump dump/ --output output/ -i
.venv/bin/python -m generator.generate --dump dump/ --output output/ -i --url-mirrors mirrors.json

Finds every external [img]/<IMG> URL referenced in posts, signatures, and forum/poll text, and reports which ones fail to resolve (via any --url-mirrors, or the network) to output/unresolved_images.json. Run ahead of a full build to see what's worth mirroring with --url-mirrors before committing to a slow full run. Does not render the site or write any assets.

-c, --check-links 

.venv/bin/python -m generator.generate --output output/ -c

Needs an already-generated output/ — run a normal build first. Scans every generated HTML page's href/src attributes and flags two things:

  1. A link to a file that doesn't exist under output/.
  2. A #anchor link (e.g. topics/106.html#p53377, a permalink to one specific post) whose target file exists but doesn't actually contain that anchor — the more useful of the two, since a plain missing-page link is easy to spot by eye, but a stale anchor pointing at a post that got excluded or never recovered isn't.

Only internal (relative) links are checked — external URLs are a separate, already-handled concern (see --ignore-hosts/--url-mirrors). Results go to output/broken_links.json.

Clone this wiki locally