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

package/app/components/DocsExample.vue

@@ -0,0 +1,43 @@
+<script setup lang="ts">
+import { previewToc } from '../lib/previewToc'
+import { markdownComponents } from '../lib/markdownComponents'
+// A ```md preview fence (ginko-content parses it into `example`): what the Markdown renders, then the Markdown
+// itself, as two tabs in one frame. The preview arrives as a parsed tree in a prop; the code block is the slot.
+// One copy button serves both tabs (the code block's own is hidden in CSS), so it sits in the same place in each.
+import type { MarkdownTree } from '@lupinum/ginko'
+import { Tab, Tabs } from '@lupinum/ginko-components/components'
+
+const props = defineProps<{ preview: MarkdownTree['nodes'] }>()
+const { t } = useI18n()
+const { t: tc } = useI18n('components') // the code block's own texts: "Copy code", "Copied"
+const tree = computed<MarkdownTree>(() => ({ nodes: props.preview, toc: previewToc(props.preview) }))
+
+const root = useTemplateRef<HTMLElement>('root')
+const copied = ref(false)
+let timer: ReturnType<typeof setTimeout> | undefined
+async function copy() {
+  const text = (root.value?.querySelector('pre')?.textContent ?? '').replace(/\n$/, '')
+  try { await navigator.clipboard.writeText(text) } catch { return }
+  copied.value = true
+  clearTimeout(timer)
+  timer = setTimeout(() => { copied.value = false }, 2000)
+}
+onBeforeUnmount(() => clearTimeout(timer))
+</script>
+
+<template>
+  <div ref="root" class="docs-example">
+    <Tabs variant="line">
+      <Tab :title="t('docs.example.preview')">
+        <GinkoMarkdown :value="tree" :components="markdownComponents" class="docs-example-preview" />
+      </Tab>
+      <Tab :title="t('docs.example.source')">
+        <slot />
+      </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" />
+      <span class="ginko-code-status" aria-live="polite">{{ copied ? tc('code.copied') : '' }}</span>
+    </button>
+  </div>
+</template>

package/app/components/DocsFooter.vue

@@ -0,0 +1,19 @@
+<script setup lang="ts">
+// Site links (texts: docs.footer.<id>) and the "Built with Ginko" line. Renders nothing when both are off.
+const { t } = useI18n()
+const { text, href } = useDocsSite()
+const footer = useAppConfig().docs?.footer
+const links = footer?.links ?? []
+const attribution = footer?.attribution ?? true
+</script>
+
+<template>
+  <footer v-if="links.length || attribution" class="docs-footer">
+    <div class="docs-footer-inner">
+      <nav v-if="links.length" :aria-label="t('docs.footerNav')">
+        <NuxtLink v-for="l in links" :key="l.id" :to="href(l.href)">{{ text(`docs.footer.${l.id}`) }}</NuxtLink>
+      </nav>
+      <a v-if="attribution" href="https://github.com/lupinum-dev/ginko" rel="noopener">{{ t('docs.builtWith') }}</a>
+    </div>
+  </footer>
+</template>

package/app/components/DocsHeader.vue

@@ -0,0 +1,112 @@
+<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.
+const { t, localePath } = useI18n()
+const cfg = useAppConfig().docs ?? {}
+const title = cfg.title ?? useGinkoSite().name
+const { text, href } = useDocsSite()
+const docs = useDocs()
+const blog = useDocsBlog()
+const route = useRoute()
+
+const within = (base: string | undefined) => !!base && (route.path === base || route.path.startsWith(`${base}/`))
+const links = computed(() => [
+  ...(docs.first.value ? [{ key: 'docs', label: t('docs.docs'), to: docs.first.value, active: within(docs.base.value) }] : []),
+  ...(blog.hasPosts ? [{ key: 'blog', label: t('docs.blog'), to: blog.blogPath.value, active: within(blog.blogPath.value) }] : []),
+  ...(blog.hasChangelog ? [{ key: 'changelog', label: t('docs.changelog'), to: blog.changelogPath.value, active: within(blog.changelogPath.value) }] : []),
+  ...(cfg.nav ?? []).map((l) => ({ key: l.id, label: text(`docs.nav.${l.id}`), to: href(l.href), active: within(href(l.href)) })),
+])
+
+// The phone menu. Where the docs navigation shows: on the docs pages only (not the blog or the start page).
+const menu = ref(false)
+const inDocs = computed(() => within(docs.base.value))
+const button = useTemplateRef<HTMLButtonElement>('button')
+const panel = useTemplateRef<HTMLElement>('panel')
+
+function close(refocus = false) {
+  if (!menu.value) return
+  menu.value = false
+  if (refocus) button.value?.focus()
+}
+function onKey(e: KeyboardEvent) {
+  // An open language popover takes the first Escape.
+  if (e.key === 'Escape' && !panel.value?.querySelector('.docs-popover')) close(true)
+}
+const wide = import.meta.client ? matchMedia('(min-width: 64rem)') : undefined
+const onWide = () => { if (wide?.matches) close() }
+
+// While open: the page behind does not scroll, Escape closes, and focus moves in (and back to the button on close).
+watch(menu, async (open) => {
+  document.documentElement.style.overflow = open ? 'hidden' : ''
+  if (open) {
+    document.addEventListener('keydown', onKey)
+    wide?.addEventListener('change', onWide)
+    await nextTick()
+    panel.value?.focus()
+  } else {
+    document.removeEventListener('keydown', onKey)
+    wide?.removeEventListener('change', onWide)
+  }
+})
+watch(() => route.fullPath, () => close())
+onBeforeUnmount(() => {
+  document.documentElement.style.overflow = ''
+  document.removeEventListener('keydown', onKey)
+  wide?.removeEventListener('change', onWide)
+})
+</script>
+
+<template>
+  <header class="docs-header">
+    <div class="docs-header-inner">
+      <NuxtLink :to="localePath('/')" class="docs-brand">
+        <template v-if="cfg.logo">
+          <img :class="{ 'docs-when-light': cfg.logo.dark }" :src="cfg.logo.light" :alt="cfg.logo.wordmark ? title : ''">
+          <img v-if="cfg.logo.dark" class="docs-when-dark" :src="cfg.logo.dark" alt="">
+        </template>
+        <span v-if="!cfg.logo?.wordmark">{{ title }}</span>
+      </NuxtLink>
+      <nav v-if="links.length > 1 || cfg.nav?.length" class="docs-nav-links" :aria-label="t('docs.siteLinks')">
+        <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 />
+        <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" />
+            </a>
+          </div>
+        </template>
+        <button
+          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" />
+        </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')">
+        <div v-if="inDocs" class="docs-menu-scroll">
+          <DocsSidebar />
+        </div>
+        <div class="docs-menu-more">
+          <nav class="docs-menu-links" :aria-label="t('docs.siteLinks')">
+            <NuxtLink v-for="l in links" :key="l.key" :to="l.to" :aria-current="l.active ? 'page' : undefined">{{ l.label }}</NuxtLink>
+            <a v-for="s in cfg.social ?? []" :key="s.href" :href="s.href" target="_blank" rel="noopener">{{ s.label }}</a>
+          </nav>
+        </div>
+        <div class="docs-menu-foot">
+          <DocsLanguage />
+          <DocsThemeToggle segmented />
+        </div>
+      </div>
+    </Teleport>
+  </header>
+</template>

package/app/components/DocsLanding.vue

@@ -0,0 +1,55 @@
+<script setup lang="ts">
+import { markdownComponents } from '../lib/markdownComponents'
+// The start page from the site's `home` brick (docsHome): hero with title, description, links and an install
+// command, the feature grid, then the free text. Everything is content, so it is translated like the docs.
+import type { ItemOf } from '@lupinum/ginko'
+import type { docsHome } from '@lupinum/ginko-docs/config'
+
+type Home = Pick<ItemOf<ReturnType<typeof docsHome>['fields']>, 'data'>
+// The layer cannot know the site's bricks at compile time; index.vue renders this only when `home` exists.
+const home = (useGinko as unknown as (b: string) => ComputedRef<Home>)('home')
+const data = computed(() => home.value.data)
+const { t } = useI18n()
+useGinkoSeo(() => ({ title: data.value.title, description: data.value.description }))
+
+const { state, copy } = useDocsCopy()
+const external = (href: string) => /^https?:\/\//.test(href)
+</script>
+
+<template>
+  <div class="docs-landing">
+    <div class="docs-landing-inner">
+      <section class="docs-hero">
+        <h1>{{ data.title }}</h1>
+        <p v-if="data.description">{{ data.description }}</p>
+        <div v-if="data.links.length" class="docs-hero-links">
+          <NuxtLink
+            v-for="(l, i) in data.links" :key="l.href" :to="l.href" :target="external(l.href) ? '_blank' : undefined"
+            class="docs-button is-large" :class="i === 0 ? 'is-primary' : 'is-soft'"
+          >
+            {{ l.label }}<Icon v-if="i === 0" name="lucide:arrow-right" class="docs-icon" />
+          </NuxtLink>
+        </div>
+        <div v-if="data.install" class="docs-install">
+          <code tabindex="0" role="region" :aria-label="t('docs.installCommand')">{{ data.install }}</code>
+          <button type="button" class="docs-icon-button" :aria-label="state === 'copied' ? t('docs.copied') : state === 'failed' ? t('docs.copyFailed') : t('docs.copyCommand')" @click="copy(data.install ?? '')">
+            <Icon :name="state === 'copied' ? 'lucide:check' : 'lucide:copy'" class="docs-icon" />
+          </button>
+        </div>
+      </section>
+      <ul v-if="data.features.length" class="docs-features">
+        <li v-for="f in data.features" :key="f.title" class="docs-feature">
+          <div v-if="f.icon" class="docs-feature-icon">
+            <Icon :name="f.icon" class="docs-icon" />
+          </div>
+          <h2>
+            <NuxtLink v-if="f.href" :to="f.href">{{ f.title }}</NuxtLink>
+            <template v-else>{{ f.title }}</template>
+          </h2>
+          <p>{{ f.description }}</p>
+        </li>
+      </ul>
+      <GinkoMarkdown v-if="data.body" :value="data.body" :components="markdownComponents" class="docs-prose docs-landing-body" />
+    </div>
+  </div>
+</template>

package/app/components/DocsLanguage.vue

@@ -0,0 +1,29 @@
+<script setup lang="ts">
+// The languages of this page (ginko-i18n alternates, so a doc links to its own translation). A menu in the
+// header and in the phone menu. Each language is named in itself ("Deutsch").
+const { t, alternates } = useI18n()
+const { open, toggle } = useDocsPopover()
+const current = computed(() => alternates.value.find((a) => a.current))
+</script>
+
+<template>
+  <template v-if="alternates.length > 1">
+    <div ref="popover" class="docs-lang">
+      <button
+        type="button" class="docs-icon-button" :aria-expanded="open" aria-controls="docs-lang-menu"
+        :aria-label="`${t('docs.language')}: ${current?.name ?? ''}`" @click="toggle"
+      >
+        <Icon name="lucide:languages" class="docs-icon" />
+        <span aria-hidden="true">{{ current?.code.toUpperCase() }}</span>
+      </button>
+      <ul v-if="open" id="docs-lang-menu" class="docs-popover">
+        <li v-for="a in alternates" :key="a.code">
+          <NuxtLink :to="a.path" :hreflang="a.language" :lang="a.language" :aria-current="a.current ? 'page' : undefined">
+            {{ a.name }}
+            <Icon v-if="a.current" name="lucide:check" class="docs-icon" />
+          </NuxtLink>
+        </li>
+      </ul>
+    </div>
+  </template>
+</template>

package/app/components/DocsNavTree.vue

@@ -0,0 +1,38 @@
+<script setup lang="ts">
+// One level of the side navigation. A node with children gets a toggle button; the branch of the current page
+// starts open, and a reader's own choice holds until the page changes.
+import type { DocNode } from '../lib/docsNav'
+
+const props = defineProps<{ nodes: DocNode[] }>()
+const { t } = useI18n()
+const route = useRoute()
+const choice = reactive(new Map<string, boolean>())
+watch(() => route.path, () => choice.clear())
+
+const holdsCurrent = (node: DocNode): boolean => node.path === route.path || node.children.some(holdsCurrent)
+const isOpen = (node: DocNode) => choice.get(node.path) ?? holdsCurrent(node)
+const toggle = (node: DocNode) => choice.set(node.path, !isOpen(node))
+</script>
+
+<template>
+  <ul class="docs-nav-list">
+    <li v-for="node in props.nodes" :key="node.path">
+      <div class="docs-nav-item">
+        <NuxtLink :to="node.path" :aria-current="node.path === route.path ? 'page' : undefined">
+          <Icon v-if="node.icon" :name="node.icon" class="docs-icon" />
+          <span class="docs-nav-title">{{ node.title }}</span>
+          <span v-if="node.badge" class="docs-badge">{{ node.badge }}</span>
+        </NuxtLink>
+        <button
+          v-if="node.children.length" type="button" class="docs-nav-toggle"
+          :aria-expanded="isOpen(node)" :aria-label="t('docs.toggle', { title: node.title })" @click="toggle(node)"
+        >
+          <Icon name="lucide:chevron-right" class="docs-icon" />
+        </button>
+      </div>
+      <div v-if="node.children.length" v-show="isOpen(node)" class="docs-nav-children">
+        <DocsNavTree :nodes="node.children" />
+      </div>
+    </li>
+  </ul>
+</template>

package/app/components/DocsPage.vue

@@ -0,0 +1,84 @@
+<script setup lang="ts">
+import { docsEditUrl, docsIssueUrl, docsStudioUrl } from '../lib/docsPage'
+import { markdownComponents } from '../lib/markdownComponents'
+// One doc: breadcrumbs, title, lead and page actions, the text with the layer's Markdown components, the edit
+// link and date, previous/next; the table of contents beside it (or in the docs bar, see doc.vue).
+import type { ItemOf } from '@lupinum/ginko'
+import { articleLd, breadcrumbLd } from '@lupinum/ginko/internal'
+import type { docsCollection } from '@lupinum/ginko-docs/config'
+
+// `source` (the page's repository path) is in the bundle because this layer asks for it (hook `ginko:files`, nuxt.config.ts).
+const props = defineProps<{ doc: ItemOf<ReturnType<typeof docsCollection>['fields']> & { source?: string } }>()
+const { t, format, language } = useI18n()
+const { crumbs } = useDocs()
+const neighbors = useGinkoNeighbors('docs', () => props.doc.id)
+const site = useGinkoSite()
+// The Studio link needs the platform address and the site name: internal keys of the Ginko module, read by its own layer.
+const { platform, site: siteName } = useRuntimeConfig().public.ginko as { site: string, platform: string }
+const route = useRoute()
+useGinkoSeo(() => ({
+  title: props.doc.data.title,
+  description: props.doc.data.description,
+  section: props.doc.data.section,
+  type: 'article',
+  jsonLd: [
+    // articleLd fixes the type to Article; docs are TechArticle.
+    { ...articleLd({ title: props.doc.data.title, url: new URL(route.path, site.url).href, description: props.doc.data.description, modified: props.doc.updatedAt, lang: language.value }), '@type': 'TechArticle' },
+    ...(crumbs.value.length > 1 ? [breadcrumbLd(crumbs.value.map((c) => ({ ...c, children: [] })), new URL(site.url).origin)] : []),
+  ],
+}))
+
+const repository = useAppConfig().docs?.repository
+// A page from a file is edited in the repository; one stored on the platform in the Studio.
+const editUrl = computed(() => (props.doc.source ? docsEditUrl(repository, props.doc.source) : docsStudioUrl(platform, siteName, 'docs', props.doc.id)))
+const issueUrl = computed(() => docsIssueUrl(repository, props.doc.data.title, new URL(route.path, site.url).href))
+const updated = computed(() => props.doc.updatedAt && {
+  iso: props.doc.updatedAt,
+  text: format.date(new Date(props.doc.updatedAt), 'long'),
+})
+const toc = computed(() => props.doc.data.body.toc?.links ?? [])
+const top = () => window.scrollTo({ top: 0, behavior: matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth' })
+</script>
+
+<template>
+  <div class="docs-page">
+    <article class="docs-article">
+      <nav v-if="crumbs.length > 1" class="docs-crumbs" :aria-label="t('docs.breadcrumb')">
+        <ol>
+          <li v-for="(c, i) in crumbs" :key="c.path + i">
+            <Icon v-if="i" name="lucide:chevron-right" class="docs-icon" />
+            <span v-if="i === crumbs.length - 1" aria-current="page">{{ c.title }}</span>
+            <NuxtLink v-else :to="c.path">{{ c.title }}</NuxtLink>
+          </li>
+        </ol>
+      </nav>
+      <header class="docs-page-head">
+        <h1>{{ doc.data.title }}</h1>
+        <p v-if="doc.data.description" class="docs-lead">{{ doc.data.description }}</p>
+        <DocsPageActions :path="route.path" :origin="site.url" />
+      </header>
+      <GinkoMarkdown :value="doc.data.body" :components="markdownComponents" class="docs-prose" />
+      <footer>
+        <div v-if="editUrl || updated" class="docs-page-foot">
+          <a v-if="editUrl" :href="editUrl" target="_blank" rel="noopener"><Icon name="lucide:pencil" class="docs-icon" />{{ t('docs.edit') }}</a>
+          <span v-if="updated">{{ t('docs.updated') }} <time :datetime="updated.iso">{{ updated.text }}</time></span>
+        </div>
+        <nav v-if="neighbors.prev || neighbors.next" class="docs-pager" :aria-label="t('docs.pager')">
+          <NuxtLink v-if="neighbors.prev" :to="neighbors.prev.url" rel="prev">
+            <small><Icon name="lucide:arrow-left" class="docs-icon" />{{ t('docs.previous') }}</small>{{ neighbors.prev.data.title }}
+          </NuxtLink>
+          <NuxtLink v-if="neighbors.next" :to="neighbors.next.url" rel="next" class="is-next">
+            <small>{{ t('docs.next') }}<Icon name="lucide:arrow-right" class="docs-icon" /></small>{{ neighbors.next.data.title }}
+          </NuxtLink>
+        </nav>
+      </footer>
+    </article>
+    <DocsToc v-if="toc.length" :links="toc" variant="aside">
+      <div class="docs-toc-more">
+        <a v-if="editUrl" :href="editUrl" target="_blank" rel="noopener"><Icon name="lucide:pencil" class="docs-icon" />{{ t('docs.edit') }}</a>
+        <a v-if="issueUrl" :href="issueUrl" target="_blank" rel="noopener"><Icon name="lucide:circle-alert" class="docs-icon" />{{ t('docs.issue') }}</a>
+        <button type="button" @click="top"><Icon name="lucide:arrow-up" class="docs-icon" />{{ t('docs.top') }}</button>
+      </div>
+    </DocsToc>
+  </div>
+</template>

package/app/components/DocsPageActions.vue

@@ -0,0 +1,47 @@
+<script setup lang="ts">
+import { docsAskLinks, docsMarkdownPath, type DocsAssistant } from '../lib/docsPage'
+// "Copy page" copies the page as Markdown; the menu next to it opens the Markdown twin or a chat that reads it.
+const props = defineProps<{ path: string, origin: string }>()
+const { t } = useI18n()
+const cfg = useAppConfig().docs?.markdownActions ?? {}
+const assistants = {
+  chatgpt: { icon: 'docs:openai', label: 'docs.openChatGpt' },
+  claude: { icon: 'docs:claude', label: 'docs.openClaude' },
+} as const satisfies Record<DocsAssistant, { icon: string, label: string }>
+// Unknown names in `openIn` are skipped, so a typo in app.config.ts hides one entry instead of breaking the menu.
+const openIn = (cfg.openIn ?? ['chatgpt', 'claude']).filter((id) => Object.hasOwn(assistants, id))
+const { open, toggle } = useDocsPopover()
+const mdPath = computed(() => docsMarkdownPath(props.path))
+const links = computed(() => docsAskLinks(t('docs.askPrompt', { url: new URL(mdPath.value, props.origin).href })))
+
+const { state, copy: copyText } = useDocsCopy()
+const copy = () => copyText(() => $fetch<string>(mdPath.value, { responseType: 'text' }))
+const menu = openIn.length > 0
+</script>
+
+<template>
+  <div v-if="cfg.copy !== false || menu" ref="popover" class="docs-actions" role="group" :aria-label="t('docs.pageActions')">
+    <button v-if="cfg.copy !== false" type="button" class="docs-button" @click="copy">
+      <Icon :name="state === 'copied' ? 'lucide:check' : 'lucide:copy'" class="docs-icon" />
+      <span aria-live="polite">{{ state === 'copied' ? t('docs.copied') : state === 'failed' ? t('docs.copyFailed') : t('docs.copyPage') }}</span>
+    </button>
+    <button type="button" class="docs-button" :aria-expanded="open" aria-controls="docs-page-menu" :aria-label="t('docs.moreActions')" @click="toggle">
+      <Icon name="lucide:chevron-down" class="docs-icon" />
+    </button>
+    <ul v-if="open" id="docs-page-menu" class="docs-popover">
+      <li>
+        <a :href="mdPath" target="_blank">
+          <Icon name="lucide:file-text" class="docs-icon" />
+          <span>{{ t('docs.viewMarkdown') }}<small>{{ t('docs.viewMarkdownHint') }}</small></span>
+        </a>
+      </li>
+      <li v-for="id in openIn" :key="id">
+        <a :href="links[id]" target="_blank" rel="noopener">
+          <Icon :name="assistants[id].icon" class="docs-icon" />
+          <span>{{ t(assistants[id].label) }}<small>{{ t('docs.askHint') }}</small></span>
+          <Icon name="lucide:arrow-up-right" class="docs-icon" />
+        </a>
+      </li>
+    </ul>
+  </div>
+</template>

package/app/components/DocsPost.vue

@@ -0,0 +1,58 @@
+<script setup lang="ts">
+import { markdownComponents } from '../lib/markdownComponents'
+// One blog post: title, date, authors, text. Article JSON-LD names the authors and carries both dates.
+import { articleLd } from '@lupinum/ginko/internal'
+import type { Post } from '../lib/blogTypes'
+
+const props = defineProps<{ post: Post }>()
+const { t, language } = useI18n()
+const blog = useDocsBlog()
+const site = useGinkoSite()
+const route = useRoute()
+const authors = computed(() => blog.authorsOf(props.post))
+const absolute = (path: string) => new URL(path, site.url).href
+
+useGinkoSeo(() => {
+  const { title, description, date, image } = props.post.data
+  const ld = articleLd({
+    title, description, lang: language.value, url: absolute(route.path), image: image ? absolute(image.url) : undefined,
+    published: date, modified: (props.post.updatedAt ?? date).slice(0, 10),
+  })
+  return {
+    title, description, type: 'article', image: image?.url,
+    // articleLd takes one author; a post may have several (and a link), so the list replaces it.
+    jsonLd: [authors.value.length ? { ...ld, author: authors.value.map((a) => ({ '@type': 'Person', name: a.data.name, ...(a.data.url ? { url: a.data.url } : {}) })) } : ld],
+  }
+})
+useHead(() => ({ link: [{ rel: 'alternate', type: 'application/rss+xml', title: t('docs.blog'), href: blog.feedPath.value }] }))
+</script>
+
+<template>
+  <div class="docs-blog">
+    <div class="docs-blog-panel">
+      <article class="docs-post">
+        <nav class="docs-crumbs" :aria-label="t('docs.breadcrumb')">
+          <ol>
+            <li><NuxtLink :to="blog.blogPath.value">{{ t('docs.blog') }}</NuxtLink></li>
+            <li><Icon name="lucide:chevron-right" class="docs-icon" /><span aria-current="page">{{ post.data.title }}</span></li>
+          </ol>
+        </nav>
+        <h1>{{ post.data.title }}</h1>
+        <p v-if="post.data.description" class="docs-lead">{{ post.data.description }}</p>
+        <p class="docs-meta">
+          <time :datetime="post.data.date">{{ blog.formatDate(post.data.date) }}</time>
+          <template v-if="authors.length">
+            · {{ t('docs.by') }}
+            <template v-for="(a, i) in authors" :key="a.id">
+              <template v-if="i">, </template>
+              <a v-if="a.data.url" :href="a.data.url" rel="author">{{ a.data.name }}</a>
+              <template v-else>{{ a.data.name }}</template>
+            </template>
+          </template>
+        </p>
+        <GinkoImage v-if="post.data.image" :image="post.data.image" class="docs-post-image" eager />
+        <GinkoMarkdown :value="post.data.body" :components="markdownComponents" class="docs-prose" />
+      </article>
+    </div>
+  </div>
+</template>

package/app/components/DocsSearch.vue

@@ -0,0 +1,134 @@
+<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'
+
+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)
+  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">
+    <Icon 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">
+        <Icon 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"><Icon :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>
+                <Icon 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>