Open source CapCut alternative.
TypeScript
docs: the blog guide
David Le3c13aafdcea1
diff --git a/docs/README.md b/docs/README.mdindex a5bddb01..bbcb930a 100644--- a/docs/README.md+++ b/docs/README.md@@ -23,6 +23,7 @@ Supported product and engineering guides live in `docs/guides/`. This list is th- [Backend API Guide](guides/backend-apis.md) — the hosted routes the app and site call for model-backed work.- [Configuration and Experiments](guides/config-and-experiments.md) — the settings registry with its runtime override, and experiments with audiences, per-account overrides and computed verdicts.- [Frontend and Next.js Guidelines](guides/frontend-nextjs-guidelines.md) — route structure, server/client boundaries, styling, and data access in the site app.+- [The Blog](guides/blog.md) — the posts on donkeycut.com/blog: where a post lives, how it reaches the page through the cache, and the CMS on the super-user host.- [Backlit Icon](guides/backlit-icon.md) — the dark treatment that lights the donkey mark from behind: the layer stack, the tokens, and the rules that keep the mark clean.**Operations**diff --git a/docs/guides/blog.md b/docs/guides/blog.mdnew file mode 100644index 00000000..1f67d0f1--- /dev/null+++ b/docs/guides/blog.md@@ -0,0 +1,72 @@+# The Blog++donkeycut.com/blog is the site's writing surface for search: an index of posts,+one page per post, and a sitemap that lists them. The words and images of a+post live outside the repository. A post's row is in Postgres, its article is+an MDX file in the private bucket, its images sit beside that file, and the+Blog tab on the super-user host is where all of it is written.++**The one rule:** the repository holds the layout and the machinery; the+content lives in the database and the bucket. A post reaches the site through+the CMS and the cache.++## How a post reaches the page++```text+su Blog tab: write, upload, save, publish+ │+ ▼+row in Postgres · blog/<id>/article.mdx and blog/<id>/<sha>.avif in the bucket+ │ every write clears the `blog` tag and the post's own `blog:<slug>` tag+ ▼+/blog and /blog/<slug> read through `use cache` and compile the MDX inside it+ │+ ▼+the static shell serves; the article streams in from the cache+```++The public pages are ordinary Cache Components pages: the shell is static,+the reads are cached and tagged, and a save in the CMS expires the tags so the+next visitor gets the new page. Nothing renders per request. The MDX compile+happens inside the cache too, so a page costs one compile per publish.++## What a post is++A row carries what the index card and the search result need: the address, the+title, the meta description, an optional answer-first summary, tags, keywords,+the publish and revised dates, whether it is the featured post, and the header+and thumbnail images with the header's focus point. The search controls are+per post: a meta title that overrides the title, a canonical address that+overrides the page's own, and a switch that keeps the post out of results.++The article is markdown with three named blocks the page knows: a `Video` for+a YouTube, Vimeo or direct file address, and two calls to action. Images in the+article are plain markdown images pointing at the media host. A `## FAQs`+section with `###` questions becomes FAQ structured data on its own.++Publishing holds a post to a short contract: a title within the length a+result shows, a meta description in range, both images, a body, and no publish+date in the future. The editor shows the same checklist the route enforces.++## Images++Image bytes go straight to the bucket. The browser asks for a signed upload+address under the post, puts the bytes there, then names that key to the+encode route. The route reads it, encodes it to the size its role needs (the+header crop, the thumbnail crop, or a width-capped inline image) as AVIF,+writes it under its content hash, and deletes the upload. The media Worker+serves those hashed keys under `blog/` without a token and with an immutable+cache; the article source and the upload scratch keys stay private.++## Previewing a draft++Preview is Draft Mode. The editor's Preview button opens a route on the apex+host that turns Draft Mode on for that browser and lands on the post's real+address. With the cookie set, the blog's cached reads run fresh and include+drafts for that browser alone; every other visitor keeps the cache. A banner on+the previewed page leaves Draft Mode.++## Where to look++Server reads and the publish contract live in `site/src/lib/blog/`; the public+pages in `site/src/app/cut/blog/`; the CMS in `site/src/app/su/blog/`.diff --git a/docs/guides/frontend-nextjs-guidelines.md b/docs/guides/frontend-nextjs-guidelines.mdindex 98d723bb..ab488916 100644--- a/docs/guides/frontend-nextjs-guidelines.md+++ b/docs/guides/frontend-nextjs-guidelines.md@@ -35,6 +35,9 @@ fetches uncached has to sit behind its own `<Suspense>` boundary and streams inafter the shell. Data that rarely changes goes behind `use cache`, as close tothe read as you can put it.+The blog is the worked example of a public page built this way: cached, tagged+reads that the CMS expires on save (see [The Blog](blog.md)).+The old route segment configs are gone with it. `dynamic`, `revalidate`,`fetchCache`, and `runtime` fail the build; a handler that must run per requestawaits `connection()` from `next/server`, and a cache duration is `cacheLife`