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

package/CHANGELOG.md

@@ -0,0 +1,141 @@
+# @lupinum/ginko-docs
+
+## 0.5.0
+
+### Minor Changes
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Add public ways to customize the docs: `<DocsShell>` for a site's own pages in the docs frame, the override points `DocsPageEnd` and `DocsSidebarEnd`, and `docs: { search: false }`.
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Add a docs frame for sites that embed the docs in their own layout: no framed panel, the search above the navigation, a phone bar with the navigation as a sheet, and `--docs-gutter` to line the docs up with the site's container.
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Add `homePages({ locales })` to `@lupinum/ginko-docs/config`: the start page by locale, with the main locale at `/`.
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Change the docs layer to draw icons itself instead of with @nuxt/icon: pages outside the docs no longer download an icon library (about 16 KB gzip less on every page of a site that embeds the docs), and docs pages load only the icons they use. Icon names work as before (any installed Iconify set). The build finds them in your Markdown front matter and component attributes (not in prose or code blocks), in YAML and JSON content, in `app.config.ts` and in your own `app/` components (`<Icon name="lucide:x" />`); it reads all locales and ignores commented-out code. A name built at runtime (a variable) is not found, so write it once as a literal; a name that is not installed logs one build warning with its file. A site's own `@nuxt/icon` still wins over the layer's `Icon`. Remove the `icon` options from your nuxt.config if you set any. The icon hints in the editor now say "needs a global Icon component".
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Add route links outside Markdown: the start page's buttons and cards, `nav`, `footer.links` and `banner.href` take `$docs.<page>` and `$page.<key>`, which lead to the page in the reader's language.
+
+- [#24](https://github.com/lupinum-dev/ginko/pull/24) [`c28d1e3`](https://github.com/lupinum-dev/ginko/commit/c28d1e3e4ba1e558f8c71d7b69961f7474a221d1) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Add `source: 'platform'` to docsCollection, docsHome, blogCollections and changelogCollection, so docs content can be edited in Ginko Studio; the default stays `'files'`.
+
+### Patch Changes
+
+- [#21](https://github.com/lupinum-dev/ginko/pull/21) [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Add `breadcrumbJsonLd(steps, siteUrl)` to `@lupinum/ginko`: a JSON-LD BreadcrumbList from steps with `title` and `path`, such as the nodes of `useGinkoBreadcrumbs` (templates/_features/site/app/composables/usePageSeo.ts uses it).
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Fix the 404 page's main-language link ignoring the site's i18n strategy, and name the language in the reader's language
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Fix the focus ring of the default theme in light mode: emerald-700 instead of emerald-500, 5.5:1 against the page instead of 2.5:1.
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Fix layout shift on first load of a docs page: the standalone layout preloads Inter, so text no longer re-wraps when the font arrives.
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Add French texts to the docs layer.
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Fix the "not translated" note in the language menu: screen readers read it in the page's language. An empty changelog now says where to add releases.
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Fix English fallback text on translated docs pages being read in the page language, and add a link to the main-language page on a docs 404 under another language
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Add CollectionPage JSON-LD and a description to the changelog page, and CollectionPage JSON-LD to the blog list.
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Fix tables with three columns on phones narrower than 360 px: the last column keeps its width and the table scrolls, instead of showing a few letters per line.
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Fix docs tables, the home feature list and the install box on phones.
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Change the phone header and menu of the docs layer: the light/dark button stays in the header, and the menu lists the languages as links at its top, one tap each.
+
+- [#21](https://github.com/lupinum-dev/ginko/pull/21) [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Change the JSON-LD of a blog post from Article to BlogPosting, built by `postJsonLd` of `@lupinum/ginko/basics`, with the post's tags as keywords.
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Fix route links outside Markdown (nav, footer, banner, start page): they lead to the main-language page when the current language has no such doc, instead of a raw `$docs…` address.
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Fix the docs layer adding a second blog, blog feed or changelog at /blog and /changelog to a site that has its own: it now adds them only at the address of your posts and changelog and only when you have no page there.
+  
+  A changelog page needs `changelog: changelogPages({ locales })` in `pages` (or a `route` on the changelog brick); without an address the build warns once and the layer adds no changelog. The layer now decides after all of your pages are known, so a page that the page-paths module moves to `/blog` also counts as yours, and its links to the blog and changelog follow the addresses you configured.
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Fix short tables in the docs ending before the edge of their frame: the rows and the header now fill it.
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Add a note to the language menu for a language that has no version of the page: "Not translated: opens the start page".
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Fix wide tables, long titles and the previous and next links making docs pages scroll or squeeze text on phones
+
+- [#21](https://github.com/lupinum-dev/ginko/pull/21) [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Change Markdown refs in page state to carry no table of contents: read `toc` from the loaded text, `(await useGinkoMarkdown(() => entry.value.data.body)).value?.toc`.
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Add `releaseAnchor(version)` to `@lupinum/ginko/basics`: the anchor of a release on a changelog page (`4.6.0` → `v4-6-0`). The changelog page of `@lupinum/ginko-docs` and the changelog feature of the templates (templates/_features/changelog/app/composables/useChangelog.ts, server/middleware/changelog-feed.ts) use it, so both keep the same public addresses.
+- Updated dependencies [[`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7), [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7), [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7), [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7), [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7), [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7), [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7), [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7), [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7), [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7), [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`c28d1e3`](https://github.com/lupinum-dev/ginko/commit/c28d1e3e4ba1e558f8c71d7b69961f7474a221d1), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991), [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991)]:
+  - @lupinum/ginko@0.5.0
+  - @lupinum/ginko-components@0.5.0
+  - @lupinum/ginko-content@0.5.0
+  - @lupinum/ginko-i18n@0.5.0
+
+## 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,333 @@
-<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, homePages } from '@lupinum/ginko-docs/config'
 
-## Purpose
+const locales = ['en', 'de'] 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.
+export default defineSite({
+  site: 'my-docs',
+  name: 'My docs',
+  url: 'https://docs.example.com',
+  timeZone: 'Europe/Vienna',
+  locales,
+  currency: 'EUR',
+  pages: { home: homePages({ locales }) }, // the start page is the page `home`
+  components, // the Markdown components: ::callout, ::tabs, ::steps …
+  bricks: { docs: docsCollection({ locales }) },
+})
+```
 
-## Requirements
+`docsCollection`, `blogCollections`, `homePages`, `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`).
 
-- 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
+The bricks read Markdown files from `content/`. To edit them in Ginko Studio instead, pass `source: 'platform'` to
+`docsCollection`, `docsHome`, `blogCollections` or `changelogCollection` (each brick on its own; the default is
+`'files'`). The pages, their Markdown twins and `read_doc` work the same with either source, and a page from the
+platform links "Edit this page" to its form in the Studio. Two things are built from files only: the search index
+(the search box and `search_docs`) finds no page that lives on the platform, and an icon named only in Studio content
+is not bundled (name it once in a file the icon scan reads, see "Icons").
 
-## Installation
+`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").
 
-```bash
-pnpm add -D @lupinum/ginko-docs@0.4.0-rc.9 @lupinum/ginko-content@1.0.0-beta.5
+Limits of the layer:
+
+- 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`).
+
+```ts
+// nuxt.config.ts
+import ginko from './ginko.config.ts'
+
+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. A route link names the page
+instead of its address, as in Markdown: `$docs.<page>` (a docs page by its file name, such as `$docs.webhooks`, or its
+slug) and `$page.<key>` (a page of `pages` in `ginko.config.ts`, such as `$page.changelog`), with an optional `#anchor`.
+It leads to the page in the reader's language, also when a translation has another slug.
+
 ```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
+    },
+  },
+})
+```
+
+Texts are not part of the config, they come from the site's own messages (`i18n/<code>.json`), so every
+language has its own:
+
+```json
+{ "docs": { "banner": { "v2": "Version 2 is out." }, "nav": { "guide": "Guide" }, "footer": { "github": "GitHub" } } }
+```
+
+- `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
+
+The layer draws icons itself (no `@nuxt/icon`, no icon API call, no icon library in the browser). At build time it reads
+exactly the icons your site names from the installed `@iconify-json/<set>` packages (`lucide` is installed with the
+layer; add others with `pnpm add -D @iconify-json/<set>`) and bundles them in one small map that only docs pages load.
+
+The build scans, in all locales:
+
+- the front matter of your Markdown files, the attributes of Markdown components (`::card{icon="lucide:rocket"}`) and the
+  `---` block inside a component; prose and code blocks are not read;
+- YAML and JSON content files and `app.config.ts` (`icon:` values and `social`);
+- the layer's own components and your site's `app/**/*.vue` files (`<Icon name="lucide:x" />`, `icon="..."`, or a bound
+  literal `:name="'lucide:x'"`). Commented-out code is ignored; other `.ts` files than `app.config.ts` are not read.
+
+A name is `set:name`; a bare name such as `book-open` means Lucide. The `i-set-name` form is not supported. Names built at
+runtime (a variable, a template string) are not found; write the name once as a literal somewhere in the places above. A
+name the build cannot find logs one warning with its file and renders nothing.
+
+The layer registers a global `Icon` component that the Markdown components (card, tabs, callout) use. If your site installs
+`@nuxt/icon` itself, yours wins (the layer's has a lower priority).
+
+### 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 }
+---
+```
+
+`href` takes a path as written, an absolute URL, or a route link (`$docs.introduction`, `$page.changelog`) that follows
+the reader's language, so the translations (`home.<locale>.md`) can use the same links.
+
+Add `home: docsHome()` to `bricks`. Without it, `/` leads to the first docs page. A site's own `pages/index.vue` wins.
+
+### Look and colours
+
+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;
+}
 ```
 
-## Quick start
+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`.
+
+## Inside an existing site
+
+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`:
 
 ```ts
-import { defineGinkoDocsConfig } from "@lupinum/ginko-docs/content";
+// nuxt.config.ts of the existing site
+export default defineNuxtConfig({ extends: ['@lupinum/ginko-docs'], modules: ['@lupinum/ginko/nuxt'], ginko })
+```
 
-export default defineGinkoDocsConfig({
-  site: {
-    name: "Example Docs",
-    description: "Documentation for Example.",
-    whenToUse: "Use this site to learn and operate Example.",
-  },
-  locales: ["en"],
-  blog: false,
-});
+```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'
+
+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, after all pages of the site are
+  known: the docs at the `base` of `docsCollection` (default `/docs`), the blog (with its RSS feed) at the route of
+  the `posts` brick and the changelog at the route of the `changelog` brick (or `pages.changelog`), and `/` only when
+  the site has no start page of its own. A page the site defines itself at one of these addresses always wins, also
+  when the page-paths module gives it that address (a page file `news.vue` that answers at `/blog`). Then the layer
+  adds no page and no feed there, and its header and post links point to the site's page.
+- **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, without the layer's framed panel, on the site's background. The search sits above the navigation.
+  On phones a bar under the site's header holds a "Contents" button (the navigation as a sheet), the search and the
+  "On this page" menu, 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 and `<DocsLanguage list />` the languages as a row of links (the phone menu uses
+  both). A language without a version of the page says so ("Not translated: opens the start page"). These three,
+  `<DocsShell>` and the override points under [Customize](#customize) 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`). Three layout tokens line the docs up with the site:
+  - `--docs-max` and `--docs-gutter`: the width and the side padding of the site's content container, so the search
+    and the navigation start where the header's logo does.
+  - `--docs-top`: the space the sidebar, the phone bar and the 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 one that scrolls away, 0.
+
+```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-gutter: 1.5rem;
+  --docs-top: 4.5rem; /* sticky header 4.5rem high; 0 for one that scrolls away */
+}
 ```
 
-Put Markdown files in `content/docs`. Open `/docs` after the Nuxt server starts.
+Headings use the site's own heading styles; the layer sets no font on them.
 
-Generate the browser icon set from one square SVG or raster source:
+## Customize
 
-```bash
-pnpm exec ginko-docs-favicons --source public/product-icon.svg --out public
+Everything here is public and stays stable between releases.
+
+**Tokens.** The colour tokens are listed under [Look and colours](#look-and-colours). The layout tokens:
+
+| Token | Default | What it sets |
+| --- | --- | --- |
+| `--docs-max` | `90rem` | Width of the docs, gutters included |
+| `--docs-gutter` | `1rem` | Space between the window edge and the docs |
+| `--docs-top` | `0px` (standalone: the header) | Height of what sticks above the docs |
+| `--docs-sidebar` | `17rem` | Width of the navigation |
+| `--docs-toc` | `13.5rem` | Width of "On this page" beside the text (from 80rem window width) |
+| `--docs-measure` | `38rem` | Reading width of running text |
+| `--docs-h1` | `clamp(1.75rem, …, 2.25rem)` | Size of page titles |
+| `--docs-header` | `4rem` | Height of the standalone header |
+
+**Override points.** The layer ships empty components that a site replaces with its own file of the same name in
+`app/components/`:
+
+- `DocsPageEnd` (prop `doc`, the page's entry): after the text of every page, before "Edit this page" and the pager.
+  For a support box or a call to action.
+- `DocsSidebarEnd`: below the navigation, in the sidebar and in the phone menu. For a few links or a contact line.
+
+**Own pages in the docs frame.** `<DocsShell>` is the docs body (navigation, search, the phone bar) with a default slot
+for the page and a `bar` slot for controls in the phone bar. A help center's start page, for example:
+
+```vue
+<!-- app/pages/help/index.vue; the docs live at /help (docsCollection({ locales, base: '/help' })) -->
+<script setup lang="ts">
+const docs = useGinko('docs')
+</script>
+
+<template>
+  <DocsShell>
+    <h1>How can we help?</h1>
+    <ul>
+      <li v-for="item in docs.items" :key="item.id"><NuxtLink :to="item.url">{{ item.data.title }}</NuxtLink></li>
+    </ul>
+  </DocsShell>
+</template>
 ```
 
-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 layer then adds no page of its own at that address.
+
+**Search.** `docs: { search: false }` in app.config leaves out the built-in search (header, sidebar and phone bar), for
+a site that puts `<DocsSearch />` into its own header.
 
-## Exports
+**Texts.** Every text of the layer is a `docs.*` message, and the site's own i18n wins per key. A help center, for
+example, words the search for itself in `i18n/en.json`: `{ "docs": { "searchPlaceholder": "Search help…" } }`. The
+layer brings English, German and French.
 
-- `@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.
+## Blog and changelog (optional)
 
-## Documentation
+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.
 
-Read the [Ginko Docs documentation](https://ginko-docs.lupinum.com) and the [root README](https://github.com/lupinum-dev/ginko-docs#readme).
+```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.
+- **Addresses:** the blog list is the parent of the `posts` route (`/blog/[slug]` gives `/blog`; `blogCollections` uses `/blog`). The changelog page is at the route of the `changelog` brick, else at `pages.changelog` (`changelogPages({ locales })`, `/changelog`). A changelog brick with neither gets no page, and the build warns once. A site that has its own page at an address keeps it; the layer then adds nothing there.
+- **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