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

package/app/docs-pages/index.vue

@@ -0,0 +1,12 @@
+<script setup lang="ts">
+import { toFirstDoc } from '../lib/docsFirst'
+// The start page: the site's `home` brick (docsHome) when it has one, otherwise the first docs page.
+import schema from '#ginko/schema'
+
+const hasHome = Object.hasOwn(schema.bricks, 'home')
+if (!hasHome) await toFirstDoc()
+</script>
+
+<template>
+  <DocsLanding v-if="hasHome" />
+</template>

package/app/docs-pages/post.vue

@@ -0,0 +1,8 @@
+<script setup lang="ts">
+const blog = useDocsBlog()
+const post = blog.post(String(useRoute().params.slug))
+</script>
+
+<template>
+  <DocsPost :post="post" />
+</template>

package/app/error.vue

@@ -1,121 +1,44 @@
 <script setup lang="ts">
-import { localizedRoutes } from "../i18n/routes";
-import { messages } from "../i18n/messages/index";
-import { normalizeAppError } from "./lib/errors";
-import { computed } from "vue";
-import { clearError, useHead } from "#imports";
-import { localeFromPath, localizedPath } from "../i18n/locales";
-
-type NuxtErrorLike = {
-  message?: string;
-  status?: number;
-  statusCode?: number;
-  statusMessage?: string;
-  statusText?: string;
-  url?: string;
-};
-
-const props = defineProps<{
-  error: NuxtErrorLike;
-}>();
-
-const normalized = computed(() => normalizeAppError(props.error));
-const requestPath = computed(
-  () => props.error?.url || (import.meta.client ? window.location.pathname : "/"),
-);
-const locale = computed(() => localeFromPath(requestPath.value));
-const copy = computed(() => {
-  const catalog = messages[locale.value].errors;
-  return catalog[normalized.value.kind] ?? catalog.unavailable;
-});
-const homePath = computed(() => localizedPath(locale.value, localizedRoutes[locale.value].home));
-const docsPath = computed(() => localizedPath(locale.value, localizedRoutes[locale.value].docs));
-const title = computed(() => `${normalized.value.statusCode} - ${copy.value.title}`);
-// Keep the full site chrome for content-level errors (404 and friends); hard
-// server failures fall back to the bare page so the error screen cannot crash.
-const showChrome = computed(() => normalized.value.kind !== "server");
-
-useHead(() => ({
-  title: title.value,
-  meta: [{ name: "robots", content: "noindex, nofollow" }],
-}));
-
-const handleError = () => clearError({ redirect: homePath.value });
+// Not found and other errors, inside the site's frame (the layer's layout, or the site's own). A site with its own
+// error.vue replaces this one.
+import type { NuxtError } from '#app'
+import { docsMainLanguagePath } from './lib/docsPage'
+
+const props = defineProps<{ error: NuxtError }>()
+const { t, localePath, locales, locale } = useI18n()
+const docs = useDocs()
+const route = useRoute()
+const { mainLocale } = useGinkoSite()
+const notFound = computed(() => props.error.statusCode === 404)
+useGinkoSeo(() => ({ title: notFound.value ? t('docs.notFound.title') : t('docs.error.title'), noindex: true }))
+// A 404 under another language's docs address offers the same address in the main language, named in itself. It is a
+// guess (the slug may differ there); the language menu covers the normal way.
+const mainPage = computed(() => {
+  const path = notFound.value ? docsMainLanguagePath(route.path, locales.map((l) => l.code), mainLocale, docs.mainBase, (p) => localePath(p, mainLocale)) : undefined
+  if (!path) return undefined
+  // The language's name in the reader's language; the locale's own name if the runtime does not know the code.
+  const fallback = locales.find((l) => l.code === mainLocale)?.name ?? mainLocale
+  let language = fallback
+  try { language = new Intl.DisplayNames([locale.value], { type: 'language' }).of(mainLocale) ?? fallback } catch { /* keep the fallback */ }
+  return { path, language }
+})
+// Links work without JavaScript; with it, clearError leaves the error state and navigates.
+const leave = (to: string) => clearError({ redirect: to })
 </script>
 
 <template>
-  <div class="flex min-h-dvh flex-col bg-background text-foreground">
-    <template v-if="showChrome">
-      <SiteSkipLink />
-      <SiteHeader />
-    </template>
-    <main id="main-content" class="flex flex-1 items-center justify-center px-4 py-24">
-      <section class="w-full max-w-xl text-center">
-        <p
-          class="mb-6 text-8xl leading-none font-bold text-primary/20 select-none"
-          aria-hidden="true"
-        >
-          {{ normalized.statusCode }}
-        </p>
-
-        <h1 class="mb-4 text-3xl font-semibold tracking-tight text-foreground sm:text-4xl">
-          {{ copy.title }}
-        </h1>
-        <p class="mx-auto mb-8 max-w-md leading-7 text-muted-foreground">
-          {{ copy.description }}
-        </p>
-
-        <div class="flex flex-col items-center justify-center gap-3 sm:flex-row">
-          <button class="error-action error-action-primary" type="button" @click="handleError">
-            {{ messages[locale].errors.actions.home }}
-          </button>
-          <a class="error-action error-action-secondary" :href="docsPath">
-            {{ messages[locale].errors.actions.docs }}
-          </a>
+  <NuxtLayout>
+    <div class="docs-error">
+      <div>
+        <p class="docs-error-code">{{ error.statusCode }}</p>
+        <h1>{{ notFound ? t('docs.notFound.title') : t('docs.error.title') }}</h1>
+        <p>{{ notFound ? t('docs.notFound.text') : t('docs.error.text') }}</p>
+        <div class="docs-error-actions">
+          <a :href="localePath('/')" class="docs-button is-large is-primary" @click.prevent="leave(localePath('/'))">{{ t('docs.notFound.home') }}</a>
+          <a v-if="docs.first.value" :href="docs.first.value" class="docs-button is-large is-soft" @click.prevent="leave(docs.first.value)">{{ t('docs.docs') }}</a>
+          <a v-if="mainPage" :href="mainPage.path" class="docs-button is-large is-soft" @click.prevent="leave(mainPage.path)">{{ t('docs.notFound.mainLanguage', { language: mainPage.language }) }}</a>
         </div>
-      </section>
-    </main>
-    <SiteFooter v-if="showChrome" />
-  </div>
+      </div>
+    </div>
+  </NuxtLayout>
 </template>
-
-<style scoped>
-.error-action {
-  align-items: center;
-  border-radius: 0.375rem;
-  display: inline-flex;
-  font-size: 0.875rem;
-  font-weight: 500;
-  height: 2.5rem;
-  justify-content: center;
-  padding-inline: 1rem;
-  transition:
-    background-color 150ms,
-    color 150ms,
-    border-color 150ms;
-}
-
-.error-action:focus-visible {
-  outline: 2px solid var(--ring);
-  outline-offset: 2px;
-}
-
-.error-action-primary {
-  background: var(--primary);
-  color: var(--primary-foreground);
-}
-
-.error-action-primary:hover {
-  opacity: 0.9;
-}
-
-.error-action-secondary {
-  background: var(--background);
-  border: 1px solid var(--input);
-}
-
-.error-action-secondary:hover {
-  background: var(--accent);
-  color: var(--accent-foreground);
-}
-</style>

package/app/layouts/default.vue

@@ -1,12 +1,34 @@
+<script setup lang="ts">
+// The standalone frame: banner, header, page, footer. A site with its own `layouts/default.vue` replaces it, and
+// the docs pages then sit inside the site's frame (the docs body, DocsShell, works either way).
+const { t } = useI18n()
+const { theme, banner } = useAppConfig().docs ?? {}
+provideDocsStandalone()
+useHead({
+  // `docs-standalone` turns on the page background, font and color-scheme (docs.css); embedded, the site owns those.
+  htmlAttrs: { class: 'docs-standalone', 'data-docs-theme': theme && theme !== 'default' ? theme : undefined },
+  // Inter comes with the page instead of after the stylesheet: text set in the fallback re-wraps when the font
+  // arrives late and pushes the page down (layout shift).
+  link: [{ rel: 'preload', as: 'font', type: 'font/woff2', href: '/_docs/fonts/inter-latin-wght-normal.woff2', crossorigin: '' }],
+})
+// "Skip to content" goes past the docs navigation to the page itself when the page has one (DocsShell), else to main.
+function skip(event: MouseEvent) {
+  const target = document.getElementById('docs-content') ?? document.getElementById('docs-main')
+  if (!target) return
+  event.preventDefault()
+  target.focus()
+  target.scrollIntoView()
+}
+</script>
+
 <template>
-  <div class="flex min-h-dvh flex-col bg-background text-foreground">
-    <SiteSkipLink />
-    <SiteBanner landing />
-    <SiteHeader />
-    <main id="main-content" class="flex-1">
+  <div class="docs-frame">
+    <a class="docs-skip" href="#docs-main" @click="skip">{{ t('docs.skip') }}</a>
+    <DocsBanner v-if="banner" :id="banner.id" :href="banner.href" />
+    <DocsHeader />
+    <main id="docs-main" class="docs-frame-main" tabindex="-1">
       <slot />
     </main>
-    <SiteFooter />
-    <SiteInteractionLayer />
+    <DocsFooter />
   </div>
 </template>

package/app/lib/blogTypes.ts

@@ -0,0 +1,8 @@
+// Types of the blog and changelog entries. Kept out of `composables/` so that they are not auto-imported into the host app.
+import type { ItemOf } from '@lupinum/ginko'
+import type { blogCollections, changelogCollection } from '@lupinum/ginko-docs/config'
+
+type Blog = ReturnType<typeof blogCollections>
+export type Post = ItemOf<Blog['posts']['fields']> & { url?: string }
+export type Author = ItemOf<Blog['authors']['fields']>
+export type ChangelogEntry = ItemOf<ReturnType<typeof changelogCollection>['fields']>

package/app/lib/docsFirst.ts

@@ -0,0 +1,11 @@
+import { useDocs } from '../composables/useDocs'
+
+/**
+ * Leads to the first docs page of the language. A site without any docs page yet gets a 404 instead: a redirect to
+ * `/` would loop, because `/` leads here when the site has no start page.
+ */
+export function toFirstDoc() {
+  const first = useDocs().first.value
+  if (!first) throw createError({ statusCode: 404, statusMessage: 'No docs page yet: add a Markdown file to content/docs/.' })
+  return navigateTo(first, { redirectCode: 302 })
+}

package/app/lib/docsInit.ts

@@ -0,0 +1,18 @@
+// Storage keys and the head scripts of the color-mode switch and the banner. Each component adds its own script
+// (useHead with a fixed key, so two toggles on one page add it once), so they also work inside a site's own layout.
+export const COLOR_KEY = 'docs-color-mode'
+export const bannerKey = (id: string) => `docs-banner:${id}`
+
+// Runs inline in <head>, before first paint. localStorage can throw (private windows, blocked site data); then the
+// page simply follows the system and shows the banner.
+const guarded = (body: string) => `(function(){try{var d=document.documentElement;${body}}catch(e){}})()`
+
+/** Applies the stored light/dark choice (html[data-theme]) before first paint. */
+export function colorInitScript(): string {
+  return guarded(`var m=localStorage.getItem(${JSON.stringify(COLOR_KEY)});if(m==='light'||m==='dark')d.setAttribute('data-theme',m);`)
+}
+
+/** Marks a dismissed banner (html[data-docs-banner-off]) before first paint, so it does not flash. */
+export function bannerInitScript(id: string): string {
+  return guarded(`if(localStorage.getItem(${JSON.stringify(bannerKey(id))})==='1')d.setAttribute('data-docs-banner-off','');`)
+}

package/app/lib/docsNav.ts

@@ -0,0 +1,36 @@
+// Tabs and sections of the side navigation, from the entries' fields. Pure, so the rules have a test.
+import type { NavNode } from '@lupinum/ginko'
+
+export interface DocNode extends NavNode {
+  section?: string
+  badge?: string
+  icon?: string
+  tab?: string
+  children: DocNode[]
+}
+export interface DocTab { title: string; path: string }
+
+export interface DocFields { tab?: string; section?: string; badge?: string; icon?: string }
+
+/**
+ * A root without a tab follows the one before it; a new tab starts without a section; a section runs until the
+ * next one. Children always follow their parent's tab and carry no section.
+ */
+export function enrichNav(tree: NavNode[], fieldsOf: (id: string) => DocFields | undefined): DocNode[] {
+  let running: string | undefined
+  let section: string | undefined
+  const enrich = (node: NavNode, tab: string | undefined, root: boolean): DocNode => {
+    const data = fieldsOf(node.id ?? '')
+    if (root) {
+      if (data?.tab && data.tab !== running) section = undefined
+      running = data?.tab ?? running
+      section = data?.section ?? section
+    }
+    const own = root ? running : tab
+    return {
+      ...node, tab: own, section: root ? section : undefined, badge: data?.badge, icon: data?.icon,
+      children: node.children.map((c) => enrich(c, own, false)),
+    }
+  }
+  return tree.map((n) => enrich(n, undefined, true))
+}

package/app/lib/docsPage.ts

@@ -0,0 +1,84 @@
+// Small pure helpers of the docs page (edit link, Markdown twin, "open in" links), kept apart for tests.
+
+/** Edit link of a page's file. Template placeholders: `{url}`, `{branch}`, `{source}`; default is the GitHub form. */
+export function docsEditUrl(repo: { url: string, branch?: string, editUrl?: string } | undefined, source: string | undefined): string | undefined {
+  if (!repo?.url || !source) return undefined
+  const values: Record<string, string> = { url: repo.url.replace(/\/+$/, ''), branch: repo.branch ?? 'main', source }
+  return (repo.editUrl ?? '{url}/edit/{branch}/{source}').replace(/\{(url|branch|source)\}/g, (_, k: string) => values[k]!)
+}
+
+/**
+ * Edit link of a page stored on the Ginko platform: its form in the Studio, `<platform>/s/<site>/all/<brick>/<id>`.
+ * No platform address (a production build without NUXT_PUBLIC_GINKO_PLATFORM): no link.
+ */
+export function docsStudioUrl(platform: string | undefined, site: string, brick: string, id: string): string | undefined {
+  if (!platform) return undefined
+  return `${platform.replace(/\/+$/, '')}/s/${[site, 'all', brick, id].map(encodeURIComponent).join('/')}`
+}
+
+/**
+ * "Report an issue" for a page. Placeholders: `{url}`, `{title}`, `{page}` (the page's address), URL-encoded except
+ * `{url}`. GitHub repositories get the GitHub form by default; other hosts need `issueUrl`.
+ */
+export function docsIssueUrl(repo: { url: string, issueUrl?: string } | undefined, title: string, page: string): string | undefined {
+  if (!repo?.url) return undefined
+  const url = repo.url.replace(/\/+$/, '')
+  const template = repo.issueUrl ?? (/^https:\/\/github\.com\//.test(url) ? '{url}/issues/new?title={title}&body={page}' : undefined)
+  const values: Record<string, string> = { url, title: encodeURIComponent(title), page: encodeURIComponent(page) }
+  return template?.replace(/\{(url|title|page)\}/g, (_, k: string) => values[k]!)
+}
+
+/** Path of a page's Markdown twin (`/en/docs/x` -> `/en/docs/x.md`, `/` -> `/index.md`). */
+export function docsMarkdownPath(path: string): string {
+  const clean = path.replace(/\/+$/, '')
+  return `${clean || '/index'}.md`
+}
+
+/** A chat the page menu can open the page in (`markdownActions.openIn`). */
+export type DocsAssistant = 'chatgpt' | 'claude'
+
+/** Links that open a chat with a prompt pointing at the page's Markdown. */
+export function docsAskLinks(prompt: string): Record<DocsAssistant, string> {
+  const q = encodeURIComponent(prompt)
+  return { chatgpt: `https://chatgpt.com/?q=${q}`, claude: `https://claude.ai/new?q=${q}` }
+}
+
+/**
+ * The main-language address of the docs page `ref`, from the brick's route (`/docs/[slug]`). For a page the current
+ * language lacks: the reader's bundle does not hold it, so this is how its link still leads to the main-language page,
+ * as in Markdown (core's `routeTarget`). Undefined when the route has no `[slug]`. Without the main-language entries
+ * this takes `ref` as the main-language slug: right for links by file name while the main file keeps the slug made
+ * from it; a main file with its own `slug:` or a typo gives a 404 here, where core would report the link.
+ */
+export function docsMainPath(route: Partial<Record<string, string>> | undefined, mainLocale: string, ref: string): string | undefined {
+  const pattern = route?.[mainLocale]
+  return pattern?.includes('[slug]') ? pattern.replace('[slug]', ref) : undefined
+}
+
+/**
+ * A route link outside Markdown (the start page's links and cards, `nav`, `footer.links`, `banner.href`):
+ * `$docs.<page>` names a docs page by its file name or slug, `$page.<key>` a page of `pages` in ginko.config.ts; an
+ * `#anchor` is kept. The same notation as in Markdown, so the link follows the reader's language and survives a
+ * changed slug. Undefined when `raw` is no route link or names nothing.
+ */
+export function docsRouteLink(raw: string, find: { doc: (ref: string) => string | undefined, page: (key: string) => string | undefined }): string | undefined {
+  const match = /^\$(docs|page)\.([^#]+)(#.*)?$/.exec(raw)
+  if (!match) return undefined
+  const path = match[1] === 'docs' ? find.doc(match[2]!) : find.page(match[2]!)
+  return path === undefined ? undefined : path + (match[3] ?? '')
+}
+
+/**
+ * The main-language address for a docs address in another language (`/de/docs/x` gives `/docs/x`), or undefined when
+ * `path` is not under a non-main locale prefix and the main docs base. `resolve` turns the stripped path into the
+ * main language's real address (the site's i18n strategy decides whether it carries a prefix). A guess: the slug may be German and then
+ * 404 again, like `docsMainPath`; the bundle holds no main-language data to check it.
+ */
+export function docsMainLanguagePath(path: string, locales: readonly string[], mainLocale: string, mainBase: string, resolve: (path: string) => string = (p) => p): string | undefined {
+  for (const code of locales) {
+    if (code === mainLocale || !path.startsWith(`/${code}/`)) continue
+    const rest = path.slice(code.length + 1)
+    return rest.startsWith(`${mainBase}/`) ? resolve(rest) : undefined
+  }
+  return undefined
+}

package/app/lib/markdownComponents.ts

@@ -0,0 +1,15 @@
+// Math, mermaid and ```md preview examples for the docs layer. GinkoMarkdown shows their source by default (core stays free of KaTeX);
+// a `components` map wins. Both load lazily, so a page without a formula or a diagram never loads KaTeX or mermaid.
+// Math renders on the server (the HTML holds `.katex`); mermaid renders in the browser.
+import { defineAsyncComponent } from 'vue'
+import DocsTable from '../components/DocsTable.vue'
+
+export const markdownComponents = {
+  math: defineAsyncComponent(async () => {
+    const [, { Math }] = await Promise.all([import('katex/dist/katex.min.css'), import('@comark/vue/plugins/math')])
+    return Math
+  }),
+  mermaid: defineAsyncComponent(() => import('@comark/vue/plugins/mermaid').then((m) => m.Mermaid)),
+  example: defineAsyncComponent(() => import('../components/DocsExample.vue')),
+  table: DocsTable,
+}

package/app/lib/previewToc.ts

@@ -0,0 +1,18 @@
+// The table of contents of a ```md preview: ginko-content keeps only the preview's nodes, so an `::inline-toc`
+// inside a preview gets its links from here. Same shape as the page toc: h2 links with their h3 as children.
+import type { MarkdownToc, TocLink } from '@lupinum/ginko'
+
+type Node = string | [string, Record<string, unknown>, ...unknown[]]
+const textOf = (node: Node): string => (typeof node === 'string' ? node : (node.slice(2) as Node[]).map(textOf).join(''))
+
+export function previewToc(nodes: readonly unknown[]): MarkdownToc {
+  const links: TocLink[] = []
+  for (const node of nodes as Node[]) {
+    if (typeof node === 'string' || (node[0] !== 'h2' && node[0] !== 'h3') || typeof node[1].id !== 'string') continue
+    const link: TocLink = { id: node[1].id, depth: node[0] === 'h2' ? 2 : 3, text: textOf(node).trim() }
+    const parent = links.at(-1)
+    if (link.depth === 3 && parent?.depth === 2) (parent.children ??= []).push(link)
+    else links.push(link)
+  }
+  return { links }
+}