docs(fumadocs): document on-demand SSR blog architecture

[tembo]

Summary

PR #119 switched the blog from build-time prerendering to on-demand SSR, but apps/fumadocs/README.md still described the old "fully static, baked at build time" model. This updates the Blog content (Notra) section to match the shipped behavior, and folds in the still-accurate authoring reference from #112 and the turbo env detail from #118 so this PR supersedes both.

Docs updated

• apps/fumadocs/README.md → "Blog content (Notra)" — rewritten to document the new architecture:
  • A two-path table: on-demand SSR for /blog, /blog/$slug, and /og/blog/* (live fetch, edge-cached ~60s, no rebuild) vs. the build-time snapshot that now backs only sitemap.xml / rss.xml / feed.json.
  • A "How it works" breakdown of notra-runtime.ts, fetch-notra-posts.ts, notra-content.ts, and the vercel.json Build Output change.
  • Updated Environment note: NOTRA_API_KEY is now required at both build time and runtime (the deployed SSR function needs it).
  • Corrected the publishing cadence: new/updated posts go live within the cache window without a rebuild; rebuilds only refresh the feed snapshot.

Folded-in content (from #112 and #118, re-verified for SSR)

• Notra post → BlogPost field-mapping table (mapNotraPost in scripts/notra-content.ts): slug re-slugification + -2/-3 dedupe, title requirement, ~155-char excerpt fallback, createdAt-derived publishedAt, read-time heuristic, derived OG image/alt, empty tags.
• Sanitization/authoring contract: leading-H1 strip, sanitize-html allowlist, external-link target/rel, lazy images, allowed URL schemes — reframed as server-side for both paths (request time for blog pages, build time for the feed snapshot) instead of "baked at build time".
• Visibility rules, corrected for SSR: drafts never appear (both paths request status: "published" and mapNotraPost double-checks); future-dated posts now show on the SSR blog and are only held back from sitemap/RSS/feed (isBlogPostPublished in src/lib/blog.ts) — the old "hidden from index, reachable by direct URL" claim no longer matches the code and was not carried over. Empty-body and no-posts empty states documented.
• CSP image-host note: post-body images come from Notra's CDN; root vercel.json allows https://*.usenotra.com under img-src.
• Turbo passThroughEnv requirement (from docs(fumadocs): document NOTRA_API_KEY turbo passthrough and empty-blog troubleshooting #118): "passThroughEnv": ["NOTRA_API_KEY"] in apps/fumadocs/turbo.json is required for the build-time feed fetch (scripts/fetch-notra-posts.ts) to see the key — turbo's strict env mode strips undeclared variables. The deployed SSR function reads the Vercel env directly and is unaffected.

Codepaths covered

Verified against source — no behavior described that the code doesn't do:

• apps/fumadocs/src/lib/notra-runtime.ts — request-time server functions, dynamic SDK import, edge caching.
• apps/fumadocs/src/routes/blog/index.tsx, blog/$slug.tsx, og/blog/$.ts — load from the runtime fetch with Cache-Control headers.
• apps/fumadocs/scripts/notra-content.ts — mapping, slugging, excerpt, sanitize rules.
• apps/fumadocs/vite.config.ts — prerender.filter excludes blog routes.
• apps/fumadocs/scripts/fetch-notra-posts.ts + src/lib/blog.ts — snapshot now feeds sitemap/RSS/JSON only, with the date filter.
• apps/fumadocs/turbo.json — passThroughEnv: ["NOTRA_API_KEY"].
• Root vercel.json — full .vercel/output deploy and the img-src CSP entry.

Documentation-only change; no source files modified.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
email-sdk-fumadocs	Ready	Preview, Comment	Jul 6, 2026 3:24pm

[tembo]

Requesting review from @leoisadev1 who has experience with the following files modified in this PR:

• apps/fumadocs/README.md

[greptile-apps]

Greptile Summary

This PR updates the Fumadocs README to describe the current Notra blog architecture. The main changes are:

• Documents on-demand SSR for /blog, /blog/$slug, and /og/blog/*.
• Explains the build-time snapshot used by sitemap.xml, rss.xml, and feed.json.
• Adds the Notra post mapping, sanitization, visibility, CSP, and NOTRA_API_KEY environment details.
• Clarifies that OG images update without rebuilds but can stay cached for up to a day.

Confidence Score: 5/5

Documentation-only change that aligns the README with the existing Notra blog implementation.

Only apps/fumadocs/README.md is changed, and the documented behavior matches the described codepaths for SSR blog rendering, feed snapshots, environment handling, and caching.

T-Rex Logs

What T-Rex did

• The baseline Notra README was reviewed to confirm that posts are pulled at build time and baked into notra-posts.generated.ts, keeping the site fully static.
• The head Notra README was evaluated and confirms SSR is used, a snapshot table is present, Notra mapping/sanitization/visibility details are described, and CSP notes, environment requirements, Turbo dependencies, and publishing cadence are documented.
• The head checks were executed and reported a passing result with SUMMARY: 10 passed, 0 failed, exit code 0.

_{Ran code and verified through T-Rex}

_{Reviews (2): Last reviewed commit: "docs(fumadocs): correct OG image cache f..." | Re-trigger Greptile}

[tembo]

Greptile Summary

This PR updates the Fumadocs README to describe the Notra blog's on-demand SSR architecture. The main changes are:

• Documents live SSR fetching for /blog, /blog/$slug, and OG routes.
• Explains the build-time snapshot used by sitemap.xml, rss.xml, and feed.json.
• Adds details for Notra post mapping, sanitization, visibility rules, CSP, environment setup, and publishing cadence.

Confidence Score: 5/5

Documentation-only changes with a freshness mismatch in the described OG image behavior.

The changed file is limited to README content, and the issue is specific to one documented cache duration rather than application execution.

apps/fumadocs/README.md

T-Rex Logs

What T-Rex did

• Compared architecture docs before and after to confirm the after-state includes a head README with a two-rendering-path table and new source probes for prerender exclusion, SSR route loaders, runtime Notra server functions, snapshot generation, and snapshot-backed feed/sitemap consumers.
• Compared authoring rules before and after to confirm expanded authoring/visibility contracts, including lines 54-93, and PASS assertions for slug re-slugification, draft skipping, excerpt/fallback, dates, read time, OG metadata, tags, server-side sanitization, URL schemes, future-date feed filtering, and empty states.
• Validated that NOTRA_API_KEY is required at both build time and runtime, with matching config/code excerpts shown in the after-state to enforce deployment, environment, and CSP contracts.

_{Ran code and verified through T-Rex}

_{Reviews (1): Last reviewed commit: "docs(fumadocs): fold in Notra mapping, v..." | Re-trigger Greptile}

fixed the greptile freshness issue on pr #121.

the readme grouped /og/blog/* with the ssr blog pages and claimed ~60s freshness, but the og route sets cache-control: public, max-age=86400, stale-while-revalidate=604800 in src/routes/og/blog/$.ts — so a changed title or description can serve a stale svg for up to a day.

what changed in apps/fumadocs/README.md:

• split the rendering-path table into two ssr rows — blog pages (/blog, /blog/$slug, ~60s) vs og images (/og/blog/*, cached up to ~1 day) — with a note that both update without a rebuild but og freshness lags.
• added a "how it works" bullet for src/routes/og/blog/$.ts calling out its longer cache header.
• corrected the publishing-cadence section so it no longer implies og images refresh within ~60s.

verified the cache value against source before writing. documentation-only, pushed to the existing tembo/docs-blog-ssr-readme branch — no new branch or pr.

[tembo]

this one's already handled — it's the same og cache comment i fixed last turn.

greptile's review ran against commit b6776c1, but the correction landed one commit later in 9dedeb9 (already on tembo/docs-blog-ssr-readme). verified the readme now:

• splits /og/blog/* into its own ssr row noting it caches up to ~1 day (max-age=86400), separate from the ~60s blog pages.
• has a "how it works" bullet for src/routes/og/blog/$.ts spelling out the longer cache header.
• corrects the publishing-cadence section so it no longer implies og images refresh within ~60s.

no new changes needed. re-triggering greptile on the latest commit should clear the comment.