Add descriptions to the 167 pages that had none - #1355
Open
thomasbergernz wants to merge 4 commits into
Open
Conversation
Every link in llms.txt now carries a one-line description, up from 131 of 298. Titles alone force a reader to fetch several pages to find the right one; the description is what lets them pick. Each description is written from the page's own content, not from its title. The Available_Applications pages have a real Description section in the body; the my.nesi.org.nz release notes were summarised from their own change bullets, so each version says what actually changed in it rather than sharing one generic line - the failure mode the new meta_thin_description check exists to catch. No two of the 167 descriptions are identical, and none trips that check. Only the 167 pages that appear in llms.txt are touched. docs/FORMAT.md, docs/MACROS.md and docs/NEWPAGE.md have no front matter block at all and are contributor meta pages excluded from llms.txt in #1348, so they keep their existing missing-description notice. Verified with a clean `run_test_build.py` (exit 0, no llmstxt warnings) and `run_meta_check.py` over all 307 pages: its missing-description count goes from 167 to those 3, and its thin-description count is unchanged at the 22 pre-existing pages. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Contributor
This was referenced Jul 29, 2026
CallumWalley
pushed a commit
that referenced
this pull request
Jul 29, 2026
## Summary Every per-file check in `checks.yml` has been passing without looking at a single file. From the `Determine what files to check` job on #1355: ``` fatal: ambiguous argument 'origin/...HEAD': unknown revision or path not in the working tree. ::info::Workflow triggered by PR Changed files: '' ``` and then, in `Check page meta`: ``` No files to check meta on. ``` **Cause.** `github.base_ref` is only populated on `pull_request` events. This workflow triggers on `push` (`branches-ignore: [main]`) and has no `pull_request` trigger at all, so `base_ref` is always empty. The revision in ```bash git diff --name-only origin/${{ github.base_ref }}...HEAD ``` becomes the literal `origin/...HEAD`, the diff fails, and `changed_files` comes back empty. Each dependent job then hits its `if: ${{! needs.get.outputs.filelist}}` branch and exits 0. So **Check Spelling, Check Prose, Check Markdown, Check page meta and Check slurm scripts have been green without running.** Only `Test build` was doing real work. The `::info::Workflow triggered by PR` line printed unconditionally, so the log asserted a trigger that hadn't happened. ## Fix Fall back to the repository default branch when `base_ref` is empty, and **fail the step outright** if the base ref can't be resolved. Silently linting nothing is worse than a red job, because it reads as a pass — that's what let this sit unnoticed. The base is passed through `env:` rather than interpolated into the script. ## Verification Run locally against #1355, which changes 167 pages: ``` $ git diff --name-only "origin/main...origin/docs/add-missing-page-descriptions" | grep -E '^docs/.*\.md$' | wc -l 167 ``` The old command yields an empty list on the same branch. The no-docs-changed case still works — `grep` finding no matches no longer aborts the step under `bash -e`. Note this PR changes no `docs/*.md`, so its own run will legitimately report an empty list. The fix is exercised for real by the next PR that touches documentation. ## Scope Only the `push` and `repository_dispatch` paths were affected. The `workflow_dispatch` path supplies `fileList` explicitly and is unchanged. Heads up that once this lands, PRs may start surfacing lint findings on pages that have never actually been checked. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up to #1354, which wired page front matter
descriptionintollms.txtbut left 167 of the 298 linked pages without one. This fills them in, so every link inllms.txtnow carries a one-line description (131 → 298).That is the point of the index. Titles alone force a reader to fetch several pages to work out which one answers the question; the description is what lets them pick the first time.
How the descriptions were written
From each page's own content, not from its title:
Available_Applicationspages — these have a real## Descriptionsection in the body, so the description is derived from that prose.v2.30.0reads "OnDemand and Freezer resources shown on projects" rather than a generic line repeated 55 times.That last one matters: sharing one description across a run of pages is exactly the failure mode
meta_thin_descriptionwas added to catch in #1354, and eleven Freezer pages already do it. No two of the 167 descriptions are identical, and none of them trips that check. Where a page's own text was ambiguous the description stays deliberately general rather than guessing at specifics.Scope
Only the 167 pages that appear in
llms.txt.docs/FORMAT.md,docs/MACROS.mdanddocs/NEWPAGE.mdhave no front matter block at all and are contributor meta pages excluded fromllms.txtin #1348 — they keep their existing missing-description notice.Results
Remaining backlog (not in this PR)
The 22 pages
meta_thin_descriptionflags are all pre-existing — descriptions that are present but too short to disambiguate, such as"Guide to batch computing"onBatch_Computing_Guide.mdand eleven Freezer release-note pages sharing"Freezer upgrade release notes". They are now the only pages tripping the check. Rewriting them is a separate, smaller pass.Test plan
./checks/run_test_build.pyfrom a clean state: exit 0, zero llmstxt warningschecks/run_meta_check.pyover all 307 pages: no traceback, counts as aboveyaml.safe_load— the front matter still parses and the value comes back exactly as writtenv2.22.0,v2.30.0,v2.50.0) against their full change lists to confirm the description names the lead change, not an incidental onechecks.yml) green<preview-url>/llms.txtand confirm every link has a description🤖 Generated with Claude Code