@lupinum/ginko-docs 0.2.2 → 0.2.5

package/server/utils/blog-feed.ts

@@ -0,0 +1,49 @@
+import type { H3Event } from "h3";
+import { createError, setHeader } from "h3";
+import { many } from "@lupinum/ginko-content/server";
+import { useAppConfig, useRuntimeConfig } from "#imports";
+import { blog } from "../../i18n/messages/global/blog";
+import { locales, localizedPath, type LocaleCode } from "../../i18n/locales";
+import { routeSlugs } from "../../shared/route-slugs";
+import { getLocalizedSiteText } from "../../app/config/site.utils";
+import { buildRssFeed } from "./feed";
+
+export const MAX_FEED_POSTS = 50;
+
+export function blogFeedPath(locale: LocaleCode): string {
+  return `${localizedPath(locale, routeSlugs.blog[locale])}/rss.xml`;
+}
+
+export async function serveBlogFeed(event: H3Event, locale: LocaleCode) {
+  const contentRuntime = useRuntimeConfig(event).public.content as
+    | { collections?: Record<string, unknown> }
+    | undefined;
+  if (!contentRuntime?.collections?.blog) {
+    throw createError({ statusCode: 404, statusMessage: "Blog is not enabled" });
+  }
+
+  const site = useAppConfig().ginkoDocs.site;
+  const posts = await many(event, "blog", {
+    locale,
+    fallback: true,
+    populate: { author: "authors" },
+    sort: { date: "desc" },
+    limit: MAX_FEED_POSTS,
+  });
+
+  setHeader(event, "content-type", "application/rss+xml; charset=utf-8");
+  return buildRssFeed({
+    title: `${blog.title[locale]} - ${getLocalizedSiteText(site.name, locale)}`,
+    description: blog.description[locale],
+    siteUrl: site.url,
+    feedPath: blogFeedPath(locale),
+    language: locales.find((entry) => entry.code === locale)?.language ?? locale,
+    items: posts.map((post) => ({
+      title: post.title,
+      path: post.route.resolvedPath,
+      description: post.description,
+      date: post.date,
+      authorName: post.author?.name,
+    })),
+  });
+}

package/server/utils/feed.ts

@@ -0,0 +1,70 @@
+export interface RssFeedItem {
+  title: string;
+  /** Site-relative path of the post, e.g. "/blog/my-post". */
+  path: string;
+  description: string;
+  /** Authored publication date, YYYY-MM-DD. */
+  date: string;
+  authorName?: string;
+}
+
+export interface RssFeedInput {
+  title: string;
+  description: string;
+  /** Absolute site origin, e.g. "https://docs.example.com". */
+  siteUrl: string;
+  /** Site-relative path of the feed itself, e.g. "/blog/rss.xml". */
+  feedPath: string;
+  language: string;
+  items: RssFeedItem[];
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+function toRfc822(date: string): string {
+  return new Date(`${date}T00:00:00Z`).toUTCString();
+}
+
+export function buildRssFeed(feed: RssFeedInput): string {
+  const base = feed.siteUrl.replace(/\/$/, "");
+  const newestDate = feed.items
+    .map((item) => item.date)
+    .sort()
+    .at(-1);
+
+  const items = feed.items
+    .map((item) => {
+      const link = `${base}${item.path}`;
+      const author = item.authorName
+        ? `\n      <dc:creator>${escapeXml(item.authorName)}</dc:creator>`
+        : "";
+      return `    <item>
+      <title>${escapeXml(item.title)}</title>
+      <link>${escapeXml(link)}</link>
+      <guid>${escapeXml(link)}</guid>
+      <pubDate>${toRfc822(item.date)}</pubDate>
+      <description>${escapeXml(item.description)}</description>${author}
+    </item>`;
+    })
+    .join("\n");
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
+  <channel>
+    <title>${escapeXml(feed.title)}</title>
+    <link>${escapeXml(`${base}${feed.feedPath.replace(/rss\.xml$/, "")}`)}</link>
+    <atom:link href="${escapeXml(`${base}${feed.feedPath}`)}" rel="self" type="application/rss+xml"/>
+    <description>${escapeXml(feed.description)}</description>
+    <language>${escapeXml(feed.language)}</language>${newestDate ? `\n    <lastBuildDate>${toRfc822(newestDate)}</lastBuildDate>` : ""}
+${items}
+  </channel>
+</rss>
+`;
+}

package/server/utils/redirects.ts

@@ -0,0 +1,38 @@
+import type { H3Event } from "h3";
+import { many } from "@lupinum/ginko-content/server";
+import { useRuntimeConfig } from "#imports";
+import { localeCodes } from "../../i18n/locales";
+import { buildRedirectMap, type RedirectSourceDocument } from "./redirects.utils";
+
+async function queryRedirectDocuments(event: H3Event): Promise<RedirectSourceDocument[]> {
+  const contentRuntime = useRuntimeConfig(event).public.content as
+    | { collections?: Record<string, unknown> }
+    | undefined;
+  const collections = ["docs", ...(contentRuntime?.collections?.blog ? ["blog"] : [])];
+
+  const results = await Promise.all(
+    collections.flatMap((collection) =>
+      localeCodes.map((locale) =>
+        // fallback: false — an English page resolved into a German route would
+        // otherwise register its redirectFrom entries twice.
+        many(event, collection, { locale, fallback: false }),
+      ),
+    ),
+  );
+  return results.flat() as RedirectSourceDocument[];
+}
+
+let cachedMap: Promise<Map<string, string>> | undefined;
+
+export function loadRedirectMap(event: H3Event): Promise<Map<string, string>> {
+  if (import.meta.dev) {
+    return queryRedirectDocuments(event).then(buildRedirectMap);
+  }
+  cachedMap ??= queryRedirectDocuments(event)
+    .then(buildRedirectMap)
+    .catch((error) => {
+      cachedMap = undefined;
+      throw error;
+    });
+  return cachedMap;
+}

package/server/utils/redirects.utils.ts

@@ -0,0 +1,58 @@
+import { localeCodes, localizedPath } from "../../i18n/locales";
+import { routeSlugs } from "../../shared/route-slugs";
+
+export interface RedirectSourceDocument {
+  route: { resolvedPath: string };
+  redirectFrom?: string[];
+}
+
+export function normalizeRedirectPath(path: string): string {
+  const trimmed = path.split("?")[0] ?? path;
+  if (trimmed === "/") return "/";
+  return trimmed.replace(/\/+$/, "");
+}
+
+/** Routes the theme itself owns; a redirect must never shadow one of them. */
+export function themeStaticRoutes(): string[] {
+  return localeCodes.flatMap((locale) => [
+    localizedPath(locale, routeSlugs.home[locale]),
+    localizedPath(locale, routeSlugs.docs[locale]),
+    localizedPath(locale, routeSlugs.blog[locale]),
+  ]);
+}
+
+/**
+ * Builds old-path → live-path pairs from every document's `redirectFrom`.
+ * Conflicts throw so `failOnError` stops the build instead of shipping a
+ * redirect that shadows a live page.
+ */
+export function buildRedirectMap(documents: RedirectSourceDocument[]): Map<string, string> {
+  const livePaths = new Set(
+    documents.map((document) => normalizeRedirectPath(document.route.resolvedPath)),
+  );
+  const reserved = new Set(themeStaticRoutes().map(normalizeRedirectPath));
+  const map = new Map<string, string>();
+  const problems: string[] = [];
+
+  for (const document of documents) {
+    const target = normalizeRedirectPath(document.route.resolvedPath);
+    for (const source of document.redirectFrom ?? []) {
+      const from = normalizeRedirectPath(source);
+      if (livePaths.has(from)) {
+        problems.push(`"${from}" redirects to "${target}" but is also a live page`);
+      } else if (reserved.has(from)) {
+        problems.push(`"${from}" redirects to "${target}" but is a theme route`);
+      } else if (map.has(from) && map.get(from) !== target) {
+        problems.push(`"${from}" is claimed by both "${map.get(from)}" and "${target}"`);
+      } else {
+        map.set(from, target);
+      }
+    }
+  }
+
+  if (problems.length) {
+    throw new Error(`Invalid redirectFrom entries:\n${problems.map((p) => `- ${p}`).join("\n")}`);
+  }
+
+  return map;
+}

package/shared/theme-palettes.ts

@@ -0,0 +1,37 @@
+export const GINKO_DOCS_NEUTRAL_PALETTES = [
+  "slate",
+  "gray",
+  "zinc",
+  "neutral",
+  "stone",
+  "taupe",
+  "mauve",
+  "mist",
+  "olive",
+  "custom",
+] as const;
+
+export const GINKO_DOCS_PRIMARY_PALETTES = [
+  "neutral",
+  "red",
+  "orange",
+  "amber",
+  "yellow",
+  "lime",
+  "green",
+  "emerald",
+  "teal",
+  "cyan",
+  "sky",
+  "blue",
+  "indigo",
+  "violet",
+  "purple",
+  "fuchsia",
+  "pink",
+  "rose",
+  "custom",
+] as const;
+
+export type GinkoDocsNeutralPalette = (typeof GINKO_DOCS_NEUTRAL_PALETTES)[number];
+export type GinkoDocsPrimaryPalette = (typeof GINKO_DOCS_PRIMARY_PALETTES)[number];

package/shared/types/app-config.ts

@@ -1,13 +1,62 @@
-export type GinkoDocsLocalizedText = { en: string; de?: string };
+export type { GinkoDocsNeutralPalette, GinkoDocsPrimaryPalette } from "../theme-palettes";
+import type { GinkoDocsNeutralPalette, GinkoDocsPrimaryPalette } from "../theme-palettes";
+
+export type GinkoDocsLocalizedText = string | { en: string; de?: string };
+
+export type GinkoDocsProseAppearance = "quiet" | "tint";
+export type GinkoDocsProseFamily =
+  | "callout"
+  | "aside"
+  | "excerpt"
+  | "cards"
+  | "readMore"
+  | "accordion"
+  | "tabs"
+  | "code"
+  | "files"
+  | "api"
+  | "figure"
+  | "quiz"
+  | "steps"
+  | "timeline";
+
+export interface GinkoDocsProseConfig {
+  appearance: GinkoDocsProseAppearance;
+  components?: Partial<Record<GinkoDocsProseFamily, GinkoDocsProseAppearance>>;
+}
 
 export interface GinkoDocsLink {
   label: GinkoDocsLocalizedText;
   to: GinkoDocsLocalizedText;
+  /** Iconify icon shown where nav items render with icons (e.g. mobile menu). */
+  icon?: string;
+  /** One-line subtitle shown under the label in the mobile menu. */
+  description?: GinkoDocsLocalizedText;
+}
+
+export type GinkoDocsSocialPlatform = "github" | "discord" | "linkedin";
+
+/**
+ * A URL uses the platform's built-in label and icon. Pass an object to override
+ * either — `icon` accepts any Iconify name the consuming app has registered, so
+ * sites that ship brand marks are not limited to the layer's bundled icons.
+ */
+export type GinkoDocsSocialEntry = string | { href: string; label?: string; icon?: string };
+
+export interface GinkoDocsHeroCodeTab {
+  label: GinkoDocsLocalizedText;
+  /** Iconify icon shown in the tab. */
+  icon?: string;
+  filename?: string;
+  /** Shiki language id; derived from the filename extension when unset. */
+  language?: string;
+  code: string;
 }
 
 export type GinkoDocsHeroMedia =
   | { type: "image"; src: string; alt: string }
-  | { type: "code"; code: string; language?: string; filename?: string };
+  | { type: "code"; code: string; language?: string; filename?: string }
+  | { type: "code-tabs"; tabs: GinkoDocsHeroCodeTab[] };
 
 export type GinkoDocsPlausibleExtension =
   | "hash"
@@ -21,22 +70,27 @@ export type GinkoDocsPlausibleExtension =
   | "manual";
 
 export interface GinkoDocsAppConfig {
+  theme: {
+    neutral: GinkoDocsNeutralPalette;
+    primary: GinkoDocsPrimaryPalette;
+  };
+  prose: GinkoDocsProseConfig;
   site: {
     name: GinkoDocsLocalizedText;
     description: GinkoDocsLocalizedText;
     url: string;
     logo: { light: string; dark: string };
-    localeSwitcher: "dropdown" | "segmented";
     docsSidebarSwitcher: "dropdown" | "list" | "tabs";
     lupinumAttribution: boolean;
   };
   nav: {
     /** "auto" derives Docs (+ Blog when blog routes exist); an array overrides entirely. */
     links: "auto" | GinkoDocsLink[];
+    /** Render configured social links as icon buttons in the header instead of labelled rows. */
+    socialIcons: boolean;
   };
   banner: {
-    /** "auto" shows the banner when blog routes exist (legacy behavior). */
-    enabled: boolean | "auto";
+    enabled: boolean;
     /** Dismissal storage key — change it to re-show the banner after an update. */
     id: string;
     text?: GinkoDocsLocalizedText;
@@ -53,10 +107,7 @@ export interface GinkoDocsAppConfig {
       extensions?: GinkoDocsPlausibleExtension[];
     };
   };
-  social: {
-    github?: string;
-    linkedin?: string;
-  };
+  social: Partial<Record<GinkoDocsSocialPlatform, GinkoDocsSocialEntry>>;
   feedback: {
     enabled: boolean;
   };
@@ -83,7 +134,6 @@ export interface GinkoDocsAppConfig {
     contentDirectory?: string;
   };
   landing: {
-    eyebrow?: GinkoDocsLocalizedText;
     title: GinkoDocsLocalizedText;
     description: GinkoDocsLocalizedText;
     primary: GinkoDocsLink;
@@ -91,10 +141,25 @@ export interface GinkoDocsAppConfig {
     hero?: {
       media?: GinkoDocsHeroMedia;
     };
+    /** Copyable install command shown under the hero CTAs. */
+    install?: { command: string };
     features: Array<{
       title: GinkoDocsLocalizedText;
       description: GinkoDocsLocalizedText;
       icon?: string;
     }>;
+    /** Dark full-width band highlighting agent readiness. */
+    agent?: {
+      title: GinkoDocsLocalizedText;
+      description: GinkoDocsLocalizedText;
+      /** Terminal transcript; "$"-prefixed lines render as commands, "#" as comments. */
+      code: string;
+    };
+    /** Closing call to action; primary falls back to landing.primary. */
+    cta?: {
+      title: GinkoDocsLocalizedText;
+      primary?: GinkoDocsLink;
+      secondary?: GinkoDocsLink;
+    };
   };
 }

package/tags.ts

@@ -3,42 +3,36 @@ import type { PortableComponentPolicyV1 } from "@lupinum/ginko-content/cms-contr
 export const contentComponentTags = {
   accordion: "MdcAccordion",
   "accordion-item": "MdcAccordionItem",
-  alert: "MdcAlert",
+  api: "MdcApi",
   aside: "MdcAside",
-  callout: "MdcCallout",
   card: "MdcCard",
-  "card-group": "MdcCardGroup",
+  cards: "MdcCards",
   center: "MdcCenter",
   "code-group": "MdcCodeGroup",
+  "code-tree": "MdcCodeTree",
+  collapse: "MdcCollapse",
   column: "MdcColumn",
-  danger: "MdcError",
-  "doc-img": "MdcDocImg",
   dropcap: "MdcDropcap",
   error: "MdcError",
-  field: "MdcField",
-  "field-group": "MdcFieldGroup",
+  excerpt: "MdcExcerpt",
   figure: "MdcFigure",
+  files: "MdcFiles",
   idea: "MdcIdea",
   img: "ProseImg",
   info: "MdcInfo",
-  kbd: "MdcShortcut",
+  kbd: "MdcKbd",
   layout: "MdcLayout",
   note: "MdcNote",
-  passage: "MdcPassage",
   quiz: "MdcQuiz",
-  "quiz-option": "MdcQuizOption",
   "quiz-question": "MdcQuizQuestion",
   "read-more": "MdcReadMore",
-  "read-more-group": "MdcReadMoreGroup",
-  shortcut: "MdcShortcut",
-  step: "MdcStep",
   steps: "MdcSteps",
   success: "MdcSuccess",
   tab: "MdcTab",
   tabs: "MdcTabs",
   timeline: "MdcTimeline",
   "timeline-item": "MdcTimelineItem",
-  warn: "MdcWarning",
+  toc: "MdcInlineToc",
   warning: "MdcWarning",
 } as const;
 
@@ -59,12 +53,13 @@ const inline = (props: ComponentProps = {}): ComponentDefinition => ({
   media: null,
 });
 
-const notice = block({ title: optional("string"), icon: optional("string") });
-const shortcut = inline({ value: optional("string"), size: optional("string") });
+const appearance = { appearance: optional("string") };
+const notice = block({ title: optional("string"), icon: optional("string"), ...appearance });
 
 export const contentComponentPolicy = {
   components: {
     accordion: block({
+      ...appearance,
       type: optional("string"),
       collapsible: optional("boolean"),
       defaultValue: optional("json"),
@@ -77,17 +72,15 @@ export const contentComponentPolicy = {
       },
       ["default", "title", "content"],
     ),
-    alert: block({
+    api: block({
+      ...appearance,
       title: optional("string"),
       icon: optional("string"),
-      type: optional("string"),
-    }),
-    aside: block({ label: optional("string") }),
-    callout: block({
-      title: optional("string"),
-      type: optional("string"),
-      icon: optional("string"),
+      method: optional("string"),
+      path: optional("string"),
+      groups: optional("json"),
     }),
+    aside: block({ label: optional("string"), ...appearance }),
     card: block(
       {
         title: optional("string"),
@@ -100,32 +93,31 @@ export const contentComponentPolicy = {
         img: optional("asset"),
         showLinkIcon: optional("boolean"),
         horizontal: optional("boolean"),
+        ...appearance,
       },
       ["default", "title", "description", "footer"],
       { sourceProp: "img", altProp: null, titleProp: null, filenameProp: null },
     ),
-    "card-group": block({ cols: optional("string") }),
+    cards: block({ cols: optional("string"), ...appearance }),
     center: block({
       size: optional("string"),
       max: optional("string"),
       type: optional("string"),
     }),
-    "code-group": block(),
+    "code-group": block(appearance),
+    "code-tree": block({
+      ...appearance,
+      defaultValue: optional("string"),
+      expandAll: optional("boolean"),
+    }),
+    collapse: block(appearance),
     column: block({ size: optional("string") }),
-    danger: notice,
-    "doc-img": block({ bleed: optional("string") }),
     dropcap: block({ lines: optional("json") }),
     error: notice,
-    field: block({
-      name: required("string"),
-      type: optional("string"),
-      required: optional("boolean"),
-      description: optional("string"),
-      defaultValue: optional("string"),
-    }),
-    "field-group": block(),
+    excerpt: block({ label: optional("string"), source: optional("string"), ...appearance }),
     figure: block(
       {
+        ...appearance,
         src: required("asset"),
         alt: required("string"),
         caption: optional("string"),
@@ -134,17 +126,19 @@ export const contentComponentPolicy = {
         bleed: optional("string"),
         aspect: optional("string"),
         fit: optional("string"),
+        zoom: optional("json"),
       },
       ["default"],
       { sourceProp: "src", altProp: "alt", titleProp: null, filenameProp: null },
     ),
+    files: block({ active: optional("string"), annotations: optional("json"), ...appearance }),
     idea: notice,
     info: notice,
-    kbd: shortcut,
+    kbd: inline(),
     layout: block({ type: optional("string") }),
     note: notice,
-    passage: block({ label: optional("string") }),
     quiz: block({
+      ...appearance,
       title: optional("string"),
       description: optional("string"),
       questionLabel: optional("string"),
@@ -156,44 +150,38 @@ export const contentComponentPolicy = {
       retryPrompt: optional("string"),
       resetLabel: optional("string"),
     }),
-    "quiz-option": block({
-      correct: optional("boolean"),
-      label: optional("string"),
-    }),
     "quiz-question": block({
       question: required("string"),
       type: optional("string"),
       explanation: optional("string"),
-      options: optional("json"),
+      options: required("json"),
       checkLabel: optional("string"),
       correctLabel: optional("string"),
       incorrectLabel: optional("string"),
       resetLabel: optional("string"),
       multipleChoiceLabel: optional("string"),
     }),
-    "read-more": block(
-      {
-        title: optional("string"),
-        to: required("string"),
-        target: optional("string"),
-        icon: optional("string"),
-      },
-      [],
-    ),
-    "read-more-group": block(),
-    shortcut,
-    step: block({ title: optional("string"), icon: optional("string") }),
-    steps: block({ variant: optional("string") }),
+    "read-more": block({ title: optional("string"), links: required("json"), ...appearance }, []),
+    steps: block({ mode: optional("string"), ...appearance }),
     success: notice,
     tab: block({ icon: optional("string"), label: optional("string") }),
-    tabs: block({ variant: optional("string"), padded: optional("boolean") }),
-    timeline: block(),
+    tabs: block({ layout: optional("string"), padded: optional("boolean"), ...appearance }),
+    timeline: block(appearance),
     "timeline-item": block({
       date: optional("string"),
       label: optional("string"),
       title: optional("string"),
+      icon: optional("string"),
+      active: optional("boolean"),
     }),
-    warn: notice,
+    toc: block(
+      {
+        title: optional("string"),
+        depth: optional("json"),
+        open: optional("json"),
+      },
+      [],
+    ),
     warning: notice,
   },
 } satisfies PortableComponentPolicyV1;

package/app/components/mdc/MdcAlert.vue

@@ -1,34 +0,0 @@
-<script setup lang="ts">
-import type { HTMLAttributes } from "vue";
-import { computed } from "vue";
-import MdcCallout from "./MdcCallout.vue";
-
-type AlertType = "default" | "info" | "warning" | "success" | "danger" | "secondary";
-type CalloutType = "info" | "warning" | "error" | "success" | "idea";
-
-const props = withDefaults(
-  defineProps<{
-    title?: string;
-    icon?: string;
-    type?: AlertType;
-    class?: HTMLAttributes["class"];
-  }>(),
-  {
-    type: "warning",
-  },
-);
-
-const calloutType = computed<CalloutType>(() => {
-  if (props.type === "danger") return "error";
-  if (props.type === "success") return "success";
-  if (props.type === "info" || props.type === "secondary") return "info";
-
-  return "warning";
-});
-</script>
-
-<template>
-  <MdcCallout :title="title" :icon="icon" :type="calloutType" :class="props.class">
-    <slot />
-  </MdcCallout>
-</template>