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

package/app/components/DocsSearch.vue

@@ -0,0 +1,136 @@
+<script setup lang="ts">
+// Search over /__ginko/search/<locale>.json (built at build time), loaded when the dialog first opens.
+// Hits are grouped by page: the page itself first, then its sections. Arrow keys move, Enter opens.
+import type { SearchHit, SearchIndex, SearchIndexJson } from '@lupinum/ginko/search'
+
+// `shortcut` (default true): `/` and Ctrl/⌘ K open this search. A second trigger on the same page sets it to false.
+const { shortcut = true } = defineProps<{ shortcut?: boolean }>()
+const { t, locale } = useI18n()
+const dialog = useTemplateRef<HTMLDialogElement>('dialog')
+const input = useTemplateRef<HTMLInputElement>('input')
+const query = ref('')
+const active = ref(0)
+// The engine is imported on first open, so MiniSearch stays out of the page's entry chunk.
+const engine = shallowRef<{ index: SearchIndex; search: typeof import('@lupinum/ginko/search').search }>()
+const mac = ref(true)
+
+async function open() {
+  dialog.value?.showModal()
+  input.value?.select()
+  if (engine.value) return
+  try {
+    const { loadIndex, search } = await import('@lupinum/ginko/search')
+    const url: string = `/__ginko/search/${locale.value}.json` // a plain string: the typed route union is too deep to compare
+    engine.value = { index: await loadIndex(await $fetch<SearchIndexJson>(url)), search }
+  } catch { /* no index: the dialog shows "no results" */ }
+}
+watch(locale, () => { engine.value = undefined })
+
+const hits = computed<SearchHit[]>(() => {
+  const q = query.value.trim()
+  return q && engine.value ? engine.value.search(engine.value.index, q, { limit: 12 }) : []
+})
+// One group per page, in the order of its best hit; the page hit (no heading) leads its group and its sections
+// are indented under it. Pages then sit under their area (Docs, Blog, Changelog), again in the order of the best
+// hit; the area labels show only when hits come from more than one area.
+const AREAS = { docs: 'docs.docs', blog: 'docs.blog', changelog: 'docs.changelog' } as const
+function areaOf(url: string): keyof typeof AREAS | undefined {
+  const local = url.startsWith(`/${locale.value}/`) ? url.slice(locale.value.length + 1) : url
+  const first = local.split(/[/#?]/)[1] ?? ''
+  return Object.hasOwn(AREAS, first) ? (first as keyof typeof AREAS) : undefined
+}
+const groups = computed(() => {
+  const byPage = new Map<string, SearchHit[]>()
+  for (const hit of hits.value) {
+    const page = hit.url.split('#')[0]!
+    byPage.set(page, [...(byPage.get(page) ?? []), hit])
+  }
+  const byArea = new Map<string, { label?: string; rows: { hit: SearchHit; indent: boolean }[] }>()
+  for (const list of byPage.values()) {
+    const area = areaOf(list[0]!.url)
+    const group = byArea.get(area ?? '') ?? { label: area ? t(AREAS[area]) : undefined, rows: [] }
+    byArea.set(area ?? '', group)
+    const hasPage = list.some((h) => !h.heading)
+    group.rows.push(...list.sort((a, b) => Number(!!a.heading) - Number(!!b.heading)).map((hit) => ({ hit, indent: hasPage && !!hit.heading })))
+  }
+  const list = [...byArea.values()]
+  return list.length > 1 ? list : list.map((g) => ({ ...g, label: undefined }))
+})
+const flat = computed(() => groups.value.flatMap((g) => g.rows))
+const indexOf = (hit: SearchHit) => flat.value.findIndex((r) => r.hit.id === hit.id)
+watch(query, () => { active.value = 0 })
+
+function move(step: number) {
+  if (!flat.value.length) return
+  active.value = (active.value + step + flat.value.length) % flat.value.length
+  nextTick(() => document.getElementById(`docs-hit-${active.value}`)?.scrollIntoView({ block: 'nearest' }))
+}
+function go() {
+  const row = flat.value[active.value]
+  if (row) navigateTo(row.hit.url)
+}
+
+const route = useRoute()
+watch(() => route.fullPath, () => dialog.value?.close())
+function onKey(e: KeyboardEvent) {
+  const typing = e.target instanceof HTMLInputElement || e.target instanceof HTMLTextAreaElement || (e.target as HTMLElement)?.isContentEditable
+  if ((e.key === '/' && !typing) || (e.key.toLowerCase() === 'k' && (e.metaKey || e.ctrlKey))) {
+    e.preventDefault()
+    open()
+  }
+}
+onMounted(() => {
+  mac.value = /Mac|iPhone|iPad/.test(navigator.platform)
+  if (shortcut) window.addEventListener('keydown', onKey)
+})
+onBeforeUnmount(() => window.removeEventListener('keydown', onKey))
+</script>
+
+<template>
+  <button type="button" class="docs-search-trigger" :aria-label="t('docs.search')" @click="open">
+    <DocsIcon name="lucide:search" class="docs-icon" />
+    <span class="docs-search-label">{{ t('docs.searchPlaceholder') }}</span>
+    <kbd class="docs-kbd">{{ mac ? '⌘' : 'Ctrl' }} K</kbd>
+  </button>
+  <Teleport to="body">
+    <dialog ref="dialog" class="docs-search-dialog" :aria-label="t('docs.search')" @click.self="dialog?.close()">
+      <div class="docs-search-field">
+        <DocsIcon name="lucide:search" class="docs-icon" />
+        <input
+          ref="input" v-model="query" type="search" role="combobox" aria-autocomplete="list" aria-controls="docs-search-list"
+          :aria-expanded="flat.length > 0" :aria-activedescendant="flat.length ? `docs-hit-${active}` : undefined"
+          :placeholder="t('docs.searchPlaceholder')" :aria-label="t('docs.searchPlaceholder')" autocomplete="off" spellcheck="false"
+          @keydown.down.prevent="move(1)" @keydown.up.prevent="move(-1)" @keydown.enter.prevent="go" @keydown.esc.prevent="dialog?.close()"
+        >
+        <button type="button" class="docs-kbd" @click="dialog?.close()">Esc</button>
+      </div>
+      <div class="docs-search-body" tabindex="0" role="region" :aria-label="t('docs.searchResults')">
+        <ul v-if="flat.length" id="docs-search-list" class="docs-search-results" role="listbox" :aria-label="t('docs.search')">
+          <li v-for="(g, n) in groups" :key="n" role="none">
+            <p v-if="g.label" :id="`docs-hit-group-${n}`" class="docs-search-group">{{ g.label }}</p>
+            <ul role="group" :aria-labelledby="g.label ? `docs-hit-group-${n}` : undefined">
+              <li
+                v-for="{ hit, indent } in g.rows" :id="`docs-hit-${indexOf(hit)}`" :key="hit.id" role="option" :aria-selected="indexOf(hit) === active"
+                class="docs-search-hit" :class="{ 'is-section': indent }" @mousemove="active = indexOf(hit)" @click="active = indexOf(hit); go()"
+              >
+                <span class="docs-search-tile"><DocsIcon :name="hit.heading ? 'lucide:hash' : 'lucide:file-text'" class="docs-icon" /></span>
+                <span class="docs-search-text">
+                  <strong>{{ hit.heading ?? hit.title }}</strong>
+                  <span>{{ indent ? hit.excerpt : hit.heading ? hit.title : hit.excerpt }}</span>
+                </span>
+                <DocsIcon name="lucide:corner-down-left" class="docs-icon docs-search-enter" />
+              </li>
+            </ul>
+          </li>
+        </ul>
+        <p v-else-if="query.trim()" class="docs-search-empty">{{ t('docs.noResults', { query: query.trim() }) }}</p>
+        <p v-else class="docs-search-empty">{{ t('docs.searchHint') }}</p>
+      </div>
+      <div class="docs-search-foot" aria-hidden="true">
+        <span><kbd class="docs-kbd">↑</kbd><kbd class="docs-kbd">↓</kbd> {{ t('docs.searchMove') }}</span>
+        <span><kbd class="docs-kbd">↵</kbd> {{ t('docs.searchOpen') }}</span>
+        <span><kbd class="docs-kbd">Esc</kbd> {{ t('docs.close') }}</span>
+      </div>
+    </dialog>
+  </Teleport>
+</template>

package/app/components/DocsShell.vue

@@ -0,0 +1,36 @@
+<script setup lang="ts">
+// The docs body: the navigation on the side and the page next to it. Public: a site builds its own pages inside the
+// docs frame with it (slots: default, `bar`). In the layer's own frame the header holds the search and, on phones, the
+// navigation. Inside a site's layout the shell brings both: the search above the navigation, and on phones a bar with
+// a button that opens the navigation as a sheet, the search, and the page's own controls (slot `bar`, the table of
+// contents). `docs.search: false` in app.config leaves the search out (a site with <DocsSearch /> in its own header).
+const { t } = useI18n()
+const standalone = useDocsStandalone()
+const search = !standalone && useAppConfig().docs?.search !== false
+const nav = ref(false)
+</script>
+
+<template>
+  <div class="docs-shell">
+    <nav class="docs-sidebar" :aria-label="t('docs.nav')">
+      <div v-if="search" class="docs-sidebar-search">
+        <DocsSearch />
+      </div>
+      <DocsSidebar />
+    </nav>
+    <div id="docs-content" class="docs-content" tabindex="-1">
+      <div class="docs-bar">
+        <div v-if="!standalone" class="docs-bar-start">
+          <button type="button" class="docs-bar-nav" aria-haspopup="dialog" :aria-expanded="nav" @click="nav = true">
+            <DocsIcon name="lucide:panel-left-open" class="docs-icon" />{{ t('docs.contents') }}
+          </button>
+          <!-- A second trigger for phones; the one above the navigation keeps the keyboard shortcut. -->
+          <DocsSearch v-if="search" :shortcut="false" />
+        </div>
+        <slot name="bar" />
+      </div>
+      <slot />
+    </div>
+    <DocsNavSheet v-if="!standalone" v-model:open="nav" />
+  </div>
+</template>

package/app/components/DocsSidebar.vue

@@ -0,0 +1,19 @@
+<script setup lang="ts">
+// The side navigation: the section tabs (when the docs have several), then the pages of the active tab in their
+// sections, then the site's DocsSidebarEnd. Used in the sidebar, the phone sheet and the header menu.
+const { t } = useI18n()
+const { tabs, activeTab, sections } = useDocs()
+</script>
+
+<template>
+  <div>
+    <nav v-if="tabs.length" class="docs-tabs" :aria-label="t('docs.sections')">
+      <NuxtLink v-for="tab in tabs" :key="tab.title" :to="tab.path" :aria-current="tab.title === activeTab ? 'true' : undefined">{{ tab.title }}</NuxtLink>
+    </nav>
+    <section v-for="(s, i) in sections" :key="i" class="docs-nav-section">
+      <h2 v-if="s.title" class="docs-nav-heading">{{ s.title }}</h2>
+      <DocsNavTree :nodes="s.nodes" />
+    </section>
+    <DocsSidebarEnd />
+  </div>
+</template>

package/app/components/DocsSidebarEnd.ts

@@ -0,0 +1,4 @@
+// Override point: below the docs navigation (sidebar, phone sheet and the header menu). Renders nothing here; a site
+// puts its own `components/DocsSidebarEnd.vue` in its app to add links or a contact line. A render function, not an
+// empty <template>: server and browser then agree on the empty placeholder.
+export default defineComponent({ name: 'DocsSidebarEnd', render: () => null })

package/app/components/DocsTable.vue

@@ -0,0 +1,11 @@
+<script setup lang="ts">
+// Markdown tables scroll sideways on a phone. The wrapper is the scroll box: keyboard users can focus it and scroll with the arrow keys.
+// role=group, not region: a page can hold several tables, and landmarks with the same name are an error.
+const { t } = useI18n()
+</script>
+
+<template>
+  <div class="docs-table" role="group" tabindex="0" :aria-label="t('docs.table')">
+    <table><slot /></table>
+  </div>
+</template>

package/app/components/DocsThemeToggle.vue

@@ -0,0 +1,45 @@
+<script setup lang="ts">
+// Auto, light or dark. Auto follows the system and is the default; a choice lives in localStorage and
+// <html data-theme>, and the head script applies it before paint. Both icons are in the HTML and CSS shows the
+// right one, so the server render never guesses the reader's scheme.
+import { COLOR_KEY, colorInitScript } from '../lib/docsInit'
+
+const { t } = useI18n()
+useHead({ script: [{ key: 'docs-color-init', innerHTML: colorInitScript(), tagPriority: 'critical' }] })
+
+// `segmented` is the phone menu's Auto/Light/Dark switch: the same states and the same storage.
+const props = defineProps<{ segmented?: boolean }>()
+type Choice = 'auto' | 'light' | 'dark'
+const system = (): 'light' | 'dark' => (matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')
+const current = (): Choice => (document.documentElement.getAttribute('data-theme') as Choice | null) ?? 'auto'
+// Only read when the switch is on screen (the phone menu renders on the client), so SSR never guesses.
+const choice = ref<Choice>(props.segmented && import.meta.client ? current() : 'auto')
+
+function choose(next: Choice) {
+  const html = document.documentElement
+  if (next === 'auto') html.removeAttribute('data-theme')
+  else html.setAttribute('data-theme', next)
+  choice.value = next
+  try {
+    if (next === 'auto') localStorage.removeItem(COLOR_KEY)
+    else localStorage.setItem(COLOR_KEY, next)
+  } catch { /* storage blocked: the choice lasts until reload */ }
+}
+// The header button flips what the reader sees; flipping back to the system's scheme returns to Auto.
+function toggle() {
+  const shown = current() === 'auto' ? system() : current()
+  const next = shown === 'dark' ? 'light' : 'dark'
+  choose(next === system() ? 'auto' : next)
+}
+const OPTIONS = ['auto', 'light', 'dark'] as const
+</script>
+
+<template>
+  <div v-if="props.segmented" class="docs-segmented" role="group" :aria-label="t('docs.theme.label')">
+    <button v-for="o in OPTIONS" :key="o" type="button" :aria-pressed="choice === o" @click="choose(o)">{{ t(`docs.theme.${o}`) }}</button>
+  </div>
+  <button v-else type="button" class="docs-icon-button docs-theme-toggle" :aria-label="t('docs.theme.toggle')" :title="t('docs.theme.toggle')" @click="toggle">
+    <DocsIcon name="lucide:moon" class="docs-icon docs-when-light" />
+    <DocsIcon name="lucide:sun" class="docs-icon docs-when-dark" />
+  </button>
+</template>

package/app/components/DocsToc.vue

@@ -0,0 +1,73 @@
+<script setup lang="ts">
+// The table of contents of a page: a rail beside the text on wide screens (`aside`), a menu in the docs bar
+// on narrower ones (`menu`). The current section is the last heading that has passed the top of the screen.
+interface TocLink { id: string, text: string, children?: TocLink[] }
+const props = defineProps<{ links: TocLink[], variant: 'aside' | 'menu' }>()
+const { t } = useI18n()
+const { open, toggle } = useDocsPopover()
+
+const flat = computed(() => props.links.flatMap((l) => [{ ...l, sub: false }, ...(l.children ?? []).map((c) => ({ ...c, sub: true }))]))
+const current = ref<string>()
+
+// A scroll listener instead of an IntersectionObserver: the text may render after this component on client
+// navigation, and looking the headings up on each (throttled) scroll needs no bookkeeping for that.
+let frame = 0
+function spy() {
+  cancelAnimationFrame(frame)
+  frame = requestAnimationFrame(() => {
+    const top = Number.parseFloat(getComputedStyle(document.documentElement).scrollPaddingTop) || 96
+    let id: string | undefined
+    for (const l of flat.value) {
+      const el = document.getElementById(l.id)
+      if (el && el.getBoundingClientRect().top <= top + 8) id = l.id
+    }
+    current.value = id ?? flat.value[0]?.id
+  })
+}
+onMounted(() => {
+  spy()
+  window.addEventListener('scroll', spy, { passive: true })
+})
+onBeforeUnmount(() => {
+  cancelAnimationFrame(frame)
+  window.removeEventListener('scroll', spy)
+})
+watch(() => props.links, () => nextTick(spy))
+// A long table of contents scrolls in its own box: keep the current entry in view (the box only, not the page).
+const aside = ref<HTMLElement | null>(null)
+watch(current, (id) => {
+  const box = aside.value
+  const link = id ? box?.querySelector<HTMLElement>(`a[href="#${CSS.escape(id)}"]`) : undefined
+  if (!box || !link || box.scrollHeight <= box.clientHeight) return
+  const top = link.getBoundingClientRect().top - box.getBoundingClientRect().top + box.scrollTop
+  if (top < box.scrollTop + 32 || top > box.scrollTop + box.clientHeight - 48) box.scrollTop = top - box.clientHeight / 3
+})
+const title = computed(() => flat.value.find((l) => l.id === current.value)?.text)
+</script>
+
+<template>
+  <nav v-if="props.variant === 'aside'" ref="aside" class="docs-toc" :aria-label="t('docs.onThisPage')">
+    <p class="docs-toc-title">
+      <DocsIcon name="lucide:text-align-start" class="docs-icon" />{{ t('docs.onThisPage') }}
+    </p>
+    <ul class="docs-toc-list">
+      <li v-for="l in flat" :key="l.id">
+        <a :href="`#${l.id}`" :class="{ 'is-sub': l.sub }" :aria-current="current === l.id ? 'location' : undefined">{{ l.text }}</a>
+      </li>
+    </ul>
+    <slot />
+  </nav>
+  <div v-else ref="popover" class="docs-toc-menu">
+    <button type="button" :aria-expanded="open" aria-controls="docs-toc-menu" @click="toggle">
+      <span>{{ title && flat.length > 1 ? title : t('docs.onThisPage') }}</span>
+      <DocsIcon name="lucide:chevron-down" class="docs-icon" />
+    </button>
+    <nav v-if="open" id="docs-toc-menu" class="docs-popover" :aria-label="t('docs.onThisPage')">
+      <ul class="docs-toc-list">
+        <li v-for="l in flat" :key="l.id">
+          <a :href="`#${l.id}`" :class="{ 'is-sub': l.sub }" :aria-current="current === l.id ? 'location' : undefined" @click="toggle">{{ l.text }}</a>
+        </li>
+      </ul>
+    </nav>
+  </div>
+</template>

package/app/composables/useDocs.ts

@@ -0,0 +1,53 @@
+// What is docs-specific on top of Ginko's navigation: the tree comes from `useGinkoNav`, the
+// breadcrumb chain from `useGinkoBreadcrumbs`; this adds tabs and sections from the entries' fields.
+import schema from '#ginko/schema'
+import { enrichNav, type DocNode, type DocTab } from '../lib/docsNav'
+
+export function useDocs() {
+  const items = useGinko('docs')
+  const tree = useGinkoNav(['docs'])
+  const chain = useGinkoBreadcrumbs(['docs'])
+
+  // Ginko's nodes carry title and path; badge, icon, section and tab live on the entry (rules: enrichNav).
+  const nodes = computed<DocNode[]>(() => {
+    const byId = new Map(items.value.items.map((d) => [d.id, d.data]))
+    return enrichNav(tree.value, (id) => byId.get(id))
+  })
+
+  const tabs = computed<DocTab[]>(() => {
+    const out = new Map<string, DocTab>()
+    for (const n of nodes.value) if (n.tab && !out.has(n.tab)) out.set(n.tab, { title: n.tab, path: n.path })
+    return out.size > 1 ? [...out.values()] : []
+  })
+  const activeTab = computed(() => (tabs.value.length ? nodes.value.find((n) => n.path === chain.value[0]?.path)?.tab ?? tabs.value[0]!.title : undefined))
+
+  // Roots of the active tab, grouped by `section` (a section is a run of neighbours with the same one).
+  const sections = computed(() => {
+    const out: { title?: string; nodes: DocNode[] }[] = []
+    for (const node of nodes.value) {
+      if (tabs.value.length && (node.tab ?? tabs.value[0]!.title) !== activeTab.value) continue
+      const last = out.at(-1)
+      if (last && last.title === node.section) last.nodes.push(node)
+      else out.push({ title: node.section, nodes: [node] })
+    }
+    return out
+  })
+
+  // Tab (when tabs are shown), then the parent chain down to this page.
+  const crumbs = computed<{ title: string; path: string }[]>(() => {
+    const tab = tabs.value.find((t) => t.title === activeTab.value)
+    return [...(tab ? [tab] : []), ...chain.value.map(({ title, path }) => ({ title, path }))]
+  })
+
+  /** The first page of the docs in this language: where `/docs` (and `/` without a start page) lead. */
+  const first = computed(() => nodes.value[0]?.path)
+
+  /** Where the docs live in this language (docsCollection's `base`, `/docs` by default), e.g. `/de/docs`. */
+  const { localePath } = useI18n()
+  const { mainLocale } = useGinkoSite()
+  const route = (schema.bricks.docs as { route?: Record<string, string> } | undefined)?.route?.[mainLocale]
+  const mainBase = route?.replace(/\/\[slug\]$/, '') ?? '/docs'
+  const base = computed(() => localePath(mainBase))
+
+  return { nodes, tabs, activeTab, sections, crumbs, first, base, mainBase }
+}

package/app/composables/useDocsBlog.ts

@@ -0,0 +1,33 @@
+// The optional blog and changelog: whether the site has them, where they live in this language, and typed
+// reads. The layer cannot know the site's bricks at compile time, so the reads go through one cast here.
+import schema from '#ginko/schema'
+import type { Author, ChangelogEntry, Post } from '../lib/blogTypes'
+
+
+const has = (brick: string) => Object.hasOwn(schema.bricks, brick)
+const read = <T>(brick: string) => (useGinko as unknown as (b: string) => ComputedRef<{ items: T[] }>)(brick)
+
+export function useDocsBlog() {
+  const { localePath } = useI18n()
+  // The addresses of the bricks' lists in the main language, written by modules/pages.ts.
+  const address = useRuntimeConfig().public.ginkoDocs
+  const hasPosts = has('posts') && !!address.blog
+  const hasChangelog = has('changelog') && !!address.changelog
+
+  const authors = hasPosts && has('authors') ? read<Author>('authors') : undefined
+  const authorsOf = (post: Post) => (post.data.authors ?? []).flatMap((id) => authors?.value.items.find((a) => a.id === id) ?? [])
+  const { format } = useI18n()
+  const formatDate = (iso: string) => format.date(iso, 'long')
+
+  // `draft` is a reserved content key, no schema field; it reaches the bundle only in dev, where drafts show.
+  const isDraft = (post: Post) => 'draft' in post.data && post.data.draft === true
+  return {
+    hasPosts, hasChangelog, authorsOf, isDraft, formatDate,
+    blogPath: computed(() => localePath(address.blog)),
+    feedPath: computed(() => localePath(`${address.blog}/rss.xml`)),
+    changelogPath: computed(() => localePath(address.changelog)),
+    posts: () => read<Post>('posts'),
+    changelog: () => read<ChangelogEntry>('changelog'),
+    post: (slug: string) => (useGinkoEntry as unknown as (b: string, s: string) => Readonly<Ref<Post>>)('posts', slug),
+  }
+}

package/app/composables/useDocsCopy.ts

@@ -0,0 +1,17 @@
+// Copies text and shows the result for two seconds: `copied`, or `failed` when the clipboard is blocked.
+export function useDocsCopy() {
+  const state = ref<'idle' | 'copied' | 'failed'>('idle')
+  let timer: ReturnType<typeof setTimeout> | undefined
+  async function copy(text: string | (() => Promise<string>)) {
+    try {
+      await navigator.clipboard.writeText(typeof text === 'string' ? text : await text())
+      state.value = 'copied'
+    } catch {
+      state.value = 'failed'
+    }
+    clearTimeout(timer)
+    timer = setTimeout(() => { state.value = 'idle' }, 2000)
+  }
+  onBeforeUnmount(() => clearTimeout(timer))
+  return { state, copy }
+}

package/app/composables/useDocsFrame.ts

@@ -0,0 +1,11 @@
+import type { InjectionKey } from 'vue'
+
+// Whether the docs render in the layer's own frame (layouts/default.vue) or inside a site's layout. Standalone, the
+// header holds the search and, on phones, the navigation; embedded, DocsShell brings both itself.
+const STANDALONE: InjectionKey<boolean> = Symbol('docs-standalone')
+
+/** Called by the layer's own layout. */
+export const provideDocsStandalone = () => provide(STANDALONE, true)
+
+/** True inside the layer's own frame, false when a site's layout holds the docs. */
+export const useDocsStandalone = () => inject(STANDALONE, false)

package/app/composables/useDocsPopover.ts

@@ -0,0 +1,36 @@
+// A small disclosure popover (language menu, page actions, phone table of contents): a button toggles a panel;
+// a click outside, Escape or a page change closes it, and Escape returns focus to the button.
+// The component puts `ref="popover"` on the element that holds both the button and the panel, and binds `toggle`
+// to the button's click (Escape returns focus to that button).
+export function useDocsPopover() {
+  const open = ref(false)
+  const root = useTemplateRef<HTMLElement>('popover')
+  const route = useRoute()
+  let trigger: HTMLElement | undefined
+
+  function close(refocus = false) {
+    if (!open.value) return
+    open.value = false
+    if (refocus) (trigger ?? root.value?.querySelector<HTMLElement>('[aria-expanded]'))?.focus()
+  }
+  const onClick = (e: MouseEvent) => { if (!root.value?.contains(e.target as Node)) close() }
+  const onKey = (e: KeyboardEvent) => { if (e.key === 'Escape') close(true) }
+  function listen(on: boolean) {
+    if (on) {
+      document.addEventListener('click', onClick, true)
+      document.addEventListener('keydown', onKey)
+    } else {
+      document.removeEventListener('click', onClick, true)
+      document.removeEventListener('keydown', onKey)
+    }
+  }
+
+  watch(open, (value) => listen(value))
+  watch(() => route.fullPath, () => close())
+  onBeforeUnmount(() => listen(false))
+  function toggle(event?: Event) {
+    if (event?.currentTarget instanceof HTMLElement) trigger = event.currentTarget
+    open.value = !open.value
+  }
+  return { open, toggle, close }
+}

package/app/composables/useDocsSite.ts

@@ -0,0 +1,31 @@
+// The site's own links outside Markdown (app.config nav, footer and banner, the start page's links and cards): their
+// texts and their addresses.
+import schema from '#ginko/schema'
+import { docsMainPath, docsRouteLink } from '../lib/docsPage'
+
+export function useDocsSite() {
+  const { t, localePath } = useI18n()
+  const docs = useGinko('docs')
+  const locale = useGinkoLocale()
+  const { mainLocale } = useGinkoSite()
+  const pages = schema.pages as Record<string, Partial<Record<string, string>> | undefined>
+  const docsRoute = (schema.bricks as Record<string, { route?: Partial<Record<string, string>> } | undefined>).docs?.route
+  const find = {
+    // A page the current language lacks leads to its main-language page.
+    doc: (ref: string) => docs.value.items.find((d) => d.id === `docs/${ref}` || d.data.slug === ref)?.url ?? docsMainPath(docsRoute, mainLocale, ref),
+    page: (key: string) => pages[key]?.[locale.value] ?? pages[key]?.[mainLocale],
+  }
+  return {
+    /** A message key the site defines (`docs.nav.<id>`, `docs.footer.<id>`, `docs.banner.<id>`); the layer's types do not know them. */
+    text: t as (key: string) => string,
+    /**
+     * An address in the reader's language: a route link (`$docs.<page>`, `$page.<key>`) becomes the page's path, an
+     * internal path gets the language prefix; an absolute URL, a mail link or an anchor stays as written.
+     */
+    href: (raw: string) => {
+      // A route link that names nothing never becomes an address: it would be a relative link to a 404.
+      if (raw.startsWith('$')) return docsRouteLink(raw, find) ?? localePath('/')
+      return raw.startsWith('/') && !raw.startsWith('//') ? localePath(raw) : raw
+    },
+  }
+}

package/app/docs-pages/blog.vue

@@ -0,0 +1,55 @@
+<script setup lang="ts">
+// The blog: all posts, newest first (the collection's order).
+const { t, language } = useI18n()
+const blog = useDocsBlog()
+const langOf = useGinkoLang()
+const posts = blog.posts()
+// A list page: CollectionPage JSON-LD, so search engines read it as the index of its entries.
+const site = useGinkoSite()
+const route = useRoute()
+useGinkoSeo(() => ({
+  title: t('docs.blog'),
+  description: t('docs.blogLead'),
+  jsonLd: [{ '@context': 'https://schema.org', '@type': 'CollectionPage', name: t('docs.blog'), url: new URL(route.path, site.url).href, inLanguage: language.value }],
+}))
+useHead(() => ({ link: [{ rel: 'alternate', type: 'application/rss+xml', title: t('docs.blog'), href: blog.feedPath.value }] }))
+// Nitro's crawler only follows links to pages (no `.xml`), but it also reads this header, so `nuxt generate` writes the feed.
+if (import.meta.server) useResponseHeader('x-nitro-prerender').value = blog.feedPath.value
+</script>
+
+<template>
+  <div class="docs-blog">
+    <div class="docs-blog-panel">
+      <header class="docs-blog-head">
+        <div>
+          <h1>{{ t('docs.blog') }}</h1>
+          <p class="docs-lead">{{ t('docs.blogLead') }}</p>
+        </div>
+        <a :href="blog.feedPath.value" type="application/rss+xml"><DocsIcon name="lucide:rss" class="docs-icon" />{{ t('docs.rss') }}</a>
+      </header>
+      <ul class="docs-posts">
+        <li v-for="post in posts.items" :key="post.id">
+          <div class="docs-post-side">
+            <p class="docs-meta"><time :datetime="post.data.date">{{ blog.formatDate(post.data.date) }}</time></p>
+            <p v-if="blog.authorsOf(post).length" class="docs-authors">
+              <template v-for="a in blog.authorsOf(post)" :key="a.id">
+                <GinkoImage v-if="a.data.avatar" :image="a.data.avatar" class="docs-avatar" />
+              </template>
+              {{ blog.authorsOf(post).map((a) => a.data.name).join(', ') }}
+            </p>
+          </div>
+          <div class="docs-post-main">
+            <h2>
+              <NuxtLink :to="post.url">{{ post.data.title }}</NuxtLink>
+              <span v-if="blog.isDraft(post)" class="docs-tag docs-tag-draft">{{ t('docs.draft') }}</span>
+            </h2>
+            <p v-if="post.data.description" class="docs-post-teaser" :lang="langOf(post, 'description')">{{ post.data.description }}</p>
+            <p v-if="post.data.tags?.length" class="docs-tags">
+              <span v-for="tag in post.data.tags" :key="tag.tag" class="docs-tag">{{ tag.tag }}</span>
+            </p>
+          </div>
+        </li>
+      </ul>
+    </div>
+  </div>
+</template>

package/app/docs-pages/changelog.vue

@@ -0,0 +1,35 @@
+<script setup lang="ts">
+import { releaseAnchor as anchor } from '@lupinum/ginko/basics'
+import { markdownComponents } from '../lib/markdownComponents'
+// The changelog: one page, one section per release, newest first (the collection's order). Each version has an anchor.
+const { t, language } = useI18n()
+const blog = useDocsBlog()
+const langOf = useGinkoLang()
+const entries = blog.changelog()
+// A list page: CollectionPage JSON-LD, so search engines read it as the index of its entries.
+const site = useGinkoSite()
+const route = useRoute()
+useGinkoSeo(() => ({
+  title: t('docs.changelog'),
+  description: t('docs.changelogLead'),
+  jsonLd: [{ '@context': 'https://schema.org', '@type': 'CollectionPage', name: t('docs.changelog'), url: new URL(route.path, site.url).href, inLanguage: language.value }],
+}))
+</script>
+
+<template>
+  <div class="docs-blog">
+    <div class="docs-blog-panel">
+      <header class="docs-blog-head">
+        <h1>{{ t('docs.changelog') }}</h1>
+      </header>
+      <p v-if="!entries.items.length" class="docs-meta">{{ t('docs.changelogEmpty') }}</p>
+      <section v-for="entry in entries.items" :id="anchor(entry.data.version)" :key="entry.id" class="docs-release">
+        <div class="docs-release-meta">
+          <h2><a :href="`#${anchor(entry.data.version)}`">{{ entry.data.version }}</a></h2>
+          <p class="docs-meta"><time :datetime="entry.data.date">{{ blog.formatDate(entry.data.date) }}</time></p>
+        </div>
+        <GinkoMarkdown :value="entry.data.body" :components="markdownComponents" class="docs-prose" :lang="langOf(entry, 'body')" />
+      </section>
+    </div>
+  </div>
+</template>

package/app/docs-pages/doc.vue

@@ -0,0 +1,16 @@
+<script setup lang="ts">
+const route = useRoute()
+const doc = useGinkoEntry('docs', () => route.params.slug)
+// The toc comes with the text (page state holds only its ref); the same request as the page's <GinkoMarkdown>.
+const tree = await useGinkoMarkdown(() => doc.value.data.body)
+const toc = computed(() => tree.value?.toc?.links ?? [])
+</script>
+
+<template>
+  <DocsShell>
+    <template v-if="toc.length" #bar>
+      <DocsToc :links="toc" variant="menu" />
+    </template>
+    <DocsPage :doc="doc" />
+  </DocsShell>
+</template>

package/app/docs-pages/docs.vue

@@ -0,0 +1,9 @@
+<script setup lang="ts">
+import { toFirstDoc } from '../lib/docsFirst'
+// The docs address itself (`/docs`) has no page of its own: it leads to the first docs page of the language.
+await toFirstDoc()
+</script>
+
+<template>
+  <div />
+</template>