docs(blog): document Notra post mapping, visibility rules, and troubleshooting

[tembo]

Summary

Follow-up documentation for the Notra-backed blog landed in #110. That PR added a high-level "Blog content (Notra)" section to apps/fumadocs/README.md covering the build-time fetch pipeline, the NOTRA_API_KEY env var, and the weekly refresh workflow — but the post-mapping/authoring contract, visibility rules, CSP requirement for post images, and troubleshooting were undocumented. This PR fills that gap by expanding the existing section (no new page), verified against source.

Docs added/updated

apps/fumadocs/README.md — extended the existing Blog content (Notra) section with four scannable subsections:

• How a Notra post is mapped — a field-by-field table for the BlogPost shape (slug always re-slugified + deduped, title required, description from first paragraph, dates from createdAt/updatedAt, read time at 200 wpm, derived OG image, tags always empty) plus the Markdown→sanitized-HTML rules (leading # Title stripped, allowlisted tags, external-link/image attributes, allowed URL schemes).
• Visibility rules — drafts skipped, future-dated posts hidden from the index but reachable by direct URL, empty-body and empty-list states.
• Post images and CSP — the img-src https://*.usenotra.com allowance in vercel.json and what to do if the image host changes.
• Troubleshooting — post not appearing, empty blog after a build (missing key keeps the last snapshot), regenerating locally with bun run posts:fetch, and CSP image failures.

Codepaths covered

• apps/fumadocs/scripts/notra-content.ts — mapNotraPost, slugify/dedupeSlug, excerptFromMarkdown, estimateReadTime, stripLeadingH1, renderMarkdownToSafeHtml (sanitize-html allowlist, link/image transforms).
• apps/fumadocs/scripts/fetch-notra-posts.ts — published-only fetch, snapshot fallback when NOTRA_API_KEY is unset, [notra] log line.
• apps/fumadocs/src/lib/blog.ts + blog-types.ts — BlogPost shape and the isBlogPostPublished / future-date filtering.
• apps/fumadocs/src/routes/blog/$slug.tsx & index.tsx — direct-URL reachability via includeFuture, empty-body and "No posts yet" states.
• vercel.json — Content-Security-Policy img-src allowance for Notra-hosted images.

Key knowledge gaps addressed

• That Notra slugs and tags are not used verbatim (re-slugified; tags dropped), and a leading H1 is stripped — the most likely authoring surprises.
• That a future createdAt hides a post from the index but leaves it shareable by URL.
• That a missing API key degrades gracefully to the last committed snapshot rather than failing the build.
• Where post-image hosts must be allowlisted (CSP) to avoid silent browser blocks.

Validation

Documentation-only change to a single Markdown file; no code, build, or test impact.

---

Documentation automation — triggered by the merge of #110.

Want tembo to make any changes? Add a comment with @tembo and i'll get back to work!

[tembo]

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

• apps/fumadocs/README.md

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
email-sdk-fumadocs	Ready	Preview, Comment	Jun 28, 2026 1:54am

[leoisadev1]

Closing: the still-accurate content here (field-mapping table, visibility rules, CSP note) was folded into #121 and re-verified against the current SSR architecture.