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

package/app/components/DocsBanner.vue

@@ -0,0 +1,29 @@
+<script setup lang="ts">
+// Announcement above the header. The server always renders it; a dismissed one is hidden before first
+// paint by the head script (html[data-docs-banner-off], docs.css) and removed here after hydration.
+import { bannerInitScript, bannerKey } from '../lib/docsInit'
+
+const props = defineProps<{ id: string, href?: string }>()
+const { t } = useI18n()
+const { text, href: siteHref } = useDocsSite()
+useHead({ script: [{ key: 'docs-banner-init', innerHTML: bannerInitScript(props.id), tagPriority: 'critical' }] })
+const dismissed = ref(false)
+onMounted(() => {
+  try { dismissed.value = localStorage.getItem(bannerKey(props.id)) === '1' } catch { /* shown */ }
+})
+
+function dismiss() {
+  dismissed.value = true
+  try { localStorage.setItem(bannerKey(props.id), '1') } catch { /* gone until reload */ }
+}
+</script>
+
+<template>
+  <div v-if="!dismissed" class="docs-banner" role="region" :aria-label="text(`docs.banner.${id}`)">
+    <p>
+      <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"><DocsIcon name="lucide:x" class="docs-icon" /></button>
+  </div>
+</template>

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">
+      <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>
+</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,113 @@
+<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
+// 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
+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 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">
+              <DocsIcon :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"
+        >
+          <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>
+        <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">
+          <DocsThemeToggle segmented />
+        </div>
+      </div>
+    </Teleport>
+  </header>
+</template>

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>

package/app/components/DocsLanding.vue

@@ -0,0 +1,58 @@
+<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()
+// A route link (`$docs.<page>`, `$page.<key>`) follows the reader's language; a path or URL stays as written.
+const { href } = useDocsSite()
+const to = (raw: string) => (raw.startsWith('$') ? href(raw) : raw)
+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="to(l.href)" :target="external(l.href) ? '_blank' : undefined"
+            class="docs-button is-large" :class="i === 0 ? 'is-primary' : 'is-soft'"
+          >
+            {{ l.label }}<DocsIcon 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 ?? '')">
+            <DocsIcon :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">
+            <DocsIcon :name="f.icon" class="docs-icon" />
+          </div>
+          <h2>
+            <NuxtLink v-if="f.href" :to="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,40 @@
+<script setup lang="ts">
+// The languages of this page (ginko-i18n alternates, so a doc links to its own translation), each named in itself
+// ("Deutsch"). In the header a menu; with `list` (the phone menu) a row of links, one tap each. A language without
+// this page says so, in the page's language (`lang` sits on the name only), because its link leads to that language's start page.
+const props = defineProps<{ list?: boolean }>()
+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">
+    <nav v-if="props.list" class="docs-lang-list" :aria-label="t('docs.language')">
+      <NuxtLink v-for="a in alternates" :key="a.code" :to="a.path" :hreflang="a.language" :aria-current="a.current ? 'page' : undefined">
+        <span :lang="a.language">{{ a.name }}</span>
+        <small v-if="!a.translated">{{ t('docs.untranslated') }}</small>
+      </NuxtLink>
+    </nav>
+    <div v-else 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"
+      >
+        <DocsIcon 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" :aria-current="a.current ? 'page' : undefined">
+            <span>
+              <span :lang="a.language">{{ a.name }}</span>
+              <small v-if="!a.translated">{{ t('docs.untranslated') }}</small>
+            </span>
+            <DocsIcon v-if="a.current" name="lucide:check" class="docs-icon" />
+          </NuxtLink>
+        </li>
+      </ul>
+    </div>
+  </template>
+</template>

package/app/components/DocsNavSheet.vue

@@ -0,0 +1,37 @@
+<script setup lang="ts">
+// The docs navigation on phones when a site's layout holds the docs (in the layer's own frame the header menu has it):
+// a sheet from the start edge. A native modal dialog: focus stays inside, Escape and a tap beside it close it, and the
+// page behind cannot be reached. It closes on navigation and when the window grows to the sidebar width.
+const open = defineModel<boolean>('open', { required: true })
+const { t } = useI18n()
+const route = useRoute()
+const dialog = useTemplateRef<HTMLDialogElement>('dialog')
+const wide = import.meta.client ? matchMedia('(min-width: 64rem)') : undefined
+const onWide = () => { if (wide?.matches) open.value = false }
+
+watch(open, (value) => {
+  if (value) {
+    dialog.value?.showModal()
+    wide?.addEventListener('change', onWide)
+  } else {
+    dialog.value?.close()
+    wide?.removeEventListener('change', onWide)
+  }
+})
+watch(() => route.fullPath, () => { open.value = false })
+onBeforeUnmount(() => wide?.removeEventListener('change', onWide))
+</script>
+
+<template>
+  <dialog ref="dialog" class="docs-nav-sheet" :aria-label="t('docs.nav')" @close="open = false" @click.self="open = false">
+    <div class="docs-nav-sheet-head">
+      <p>{{ t('docs.contents') }}</p>
+      <button type="button" class="docs-icon-button" :aria-label="t('docs.close')" @click="open = false">
+        <DocsIcon name="lucide:x" class="docs-icon" />
+      </button>
+    </div>
+    <div class="docs-nav-sheet-body">
+      <DocsSidebar />
+    </div>
+  </dialog>
+</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">
+          <DocsIcon 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)"
+        >
+          <DocsIcon 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,88 @@
+<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 { breadcrumbJsonLd, type ItemOf } from '@lupinum/ginko'
+import { articleLd } 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 langOf = useGinkoLang()
+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 ? [breadcrumbJsonLd(crumbs.value, site.url)] : []),
+  ],
+}))
+
+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'),
+})
+// The toc comes with the text (page state holds only its ref); the same request as <GinkoMarkdown> below.
+const tree = await useGinkoMarkdown(() => props.doc.data.body)
+const toc = computed(() => tree.value?.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">
+            <DocsIcon 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" :lang="langOf(doc, 'description')">{{ doc.data.description }}</p>
+        <DocsPageActions :path="route.path" :origin="site.url" />
+      </header>
+      <GinkoMarkdown :value="doc.data.body" :components="markdownComponents" class="docs-prose" />
+      <DocsPageEnd :doc="doc" />
+      <footer>
+        <div v-if="editUrl || updated" class="docs-page-foot">
+          <a v-if="editUrl" :href="editUrl" target="_blank" rel="noopener"><DocsIcon 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><DocsIcon 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') }}<DocsIcon 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"><DocsIcon name="lucide:pencil" class="docs-icon" />{{ t('docs.edit') }}</a>
+        <a v-if="issueUrl" :href="issueUrl" target="_blank" rel="noopener"><DocsIcon name="lucide:circle-alert" class="docs-icon" />{{ t('docs.issue') }}</a>
+        <button type="button" @click="top"><DocsIcon 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">
+      <DocsIcon :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">
+      <DocsIcon 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">
+          <DocsIcon 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">
+          <DocsIcon :name="assistants[id].icon" class="docs-icon" />
+          <span>{{ t(assistants[id].label) }}<small>{{ t('docs.askHint') }}</small></span>
+          <DocsIcon name="lucide:arrow-up-right" class="docs-icon" />
+        </a>
+      </li>
+    </ul>
+  </div>
+</template>

package/app/components/DocsPageEnd.ts

@@ -0,0 +1,12 @@
+import type { PropType } from 'vue'
+import type { ItemOf } from '@lupinum/ginko'
+import type { docsCollection } from '@lupinum/ginko-docs/config'
+
+// Override point: after the text of every docs page, before "Edit this page" and the pager. Renders nothing here; a
+// site puts its own `components/DocsPageEnd.vue` (same name, prop `doc`) in its app to show a support box or a call
+// to action. A render function, not an empty <template>: server and browser then agree on the empty placeholder.
+export default defineComponent({
+  name: 'DocsPageEnd',
+  props: { doc: { type: Object as PropType<ItemOf<ReturnType<typeof docsCollection>['fields']>>, required: true } },
+  render: () => null,
+})

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. BlogPosting JSON-LD names the authors and carries both dates.
+import { postJsonLd } from '@lupinum/ginko/basics'
+import type { Post } from '../lib/blogTypes'
+
+const props = defineProps<{ post: Post }>()
+const { t, language } = useI18n()
+const blog = useDocsBlog()
+const langOf = useGinkoLang()
+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, tags } = props.post.data
+  return {
+    title, description, type: 'article', image: image?.url,
+    jsonLd: [postJsonLd({
+      title, description, lang: language.value, url: absolute(route.path), image: image ? absolute(image.url) : undefined,
+      date, modified: (props.post.updatedAt ?? date).slice(0, 10),
+      authors: authors.value.map((a) => a.data), tags: tags?.map((item) => item.tag),
+    })],
+  }
+})
+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><DocsIcon 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" :lang="langOf(post, 'description')">{{ 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>