templates.ContentSite/SPEC.md

Content Site (Blog / Docs) — product specification

This is the contract the project is built against. It is written for the agent that scaffolds the repository, but it doubles as the human-readable brief: every requirement below is meant to be implementable and verifiable.

Values in angle brackets (<Site name>, <content type>, <authoring>) come from the project-creation dialog and are recorded in the project record; replace them as you read. <content> is blog, documentation or marketing pages; <cms> is the authoring approach (Markdown/MDX, Contentful, Sanity or Notion).

1. Goal

A content site a real team could launch with: write structured entries in <cms>, have them rendered as <content> pages with navigation, tags, authors and search, and publish a fast, crawlable, shareable site. Content is stored against a typed content model and validated at build time, so a malformed entry fails the build instead of shipping a broken page. It must be runnable end-to-end on day one (even with seeded sample content), not a set of screens wired together later.

Non-goals (do not build unless the must-have list says otherwise): multi-tenant CMS, comments, subscriptions/paywalls, live collaborative editing, multi-language content.

2. Roles

Role	Can do
Reader	Anonymous. Browse the site, read entries, filter by tag/author, search, subscribe to the feed.
Author	Everything a reader can, plus create and edit their own entries (draft → in review).
Editor	Everything an author can, plus edit and review any entry, manage taxonomy and schedules, approve and publish.
Site admin	Everything an editor can, plus site configuration, navigation, roles, feeds and redirects.

Reading is anonymous and never gated. Authoring happens in <cms> (for Markdown / MDX, in the repository itself; for hosted CMSs, in that CMS UI) and only the publishing side is guarded by roles. Provide a seeded author and editor for local development when the authoring approach has a local backend.

3. Information architecture (routes)

Public site:

• / — home: hero/intro, latest or featured entries, section links.
• /:section — section index for one collection (e.g. /blog, /docs), with pagination.
• /:section/:slug — one entry: title, metadata (author, date, reading time), body, table of contents, related entries.
• /tags and /tags/:tag — tag archive; /authors/:author — author archive; both paginated.
• /search — search over titles, tags and body, with a no-results state.
• /404 — not-found page (and a real 404 status for unknown routes).
• Authoring preview where the chosen CMS provides one (draft preview URL for an unpublished entry); otherwise a local preview route.
• Generated artifacts: /sitemap.xml, /rss.xml or /atom.xml, /robots.txt, and Open Graph images (/og/:section/:slug.png or static equivalents).

When <content> is Documentation, the section index is the docs sidebar: entries are ordered and grouped, and one document shows the same sidebar with the current page highlighted.

Admin (guarded by the editor/admin roles, only where the authoring approach has a local backend; hosted CMSs keep this in the CMS UI):

• /admin — dashboard: draft/review queue and scheduled entries.
• /admin/entries — list, create, edit, preview and publish/unpublish entries.
• /admin/taxonomy — manage tags and authors.
• /admin/site — site config, navigation and redirects.

4. Data model

Minimum viable entities (add fields the requirements imply; keep them typed and validated):

• ContentEntry — slug, title, body (Markdown/MDX or a CMS reference), excerpt, type (reference to a ContentType), tags[], author (reference), status (draft | in_review | scheduled | published | archived), publishedAt, updatedAt, seo { title, description, canonicalUrl?, image?, noindex }.
• ContentType — id/key, title, and fields[] (name, label, type, required, default) that define the front-matter a <content> entry must carry; the schema entries are validated against.
• Author — id, slug, name, bio, avatar, links[].
• Tag — id, slug, name, description, parentId? (categories are tags with children).
• SiteConfig — site name, base URL, locale, defaultSeo, and navigation[] (label, href, order, children?) used for the header and the docs sidebar.
• Relationship — a typed edge between entries: parent/child for the docs sidebar tree, series for an ordered series, related for hand-picked links.

The content model is the source of truth: front-matter missing a required field, an unknown field, or a wrong type is a build error, with the offending file and field named. Document the model so an author can add an entry without reading the renderer.

5. Key flows

1. Author → publish. An author adds a Markdown/MDX file (or creates an entry in <cms>) with the required front-matter. A malformed entry fails validation with a clear message and the build stops; a valid draft entry renders in preview only. The author marks it ready, an editor reviews and publishes it, and it appears on the section index, the tag archive and the feed with publishedAt set.
2. Read. A reader lands on the home page, opens a section, reads an entry; the table of contents tracks the scroll position, related entries are listed below, and the document's canonical URL and Open Graph metadata are present in the HTML head.
3. Documentation navigation. A reader in the docs section sees the ordered sidebar, moves between sibling and child documents, and breadcrumbs show the path from the section root.
4. Search. A reader types a query on /search and gets ranked matches over current published entries (client-side over an index for small sites, or a hosted search service); an empty query shows recent entries and a no-results query shows a clear empty state.
5. Schedule. An editor sets a future publishedAt on an entry; it is scheduled, excluded from production builds and the feed, and a rebuild at/after that time publishes it.
6. Taxonomy and feeds. The editor renames a tag; the tag archive, the entry pages and the sitemap all reflect the change, and sitemap.xml and the feed stay valid.

6. Functional requirements

• Authoring: Markdown/MDX with front-matter, or entries authored in <cms>; code blocks render with syntax highlighting; images and links resolve; the chosen CMS's preview is wired in where it exists.
• Typed validation: entry front-matter is validated against its ContentType at build time; a required field missing, an unknown field or a wrong type fails the build with the file, field and expectation in the message.
• Rendering: table of contents generated from headings; reading time computed; breadcrumbs in the docs layout; related content from series/related edges (fallback: shared tags).
• Indexes: section, tag and author archives are paginated with a stable page size and their own metadata; pagination links are crawlable.
• Search: over titles, tags and body; client-side or hosted; no query sent to a third party without the configuration saying so.
• Feeds & discovery: rss.xml (or atom.xml) built from published entries newest-first; sitemap.xml covering every published route; robots.txt with the sitemap reference and non-production hosts disallowed.
• Metadata: every route has a unique title and description and an absolute canonical URL; Open Graph and Twitter card tags are emitted; JSON-LD (Article/BlogPosting, BreadcrumbList, WebSite) is present where it applies.
• Draft/scheduled exclusion: draft, in_review and scheduled entries are excluded from production builds, the sitemap and the feed; they are visible only in preview/local mode.
• Seed data: sample content (≥ 8 entries across ≥ 2 sections, ≥ 4 tags, ≥ 2 authors, one draft and one scheduled entry) so the site is presentable on first run.

7. Non-functional requirements

This is the SEO and performance template, so these are hard requirements, not polish.

• SEO: semantic HTML (one h1 per page, ordered headings), unique title/description per route, absolute canonical URLs, a valid sitemap and feed, correct hreflang/locale if used, and no indexable duplicate routes.
• Performance: static output where possible (pre-render every published route at build time); a Lighthouse budget of LCP < 2.5 s and CLS < 0.1 on an article page; images optimised with explicit width/height and lazy loading below the fold; no client JavaScript on non-interactive pages (article, archives, 404); route-level code splitting only where interactivity needs it.
• Accessibility (AA): correct landmarks (header/nav/main/footer), heading order, alt text on every meaningful image, labelled links and controls, visible focus, contrast at least AA, keyboard-operable search and navigation.
• Resilience: explicit loading, empty and error states; a missing entry renders the 404 page with a real 404 status, not an empty shell.
• Observability: build-time report of validation errors and skipped drafts; structured logs for publish/build events; a health or build-status check for the deployed site.
• Security: no secrets in the repository; CMS tokens stay server-side and are documented in .env.example; validate and cap CMS and search inputs.

8. Acceptance criteria (definition of done)

• Install, dev server, lint, typecheck, tests and production build all pass.
• A malformed front-matter entry (missing required field, unknown field or wrong type) fails the build with a message naming the file and field.
• sitemap.xml and rss.xml/atom.xml are generated, cover the published routes and validate against their schemas.
• Every route has a unique title, description and absolute canonical URL; Open Graph and JSON-LD are present.
• A static article page ships no client JavaScript and meets the LCP/CLS budget.
• Draft, in-review and scheduled entries never appear in the production build, sitemap or feed; preview still shows them.
• Search returns ranked results for published entries and has an explicit no-results state.
• Code highlighting, table of contents, reading time, related content and pagination work on seeded entries.
• Docs navigation (sidebar order, breadcrumbs, active highlight) works when <content> is documentation.
• Seeded sample content makes the site presentable immediately; .env.example documents every secret.
• README quickstart (install, run, build, env) is accurate; loading/empty/error states exist.
• Accessibility pass: landmarks, heading order, alt text, contrast AA, keyboard-operable search.
• CI runs install + lint + typecheck + tests + build.

9. Suggested build order

Follow this order and finish (and verify) a layer before starting the next:

1. Scaffold the chosen stack, install dependencies, get the dev server and the empty shell running, and commit the skeleton.
2. Content model + typed validation: the ContentType/field schema, front-matter parsing and the build-time validation that fails on a bad entry.
3. Layouts + navigation: base layout, section index, entry page, breadcrumbs, the docs sidebar and taxonomy pages, rendered from seeded entries.
4. SEO / feed / sitemap: metadata per route, canonical URLs, JSON-LD, sitemap.xml, rss.xml/atom.xml, robots.txt, Open Graph images, and draft/scheduled exclusion.
5. Search & related content: the search index or hosted search plus related/series links.
6. Authoring workflow: <cms> wiring and preview, roles, draft → review → publish, scheduling.
7. Quality / performance: tests for validation and rendering, static-output check, Lighthouse budget, accessibility pass, CI, README and .env.example.