wagtail Overview
Analyze and maintain links in the README. Fetches metadata for each link, detects stale entries, auto-updates GitHub repo titles and descriptions, and produces a structured report for archival decisions.
Requirements
- Python 3.12+ with
uv ghCLI authenticated (gh auth status)- Network access for HTTP requests (httpx)
Available scripts
scripts/check_links.py— Fetches metadata for all links inREADME.mdand generates a Markdown report on stdout.
Workflow
1. Run the link checker
./scripts/check_links.py --dry-run
Always run with --dry-run first to preview changes without modifying
the README. Re-run without --dry-run to auto-update GitHub repo titles
and descriptions when you're ready.
Add --verbose to see progress and API call details on stderr.
The database is stored at .awesome-wagtail.duckdb by default. Subsequent
runs reuse cached data (24 h for GitHub, 30 d for web pages).
2. Read the report
The report printed to stdout is your action plan. It contains these sections:
Auto-Archive Candidates (GitHub)
Repos that are archived on GitHub or have not been pushed to in over
24 months. These should be moved to docs/archive.md and removed from
README.md.
Needs Review — 12–24 months (GitHub)
Repos with no commits in 12–24 months. For each entry, check whether the
repo's GitHub page or its entry in README.md mentions "archived",
"deprecated", or "unmaintained". If so, move to archive. If the repo is
still active despite infrequent commits, leave it in place.
Updated Link Titles (GitHub)
Repo link titles that differ from the project name found in the repo's README heading. Review the list — many README headings contain badge markup or instructions rather than a clean project name. Only update titles that are clearly better.
Updated Link Descriptions (GitHub)
Repo descriptions that differ from GitHub's project description. In most
cases the GitHub description is shorter and more accurate. Apply these
updates to README.md.
Auto-Archive Candidates (web pages)
Pages that have not been updated in over 5 years (based on HTTP
Last-Modified headers, <meta> tags, or schema.org data). Move these
to docs/archive.md.
Title Mismatches (web pages)
Page titles in README.md that differ from the actual <h1> or
<title> of the page. Review and update if the fetched title is a
better description of the link.
3. Create or update the archive file
The archive lives at docs/archive.md. Mirror the same section structure
as README.md (section > subsection). For each archived link:
- Remove the line from
README.md - Add the line under the matching section in
docs/archive.md
If the archive file does not exist yet, create it with:
# Awesome Wagtail Archive
> Archived projects from the main README that are no longer actively maintained.
## Apps
### Blogging/news
... archived items moved here ...
4. Commit changes
When finished, review the diff and commit:
git diff
git add -A
git commit -m "check-links: archive stale entries and update metadata" --trailer "Assisted-by: <Agent harness> (<Model name>)"