fix(ci): make generated endpoint pages pass CI and read correctly in the sidebar

[martzoukos]

Three gaps in the API-spec sync automation, all visible on #476 (the /v2/checks pages).

1. Missing canonical — CI failure

detect-new-endpoints.mjs writes stub frontmatter with only an openapi: key, but since the July SEO audit added check_frontmatter.py every built page must declare a self-referential trailing-slash canonical. The stub now derives it from the same page path it hands docs.json, so the two cannot drift. SITE_BASE carries a comment pointing at BASE in check_frontmatter.py.

2. Stale sitemap — CI failure

sitemap.xml is generated from docs.json navigation, which the generator mutates — so the "Sitemap up to date" gate failed on the same PRs, hidden behind the frontmatter failure. The workflow now regenerates it after page generation and stages it.

3. Duplicate sidebar labels, stranded pages

Mintlify falls back to the OpenAPI summary when a page declares no title. getV2ChecksId's summary is literally "Retrieve a check", so the sidebar showed two identical "Retrieve a check" entries — and addToDocsJson appends, so the v2 pair sat at the bottom of "Checks and Monitors" behind the SSL monitor pages.

Version-suffixed pages now get an explicit title: '… (v2)' and are inserted directly after the /v1 page they supersede. Pages whose summary already names the version (the check-group ones end in (V2)) are left alone rather than becoming "… (V2) (v2)".

Backfilled onto the nine existing *-v2 pages: five gained a title, six moved next to their sibling. Check Sessions was already ordered this way by hand — that pattern is now what the generator produces.

Before / after in "Checks and Monitors":

List all checks              List all checks
Retrieve a check             List all checks (v2)
Delete a check               Retrieve a check
Create a check               Retrieve a check (v2)
Update a check          →    Delete a check
Create an SSL monitor        Create a check
Update an SSL Monitor        Update a check
List all checks              Create an SSL monitor
Retrieve a check             Update an SSL Monitor

Verification

Deleted the four /v2 pages from #476 and their nav entries, then re-ran the patched generator on a clean tree. It reproduces the committed state byte-for-byte — git status comes back empty — so what ships here is exactly what the automation will produce next time.

All three static gates pass:

Wrote sitemap.xml with 592 trailing-slash URLs (incl. home)
Frontmatter check passed (654 .mdx files scanned).
OK: 184 /reference/* redirect destinations all resolve to on-disk pages

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
checkly-422f444a	🟢 Ready	View Preview	Aug 11, 2026, 7:49 AM