@uxfront/layer-docs 0.1.1 → 0.2.1

package/nuxt.schema.ts

@@ -0,0 +1,359 @@
+import { field, group } from "@nuxt/content/preview";
+
+/**
+ * Nuxt Content Studio preview schema for this layer's `app.config.ts` surface.
+ *
+ * Every field below describes a key the layer itself declares and reads, so the
+ * schema is owned here rather than restated in each consumer. Nuxt merges
+ * schemas across layers, so a consumer declares only the keys it adds on top.
+ *
+ * This file is load-bearing beyond Studio: once a schema exists, Nuxt derives
+ * the generated `AppConfig` type from it, and any key the layer reads but the
+ * schema omits collapses to `{}` and fails typecheck at the read site. Adding a
+ * key to `app.config.ts` or reading a new one from a component means adding it
+ * here in the same change.
+ *
+ * Brand-free by construction: the defaults are Nuxt UI palette tokens and
+ * generic placeholder strings, never a product's values.
+ */
+export default defineNuxtSchema({
+  appConfig: {
+    ui: group({
+      title: "UI",
+      description: "UI Customization.",
+      icon: "i-lucide-palette",
+      fields: {
+        colors: group({
+          title: "Colors",
+          description: "Manage main colors of your application",
+          icon: "i-lucide-palette",
+          fields: {
+            primary: field({
+              type: "string",
+              title: "Primary",
+              description: "Primary color of your UI.",
+              icon: "i-lucide-palette",
+              default: "green",
+              required: [
+                "red",
+                "orange",
+                "amber",
+                "yellow",
+                "lime",
+                "green",
+                "emerald",
+                "teal",
+                "cyan",
+                "sky",
+                "blue",
+                "indigo",
+                "violet",
+                "purple",
+                "fuchsia",
+                "pink",
+                "rose",
+              ],
+            }),
+            neutral: field({
+              type: "string",
+              title: "Neutral",
+              description: "Neutral color of your UI.",
+              icon: "i-lucide-palette",
+              default: "slate",
+              required: ["slate", "gray", "zinc", "neutral", "stone"],
+            }),
+          },
+        }),
+        icons: group({
+          title: "Icons",
+          description: "Manage icons used in the application.",
+          icon: "i-lucide-settings",
+          fields: {
+            search: field({
+              type: "icon",
+              title: "Search Bar",
+              description: "Icon to display in the search bar.",
+              icon: "i-lucide-search",
+              default: "i-lucide-search",
+            }),
+            dark: field({
+              type: "icon",
+              title: "Dark mode",
+              description: "Icon of color mode button for dark mode.",
+              icon: "i-lucide-moon",
+              default: "i-lucide-moon",
+            }),
+            light: field({
+              type: "icon",
+              title: "Light mode",
+              description: "Icon of color mode button for light mode.",
+              icon: "i-lucide-sun",
+              default: "i-lucide-sun",
+            }),
+            external: field({
+              type: "icon",
+              title: "External Link",
+              description: "Icon for external link.",
+              icon: "i-lucide-external-link",
+              default: "i-lucide-external-link",
+            }),
+            chevron: field({
+              type: "icon",
+              title: "Chevron",
+              description: "Icon for chevron.",
+              icon: "i-lucide-chevron-down",
+              default: "i-lucide-chevron-down",
+            }),
+            hash: field({
+              type: "icon",
+              title: "Hash",
+              description: "Icon for hash anchors.",
+              icon: "i-lucide-hash",
+              default: "i-lucide-hash",
+            }),
+          },
+        }),
+      },
+    }),
+    seo: group({
+      title: "SEO",
+      description: "SEO configuration.",
+      icon: "i-lucide-search",
+      fields: {
+        title: field({
+          type: "string",
+          title: "Title",
+          description: "Title to display in the header.",
+          icon: "i-lucide-type",
+          default: "",
+        }),
+        description: field({
+          type: "string",
+          title: "Description",
+          description: "Description to display in the header.",
+          icon: "i-lucide-type",
+          default: "",
+        }),
+      },
+    }),
+    header: group({
+      title: "Header",
+      description: "Header configuration.",
+      icon: "i-lucide-layout",
+      fields: {
+        title: field({
+          type: "string",
+          title: "Title",
+          description: "Title to display in the header.",
+          icon: "i-lucide-type",
+          default: "",
+        }),
+        logo: group({
+          title: "Logo",
+          description: "Header logo configuration.",
+          icon: "i-lucide-image",
+          fields: {
+            light: field({
+              type: "media",
+              title: "Light Mode Logo",
+              description: "Pick an image from your gallery.",
+              icon: "i-lucide-sun",
+              default: "",
+            }),
+            dark: field({
+              type: "media",
+              title: "Dark Mode Logo",
+              description: "Pick an image from your gallery.",
+              icon: "i-lucide-moon",
+              default: "",
+            }),
+            alt: field({
+              type: "string",
+              title: "Alt",
+              description: "Alt to display for accessibility.",
+              icon: "i-lucide-text",
+              default: "",
+            }),
+          },
+        }),
+        links: field({
+          type: "array",
+          title: "Links",
+          description: "Navigation links to display in the header.",
+          icon: "i-lucide-link",
+          default: [],
+        }),
+        attribution: group({
+          title: "Attribution",
+          description: "Brand attribution rendered beside the header wordmark.",
+          icon: "i-lucide-badge",
+          fields: {
+            prefix: field({
+              type: "string",
+              title: "Prefix",
+              description: 'Unlinked word before the label, e.g. "by".',
+              icon: "i-lucide-text",
+              default: "",
+            }),
+            label: field({
+              type: "string",
+              title: "Label",
+              description: "Linked attribution text. Empty renders nothing.",
+              icon: "i-lucide-type",
+              default: "",
+            }),
+            to: field({
+              type: "string",
+              title: "URL",
+              description: "Destination the label links to.",
+              icon: "i-lucide-link",
+              default: "",
+            }),
+          },
+        }),
+      },
+    }),
+    footer: group({
+      title: "Footer",
+      description: "Footer configuration.",
+      icon: "i-lucide-panel-bottom",
+      fields: {
+        credits: field({
+          type: "string",
+          title: "Credits",
+          description: "Copyright line. Falls back to the header title.",
+          icon: "i-lucide-copyright",
+          default: "",
+        }),
+        links: field({
+          type: "array",
+          title: "Links",
+          description: "Navigation links to display in the footer.",
+          icon: "i-lucide-link",
+          default: [],
+        }),
+      },
+    }),
+    socials: field({
+      type: "object",
+      title: "Social Networks",
+      description: "Social links configuration.",
+      icon: "i-lucide-network",
+      default: {},
+    }),
+    toc: group({
+      title: "Table of contents",
+      description: "TOC configuration.",
+      icon: "i-lucide-list",
+      fields: {
+        title: field({
+          type: "string",
+          title: "Title",
+          description: "Title of the table of contents.",
+          icon: "i-lucide-heading",
+          default: "On this page",
+        }),
+        bottom: group({
+          title: "Bottom",
+          description: "Bottom section of the table of contents.",
+          icon: "i-lucide-list",
+          fields: {
+            title: field({
+              type: "string",
+              title: "Title",
+              description: "Title of the bottom section.",
+              icon: "i-lucide-heading",
+              default: "Community",
+            }),
+            links: field({
+              type: "array",
+              title: "Links",
+              description: "Links to display in the bottom section.",
+              icon: "i-lucide-link",
+              default: [],
+            }),
+          },
+        }),
+      },
+    }),
+    analytics: group({
+      title: "Analytics",
+      description: "PostHog analytics plugin (production only, requires a runtime key).",
+      icon: "i-lucide-chart-line",
+      fields: {
+        enabled: field({
+          type: "boolean",
+          title: "Enabled",
+          description: "Set to false to opt out of the analytics plugin.",
+          icon: "i-lucide-toggle-right",
+          default: true,
+        }),
+      },
+    }),
+    i18nRedirect: group({
+      title: "Locale redirect",
+      description: "Redirect `/` to `/{locale}` (only fires when i18n is configured).",
+      icon: "i-lucide-languages",
+      fields: {
+        enabled: field({
+          type: "boolean",
+          title: "Enabled",
+          description: "Set to false to opt out of the locale redirect.",
+          icon: "i-lucide-toggle-right",
+          default: true,
+        }),
+      },
+    }),
+    nonRouteCategories: field({
+      type: "object",
+      title: "Non-route categories",
+      description:
+        "Navigation folders that group pages without owning a route, keyed by directory name.",
+      icon: "i-lucide-folder-tree",
+      default: {},
+    }),
+    docsTheme: group({
+      title: "Docs theme",
+      description: "Documentation-specific theme options.",
+      icon: "i-lucide-book-open",
+      fields: {
+        frameworks: field({
+          type: "array",
+          title: "Frameworks",
+          description:
+            "Frameworks offered by the sidebar select and in-content switcher, in display order. Empty by default — `defu` concatenates arrays across layers, so a non-empty default here could only be appended to, never overridden.",
+          icon: "i-lucide-layers",
+          default: [],
+        }),
+      },
+    }),
+    github: group({
+      title: "GitHub",
+      description: "GitHub configuration.",
+      icon: "i-simple-icons-github",
+      fields: {
+        url: field({
+          type: "string",
+          title: "URL",
+          description: "GitHub URL.",
+          icon: "i-simple-icons-github",
+          default: "",
+        }),
+        branch: field({
+          type: "string",
+          title: "Branch",
+          description: "GitHub branch.",
+          icon: "i-lucide-git-branch",
+          default: "main",
+        }),
+        rootDir: field({
+          type: "string",
+          title: "Root Directory",
+          description: "Root directory of the GitHub repository.",
+          icon: "i-lucide-folder",
+          default: "",
+        }),
+      },
+    }),
+  },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uxfront/layer-docs",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Neutral, brandable Nuxt-layer documentation theme. Consumers extend it and supply their own branding, content and section topology.",
   "keywords": [
     "docs",
@@ -25,6 +25,7 @@
     "server",
     "utils",
     "nuxt.config.ts",
+    "nuxt.schema.ts",
     "tsconfig.json",
     "README.md",
     "CHANGELOG.md",

package/utils/content.ts

@@ -1,6 +1,7 @@
 import type { DefinedCollection } from "@nuxt/content";
 import { defineContentConfig, defineCollection, z } from "@nuxt/content";
 import { useNuxt } from "@nuxt/kit";
+import { defineSitemapSchema } from "@nuxtjs/sitemap/content";
 
 /**
  * Minimal structural shape of a documentation section descriptor. The consuming
@@ -15,8 +16,11 @@ export interface DocsSectionDescriptor {
   slug: string;
   /** Human label, used as a fallback nav title. */
   label: string;
-  /** Source folder(s) under `content/docs/`. String or list. */
-  folder: string | string[];
+  /**
+   * Source folder(s) under `content/docs/`. String or list. Accepts a readonly
+   * list so a consumer can declare its topology with `as const`.
+   */
+  folder: string | readonly string[];
   /**
    * When `folder` is a list, the index whose pages mount at the section root
    * (`/docs/<slug>`) instead of `/docs/<slug>/<folder>`. Defaults to none.
@@ -24,8 +28,40 @@ export interface DocsSectionDescriptor {
   rootFolder?: number;
 }
 
-const createDocsSchema = () =>
+/**
+ * Opt-in extras layered on top of the base collection set. Both default to
+ * `false`, so an existing `defineDocsCollections(sections)` call is unchanged.
+ */
+export interface DefineDocsCollectionsOptions {
+  /**
+   * Fold `@nuxtjs/sitemap`'s frontmatter schema into every page collection so
+   * authors can set per-page sitemap fields (priority, changefreq, lastmod).
+   * Requires the consumer to register `@nuxtjs/sitemap`.
+   */
+  sitemap?: boolean;
+  /**
+   * Emit a locale-independent `changelog` collection sourced from
+   * `content/changelog/*.md`. One entry per released version, with `version`,
+   * `date`, and an optional `releaseUrl` override for entries that predate the
+   * repository's current release-tag convention.
+   */
+  changelog?: boolean;
+}
+
+// `@nuxtjs/sitemap` and `@nuxt/content` can resolve different zod majors in a
+// consumer's tree (v4 and v3 respectively), and the two `ZodType` shapes are
+// structurally incompatible even though the runtime value is fine. Cast at the
+// single seam rather than pinning a consumer's zod.
+const sitemapSchema = () =>
   z.object({
+    sitemap: defineSitemapSchema() as unknown as ReturnType<typeof z.any>,
+  });
+
+const createLandingSchema = (options: DefineDocsCollectionsOptions) =>
+  options.sitemap ? sitemapSchema() : undefined;
+
+const createDocsSchema = (options: DefineDocsCollectionsOptions) => {
+  const schema = z.object({
     links: z
       .array(
         z.object({
@@ -38,8 +74,18 @@ const createDocsSchema = () =>
       .optional(),
   });
 
+  return options.sitemap ? schema.extend(sitemapSchema().shape) : schema;
+};
+
+const createChangelogSchema = () =>
+  z.object({
+    version: z.string(),
+    date: z.string(),
+    releaseUrl: z.string().url().optional(),
+  });
+
 const buildDocsSource = (section: DocsSectionDescriptor, pathPrefix = "", urlPrefix = "") => {
-  const folders = Array.isArray(section.folder) ? section.folder : [section.folder];
+  const folders = typeof section.folder === "string" ? [section.folder] : section.folder;
   const baseUrl = `${urlPrefix}/docs/${section.slug}`;
 
   if (folders.length === 1) {
@@ -64,7 +110,7 @@ const buildDocsSource = (section: DocsSectionDescriptor, pathPrefix = "", urlPre
  * ```ts
  * import { defineDocsCollections } from "@uxfront/layer-docs/content";
  * import { DOCS_SECTIONS } from "./app/constants/sections";
- * export default defineDocsCollections(DOCS_SECTIONS);
+ * export default defineDocsCollections([...DOCS_SECTIONS]);
  * ```
  *
  * Produces one `landing` collection (root markdown) plus one `docs_<key>`
@@ -72,10 +118,26 @@ const buildDocsSource = (section: DocsSectionDescriptor, pathPrefix = "", urlPre
  * collections are generated per-locale (`landing_<code>`, `docs_<key>_<code>`)
  * and sourced from a matching `content/<code>/` subtree; otherwise a single flat
  * set is produced. The section topology and content stay in the consuming app.
+ *
+ * Two opt-in extras are available — sitemap frontmatter on every page, and a
+ * `changelog` collection:
+ *
+ * ```ts
+ * export default defineDocsCollections([...DOCS_SECTIONS], {
+ *   sitemap: true,
+ *   changelog: true,
+ * });
+ * ```
  */
-export function defineDocsCollections(sections: DocsSectionDescriptor[]) {
-  const { options } = useNuxt();
-  const locales = options.i18n?.locales;
+export function defineDocsCollections(
+  sections: readonly DocsSectionDescriptor[],
+  options: DefineDocsCollectionsOptions = {},
+) {
+  const { options: nuxtOptions } = useNuxt();
+  const locales = nuxtOptions.i18n?.locales;
+
+  const landingSchema = createLandingSchema(options);
+  const docsSchema = createDocsSchema(options);
 
   let collections: Record<string, DefinedCollection>;
 
@@ -87,13 +149,14 @@ export function defineDocsCollections(sections: DocsSectionDescriptor[]) {
       collections[`landing_${code}`] = defineCollection({
         type: "page",
         source: [{ include: `${code}/*.md` }],
+        ...(landingSchema ? { schema: landingSchema } : {}),
       });
 
       for (const section of sections) {
         collections[`docs_${section.key}_${code}`] = defineCollection({
           type: "page",
           source: buildDocsSource(section, `${code}/`, `/${code}`),
-          schema: createDocsSchema(),
+          schema: docsSchema,
         });
       }
     }
@@ -102,6 +165,7 @@ export function defineDocsCollections(sections: DocsSectionDescriptor[]) {
       landing: defineCollection({
         type: "page",
         source: [{ include: "*.md" }],
+        ...(landingSchema ? { schema: landingSchema } : {}),
       }),
     };
 
@@ -109,10 +173,21 @@ export function defineDocsCollections(sections: DocsSectionDescriptor[]) {
       collections[`docs_${section.key}`] = defineCollection({
         type: "page",
         source: buildDocsSource(section),
-        schema: createDocsSchema(),
+        schema: docsSchema,
       });
     }
   }
 
+  if (options.changelog) {
+    // Locale-independent on purpose: a release history is the same document in
+    // every language. The index route renders every body inline; each entry also
+    // has a deep-linkable detail route reading from this same collection.
+    collections.changelog = defineCollection({
+      type: "page",
+      source: { include: "changelog/*.md" },
+      schema: createChangelogSchema(),
+    });
+  }
+
   return defineContentConfig({ collections });
 }