Skip to content

feat(seo): show the crawler body in a browser with ?ssr - #1827

Open
perber wants to merge 1 commit into
mainfrom
feat/seo-ssr-preview-param
Open

perber wants to merge 1 commit into
mainfrom
feat/seo-ssr-preview-param

Conversation

@perber

@perber perber commented Nov 17, 2026

Copy link
Copy Markdown
Owner

Related issue

Part of #1292

What changed

Add ?ssr to a page URL of a public wiki (e.g. /docs/setup?ssr=1) to see in the browser the HTML that search-engine crawlers get. Any value works, including ?ssr= and a bare ?ssr.

  • Backend (internal/wiki/seo): with the ssr query parameter, the crawler-body contributor puts the server-rendered page into #root for any user agent. Without the parameter, only crawler user agents get it. It sits behind the same PublicOnly gate and uses the same render cache and parallel-render cap. The body was already reachable before: any client could get it by sending a crawler user agent.
  • Frontend (src/lib/ssrPreview.ts, main.tsx): with ?ssr, the SPA does not mount while #root holds an element, so the server's markup stays on screen. Without a server body (private wiki, unknown page, SPA route, permalink) the SPA mounts as usual, so the parameter never leaves a blank page.
  • /?ssr still redirects to the first page, without the parameter. Links inside the preview carry no ?ssr, so following one opens the normal SPA.
  • Docs: ADR-0018 has a new "Later changes" entry, and the source map is updated.

How I tested it

  • Go: unit tests for the use case (Preview gives any user agent the body, and returns nothing where crawlers get nothing) and for the contributor (parameter variants, unknown page, public access off), plus an integration test on the real router under --base-path /wiki.
  • Vitest: isSSRPreview with parameter variants, an empty #root, and the bare {{__BODY__}} placeholder the Vite dev server serves.
  • E2E (seo-crawler-body.spec.ts): with ?ssr the server article stays and the browser makes no /api/ request, which shows the SPA never mounted. On an unknown page, ?ssr lets the SPA mount normally. Negative check: with the mount guard disabled, the spec fails.
  • Local checks: make lint, make verify, make cross, the Go tests for internal/wiki and seo, the full Vitest suite, UI lint and UI build all pass. I ran the e2e spec against a locally built binary and it passed.
  • Reviews: independent architecture, code and security reviews found no blockers. Their findings are worked into this PR.

Checklist

  • I discussed the approach on the linked issue before starting (or this is a trivial fix: typo, docs, obvious one-liner)
  • This PR is focused on a single change
  • New behaviour plugs into an extension point; no new if feature branches in shared code (rule 1)
  • I updated documentation if needed
  • If users or admins will notice a change in behaviour, the commit carries a Behavior-Change: trailer (commit style). Not needed here: the parameter is opt-in and nothing existing changes.
  • For UI changes: behaviour is covered by automated tests where possible (rule 11)
  • For UI changes: I checked by hand what tests can't cover (look in light/dark mode, mobile width where relevant)
  • AI tools were used for this PR (name them: Claude Code). I have reviewed and understand every line

🤖 Generated with Claude Code

A shell request with the ssr query parameter (any value) gets the body
search-engine crawlers get, whatever its user agent, and the SPA does not
mount while #root holds the server's markup, so site owners can check
what crawlers see. Without a body (private wiki, unknown page, SPA route)
the SPA mounts as usual. Same public-access gate, render cache and
parallel-render cap as for crawlers (#1292).
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