Skip to content

docs: remediate SEO audit findings - #5606

Merged
NicholasKissel merged 1 commit into
mainfrom
codex/seo-upstream-docs
Aug 26, 2026
Merged

docs: remediate SEO audit findings#5606
NicholasKissel merged 1 commit into
mainfrom
codex/seo-upstream-docs

Conversation

@NicholasKissel

Copy link
Copy Markdown
Member

Summary\n\n- improve current Actors documentation SEO titles and descriptions\n- restore three valid documentation image URLs and remove duplicate body H1s\n- retire three empty moved-page stubs so the website can serve one-hop redirects\n- update current documentation links to canonical destinations\n\n## Validation\n\n- consumed these sources through the website docs assembler\n- production website build, sitemap validation, and built SEO crawl pass\n- git diff --check passes

@railway-app

railway-app Bot commented Aug 26, 2026

Copy link
Copy Markdown

🚅 Deployed to the actors-pr-5606 environment in rivet-frontend

Service Status Web Updated (UTC)
frontend-cloud 😴 Sleeping (View Logs) Web Aug 26, 2026 at 7:36 am
kitchen-sink 😴 Sleeping (View Logs) Web Aug 26, 2026 at 7:32 am
frontend-inspector 😴 Sleeping (View Logs) Web Aug 26, 2026 at 7:31 am
ladle ✅ Success (View Logs) Web Aug 26, 2026 at 7:26 am
mcp-hub ✅ Success (View Logs) Web Aug 26, 2026 at 7:25 am
website ❌ Build Failed (View Logs) Web Aug 26, 2026 at 7:25 am

@railway-app
railway-app Bot temporarily deployed to rivet-frontend / actors-pr-5606 August 26, 2026 07:25 Destroyed
@claude

claude Bot commented Aug 26, 2026

Copy link
Copy Markdown
Contributor

Review: docs SEO remediation

This is a docs-only PR (~59 .mdx files under docs/content/docs/) making SEO-related edits. Findings below.

1. Deleted pages have no redirect (potential broken links)
docs/content/docs/scaling.mdx, helper-types.mdx, and sharing-and-joining-state.mdx appear to be removed outright rather than replaced with a redirect stub, with content presumably folded into design-patterns.mdx. If any external links, bookmarks, or search-engine results point at the old URLs, visitors will hit a 404 instead of being forwarded. Worth confirming whether redirects for these are handled in the separate rivet-dev/website repo, if not, consider adding a redirect entry there (or keeping a thin stub page) as part of this change.

2. New seoTitle frontmatter field is unprecedented and only applied to 9/59 pages
Files like cli.mdx, errors.mdx, limits.mdx, request-handler.mdx, types.mdx, general/skill.mdx, clients/react.mdx, clients/swift.mdx, and sqlite.mdx introduce a seoTitle frontmatter key that does not appear to have existed before in this repos docs schema (see .claude/reference/content-frontmatter.md). Two concerns: if the website repos content schema is strict about frontmatter fields, this could fail validation or silently get dropped during docs-sync, wasting the intended SEO benefit; and applying it to only a subset of pages is inconsistent, worth clarifying whether this is intentional (targeted fixes from the audit) or should be rolled out more broadly for consistency.

3. Repointed image asset paths may reference objects that do not exist yet
general/endpoints.mdx (and likely general/runtime-modes.mdx) change R2 asset keys from website/actors/docs/... to website/docs/.... Per CLAUDE.md, docs media lives in the rivet-assets R2 bucket outside of git, so this diff alone does not confirm the objects were copied/re-uploaded to the new key. Please confirm the R2 objects exist at the new paths before merging, otherwise these images will render broken.

Other notes
Since this is a pure content/metadata change, standard code-quality/test-coverage/security concerns do not really apply here, no test coverage gap and no security surface touched. Per .claude/reference/docs-sync.md, worth double-checking whether any of the touched pages also need updates to website/src/sitemap/mod.ts (e.g., if URLs changed due to the deletions above).

Nice cleanup overall, flagging the above mainly to make sure the redirect and asset-path items do not slip through as silent 404s/broken images post-merge.

@NicholasKissel
NicholasKissel merged commit d3e0750 into main Aug 26, 2026
11 of 12 checks passed
@NicholasKissel
NicholasKissel deleted the codex/seo-upstream-docs branch August 26, 2026 07:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant