@lupinum/ginko-docs 0.4.0 → 0.6.0

package/app/components/DocsLanding.vue

@@ -13,6 +13,9 @@ 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>
 
@@ -24,26 +27,26 @@ const external = (href: string) => /^https?:\/\//.test(href)
         <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"
+            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 }}<Icon v-if="i === 0" name="lucide:arrow-right" class="docs-icon" />
+            {{ 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 ?? '')">
-            <Icon :name="state === 'copied' ? 'lucide:check' : 'lucide:copy'" class="docs-icon" />
+            <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">
-            <Icon :name="f.icon" class="docs-icon" />
+            <DocsIcon :name="f.icon" class="docs-icon" />
           </div>
           <h2>
-            <NuxtLink v-if="f.href" :to="f.href">{{ f.title }}</NuxtLink>
+            <NuxtLink v-if="f.href" :to="to(f.href)">{{ f.title }}</NuxtLink>
             <template v-else>{{ f.title }}</template>
           </h2>
           <p>{{ f.description }}</p>

package/app/components/DocsLanguage.vue

@@ -1,6 +1,8 @@
 <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").
+// 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))
@@ -8,19 +10,28 @@ const current = computed(() => alternates.value.find((a) => a.current))
 
 <template>
   <template v-if="alternates.length > 1">
-    <div ref="popover" class="docs-lang">
+    <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"
       >
-        <Icon name="lucide:languages" class="docs-icon" />
+        <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" :lang="a.language" :aria-current="a.current ? 'page' : undefined">
-            {{ a.name }}
-            <Icon v-if="a.current" name="lucide:check" class="docs-icon" />
+          <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>

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

@@ -19,7 +19,7 @@ const toggle = (node: DocNode) => choice.set(node.path, !isOpen(node))
     <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" />
+          <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>
@@ -27,7 +27,7 @@ const toggle = (node: DocNode) => choice.set(node.path, !isOpen(node))
           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" />
+          <DocsIcon name="lucide:chevron-right" class="docs-icon" />
         </button>
       </div>
       <div v-if="node.children.length" v-show="isOpen(node)" class="docs-nav-children">

package/app/components/DocsPage.vue

@@ -3,14 +3,15 @@ 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 { 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.
@@ -24,7 +25,7 @@ useGinkoSeo(() => ({
   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)] : []),
+    ...(crumbs.value.length > 1 ? [breadcrumbJsonLd(crumbs.value, site.url)] : []),
   ],
 }))
 
@@ -36,7 +37,9 @@ 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 ?? [])
+// 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>
 
@@ -46,7 +49,7 @@ const top = () => window.scrollTo({ top: 0, behavior: matchMedia('(prefers-reduc
       <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" />
+            <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>
@@ -54,30 +57,31 @@ const top = () => window.scrollTo({ top: 0, behavior: matchMedia('(prefers-reduc
       </nav>
       <header class="docs-page-head">
         <h1>{{ doc.data.title }}</h1>
-        <p v-if="doc.data.description" class="docs-lead">{{ doc.data.description }}</p>
+        <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"><Icon name="lucide:pencil" class="docs-icon" />{{ t('docs.edit') }}</a>
+          <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><Icon name="lucide:arrow-left" class="docs-icon" />{{ t('docs.previous') }}</small>{{ neighbors.prev.data.title }}
+            <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') }}<Icon name="lucide:arrow-right" class="docs-icon" /></small>{{ neighbors.next.data.title }}
+            <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"><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>
+        <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>

package/app/components/DocsPageActions.vue

@@ -22,24 +22,24 @@ const menu = openIn.length > 0
 <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" />
+      <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">
-      <Icon name="lucide:chevron-down" class="docs-icon" />
+      <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">
-          <Icon name="lucide:file-text" class="docs-icon" />
+          <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">
-          <Icon :name="assistants[id].icon" class="docs-icon" />
+          <DocsIcon :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" />
+          <DocsIcon name="lucide:arrow-up-right" class="docs-icon" />
         </a>
       </li>
     </ul>

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

@@ -1,27 +1,27 @@
 <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'
+// 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 } = 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),
-  })
+  const { title, description, date, image, tags } = props.post.data
   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],
+    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 }] }))
@@ -34,11 +34,11 @@ useHead(() => ({ link: [{ rel: 'alternate', type: 'application/rss+xml', title:
         <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>
+            <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">{{ post.data.description }}</p>
+        <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">

package/app/components/DocsSearch.vue

@@ -3,6 +3,8 @@
 // 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')
@@ -79,21 +81,21 @@ function onKey(e: KeyboardEvent) {
 }
 onMounted(() => {
   mac.value = /Mac|iPhone|iPad/.test(navigator.platform)
-  window.addEventListener('keydown', onKey)
+  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">
-    <Icon name="lucide:search" class="docs-icon" />
+    <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">
-        <Icon name="lucide:search" class="docs-icon" />
+        <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"
@@ -111,12 +113,12 @@ onBeforeUnmount(() => window.removeEventListener('keydown', onKey))
                 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-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>
-                <Icon name="lucide:corner-down-left" class="docs-icon docs-search-enter" />
+                <DocsIcon name="lucide:corner-down-left" class="docs-icon docs-search-enter" />
               </li>
             </ul>
           </li>

package/app/components/DocsShell.vue

@@ -1,20 +1,36 @@
 <script setup lang="ts">
-// The docs body: the navigation on the side and the page next to it. On phones the navigation lives in the
-// header's menu (DocsHeader); the bar above the page holds the page's own controls (slot `bar`, the table of
-// contents). It needs no header of its own, so it works in the standalone frame and inside a site's layout alike.
+// 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

@@ -1,6 +1,6 @@
 <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. Used in the sidebar and in the phone menu.
+// 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>
@@ -14,5 +14,6 @@ const { tabs, activeTab, sections } = useDocs()
       <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/DocsThemeToggle.vue

@@ -38,8 +38,8 @@ const OPTIONS = ['auto', 'light', 'dark'] as const
   <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" :aria-label="t('docs.theme.toggle')" :title="t('docs.theme.toggle')" @click="toggle">
-    <Icon name="lucide:moon" class="docs-icon docs-when-light" />
-    <Icon name="lucide:sun" class="docs-icon docs-when-dark" />
+  <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

@@ -48,7 +48,7 @@ const title = computed(() => flat.value.find((l) => l.id === current.value)?.tex
 <template>
   <nav v-if="props.variant === 'aside'" ref="aside" class="docs-toc" :aria-label="t('docs.onThisPage')">
     <p class="docs-toc-title">
-      <Icon name="lucide:text-align-start" class="docs-icon" />{{ t('docs.onThisPage') }}
+      <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">
@@ -60,7 +60,7 @@ const title = computed(() => flat.value.find((l) => l.id === current.value)?.tex
   <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>
-      <Icon name="lucide:chevron-down" class="docs-icon" />
+      <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">

package/app/composables/useDocs.ts

@@ -46,7 +46,8 @@ export function useDocs() {
   const { localePath } = useI18n()
   const { mainLocale } = useGinkoSite()
   const route = (schema.bricks.docs as { route?: Record<string, string> } | undefined)?.route?.[mainLocale]
-  const base = computed(() => localePath(route?.replace(/\/\[slug\]$/, '') ?? '/docs'))
+  const mainBase = route?.replace(/\/\[slug\]$/, '') ?? '/docs'
+  const base = computed(() => localePath(mainBase))
 
-  return { nodes, tabs, activeTab, sections, crumbs, first, base }
+  return { nodes, tabs, activeTab, sections, crumbs, first, base, mainBase }
 }

package/app/composables/useDocsBlog.ts

@@ -1,7 +1,6 @@
 // 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 { BLOG_PATH, CHANGELOG_PATH } from '../../shared/paths'
 import type { Author, ChangelogEntry, Post } from '../lib/blogTypes'
 
 
@@ -10,8 +9,10 @@ const read = <T>(brick: string) => (useGinko as unknown as (b: string) => Comput
 
 export function useDocsBlog() {
   const { localePath } = useI18n()
-  const hasPosts = has('posts')
-  const hasChangelog = has('changelog')
+  // 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) ?? [])
@@ -22,11 +23,11 @@ export function useDocsBlog() {
   const isDraft = (post: Post) => 'draft' in post.data && post.data.draft === true
   return {
     hasPosts, hasChangelog, authorsOf, isDraft, formatDate,
-    blogPath: computed(() => localePath(BLOG_PATH)),
-    feedPath: computed(() => localePath(`${BLOG_PATH}/rss.xml`)),
-    changelogPath: computed(() => localePath(CHANGELOG_PATH)),
+    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) => ComputedRef<Post>)('posts', slug),
+    post: (slug: string) => (useGinkoEntry as unknown as (b: string, s: string) => Readonly<Ref<Post>>)('posts', slug),
   }
 }

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/useDocsSite.ts

@@ -1,10 +1,31 @@
-// The site's own entries in app.config (nav, footer and banner links): their texts and their addresses.
+// 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 internal path in the reader's language; an absolute URL, a mail link or an anchor stays as written. */
-    href: (raw: string) => (raw.startsWith('/') && !raw.startsWith('//') ? localePath(raw) : raw),
+    /**
+     * 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

@@ -1,9 +1,17 @@
 <script setup lang="ts">
 // The blog: all posts, newest first (the collection's order).
-const { t } = useI18n()
+const { t, language } = useI18n()
 const blog = useDocsBlog()
+const langOf = useGinkoLang()
 const posts = blog.posts()
-useGinkoSeo(() => ({ title: t('docs.blog'), description: t('docs.blogLead') }))
+// 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
@@ -17,7 +25,7 @@ if (import.meta.server) useResponseHeader('x-nitro-prerender').value = blog.feed
           <h1>{{ t('docs.blog') }}</h1>
           <p class="docs-lead">{{ t('docs.blogLead') }}</p>
         </div>
-        <a :href="blog.feedPath.value" type="application/rss+xml"><Icon name="lucide:rss" class="docs-icon" />{{ t('docs.rss') }}</a>
+        <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">
@@ -35,7 +43,7 @@ if (import.meta.server) useResponseHeader('x-nitro-prerender').value = blog.feed
               <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">{{ post.data.description }}</p>
+            <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>