@lupinum/ginko-docs 0.4.0-rc.9 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,78 @@
+# @lupinum/ginko-docs
+
+## 0.4.0
+
+### Minor Changes
+
+- [`ea2ea13`](https://github.com/lupinum-dev/ginko/commit/ea2ea133997f2011ad0d43f77a0f1dc75605923e) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Add Ginko 0.4, the first release: one content system for Nuxt websites, from Markdown files in Git to a hosted platform.
+  
+  Owners, staff and AI agents edit the same content. All seven packages release together under one version. It starts at 0.4 because `@lupinum/ginko-content` and `@lupinum/ginko-docs` already published an older, unrelated line up to 0.3. Until 1.0, a minor version (0.4 → 0.5) may contain breaking changes; the changelog names each one and how to update.
+  
+  Requirements: Node 22.18+, 24 or 26, and Nuxt 4.6+ or Nuxt 5 (tested on its nightly until it is released). Start a site with `npm create ginko@latest my-site`; the documentation explains every step.
+  
+  **Public API**
+  
+  - `@lupinum/ginko`: `defineSite`, `single`, `collection`, `f`, `defineComponents`, `formatMoney`, `plainText`, `safeHref`, `startOfWeek` and the documented types. Imported, not auto-imported.
+  - `@lupinum/ginko/nuxt`: the module, the `useGinko*` composables (everything that needs a Nuxt app starts with `useGinko`), `<GinkoMarkdown>` and `<GinkoImage>`. `@lupinum/ginko/vue`: `<GinkoMarkdown>` for any Vue app. `@lupinum/ginko/search`: `loadIndex` and `search`.
+  - `@lupinum/ginko/internal` and `@lupinum/ginko/internal/search` are for Ginko's own packages and have no stability promise.
+  - The `ginko` CLI: `check [--offline]`, `release` and `export [folder]`, plus `--version`. Every command run prints one JSON line, `{ "ok": true, … }` or `{ "ok": false, "error": { code, message } }` (`--help` and `--version` print plain text), and ends with exit code 0 (ok), 1 (fix the code), 2 (usage), 3 (platform unreachable, retry) or 4 (key not allowed). CI deploys the site only when `release` prints `"deploy": true` (a superseded run exits 0 with `"deploy": false`). The CLI reads `GINKO_PLATFORM` (or `NUXT_PUBLIC_GINKO_PLATFORM`), `GINKO_KEY`, `GINKO_COMMIT` (or `GITHUB_SHA`), `GINKO_BRANCH` and `GINKO_REMOTE`; it does not read `.env` files. `ginko-i18n --json` uses the same output shape, error codes (`USAGE`, `INVALID`) and exit codes.
+  - Config names: `f.ref` (one entry) and `f.refs` (several); `visible: { mode: 'until', field, days?, deleteExpired? }`; prefill tokens `@today`, `@workWeek`, `@nextWorkWeek`; `firstDayOfWeek`, `linkCheck`, `untranslated`, `maxBytes`, `Migration.compute`, `retired` rule `{ drop: true }`. Options and defaults are typed per field, and an unknown top-level key fails the build.
+  - Markdown components: `embed`, `frame` (`none`, `card`, `border`, …), `background` (`none`, `muted`, `tint`), `appearance` (`quiet`, `tint`), `quiz-question{mode}`, `code-tree{file}`.
+  
+  **Content (`@lupinum/ginko`, `@lupinum/ginko-content`)**
+  
+  - One text format: Markdown (comark 0.7) everywhere, with field profiles that limit what a field may contain. Footnotes, emoji, alerts, Shiki code, task lists, route links (`$blog.my-post`), reusable snippets and heading anchors.
+  - Data files: YAML and JSON (one file, one entry) and CSV (one file, many entries), checked against the field schema; every error names the file and field, and the line for CSV rows and unreadable files. Entries with `draft: true` stay out of production builds.
+  - Query engine in the site, over the loaded bundle: `where`, `order`, `limit`, pagination with totals, field selection, `include` for references, previous/next and facet counts.
+  - References (`f.ref`, `f.refs`), navigation trees and breadcrumbs, and a URL for every entry in every language; two entries on one URL fail the build.
+  - Link check before any HTML exists: route links, anchors, snippets and redirected paths, in the build, the dev terminal, `ginko check` and the agent tools. On the platform a save, a new entry or a scheduled publish that adds a broken link is stopped, and History says why. External links are checked on request (`linkCheck.external`), at build and in `ginko check` (never in dev), with a 7-day cache.
+  - Images: WebP copies at 480, 960 and 1600 px, made at upload on the platform and at build for files. `<GinkoImage>` and Markdown images get `srcset` and `sizes`.
+  - Redirects from `redirectFrom` (301) and site rules in `redirects` (301 by default, `status` 302/307/308 per rule).
+  - SEO from the bundle, with no other module: title template, canonical, Open Graph with `og:url`, `<html lang>`, hreflang with `x-default`, sitemap with `lastmod`, images and alternates, robots.txt with `noindex` on preview hosts, JSON-LD. With `nuxt-og-image` (in every starter), every page gets a generated share card in the brand colour `seo.color`, with the site's logo and the page's image.
+  - Works with the Nuxt SEO modules (`@nuxtjs/seo` or single ones, in any order): Ginko leaves them sitemap, robots.txt and JSON-LD defaults and hands them its pages with hreflang, the site's address, name and languages, and `noindex` on preview hosts. `nuxt-ai-ready` stays off while Ginko serves `/llms.txt`. Requires `nuxt-og-image` 7.
+  - Search index built in plain JS at build time, one record per heading section, loaded lazily per language.
+  - Agent output: `/llms.txt`, `/llms-full.txt`, a `.md` twin for every entry page (collections with a `route`), and a Markdown 404 that suggests pages. The normal address always answers with HTML.
+  - Render modes: Git-only sites prerender everything; platform sites refresh changed pages after a publish; previews render with `noindex`.
+  - In dev, `nuxt dev` restarts when `ginko.config.ts` changes, and a brick that cannot reach the platform names itself and the fix.
+  - CLI `ginko`: `check` (schema, links and the share image, for every site; `--offline` without the platform) and `release` for CI, `export` for backups; `pnpm local:dev|import|pull` run only in the Ginko monorepo.
+  
+  **Languages (`@lupinum/ginko-i18n`)**
+  
+  - The only locale authority: routes, alternates, hreflang, messages with plurals, and formatters for dates, ranges, relative time, numbers, currency and lists, each in the site's time zone.
+  - Works on its own in any Nuxt 4.6+ or Nuxt 5 app, without the rest of Ginko.
+  
+  **Components and docs (`@lupinum/ginko-components`, `@lupinum/ginko-docs`)**
+  
+  - Content components with props defined as Ginko fields: callouts, tabs, code groups, steps, cards, accordion, figures, embeds (click to load), timeline, quiz and more. Each one can also be copied into an app with the shadcn-vue CLI, from a registry the docs build generates.
+  - Docs layer (`@lupinum/ginko-docs`; `npm create ginko@latest my-docs -- --preset docs` starts a site with it): navigation, section tabs, breadcrumbs, table of contents with scroll spy, previous/next, ⌘K search with heading results, blog with authors and RSS, changelog, copy page as Markdown, dark mode. A guide for switching from Nuxt Content and `@nuxtjs/i18n`. Math (KaTeX) and mermaid diagrams render and load only on pages that use them.
+  
+  **Platform and Studio (hosted by Lupinum)**
+  
+  The platform is a hosted service, not an npm package. A site connects to it with one setting; without it, the site reads its content from files.
+  
+  - Quick tasks for the jobs owners do most ("Heute geschlossen", "Preis ändern"), phone first, with the full form behind "Alles bearbeiten".
+  - Files library: All, Recent, Unused, Missing alt text, Duplicates and folders; icon and list views; "used in" with links; replace a file and keep its references; a used file cannot be removed by mistake. Alt text set in the library is the default for every use, per language.
+  - Approvals, off by default: a task or agent key can need a yes. Reviewers see the change, approve, approve for a time, or reject with a sentence; the author sees the reason. Releases publish several changes together.
+  - History with "show changes", "back to this version" and undo; drafts and scheduled publishing; trash with restore; translation status per language; "why is this not on the website?".
+  - Team and invitations with per-task rights, sign-in with an emailed code, AI agent keys with an MCP tool catalog derived from the operations, and weekly reminder mails.
+  - Long forms group their fields under headings or in tabs (`group` on a field, `layout: 'tabs'` on a brick); phones always show headings.
+  - A rich text editor (TipTap 3) that writes Markdown, where untouched text stays byte for byte. Headings, lists, task lists, quotes, code blocks, tables, images from the library, embeds, registry components with prop forms, slash and bubble menus, Markdown shortcuts and paste, source mode, find and replace (⌘F), a drag handle and Alt+↑/↓ to move blocks, character counter, a link card for pasted URLs, uploads with progress, and a formatting bar above the phone keyboard.
+  - Delete a site, with seven days to cancel, and delete your own account. The last owner of a site must hand it over or delete it first.
+  - Studio in German, English and Spanish (beta), light and dark.
+  
+  **Presets (`@lupinum/ginko-preset-gastro`, `create-ginko`)**
+  
+  - Gastro: opening hours with exceptions, seasons, holidays and new hours from a date; lunch week with planning ahead and an optional PDF; menu with prices from a date; notices that expire; events; JSON-LD for Restaurant, Menu, opening hours and Event; a printable lunch sheet.
+  - `create-ginko` starts a new site, plain or with `--preset gastro|docs`. Starters install with npm, pnpm 11 and bun, carry a `typecheck` script, a page description and share cards (`nuxt-og-image` with Takumi, Nuxt 4.6.1 or later; set `NUXT_APP_SECRET` where the site runs, `.env` has one), and create-ginko warns on an unsupported Node.
+  
+  **Not in 0.4**
+  
+  Real-time co-editing comes next. Also not included: an agency preset, the editor UI as a shadcn-vue registry, OAuth for agent connectors, and a Google Business sync.
+
+### Patch Changes
+
+- Updated dependencies [[`ea2ea13`](https://github.com/lupinum-dev/ginko/commit/ea2ea133997f2011ad0d43f77a0f1dc75605923e)]:
+  - @lupinum/ginko@0.4.0
+  - @lupinum/ginko-i18n@0.4.0
+  - @lupinum/ginko-content@0.4.0
+  - @lupinum/ginko-components@0.4.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024-present Lupinum OG and contributors
+Copyright (c) 2025-2026 Lupinum OG
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,86 +1,238 @@
-<p align="center">
-  <img src="https://raw.githubusercontent.com/lupinum-dev/ginko-docs/main/docs/public/favicon.svg" width="128" alt="Ginko Docs icon">
-</p>
+# @lupinum/ginko-docs
 
-<h1 align="center">@lupinum/ginko-docs</h1>
+A Nuxt layer for documentation sites on [`@lupinum/ginko`](https://github.com/lupinum-dev/ginko/tree/main/packages/ginko)
+and [`@lupinum/ginko-content`](https://github.com/lupinum-dev/ginko/tree/main/packages/ginko-content):
+a whole docs site with a start page, navigation, search, blog and changelog, or docs inside a site that already exists
+(see "Inside an existing site"). The Markdown components (callouts, tabs, steps, cards,
+code blocks and more) come from `@lupinum/ginko-components`. Math (`$x^2$`, `$$…$$`) renders with KaTeX and `mermaid` code fences as diagrams; both load only on pages that use them. Pages are Markdown files in `content/docs/`.
 
-<p align="center">Add a complete documentation experience to a Nuxt application through one reusable layer.</p>
+## Use
 
-<p align="center">
-  <a href="https://www.npmjs.com/package/@lupinum/ginko-docs"><img src="https://img.shields.io/npm/v/@lupinum/ginko-docs?color=00DC82" alt="npm version"></a>
-  <a href="https://github.com/lupinum-dev/ginko-docs/actions/workflows/ci.yml"><img src="https://github.com/lupinum-dev/ginko-docs/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
-  <a href="https://github.com/lupinum-dev/ginko-docs/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
-</p>
+```bash
+npm install @lupinum/ginko @lupinum/ginko-content @lupinum/ginko-i18n @lupinum/ginko-docs
+```
 
-> [!WARNING]
-> This package is stable in the 0.3 release line. Because it is pre-1.0, a later minor release can contain breaking changes.
+```ts
+// ginko.config.ts
+import { defineSite } from '@lupinum/ginko'
+import { components, docsCollection } from '@lupinum/ginko-docs/config'
+
+const locales = ['en', 'de'] as const
+
+export default defineSite({
+  site: 'my-docs',
+  name: 'My docs',
+  url: 'https://docs.example.com',
+  timeZone: 'Europe/Vienna',
+  locales,
+  currency: 'EUR',
+  pages: { home: { en: '/', de: '/de' } }, // the start page is the page `home`
+  components, // the Markdown components: ::callout, ::tabs, ::steps …
+  bricks: { docs: docsCollection({ locales }) },
+})
+```
 
-## Purpose
+`docsCollection`, `blogCollections`, `blogPages` and `changelogPages` take one options object. `locales` is the same list as
+in `defineSite` (the layer accepts any `readonly string[]`; `defineSite` itself needs the tuple, hence `as const`).
 
-Use this package when a Nuxt application needs documentation routes, navigation, search, localization, metadata, social images, feedback, and agent-readable content. The layer provides the interface while the consuming application keeps ownership of its content and identity.
+`components` is the registry of `@lupinum/ginko-components` (a dependency of the layer, re-exported here). With it, Ginko checks every component tag and prop in the
+pages; a site can add its own components next to it (see "Inside an existing site").
 
-## Requirements
+Limits of the layer:
 
-- Node.js 22.18, 24.11, or 26 and later maintenance releases
-- Nuxt 4.5.1 or later in the Nuxt 4 line
-- Vue 3.5.40 or later
-- Ginko Content 0.4 prerelease or later in the 0.4 line
+- It finds its content by brick key, so keep these names: `docs` (docsCollection), `home` (docsHome), `posts` and
+  `authors` (blogCollections), `changelog` (changelogCollection). Only `docs` is required. One site has one docs
+  collection.
+- The docs move with `base`; the blog is always at `/blog` and the changelog at `/changelog` (with the language
+  prefix in other languages, for example `/de/blog`).
 
-## Installation
+```ts
+// nuxt.config.ts
+import ginko from './ginko.config.ts'
 
-```bash
-pnpm add -D @lupinum/ginko-docs@0.4.0-rc.9 @lupinum/ginko-content@1.0.0-beta.5
+export default defineNuxtConfig({ extends: ['@lupinum/ginko-docs'], modules: ['@lupinum/ginko/nuxt'], ginko })
 ```
 
+## Configure
+
+Options go in the site's `app.config.ts`. All are optional. Internal paths in `nav`, `footer.links` and `banner.href`
+follow the reader's language (`/guide` becomes `/de/guide`); absolute URLs stay as written.
+
 ```ts
-export default defineNuxtConfig({
-  extends: ["@lupinum/ginko-docs"],
-  site: { url: "https://docs.example.com" },
-  i18n: { baseUrl: "https://docs.example.com" },
-});
+export default defineAppConfig({
+  docs: {
+    title: 'My docs',                                   // header text, next to the logo (default: `name` from ginko.config.ts)
+    logo: { light: '/logo.svg', dark: '/logo-dark.svg' }, // `wordmark: true` when the image holds the name
+    theme: 'green',                                     // colour preset: 'default' (emerald on zinc) or 'green' (green on slate)
+    nav: [{ id: 'guide', href: '/guide' }],             // header links after Docs, Blog, Changelog
+    social: [{ icon: 'docs:github', href: 'https://github.com/me/docs', label: 'GitHub' }],
+    banner: { id: 'v2', href: '/docs/changes' },        // dismissible notice above the header; `href` optional
+    repository: { url: 'https://github.com/me/docs', branch: 'main' }, // "Edit this page" and "Report an issue"
+    markdownActions: { copy: true, openIn: ['chatgpt', 'claude'] },     // "Copy page" and the chats of its menu (the defaults)
+    footer: {
+      links: [{ id: 'github', href: 'https://github.com/me/docs' }],
+      attribution: true,                                // "Built with Ginko", default true
+    },
+  },
+})
 ```
 
-## Quick start
+Texts are not part of the config, they come from the site's own messages (`i18n/<code>.json`), so every
+language has its own:
 
-```ts
-import { defineGinkoDocsConfig } from "@lupinum/ginko-docs/content";
+```json
+{ "docs": { "banner": { "v2": "Version 2 is out." }, "nav": { "guide": "Guide" }, "footer": { "github": "GitHub" } } }
+```
 
-export default defineGinkoDocsConfig({
-  site: {
-    name: "Example Docs",
-    description: "Documentation for Example.",
-    whenToUse: "Use this site to learn and operate Example.",
-  },
-  locales: ["en"],
-  blog: false,
-});
+- `docs` is a reserved message namespace: keep your own messages out of it. Only `docs.nav.<id>`, `docs.footer.<id>` and `docs.banner.<id>` are yours to set; the other `docs.*` keys are the layer's own texts.
+- `banner.id` picks the message `docs.banner.<id>`. A reader who closes the banner does not see it again (it is remembered in `localStorage`, and the page gets `data-docs-banner-off` on `<html>`); a new `id` shows it to everyone.
+- Each `nav` and footer link `id` picks the message `docs.nav.<id>` or `docs.footer.<id>`.
+- `social` icons are any Iconify name. Built in: `docs:github`, `docs:discord`, `docs:x`, `docs:bluesky`, `docs:mastodon`, `docs:linkedin`, `docs:youtube`.
+- `repository` adds "Edit this page" to every page that comes from a file (`<url>/edit/<branch>/<source>`; `branch` defaults to `main`)
+  and, for GitHub, "Report an issue". `editUrl` (`{url}`, `{branch}`, `{source}`) and `issueUrl` (`{url}`, `{title}`, `{page}`) are templates for other hosts. Pages stored on the Ginko platform (not in files) link to
+  their form in the Studio instead, at the site's platform address.
+- Every page shows "Last updated" from the entry's `updatedAt`, and its JSON-LD is a `TechArticle` with `dateModified`.
+- "Copy page" copies the page as Markdown; its menu opens the `.md` twin, or ChatGPT or Claude with a prompt that points at it.
+- The layer also serves a read-only [MCP](https://modelcontextprotocol.io) endpoint at `POST /__ginko/docs-mcp` (Streamable HTTP, JSON-RPC)
+  with the tools `search_docs(query, locale?)` and `read_doc(path)`. No auth, no rate limit: it only exposes what the public site shows.
+
+### Pages
+
+Each docs page's frontmatter can set, besides `title` and `description`:
+
+| Field | Effect |
+| --- | --- |
+| `section` | Starts a group in the side navigation with this heading; the pages after it belong to it until the next `section`. |
+| `tab` | Starts a tab above the side navigation (for example "Guide" and "Reference"); pages follow the tab before them. |
+| `parent` | Nests the page under another one (`parent: docs/<name>`: the entry id, the file name without number, locale and extension). |
+| `icon` | An Iconify name, e.g. `lucide:rocket`, before the title in the navigation. Main locale only. |
+| `badge` | A short label after the title, e.g. "New". |
+
+Icons come from `@nuxt/icon` with the `lucide` set installed. Any other Iconify set works once the site installs it
+(`pnpm add -D @iconify-json/<set>`). Icons are bundled at build time; no icon API is called.
+
+### Start page (optional)
+
+`docsHome()` adds a `home` brick: one file `content/home.md` (and `home.<locale>.md`). Its frontmatter fills the hero
+and the feature grid, the text below it follows them:
+
+```md
+---
+title: Docs for my library.
+description: One sentence on what it does.
+install: npm install my-library
+links:
+  - { label: Get started, href: /docs/introduction }
+  - { label: GitHub, href: https://github.com/me/lib }
+features:
+  - { icon: lucide:zap, title: Fast, description: Why it is fast., href: /docs/speed }
+---
 ```
 
-Put Markdown files in `content/docs`. Open `/docs` after the Nuxt server starts.
+Add `home: docsHome()` to `bricks`. Without it, `/` leads to the first docs page. A site's own `pages/index.vue` wins.
 
-Generate the browser icon set from one square SVG or raster source:
+### Look and colours
 
-```bash
-pnpm exec ginko-docs-favicons --source public/product-icon.svg --out public
+The layer is plain CSS. Colours, radius and fonts are shadcn-style tokens, the same ones
+`@lupinum/ginko-components` reads: `--background`, `--foreground`, `--muted`, `--muted-foreground`, `--accent`,
+`--border`, `--primary`, `--primary-foreground`, `--card`, `--popover`, `--ring`, `--radius`, `--font-sans`,
+`--font-mono`. The layer's defaults have zero specificity, so any value the site sets wins:
+
+```css
+/* assets/site.css */
+:root {
+  --primary: light-dark(#2f6f4f, #7cc59d);
+  --primary-foreground: light-dark(#fff, #0c1f15);
+  --font-sans: 'Inter', system-ui, sans-serif;
+}
 ```
 
-The command writes `favicon.svg`, `favicon-96x96.png`, `apple-touch-icon.png`, and `favicon.ico`. Ginko Docs adds the matching head links and uses the generated 96px PNG in Nuxt-preset social images so every supported source format renders consistently.
+The defaults are `light-dark(light, dark)` pairs. The header switch stores the reader's choice in `localStorage`
+(key `docs-color-mode`) and sets `data-theme="light|dark"` on `<html>`; a small inline script applies it before the first paint. A `.dark` class
+on `<html>` (for example from `@nuxtjs/color-mode`) works too. Layout sizes are tokens as well: `--docs-sidebar`,
+`--docs-toc`, `--docs-max`, `--docs-header`.
 
-## Exports
+## Inside an existing site
 
-- `@lupinum/ginko-docs` is the Nuxt layer entry.
-- `@lupinum/ginko-docs/content` exports `defineGinkoDocsConfig`.
-- `@lupinum/ginko-docs/app-config` exports application configuration types.
-- `@lupinum/ginko-docs/components` exports the public MDC component contract.
+The layer can add docs to a site that has its own design, pages and layout, for example a company site with docs
+under `/docs` or `/handbook`:
 
-## Documentation
+```ts
+// nuxt.config.ts of the existing site
+export default defineNuxtConfig({ extends: ['@lupinum/ginko-docs'], modules: ['@lupinum/ginko/nuxt'], ginko })
+```
+
+```ts
+// ginko.config.ts: the docs brick next to the site's own bricks, the Markdown components next to the site's own
+import { components, docsCollection } from '@lupinum/ginko-docs/config'
 
-Read the [Ginko Docs documentation](https://ginko-docs.lupinum.com) and the [root README](https://github.com/lupinum-dev/ginko-docs#readme).
+bricks: { docs: docsCollection({ locales, base: '/handbook' }), /* … */ },
+components: { ...components, /* the site's own components; same name wins */ },
+```
+
+- **Only the docs pages are added.** The layer registers its pages from the bricks: the docs at the `base` of
+  `docsCollection` (default `/docs`), `/blog` (with its RSS feed) and `/changelog` only when those bricks exist, `/` only when the site
+  has no start page of its own. A page the site defines itself always wins.
+- **The site's frame stays.** The header, footer and page background are the layer's `layouts/default.vue`. When
+  the site has its own `layouts/default.vue`, that one is used and the docs (navigation, page, table of contents)
+  sit inside it. On phones the navigation opens from a bar above the page, so the docs need no header of their own.
+- **Nothing leaks.** Every rule is under a `docs-` class; the page background, font and `color-scheme` are only set
+  by the layer's own frame. The search, the language menu and the light/dark switch are components
+  (`<DocsSearch />`, `<DocsLanguage />`, `<DocsThemeToggle />`) the site can put into its own header; the switch sets
+  `data-theme` on `<html>`, so it fits a site that themes with that attribute. `<DocsThemeToggle segmented />` is the
+  three-way Auto/Light/Dark switch (the phone menu uses it). These three are the public components. The other `Docs*`
+  components, the `useDocs*` composables and the files in `app/lib` are internal and can change in any release.
+- **Error page:** the layer's `error.vue` shows a not-found page inside the site's layout, with links home and to
+  the docs. A site with its own `error.vue` keeps it.
+- **Components:** the layer loads the Vue side of `@lupinum/ginko-components`. Pass the registry in the site's
+  `components` (see above): only then does Ginko check the tags and props in the pages. Without a registry, the
+  check accepts any tag, so a misspelled `::calout` goes through without an error.
+- **Title:** pages get the title `Page · Site name` from Ginko (`seo.titleTemplate` in `defineSite`). A
+  `titleTemplate` in `app.head` or from nuxt-seo-utils does not apply to them, so the name is never added twice.
+- **Styling:** map the site's design tokens to the token names above (leave out the ones the site already defines
+  under the same name, often `--font-sans` and `--font-mono`). Two layout tokens line the docs up with the site:
+  - `--docs-max`: the width of the site's content container, so the sidebar starts where the header's logo does.
+  - `--docs-top`: the space the sidebar and table of contents keep from the top of the window when they stick, and
+    the scroll offset of headings. With a sticky header, its height; with a header that scrolls away, a small gap.
+
+```css
+:root {
+  --background: var(--color-white);
+  --foreground: var(--color-ink);
+  --muted: var(--color-stone-100);
+  --muted-foreground: var(--color-stone-600);
+  --border: var(--color-stone-300);
+  --primary: var(--color-brand);
+  --radius: 0.75rem;
+  --docs-max: 82.5rem;
+  --docs-top: 4.5rem; /* sticky header 4.5rem high; 1.5rem for one that scrolls away */
+}
+```
+
+## Blog and changelog (optional)
+
+A site opts in by adding the collections to `ginko.config.ts`. The layer then adds the pages and the header links;
+a site without them gets neither.
+
+```ts
+import { blogCollections, blogPages, changelogCollection, changelogPages, docsCollection } from '@lupinum/ginko-docs/config'
+
+export default defineSite({
+  // ...
+  pages: { /* home */ blog: blogPages({ locales }), changelog: changelogPages({ locales }) },
+  bricks: { docs: docsCollection({ locales }), ...blogCollections({ locales }), changelog: changelogCollection() },
+})
+```
 
-## Support and security
+- `blogCollections({ locales })` returns `{ posts, authors }`. Both are file bricks, so the folders are `content/posts/` and `content/authors/` (the brick name is the folder name).
+- **Posts** (`content/posts/<n>.<name>[.<locale>].md`) have `title`, `description`, `date` (`YYYY-MM-DD`), `authors` (a list of author ids), `image`, `tags` and `slug`. They live at `/blog/<slug>` (`/<l>/blog/<slug>` in other languages), the list at `/blog`, newest first.
+- **Authors** (`content/authors/<name>[.<locale>].yml`) have `name`, `role`, `avatar` and `url`. A post names them by id: `authors: [authors/jane]`. Authors have no page.
+- A post page writes Article JSON-LD with the author names, `datePublished` from `date` and `dateModified` from the entry's `updatedAt`.
+- **RSS:** `/blog/rss.xml` and `/<l>/blog/rss.xml`, RSS 2.0 with title and description (not the full text) and absolute links. It reads the build-time file bundle, so it works for file blogs only. `nuxt generate` writes it: the blog page sends the feed path in the `x-nitro-prerender` header, because Nitro's crawler does not follow `.xml` links.
+- **Changelog:** `changelogCollection()` (options: `max`) is one collection with `version`, `date` and Markdown text per release (`content/changelog/v1-2-0.md`; no dots in the file name, a dot reads as a language). The page `/changelog` shows all releases newest first, each with an anchor (`#v1-2-0`). It is a collection, not a docs page, so the date orders it and it has its own link in the header.
 
-Use [GitHub issues](https://github.com/lupinum-dev/ginko-docs/issues) or the [Lupinum OSS Discord](https://discord.gg/RPH6SeA36N) for support. Report vulnerabilities through the [private security process](https://github.com/lupinum-dev/ginko-docs/security/policy).
+The Ginko docs themselves are built this way: [sites/docs](https://github.com/lupinum-dev/ginko/tree/main/sites/docs).
 
 ## License
 
-Released by [Lupinum OG](https://lupinum.com) under the [MIT License](https://github.com/lupinum-dev/ginko-docs/blob/main/LICENSE).
+MIT © Lupinum OG

package/app/app.config.ts

@@ -1,55 +1,42 @@
-import type { GinkoDocsAppConfig } from "../shared/types/app-config";
-export default {
-  ginkoDocs: {
-    theme: {
-      preset: "default",
-      neutral: "zinc",
-      primary: "neutral",
-      codeBlocks: "dark",
-    },
-    prose: {
-      appearance: "tint",
-    },
-    site: {
-      name: { en: "Ginko Docs", de: "Ginko Docs" },
-      description: {
-        en: "Documentation sites built with Nuxt and Ginko Content.",
-        de: "Dokumentations-Sites auf Basis von Nuxt und Ginko Content.",
-      },
-      url: "http://localhost:3000",
-      icon: "/favicon.svg",
-      logo: { light: "/logo.svg", dark: "/logo-dark.svg" },
-      docsSidebarSwitcher: "tabs",
-      lupinumAttribution: true,
-      legalLinks: [],
-    },
-    nav: { links: "auto", socialIcons: false },
-    banner: {
-      enabled: false,
-      id: "default",
-      showOnLanding: true,
-    },
-    social: {},
-    feedback: { enabled: false },
-    ogImage: { enabled: true, component: "GinkoDocs" },
-    markdownActions: { chatGpt: true, claude: true, mcp: true },
-    images: { zoom: true },
-    toc: { depth: 3 },
-    repository: undefined,
-    landing: {
-      title: {
-        en: "Publish structured documentation.",
-        de: "Veröffentliche strukturierte Dokumentation.",
-      },
-      description: {
-        en: "A Nuxt layer for searchable, localized documentation with stable routes and agent-readable output.",
-        de: "Ein Nuxt-Layer für durchsuchbare, lokalisierte Dokumentation mit stabilen Routen und agentenlesbarer Ausgabe.",
-      },
-      primary: {
-        label: { en: "Get started", de: "Erste Schritte" },
-        to: { en: "/docs", de: "/de/dokumentation" },
-      },
-      features: [],
-    },
-  } satisfies GinkoDocsAppConfig,
-};
+// The site sets its docs options in its own app.config.ts; every option is optional:
+//   export default defineAppConfig({ docs: { title: 'Ginko', logo: { light: '/logo.svg' }, social: [...] } })
+// Texts are not configured here but in the site's i18n messages (see the README).
+import type { DocsAssistant } from './lib/docsPage'
+
+export default defineAppConfig({ docs: {} })
+
+export interface DocsConfig {
+  /** Brand name in the header; the accessible name of the logo. Default: `name` from ginko.config.ts. */
+  title?: string
+  /** A logo before the title, or instead of it with `wordmark: true` (the image then carries the name).
+   *  `dark` is shown in dark mode (else `light` always). */
+  logo?: { light: string, dark?: string, wordmark?: boolean }
+  /** Colour preset: `default` (emerald on zinc) or `green` (green on slate). A site's own shadcn tokens win over either. */
+  theme?: 'default' | 'green'
+  /** More header links after Docs, Blog and Changelog. Texts: messages `docs.nav.<id>`. */
+  nav?: { id: string, href: string }[]
+  /** Icon links at the end of the header, e.g. `{ icon: 'docs:github', href, label: 'GitHub' }`. Built in:
+   *  `docs:github`, `docs:discord`, `docs:x`, `docs:bluesky`, `docs:mastodon`, `docs:linkedin`, `docs:youtube`. */
+  social?: { icon: string, href: string, label: string }[]
+  /** Dismissible banner above the header. Text: message `docs.banner.<id>`. A new id shows it again to everyone. */
+  banner?: { id: string, href?: string }
+  /** Git host of the docs: "Edit this page" for pages from files, "Report an issue" for GitHub repositories. */
+  repository?: {
+    url: string
+    /** Default `main`. */
+    branch?: string
+    /** Edit link template; `{url}`, `{branch}` and `{source}` are replaced. Default `{url}/edit/{branch}/{source}`. */
+    editUrl?: string
+    /** Issue link template; `{url}`, `{title}` and `{page}` are replaced. Default on GitHub: a new issue with the page title. */
+    issueUrl?: string
+  }
+  /** "Copy page" (default true) and the chats the page menu can open it in (default both, `[]` for none). */
+  markdownActions?: { copy?: boolean, openIn?: DocsAssistant[] }
+  /** Footer. Link texts: messages `docs.footer.<id>`. `attribution` (default true) adds "Built with Ginko". */
+  footer?: { links?: { id: string, href: string }[], attribution?: boolean }
+}
+
+declare module '@nuxt/schema' {
+  interface AppConfigInput { docs?: DocsConfig }
+  interface AppConfig { docs: DocsConfig }
+}