Error code docs: render the ably-common registry into the docs site

[lmars]

Summary

Renders the Ably error-code registry (introduced in ably-common#348) into the docs site: a documentation page per error code plus a browsable index, all sourced from ably-common/errors/codes/*.md.

• Detail page — /docs/platform/errors/codes/<code>: heading <code>: <title>, the stable identifier as a soft sub-title, the summary as the primary description, then the detail body (causes / how to resolve).
• Index — /docs/platform/errors/codes: one section per code (linked code: title heading, identifier, summary), replacing the old hand-maintained codes.mdx.

Screenshots

Index page

---

Detail page (summary only)

---

Detail page (summary + body)

---

How it works

The pages are generated and committed, not built at runtime:

• bin/generate-error-pages.ts (yarn generate:errors) reads the ably-common submodule and writes the MDX pages under src/pages/docs/platform/errors/codes/. Each carries a hidden {/* DO NOT EDIT */} MDX comment.
• Committing the output means the site build/deploy needs no submodule (CircleCI's checkout doesn't init submodules — build-time generation would silently emit nothing).
• A CI job (check-error-docs) inits the submodule, regenerates, and fails on any diff, so the committed pages can't drift from the registry or be hand-edited.

The two commits are split as machinery (submodule, generator, CI, component changes, link migrations) and generated pages (the 254 pages + index).

Supporting changes

• PageHeader gains an optional subtitle slot; MDXWrapper renders frontmatter.identifier there.
• Error-code detail pages resolve to the Platform "Error codes" nav entry, so they show the Platform sidebar.
• Footer "Edit on GitHub" points error-code pages at their ably-common source file (hidden on the generated index).
• The 8 inline links to …/errors/codes#<code> now point at the detail pages; the index keeps the /docs/platform/errors/codes URL (old /docs/errors/codes redirect preserved) and carries #<code> anchors for old deep links.

Depends on / follow-ups

• Depends on ably-common#348. The submodule is pinned to that PR's commit. Once it merges, bump the submodule to ably-common main — until then the "Edit on GitHub" links target main and 404.
• Deferred (tracked separately): SDK codegen migrations (ably-go / ably-ruby / ably-ai-transport-js) and the help.ably.io/error/{code} → /docs/platform/errors/codes/<code> redirect cutover.

Verification

• Full gatsby build succeeds: 254 detail pages + index emitted, LLM-markdown export and redirects generated.
• All 255 pages compile with the MDX + GFM config the site uses; the "DO NOT EDIT" banner is confirmed absent from rendered HTML.
• Lint and typecheck clean on all changed files.

Add the review-app label to spin up a review deployment. Tag @team-deved for review.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: bb0960e6-b12f-4783-80da-6bb126d49e01

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch error-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[m-hulbert]

This mostly LGTM. Just a few comments/suggestions:

• I think the index of error codes would work better as a table, rather than 100s of headings. Debatable whether it's 1 continuous table or we split it into error code batches for easier navigation.
• I think a design pass at the sub-header identifier is probably in order as it looks a bit odd.
• I think the identifier should probably be output to the .md version of each page (configured in data/onPostBuild/transpileMdxToMarkdown.ts) for LLM consumption.