merge queue: checking #12597 on main (558a44c) by mergify[bot] · Pull Request #12731 · Mergifyio/docs

mergify · 2026-09-08T13:48:00Z

🎉 This pull request has been checked successfully and will be merged soon. 🎉

#12597 is queued for merge on branch main (558a44c).

This pull request has been created by Mergify to check the mergeability of #12597.
You don't need to do anything. Mergify will close this pull request automatically when it is complete.

Required conditions of queue rule default for merge:

Required conditions to stay in the queue:

---
checking_base_sha: 558a44cd7a9a6f9ccdf175902e920ac6a3289bde
previous_check_retries: []
previous_failed_batches: []
pull_requests:
  - number: 12597
    scopes: []
scopes: []
...

`getOgImageUrl` strips the leading and trailing slashes off the pathname to build the image filename. For the homepage that pathname is `/`, so stripping left an empty string and the lookup missed — every docs page had an OpenGraph image and the homepage shipped `<meta property="og:image">` with no content. The homepage's collection id is `index`, which is what `getStaticPaths` names its image, so fall back to that when the slug comes out empty. Covered by a regression test that fails against the old expression. The generated-image set comes from the content collection and needs the Astro build pipeline, so the test stubs it and exercises the derivation, which is the half that was wrong. Change-Id: Ifb9a23ea2caa20d28489a4f21363d85ed5e3342c

Docset cards rendered their title as `h4`. Almost every grid sits directly under an `##`, so the outline jumped h2 to h4 — including on the homepage, whose whole body is the "Products" grid. Screen readers and anything parsing the document outline read that as a missing level. Default the card heading to `h3` and make it a prop, because one grid does belong at h4: the "Components" grid in `ci-insights.mdx` is nested under an `### Components`, where h3 would make the cards siblings of their own section heading instead of children. Change-Id: Ie01f4c2b03f1f2b7f798ae89b056135a5b00800e

The Mergify OpenAPI 3.1 document is already deployed — it is what the API Reference pages are generated from — but only at `/api-schemas.json`, a filename that exists nowhere outside this repository. Every OpenAPI client, SDK generator and crawler probes `/openapi.json`, so nothing finds it and the docs read as a site with no API at all. Serve the same bytes at `/openapi.json`. The route does not transform the document: the spec is synced from the engine repository, and two spellings of it that could disagree would be worse than one obscure path. Alongside it, three other entry points that were undiscoverable: - `<link rel="service-desc">` in every page head, the IANA relation for "the description of this site's API" (RFC 8631), plus one for `llms.txt`. - `robots.txt` had no `Sitemap:` line, so crawlers had to guess `sitemap-index.xml` rather than be told. - `/developers` is the path people and tools guess for a developer portal and was a 404; it now redirects to the API reference. Change-Id: I1b625f960363c8427d5282c052fee74111bf07fa

Every page already ships its Markdown source at `<path>.md`, which is what the "View as Markdown" button and `llms.txt` link to. But the convention agents reach for first is to request the page's own URL with `Accept: text/markdown` (https://acceptmarkdown.com), and that returned HTML. The site is a static build, so a Cloudflare Pages middleware is the only layer that sees request headers. It rewrites to the `.md` twin when Markdown is asked for, answers 404s in the format that was requested, and merges `Accept` into `Vary` on both variants — without it a CDN would hand whichever variant it cached first to everyone, which is the failure this is most likely to produce in production and the least likely to be noticed. The `Vary` goes on `304` responses too, since those are exactly the ones a cache is about to act on. Markdown is served only when `text/markdown` is named explicitly and not outranked by `text/html`. Browsers send `text/html,...,*/*;q=0.8`, so honouring wildcards would serve raw Markdown to every human visitor; the tests pin the real Chrome and Firefox Accept headers against that. HTML is served as the fallback only on a `404` from the `.md` route, not on anything that is merely not `ok`: `304 Not Modified` is the normal answer to a client revalidating Markdown it already holds, and treating it as a missing page answered it with HTML. Three things about adding a root `_middleware` needed care, all three verified against the real Pages runtime with `wrangler pages dev dist`: Cloudflare documents that `_redirects` are not applied to requests served by Functions, and this repository has 99 of them. `next()` does still route through the asset server, so every redirect, the `_headers` rules, the `.md` routes and the static 404 behave exactly as before. `next()` is called with an explicit request everywhere. A bare `next()` is documented as forwarding the original request, but once the middleware has asked for the Markdown twin the runtime forwards *that* request again — so `/api` and `/cli`, which are built from `src/pages/` and have no `.md`, were answered with the Markdown 404 instead of their own HTML. The test double refuses a call with no request so this cannot come back. A root middleware otherwise turns every request into a Worker invocation, assets included — roughly thirty per page view, none of which can be negotiated. `_routes.json` excludes the bundle, the search index, the OpenGraph images and the static files by name, so only page requests reach the Function. Also ignore `.wrangler/` — running the Pages runtime locally drops generated bundles there, and eslint linted them. Change-Id: I52f9d2a1c70248b1406412129a633cc3bee219de

`llms.txt` was a page index and nothing else: an agent could see every URL we publish and still not know whether Mergify was the right tool for the task in front of it, or how to call it. Add two sections above the index. "When to use Mergify" names the jobs concretely — keeping main green, merging at volume without the CI bill, diagnosing CI, flaky tests, merge requirements GitHub cannot express, stacked PRs — and, just as usefully, says what is out of scope. GitHub only, no other code host; GitLab appears solely as a source of CI results. That one line saves an agent from planning an integration that does not exist, which is worth more than another paragraph of capabilities. "For agents" points at the machine-readable surfaces: the `.md` twin of every page and the `Accept: text/markdown` equivalent, the OpenAPI document with its base URL and auth scheme, the sitemap, the `.mergify.yml` JSON Schema, and how to install the CLI. That last one because naming a CLI without an install path leaves an agent exactly where it started; the paths are the Homebrew tap, the install script and the Windows release zip, per /cli/usage. Change-Id: I03f7b473ced0969e850d78b48758e1849535062f

jd and others added 6 commits August 28, 2026 17:08

Merge of #12597

7116e3b

mergify Bot deployed to Mergify Merge Protections September 8, 2026 13:48 Active

mergify Bot mentioned this pull request Sep 8, 2026

feat(docs): tell agents what Mergify is for in llms.txt #12597

Merged

mergify Bot closed this Sep 8, 2026

mergify Bot deleted the mergify/merge-queue/0206fd2c48 branch September 8, 2026 13:50

Navigation Menu

Uh oh!

merge queue: checking #12597 on main (558a44c) - #12731

merge queue: checking #12597 on main (558a44c)#12731
mergify[bot] wants to merge 6 commits into
mainfrom
mergify/merge-queue/0206fd2c48

mergify Bot commented Sep 8, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

mergify Bot commented Sep 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

1 participant

mergify Bot commented Sep 8, 2026 •

edited

Loading