@lupinum/ginko-docs 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # @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

package/README.md

@@ -15,7 +15,7 @@ npm install @lupinum/ginko @lupinum/ginko-content @lupinum/ginko-i18n @lupinum/g
 ```ts
 // ginko.config.ts
 import { defineSite } from '@lupinum/ginko'
-import { components, docsCollection } from '@lupinum/ginko-docs/config'
+import { components, docsCollection, homePages } from '@lupinum/ginko-docs/config'
 
 const locales = ['en', 'de'] as const
 
@@ -26,15 +26,22 @@ export default defineSite({
   timeZone: 'Europe/Vienna',
   locales,
   currency: 'EUR',
-  pages: { home: { en: '/', de: '/de' } }, // the start page is the page `home`
+  pages: { home: homePages({ locales }) }, // the start page is the page `home`
   components, // the Markdown components: ::callout, ::tabs, ::steps …
   bricks: { docs: docsCollection({ locales }) },
 })
 ```
 
-`docsCollection`, `blogCollections`, `blogPages` and `changelogPages` take one options object. `locales` is the same list as
+`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`).
 
+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").
+
 `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").
 
@@ -56,7 +63,10 @@ export default defineNuxtConfig({ extends: ['@lupinum/ginko-docs'], modules: ['@
 ## 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.
+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 defineAppConfig({
@@ -108,8 +118,26 @@ Each docs page's frontmatter can set, besides `title` and `description`:
 | `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.
+### 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)
 
@@ -129,6 +157,9 @@ features:
 ---
 ```
 
+`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
@@ -170,17 +201,24 @@ 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.
+- **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. On phones the navigation opens from a bar above the page, so the docs need no header of their own.
+  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 (the phone menu uses it). These three are the public components. The other `Docs*`
+  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.
@@ -190,10 +228,11 @@ components: { ...components, /* the site's own components; same name wins */ },
 - **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.
+  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 {
@@ -205,10 +244,65 @@ components: { ...components, /* the site's own components; same name wins */ },
   --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 */
+  --docs-gutter: 1.5rem;
+  --docs-top: 4.5rem; /* sticky header 4.5rem high; 0 for one that scrolls away */
 }
 ```
 
+Headings use the site's own heading styles; the layer sets no font on them.
+
+## Customize
+
+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 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.
+
+**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.
+
 ## 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;
@@ -229,6 +323,7 @@ export default defineSite({
 - **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.
 
 The Ginko docs themselves are built this way: [sites/docs](https://github.com/lupinum-dev/ginko/tree/main/sites/docs).

package/app/app.config.ts

@@ -32,6 +32,8 @@ export interface DocsConfig {
   }
   /** "Copy page" (default true) and the chats the page menu can open it in (default both, `[]` for none). */
   markdownActions?: { copy?: boolean, openIn?: DocsAssistant[] }
+  /** `false` leaves out the built-in search (header, sidebar, phone bar), for a site with <DocsSearch /> in its own header. */
+  search?: boolean
   /** Footer. Link texts: messages `docs.footer.<id>`. `attribution` (default true) adds "Built with Ginko". */
   footer?: { links?: { id: string, href: string }[], attribution?: boolean }
 }

package/app/assets/docs.css

@@ -26,7 +26,7 @@
   --input: light-dark(#d4d4d8, #52525b);
   --primary: light-dark(#047857, #34d399);
   --primary-foreground: light-dark(#ffffff, #09090b);
-  --ring: light-dark(#10b981, #34d399);
+  --ring: light-dark(#047857, #34d399);
   --success: light-dark(#157a39, #4ade80);
   --warning: light-dark(#985807, #fbbf24);
   --info: light-dark(#1d4ed8, #60a5fa);
@@ -43,6 +43,8 @@
   --docs-sidebar: 17rem;
   --docs-toc: 13.5rem;
   --docs-max: 90rem;
+  /* Space between the window edge and the docs: the site's container padding when the docs sit in its layout. */
+  --docs-gutter: 1rem;
   /* One page-title size for docs, blog, changelog and 404. */
   --docs-h1: clamp(1.75rem, 1.4rem + 1vw, 2.25rem);
   /* Height of the phone bar above the page; 0 where the bar is hidden. Anchors scroll below both. */
@@ -195,7 +197,7 @@
 /* ---------- Docs shell: sidebar, phone bar, content ---------- */
 
 /* The navigation sits on the page background; the page is a framed panel. */
-.docs-shell { display: grid; grid-template-columns: var(--docs-sidebar) minmax(0, 1fr); gap: 0.75rem; max-width: var(--docs-max); margin: 0 auto; padding: 0 1rem 1rem; }
+.docs-shell { display: grid; grid-template-columns: var(--docs-sidebar) minmax(0, 1fr); gap: 0.75rem; box-sizing: border-box; max-width: var(--docs-max); margin: 0 auto; padding: 0 var(--docs-gutter) 1rem; }
 .docs-sidebar { position: sticky; top: var(--docs-top); align-self: start; max-height: calc(100dvh - var(--docs-top)); overflow-y: auto; overscroll-behavior: contain; padding: 1rem 0.5rem 3rem 0.25rem; scrollbar-width: none; }
 .docs-content { min-width: 0; padding: 2rem 2.25rem 4.5rem 3.5rem; border: 1px solid var(--border); border-radius: var(--docs-r-panel); background: var(--card); }
 .docs-bar { display: none; }
@@ -239,8 +241,11 @@
 .docs-menu-links a:hover { background: color-mix(in oklab, var(--foreground) 9%, var(--muted)); }
 .docs-menu-links a[aria-current] { font-weight: 700; }
 .docs-menu-foot { display: flex; flex: none; align-items: center; justify-content: space-between; gap: 0.75rem; margin-top: auto; padding: 0.75rem 1rem 1.75rem; border-top: 1px solid var(--border); }
-.docs-menu-foot .docs-lang > button { height: 2.25rem; background: var(--muted); color: var(--foreground); }
-.docs-menu-foot .docs-lang .docs-popover { top: auto; right: auto; bottom: calc(100% + 0.375rem); left: 0; }
+/* The languages at the top of the phone menu: one link each, named in its own language. */
+.docs-lang-list { display: flex; flex: none; flex-wrap: wrap; gap: 0.5rem; padding: 0.75rem 1rem; border-bottom: 1px solid var(--border); }
+.docs-lang-list a { display: inline-flex; flex-direction: column; justify-content: center; min-height: 2.75rem; padding: 0.25rem 0.875rem; border-radius: var(--docs-r-control); background: var(--muted); color: var(--foreground); font-size: 0.9375rem; font-weight: 500; line-height: 1.25; text-decoration: none; }
+.docs-lang-list a[aria-current] { box-shadow: inset 0 0 0 1px var(--foreground); font-weight: 700; }
+.docs-lang-list small { display: block; color: var(--muted-foreground); font-size: 0.75rem; font-weight: 400; }
 .docs-segmented { display: inline-flex; gap: 4px; padding: 3px; border-radius: calc(var(--docs-r-control) + 2px); background: var(--muted); }
 .docs-segmented button { height: 1.875rem; padding: 0 0.75rem; border: 0; border-radius: var(--docs-r-control); background: none; color: var(--muted-foreground); font: 500 0.8125rem/1 var(--font-sans); cursor: pointer; }
 .docs-segmented button[aria-pressed='true'] { background: light-dark(var(--card), var(--muted)); color: var(--foreground); box-shadow: 0 1px 2px rgb(0 0 0 / 0.08); }
@@ -272,26 +277,30 @@
 .docs-page-foot { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 0.5rem 1.5rem; margin-top: 3.5rem; color: var(--muted-foreground); font-size: 0.8125rem; }
 .docs-page-foot a { display: inline-flex; align-items: center; gap: 0.375rem; color: var(--muted-foreground); text-decoration: none; }
 .docs-page-foot a:hover { color: var(--foreground); }
-.docs-pager { display: grid; grid-template-columns: 1fr 1fr; gap: 0.75rem; margin-top: 1rem; }
-.docs-pager a { display: flex; flex-direction: column; gap: 0.1875rem; padding: 0.875rem 1rem 0.9375rem; border: 1px solid var(--border); border-radius: var(--docs-r-box); color: var(--foreground); font-size: 0.9375rem; font-weight: 600; text-decoration: none; transition: border-color 0.15s, background-color 0.15s; }
+.docs-pager { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0.75rem; margin-top: 1rem; }
+.docs-pager a { display: flex; flex-direction: column; gap: 0.1875rem; padding: 0.875rem 1rem 0.9375rem; border: 1px solid var(--border); border-radius: var(--docs-r-box); color: var(--foreground); font-size: 0.9375rem; font-weight: 600; text-decoration: none; overflow-wrap: anywhere; hyphens: auto; transition: border-color 0.15s, background-color 0.15s; }
 .docs-pager a:hover { background: color-mix(in oklab, var(--muted) 60%, transparent); }
 .docs-pager small { display: inline-flex; align-items: center; gap: 0.375rem; color: var(--muted-foreground); font-size: 0.78125rem; font-weight: 500; }
 .docs-pager .is-next { grid-column: 2; align-items: flex-end; text-align: right; }
 
+/* Headings outside .docs-prose have no wrap rule of their own. `anywhere` (not break-word) because the blog head is a flex container and needs the smaller min-content. */
+:where(.docs-page-head, .docs-hero, .docs-blog, .docs-error) h1, .docs-posts h2, .docs-prose :is(h1, h2, h3, h4) { hyphens: auto; overflow-wrap: anywhere; }
+
 /* Table of contents: a rail on wide screens, a menu in the phone bar */
 .docs-toc { position: sticky; top: calc(var(--docs-top) + 2rem); align-self: start; max-height: calc(100dvh - var(--docs-top) - 4rem); overflow-y: auto; scrollbar-width: none; font-size: 0.8125rem; }
 .docs-toc-title { display: flex; align-items: center; gap: 0.5rem; margin: 0 0 0.625rem; color: var(--foreground); font-size: 0.78125rem; font-weight: 600; }
 .docs-toc-title .docs-icon { color: var(--muted-foreground); font-size: 0.875rem; }
 .docs-toc-list { margin: 0; padding: 0; list-style: none; border-left: 1px solid var(--border); }
-.docs-toc-list a { display: block; margin-left: -1px; padding: 0.3125rem 0 0.3125rem 0.875rem; border-left: 2px solid transparent; color: var(--muted-foreground); line-height: 1.4; text-decoration: none; transition: color 0.15s, border-color 0.15s; }
+.docs-toc-list a { display: block; margin-left: -1px; padding: 0.3125rem 0 0.3125rem 0.875rem; border-left: 2px solid transparent; color: var(--muted-foreground); line-height: 1.4; text-decoration: none; overflow-wrap: break-word; hyphens: auto; transition: color 0.15s, border-color 0.15s; }
 .docs-toc-list a.is-sub { padding-left: 1.625rem; }
 .docs-toc-list a:hover { color: var(--foreground); }
 .docs-toc-list a[aria-current] { border-left-color: var(--primary); color: var(--foreground); font-weight: 500; }
 .docs-toc-more { display: flex; flex-direction: column; gap: 0.125rem; margin-top: 1.125rem; padding-top: 0.875rem; border-top: 1px solid var(--border); }
 .docs-toc-more a, .docs-toc-more button { display: inline-flex; align-items: center; gap: 0.5rem; padding: 0.25rem 0; border: 0; background: none; color: var(--muted-foreground); font: inherit; text-decoration: none; cursor: pointer; }
 .docs-toc-more a:hover, .docs-toc-more button:hover { color: var(--foreground); }
-.docs-toc-menu { position: relative; }
-.docs-toc-menu > button { display: inline-flex; align-items: center; gap: 0.375rem; height: 2rem; padding: 0 0.5rem; border: 0; border-radius: calc(var(--radius) - 2px); background: none; color: var(--muted-foreground); font: 500 0.8125rem/1 var(--font-sans); cursor: pointer; }
+.docs-toc-menu { position: relative; min-width: 0; max-width: 100%; }
+.docs-toc-menu > button > span { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.docs-toc-menu > button { display: inline-flex; align-items: center; gap: 0.375rem; height: 2rem; padding: 0 0.5rem; border: 0; border-radius: calc(var(--radius) - 2px); background: none; color: var(--muted-foreground); font: 500 0.8125rem/1 var(--font-sans); cursor: pointer;  max-width: 100%;}
 .docs-toc-menu > button:hover { color: var(--foreground); }
 .docs-toc-menu > button[aria-expanded='true'] .docs-icon { transform: rotate(180deg); }
 .docs-toc-menu .docs-popover { right: 0; top: calc(100% + 0.25rem); width: min(20rem, calc(100vw - 2rem)); max-height: 60dvh; overflow-y: auto; padding: 0.75rem 0.75rem 0.75rem 0.5rem; }
@@ -328,12 +337,26 @@
 .docs-prose hr { margin: 2.5rem 0; border: 0; border-top: 1px solid var(--border); }
 .docs-prose blockquote { padding-left: 1rem; border-left: 2px solid var(--border); color: var(--muted-foreground); }
 .docs-prose img { max-width: 100%; height: auto; border-radius: var(--radius); }
-.docs-prose .docs-table { width: 100%; max-width: 100%; overflow-x: auto; border: 1px solid var(--border); border-radius: var(--docs-r-box); }
-.docs-prose table { border-collapse: separate; border-spacing: 0; margin: 0; font-size: 0.875rem; line-height: 1.5; font-variant-numeric: tabular-nums; }
+/* The edge shadows are the scroll cue: the "local" covers hide them at the ends, so a shadow shows only on a side with more to scroll to. */
+.docs-prose .docs-table {
+  width: 100%; max-width: 100%; overflow-x: auto; border: 1px solid var(--border); border-radius: var(--docs-r-box);
+  background:
+    linear-gradient(to right, var(--card), var(--card)) left center / 1.5rem 100% no-repeat local,
+    linear-gradient(to left, var(--card), var(--card)) right center / 1.5rem 100% no-repeat local,
+    linear-gradient(to right, color-mix(in oklab, var(--foreground) 14%, transparent), transparent) left center / 0.75rem 100% no-repeat scroll,
+    linear-gradient(to left, color-mix(in oklab, var(--foreground) 14%, transparent), transparent) right center / 0.75rem 100% no-repeat scroll;
+}
+/* At least as wide as its frame, so a short table's rows and header reach the frame's edge. */
+.docs-prose table { min-width: 100%; border-collapse: separate; border-spacing: 0; margin: 0; font-size: 0.875rem; line-height: 1.5; font-variant-numeric: tabular-nums; }
 .docs-prose :where(th, td) { padding: 0.6875rem 0.875rem; border-bottom: 1px solid var(--border); text-align: left; vertical-align: top; }
 .docs-prose tr:last-child > td { border-bottom: 0; }
 .docs-prose th { background: var(--sidebar); color: var(--muted-foreground); font-size: 0.78125rem; font-weight: 600; white-space: nowrap; }
-.docs-prose td code { white-space: nowrap; }
+.docs-prose td code { white-space: normal; overflow-wrap: normal; }
+.docs-prose td:first-child code { white-space: nowrap; }
+/* Only the last column of a table with 4+ columns needs room; in narrower tables it would force a scroll on phones. */
+.docs-prose table:has(th:nth-child(4)) td:last-child { min-width: 14rem; }
+/* Below 360 px a 3-column table squeezes its last column to a few letters; there it scrolls too. */
+@media (max-width: 22.5rem) { .docs-prose table:has(th:nth-child(3)) td:last-child { min-width: 10rem; } }
 
 /* Code blocks: one bordered panel with the file name or tabs on a lighter head (ginko-components draws an inset). */
 :where(.docs-prose, .docs-landing) :is(.ginko-code, .ginko-code-group, .ginko-code-tree):not([data-bare]) { padding: 0; overflow: hidden; border: 1px solid var(--docs-code-line); border-radius: var(--docs-r-box); }
@@ -403,7 +426,7 @@
 .docs-hero p { max-width: 40rem; margin: 1.5rem auto 0; color: var(--muted-foreground); font-size: 1.1875rem; line-height: 1.6; text-wrap: pretty; }
 .docs-hero-links { display: flex; flex-wrap: wrap; justify-content: center; gap: 0.625rem; margin-top: 2.25rem; }
 .docs-install { display: inline-flex; align-items: center; gap: 0.625rem; max-width: 100%; height: 2.625rem; margin-top: 1rem; padding: 0 0.3125rem 0 0.875rem; border: 1px solid var(--border); border-radius: var(--docs-r-control); background: var(--card); font: 500 0.84375rem/1 var(--font-mono); }
-.docs-install code { font: inherit; overflow-x: auto; white-space: nowrap; scrollbar-width: none; }
+.docs-install code { min-width: 0; font: inherit; overflow-x: auto; white-space: nowrap; scrollbar-width: none; }
 .docs-install code::before { content: '$ '; color: var(--muted-foreground); }
 .docs-features { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 2.75rem 3rem; margin: 6.5rem 0 0; padding: 0; list-style: none; }
 .docs-feature { position: relative; display: grid; align-content: start; gap: 0.5rem; padding-top: 1.375rem; border-top: 1px solid var(--border); }
@@ -512,7 +535,7 @@ html[data-docs-banner-off] .docs-banner { display: none; }
   .docs-sidebar { display: none; }
   .docs-content { padding: 0 1.5rem 4rem; border: 0; border-radius: 0; background: none; }
   .docs-bar { justify-content: flex-end; margin: 0 -1.5rem; padding: 0 0.75rem 0 1rem; border-block: 1px solid var(--border); border-radius: 0; background: color-mix(in oklab, var(--background) 92%, transparent); }
-  .docs-nav-links, .docs-header-end > :not(.docs-search-trigger, .docs-header-menu) { display: none; }
+  .docs-nav-links, .docs-header-end > :not(.docs-search-trigger, .docs-theme-toggle, .docs-header-menu) { display: none; }
   .docs-header-menu { display: inline-grid; }
   .docs-header-inner { padding: 0 0.5rem 0 1rem; }
   .docs-search-trigger { width: 2.25rem; padding: 0; justify-content: center; border-color: transparent; background: none; }
@@ -527,10 +550,14 @@ html[data-docs-banner-off] .docs-banner { display: none; }
   .docs-bar { margin: 0 -1rem; padding: 0 0.5rem; }
   .docs-page-head { grid-template-columns: minmax(0, 1fr); }
   .docs-page-head .docs-actions { grid-column: 1; grid-row: auto; margin-top: 0.75rem; }
-  .docs-pager { grid-template-columns: 1fr; }
+  .docs-pager { grid-template-columns: minmax(0, 1fr); }
   .docs-pager .is-next { grid-column: 1; }
   .docs-landing-inner { padding: 3rem 1rem 4rem; }
   .docs-features { margin-top: 3.5rem; }
+  .docs-landing-body { margin-top: 3.5rem; }
+  .docs-feature:has(.docs-feature-icon) { grid-template-columns: auto minmax(0, 1fr); column-gap: 0.75rem; align-items: center; }
+  .docs-feature-icon { margin-bottom: 0; }
+  .docs-feature > p { grid-column: 1 / -1; }
   .docs-blog-panel { padding: 1.5rem 1rem 3rem; border: 0; background: none; }
   .docs-posts { margin-inline: 0; }
   .docs-posts li { grid-template-columns: minmax(0, 1fr); gap: 0.5rem; padding-inline: 0; }
@@ -541,6 +568,38 @@ html[data-docs-banner-off] .docs-banner { display: none; }
 }
 
 /* Touch screens: small controls keep their look but get a 44px hit area. */
+/* ---------- Embedded: the docs inside a site's own layout (no html.docs-standalone) ----------
+   No framed panel: the page sits on the site's background, and the shell lines up with the site's container through
+   --docs-max and --docs-gutter. The search sits above the navigation; on phones the bar always shows, with the
+   navigation button and the search on the start side and the table of contents on the end side. */
+:root:not(.docs-standalone) .docs-shell { gap: 3rem; padding-bottom: 0; }
+:root:not(.docs-standalone) .docs-sidebar { padding: 2rem 0 3rem; }
+:root:not(.docs-standalone) .docs-content { padding: 2rem 0 4.5rem; border: 0; border-radius: 0; background: none; }
+.docs-sidebar-search { margin: 0 0 1.25rem; }
+.docs-sidebar-search .docs-search-trigger { width: 100%; }
+.docs-bar-start { display: none; }
+.docs-bar-nav { display: inline-flex; align-items: center; gap: 0.5rem; height: 2.75rem; padding: 0 0.5rem; border: 0; background: none; color: var(--foreground); font: 500 0.875rem/1 var(--font-sans); cursor: pointer; }
+.docs-bar-nav .docs-icon { font-size: 1.125rem; color: var(--muted-foreground); }
+.docs-nav-sheet { inset-block: 0; inset-inline: 0 auto; width: min(20rem, calc(100vw - 3rem)); max-width: none; height: 100dvh; max-height: none; margin: 0; padding: 0; border: 0; border-inline-end: 1px solid var(--border); background: var(--background); color: var(--foreground); font-family: var(--font-sans); animation: docs-menu-in 0.15s ease-out; }
+.docs-nav-sheet[open] { display: flex; flex-direction: column; }
+.docs-nav-sheet::backdrop { background: rgb(0 0 0 / 0.4); }
+.docs-nav-sheet-head { display: flex; flex: none; align-items: center; justify-content: space-between; height: 3.5rem; padding: 0 0.5rem 0 1rem; border-bottom: 1px solid var(--border); }
+.docs-nav-sheet-head p { margin: 0; font-weight: 600; }
+.docs-nav-sheet-body { flex: 1; min-height: 0; overflow-y: auto; overscroll-behavior: contain; padding: 0.75rem 0.5rem 2rem; }
+.docs-nav-sheet-body .docs-nav-item > a { min-height: 2.75rem; }
+@media (prefers-reduced-motion: reduce) { .docs-nav-sheet { animation: none; } }
+@media (max-width: 79.99rem) {
+  :root:not(.docs-standalone) .docs-content { padding-top: 0; }
+  :root:not(.docs-standalone) .docs-bar { margin: 0; padding: 0; border-radius: 0; background: color-mix(in oklab, var(--background) 92%, transparent); }
+}
+@media (max-width: 63.99rem) {
+  :root:not(.docs-standalone) .docs-shell { padding: 0 var(--docs-gutter); }
+  :root:not(.docs-standalone) .docs-content { padding: 0 0 4rem; }
+  /* No top border: the site's header above has one. */
+  :root:not(.docs-standalone) .docs-bar { display: flex; justify-content: space-between; margin: 0 calc(-1 * var(--docs-gutter)); padding: 0 max(0px, calc(var(--docs-gutter) - 0.5rem)); border-top: 0; }
+  .docs-bar-start { display: flex; align-items: center; gap: 0.25rem; }
+}
+
 @media (pointer: coarse) {
   :where(.docs-icon-button, .ginko-code-copy, .ginko-code-tab, .docs-toc-menu > button, .docs-example .ginko-tabs-tab) { position: relative; }
   :where(.docs-icon-button, .ginko-code-copy, .ginko-code-tab, .docs-toc-menu > button, .docs-example .ginko-tabs-tab)::after { content: ''; position: absolute; inset: -7px; }
@@ -552,4 +611,9 @@ html[data-docs-banner-off] .docs-banner { display: none; }
   .docs-blog { padding-inline: 0; }
   .docs-hero p { font-size: 1.0625rem; }
 }
+/* 320px: both hero buttons fill the row. */
+@media (max-width: 23.99rem) {
+  .docs-hero-links { flex-direction: column; }
+  .docs-hero-links > .docs-button { width: 100%; justify-content: center; }
+}
 .ginko-excerpt-source { font-family: var(--font-sans); }

package/app/components/DocsBanner.vue

@@ -24,6 +24,6 @@ function dismiss() {
       <NuxtLink v-if="href" :to="siteHref(href)">{{ text(`docs.banner.${id}`) }}</NuxtLink>
       <template v-else>{{ text(`docs.banner.${id}`) }}</template>
     </p>
-    <button type="button" class="docs-icon-button" :aria-label="t('docs.bannerClose')" @click="dismiss"><Icon name="lucide:x" class="docs-icon" /></button>
+    <button type="button" class="docs-icon-button" :aria-label="t('docs.bannerClose')" @click="dismiss"><DocsIcon name="lucide:x" class="docs-icon" /></button>
   </div>
 </template>

package/app/components/DocsExample.vue

@@ -36,7 +36,7 @@ onBeforeUnmount(() => clearTimeout(timer))
       </Tab>
     </Tabs>
     <button type="button" class="ginko-code-copy docs-example-copy" :aria-label="tc('code.copy')" @click="copy">
-      <Icon :name="copied ? 'lucide:check' : 'lucide:copy'" class="docs-icon" />
+      <DocsIcon :name="copied ? 'lucide:check' : 'lucide:copy'" class="docs-icon" />
       <span class="ginko-code-status" aria-live="polite">{{ copied ? tc('code.copied') : '' }}</span>
     </button>
   </div>

package/app/components/DocsHeader.vue

@@ -1,7 +1,8 @@
 <script setup lang="ts">
 // The standalone header: brand, the site's sections (Docs, Blog, Changelog and the site's own links), search,
-// language, light/dark and social links. On phones the menu button opens one full-screen menu: the docs
-// navigation (on docs pages), the site links and social link, the language and the light/dark switch.
+// language, light/dark and social links. On phones the menu button opens one full-screen menu: the
+// languages as links at its top, the docs navigation (on docs pages), the site links and social links, and the
+// Auto/Light/Dark switch. The light/dark button stays in the header on phones too.
 const { t, localePath } = useI18n()
 const cfg = useAppConfig().docs ?? {}
 const title = cfg.title ?? useGinkoSite().name
@@ -71,14 +72,14 @@ onBeforeUnmount(() => {
         <NuxtLink v-for="l in links" :key="l.key" :to="l.to" :aria-current="l.active ? 'page' : undefined">{{ l.label }}</NuxtLink>
       </nav>
       <div class="docs-header-end">
-        <DocsSearch />
+        <DocsSearch v-if="cfg.search !== false" />
         <DocsLanguage />
         <DocsThemeToggle />
         <template v-if="cfg.social?.length">
           <span class="docs-header-sep" aria-hidden="true" />
           <div class="docs-social">
             <a v-for="s in cfg.social" :key="s.href" class="docs-icon-button" :href="s.href" target="_blank" rel="noopener" :aria-label="s.label" :title="s.label">
-              <Icon :name="s.icon" class="docs-icon" />
+              <DocsIcon :name="s.icon" class="docs-icon" />
             </a>
           </div>
         </template>
@@ -86,13 +87,14 @@ onBeforeUnmount(() => {
           ref="button" type="button" class="docs-icon-button docs-header-menu" :aria-expanded="menu" aria-controls="docs-menu"
           :aria-label="menu ? t('docs.close') : t('docs.siteMenu')" @click="menu = !menu"
         >
-          <Icon :name="menu ? 'lucide:x' : 'lucide:menu'" class="docs-icon" />
+          <DocsIcon :name="menu ? 'lucide:x' : 'lucide:menu'" class="docs-icon" />
         </button>
       </div>
     </div>
     <!-- Teleported: the header's backdrop blur would otherwise make it the containing block of the fixed menu. -->
     <Teleport to="body">
       <div v-if="menu" id="docs-menu" ref="panel" class="docs-menu" role="dialog" tabindex="-1" :aria-label="t('docs.siteMenu')">
+        <DocsLanguage list />
         <div v-if="inDocs" class="docs-menu-scroll">
           <DocsSidebar />
         </div>
@@ -103,7 +105,6 @@ onBeforeUnmount(() => {
           </nav>
         </div>
         <div class="docs-menu-foot">
-          <DocsLanguage />
           <DocsThemeToggle segmented />
         </div>
       </div>

package/app/components/DocsIcon.vue

@@ -0,0 +1,12 @@
+<script setup lang="ts">
+// One icon from the build-time map (modules/icons.ts). A bare name is a Lucide icon; an unknown name renders nothing.
+import { computed } from 'vue'
+import icons from '#docs-icons'
+
+const props = defineProps<{ name: string }>()
+const icon = computed(() => icons[props.name.includes(':') ? props.name : `lucide:${props.name}`])
+</script>
+
+<template>
+  <svg v-if="icon" xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" :viewBox="icon[1]" aria-hidden="true" v-html="icon[0]" />
+</template>