nimbus-docs 0.1.0 → 0.1.1

package/dist/schemas.d.ts

@@ -79,6 +79,7 @@ declare function defineDocSchema(config?: DocSchemaConfig): z.ZodObject<{
     link: z.ZodOptional<z.ZodString>;
     label: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>, z.ZodLiteral<false>]>>;
+  previousSlug: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
 }, z.core.$strip> | z.ZodObject<{
   [x: string]: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
 }, z.core.$strip>;
@@ -152,6 +153,7 @@ declare const docsSchema: z.ZodObject<{
     link: z.ZodOptional<z.ZodString>;
     label: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>, z.ZodLiteral<false>]>>;
+  previousSlug: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
 }, z.core.$strip> | z.ZodObject<{
   [x: string]: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
 }, z.core.$strip>;
@@ -159,6 +161,27 @@ declare const docsSchema: z.ZodObject<{
 declare const partialsSchema: z.ZodDefault<z.ZodObject<{
   params: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>>;
+/** One row in a component's `props` frontmatter array. */
+declare const componentPropSchema: z.ZodObject<{
+  name: z.ZodString;
+  type: z.ZodString;
+  defaultValue: z.ZodOptional<z.ZodString>;
+  required: z.ZodDefault<z.ZodBoolean>;
+  description: z.ZodString;
+}, z.core.$strip>;
+type ComponentProp = z.infer<typeof componentPropSchema>;
+/** Default schema for the components collection. */
+declare const componentsSchema: z.ZodObject<{
+  title: z.ZodString;
+  tagline: z.ZodString;
+  props: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodString;
+    defaultValue: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+    description: z.ZodString;
+  }, z.core.$strip>>>;
+}, z.core.$strip>;
 //#endregion
-export { DocSchemaConfig, defineDocSchema, docsSchema, partialsSchema };
+export { ComponentProp, DocSchemaConfig, componentsSchema, defineDocSchema, docsSchema, partialsSchema };
 //# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","names":[],"sources":["../src/schemas.ts"],"mappings":";;;UAgBiB,eAAA;;EAEf,MAAA,GAAS,MAAA,SAAe,CAAA,CAAE,UAAA;AAAA;;;;;;iBAgJZ,eAAA,CAAgB,MAAA,GAAQ,eAAA,GAAoB,CAAA,CAAA,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAS/C,UAAA,EAAU,CAAA,CAAA,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAGV,cAAA,EAAc,CAAA,CAAA,UAAA,CAAA,CAAA,CAAA,SAAA"}
+{"version":3,"file":"schemas.d.ts","names":[],"sources":["../src/schemas.ts"],"mappings":";;;UAgBiB,eAAA;;EAEf,MAAA,GAAS,MAAA,SAAe,CAAA,CAAE,UAAA;AAAA;;;;;;iBA2KZ,eAAA,CAAgB,MAAA,GAAQ,eAAA,GAAoB,CAAA,CAAA,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAS/C,UAAA,EAAU,CAAA,CAAA,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAGV,cAAA,EAAc,CAAA,CAAA,UAAA,CAAA,CAAA,CAAA,SAAA;;;;cAkBrB,mBAAA,EAAmB,CAAA,CAAA,SAAA;;;;;;;KAQb,aAAA,GAAgB,CAAA,CAAE,KAAA,QAAa,mBAAA;;cAG9B,gBAAA,EAAgB,CAAA,CAAA,SAAA"}

package/dist/schemas.js

@@ -87,7 +87,8 @@ function baseDocSchema() {
 		lastUpdated: z.coerce.date({ error: "\"lastUpdated\" must be a valid date (e.g. 2024-01-15)" }).optional(),
 		socialImage: z.string({ error: "\"socialImage\" must be a string (path or URL)" }).optional(),
 		prev: prevNextFrontmatterSchema,
-		next: prevNextFrontmatterSchema
+		next: prevNextFrontmatterSchema,
+		previousSlug: z.union([z.string(), z.array(z.string())], { error: "\"previousSlug\" must be a string or array of strings" }).optional()
 	});
 }
 /**
@@ -104,7 +105,21 @@ function defineDocSchema(config = {}) {
 const docsSchema = defineDocSchema();
 /** Schema for partials (`<Render file="..." />` snippets). */
 const partialsSchema = z.object({ params: z.array(z.string()).optional() }).default({});
+/** One row in a component's `props` frontmatter array. */
+const componentPropSchema = z.object({
+	name: z.string({ error: "prop needs a \"name\"" }),
+	type: z.string({ error: "prop needs a \"type\"" }),
+	defaultValue: z.string().optional(),
+	required: z.boolean().default(false),
+	description: z.string({ error: "prop needs a \"description\"" })
+});
+/** Default schema for the components collection. */
+const componentsSchema = z.object({
+	title: z.string({ error: (iss) => iss.input === void 0 ? "Missing \"title\" in frontmatter — display name used in the sidebar and page header." : `"title" must be a string, received ${typeof iss.input}` }),
+	tagline: z.string({ error: (iss) => iss.input === void 0 ? "Missing \"tagline\" in frontmatter — one-sentence summary shown under the title." : `"tagline" must be a string, received ${typeof iss.input}` }),
+	props: z.array(componentPropSchema).default([])
+});
 
 //#endregion
-export { defineDocSchema, docsSchema, partialsSchema };
+export { componentsSchema, defineDocSchema, docsSchema, partialsSchema };
 //# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.js","names":[],"sources":["../src/schemas.ts"],"sourcesContent":["/**\n * Content schemas for Nimbus.\n *\n * `docsSchema` is the default frontmatter contract for the `docs` collection.\n * `partialsSchema` is the contract for `<Render file=\"...\" />` partials.\n * `defineDocSchema(config)` returns a customizable schema for advanced users\n *   composing schemas outside the `docsCollection()` factory.\n *\n * Error messages target content authors, not framework developers.\n * Astro 6 ships Zod v4 via `astro/zod`. The v4 API uses a single `error`\n * field on every schema constructor — NOT v3's `required_error` /\n * `invalid_type_error` / `errorMap`.\n */\n\nimport { z } from \"astro/zod\";\n\nexport interface DocSchemaConfig {\n  /** Additional frontmatter fields merged into the default schema. */\n  fields?: Record<string, z.ZodTypeAny>;\n}\n\n// ---------------------------------------------------------------------------\n// Building blocks\n// ---------------------------------------------------------------------------\n\nconst sidebarBadgeSchema = z.union([\n  z.string(),\n  z.object({\n    text: z.string({ error: 'sidebar badge needs a \"text\" field' }),\n    variant: z\n      .enum(\n        [\"default\", \"info\", \"note\", \"success\", \"tip\", \"warning\", \"caution\", \"danger\"],\n        {\n          error:\n            '\"variant\" must be one of: default, info, note, success, tip, warning, caution, danger',\n        },\n      )\n      .default(\"default\"),\n  }),\n]);\n\nconst sidebarFrontmatterSchema = z\n  .object({\n    order: z.number({ error: '\"sidebar.order\" must be a number' }).optional(),\n    label: z.string({ error: '\"sidebar.label\" must be a string' }).optional(),\n    badge: sidebarBadgeSchema.optional(),\n    hidden: z.boolean({ error: '\"sidebar.hidden\" must be true or false' }).optional(),\n    hideChildren: z\n      .boolean({ error: '\"sidebar.hideChildren\" must be true or false' })\n      .optional(),\n  })\n  .optional();\n\nconst heroActionSchema = z.object({\n  text: z.string({ error: 'hero action needs a \"text\" field' }),\n  link: z.string({ error: 'hero action needs a \"link\" field' }),\n  variant: z\n    .enum([\"primary\", \"secondary\", \"outline\"], {\n      error: 'hero action \"variant\" must be \"primary\", \"secondary\", or \"outline\"',\n    })\n    .default(\"primary\"),\n  icon: z.string().optional(),\n});\n\nconst heroSchema = z\n  .object({\n    title: z.string().optional(),\n    tagline: z.string().optional(),\n    actions: z.array(heroActionSchema).optional(),\n  })\n  .optional();\n\nconst prevNextFrontmatterSchema = z\n  .union([\n    z.string(),\n    z.object({ link: z.string().optional(), label: z.string().optional() }),\n    z.literal(false),\n  ])\n  .optional();\n\nconst headElementSchema = z.object({\n  tag: z.enum([\"meta\", \"link\", \"script\", \"style\"], {\n    error: 'head element \"tag\" must be \"meta\", \"link\", \"script\", or \"style\"',\n  }),\n  attrs: z.record(z.string(), z.string()).default({}),\n  content: z.string().optional(),\n});\n\n// ---------------------------------------------------------------------------\n// Base docs schema\n// ---------------------------------------------------------------------------\n\nfunction baseDocSchema() {\n  return z.object({\n    title: z.string({\n      error: (iss) =>\n        iss.input === undefined\n          ? 'Missing required \"title\" in frontmatter. Every doc needs:\\n\\n  ---\\n  title: \"Your Page Title\"\\n  ---'\n          : `\"title\" must be a string, received ${typeof iss.input}`,\n    }),\n    description: z.string({ error: '\"description\" must be a string' }).optional(),\n    template: z\n      .enum([\"doc\", \"splash\"], {\n        error: '\"template\" must be \"doc\" or \"splash\"',\n      })\n      .default(\"doc\"),\n    sidebar: sidebarFrontmatterSchema,\n    hero: heroSchema,\n    head: z.array(headElementSchema).default([]),\n    draft: z.boolean({ error: '\"draft\" must be true or false' }).default(false),\n    noindex: z.boolean({ error: '\"noindex\" must be true or false' }).default(false),\n    /** Include this page in llms.txt and AI consumption indexes */\n    llms: z.boolean({ error: '\"llms\" must be true or false' }).default(true),\n    /** Signal AI crawlers to deprioritize this page */\n    aiDeprioritize: z\n      .boolean({ error: '\"aiDeprioritize\" must be true or false' })\n      .default(false),\n    pagefind: z.boolean({ error: '\"pagefind\" must be true or false' }).default(true),\n    tableOfContents: z\n      .object({\n        minHeadingLevel: z\n          .number({ error: '\"minHeadingLevel\" must be a number (1-6)' })\n          .int()\n          .min(1)\n          .max(6)\n          .default(2),\n        maxHeadingLevel: z\n          .number({ error: '\"maxHeadingLevel\" must be a number (1-6)' })\n          .int()\n          .min(1)\n          .max(6)\n          .default(3),\n      })\n      .refine((v) => v.minHeadingLevel <= v.maxHeadingLevel, {\n        message: \"minHeadingLevel must be <= maxHeadingLevel\",\n      })\n      .optional(),\n    lastUpdated: z.coerce\n      .date({ error: '\"lastUpdated\" must be a valid date (e.g. 2024-01-15)' })\n      .optional(),\n    /**\n     * Explicit per-page social/OG image override (path or absolute URL).\n     * When omitted, the page route is expected to fall back to a\n     * programmatically-generated card or the site-wide `config.socialImage`.\n     */\n    socialImage: z\n      .string({ error: '\"socialImage\" must be a string (path or URL)' })\n      .optional(),\n    prev: prevNextFrontmatterSchema,\n    next: prevNextFrontmatterSchema,\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\n/**\n * Build a customizable docs schema. Use this when composing schemas outside\n * the `docsCollection()` factory (e.g. multiple docs collections with\n * different shapes).\n */\nexport function defineDocSchema(config: DocSchemaConfig = {}) {\n  const base = baseDocSchema();\n  if (config.fields) {\n    return base.extend(config.fields);\n  }\n  return base;\n}\n\n/** Default docs schema. Equivalent to `defineDocSchema()`. */\nexport const docsSchema = defineDocSchema();\n\n/** Schema for partials (`<Render file=\"...\" />` snippets). */\nexport const partialsSchema = z\n  .object({\n    /**\n     * Declared parameters this partial accepts.\n     * Suffix with `?` for optional params: `[\"name\", \"deprecated?\"]`\n     */\n    params: z.array(z.string()).optional(),\n  })\n  .default({});\n"],"mappings":"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"}
+{"version":3,"file":"schemas.js","names":[],"sources":["../src/schemas.ts"],"sourcesContent":["/**\n * Content schemas for Nimbus.\n *\n * `docsSchema` is the default frontmatter contract for the `docs` collection.\n * `partialsSchema` is the contract for `<Render file=\"...\" />` partials.\n * `defineDocSchema(config)` returns a customizable schema for advanced users\n *   composing schemas outside the `docsCollection()` factory.\n *\n * Error messages target content authors, not framework developers.\n * Astro 6 ships Zod v4 via `astro/zod`. The v4 API uses a single `error`\n * field on every schema constructor — NOT v3's `required_error` /\n * `invalid_type_error` / `errorMap`.\n */\n\nimport { z } from \"astro/zod\";\n\nexport interface DocSchemaConfig {\n  /** Additional frontmatter fields merged into the default schema. */\n  fields?: Record<string, z.ZodTypeAny>;\n}\n\n// ---------------------------------------------------------------------------\n// Building blocks\n// ---------------------------------------------------------------------------\n\nconst sidebarBadgeSchema = z.union([\n  z.string(),\n  z.object({\n    text: z.string({ error: 'sidebar badge needs a \"text\" field' }),\n    variant: z\n      .enum(\n        [\"default\", \"info\", \"note\", \"success\", \"tip\", \"warning\", \"caution\", \"danger\"],\n        {\n          error:\n            '\"variant\" must be one of: default, info, note, success, tip, warning, caution, danger',\n        },\n      )\n      .default(\"default\"),\n  }),\n]);\n\nconst sidebarFrontmatterSchema = z\n  .object({\n    order: z.number({ error: '\"sidebar.order\" must be a number' }).optional(),\n    label: z.string({ error: '\"sidebar.label\" must be a string' }).optional(),\n    badge: sidebarBadgeSchema.optional(),\n    hidden: z.boolean({ error: '\"sidebar.hidden\" must be true or false' }).optional(),\n    hideChildren: z\n      .boolean({ error: '\"sidebar.hideChildren\" must be true or false' })\n      .optional(),\n  })\n  .optional();\n\nconst heroActionSchema = z.object({\n  text: z.string({ error: 'hero action needs a \"text\" field' }),\n  link: z.string({ error: 'hero action needs a \"link\" field' }),\n  variant: z\n    .enum([\"primary\", \"secondary\", \"outline\"], {\n      error: 'hero action \"variant\" must be \"primary\", \"secondary\", or \"outline\"',\n    })\n    .default(\"primary\"),\n  icon: z.string().optional(),\n});\n\nconst heroSchema = z\n  .object({\n    title: z.string().optional(),\n    tagline: z.string().optional(),\n    actions: z.array(heroActionSchema).optional(),\n  })\n  .optional();\n\nconst prevNextFrontmatterSchema = z\n  .union([\n    z.string(),\n    z.object({ link: z.string().optional(), label: z.string().optional() }),\n    z.literal(false),\n  ])\n  .optional();\n\nconst headElementSchema = z.object({\n  tag: z.enum([\"meta\", \"link\", \"script\", \"style\"], {\n    error: 'head element \"tag\" must be \"meta\", \"link\", \"script\", or \"style\"',\n  }),\n  attrs: z.record(z.string(), z.string()).default({}),\n  content: z.string().optional(),\n});\n\n// ---------------------------------------------------------------------------\n// Base docs schema\n// ---------------------------------------------------------------------------\n\nfunction baseDocSchema() {\n  return z.object({\n    title: z.string({\n      error: (iss) =>\n        iss.input === undefined\n          ? 'Missing required \"title\" in frontmatter. Every doc needs:\\n\\n  ---\\n  title: \"Your Page Title\"\\n  ---'\n          : `\"title\" must be a string, received ${typeof iss.input}`,\n    }),\n    description: z.string({ error: '\"description\" must be a string' }).optional(),\n    template: z\n      .enum([\"doc\", \"splash\"], {\n        error: '\"template\" must be \"doc\" or \"splash\"',\n      })\n      .default(\"doc\"),\n    sidebar: sidebarFrontmatterSchema,\n    hero: heroSchema,\n    head: z.array(headElementSchema).default([]),\n    draft: z.boolean({ error: '\"draft\" must be true or false' }).default(false),\n    noindex: z.boolean({ error: '\"noindex\" must be true or false' }).default(false),\n    /** Include this page in llms.txt and AI consumption indexes */\n    llms: z.boolean({ error: '\"llms\" must be true or false' }).default(true),\n    /** Signal AI crawlers to deprioritize this page */\n    aiDeprioritize: z\n      .boolean({ error: '\"aiDeprioritize\" must be true or false' })\n      .default(false),\n    pagefind: z.boolean({ error: '\"pagefind\" must be true or false' }).default(true),\n    tableOfContents: z\n      .object({\n        minHeadingLevel: z\n          .number({ error: '\"minHeadingLevel\" must be a number (1-6)' })\n          .int()\n          .min(1)\n          .max(6)\n          .default(2),\n        maxHeadingLevel: z\n          .number({ error: '\"maxHeadingLevel\" must be a number (1-6)' })\n          .int()\n          .min(1)\n          .max(6)\n          .default(3),\n      })\n      .refine((v) => v.minHeadingLevel <= v.maxHeadingLevel, {\n        message: \"minHeadingLevel must be <= maxHeadingLevel\",\n      })\n      .optional(),\n    lastUpdated: z.coerce\n      .date({ error: '\"lastUpdated\" must be a valid date (e.g. 2024-01-15)' })\n      .optional(),\n    /**\n     * Explicit per-page social/OG image override (path or absolute URL).\n     * When omitted, the page route is expected to fall back to a\n     * programmatically-generated card or the site-wide `config.socialImage`.\n     */\n    socialImage: z\n      .string({ error: '\"socialImage\" must be a string (path or URL)' })\n      .optional(),\n    prev: prevNextFrontmatterSchema,\n    next: prevNextFrontmatterSchema,\n    /**\n     * Versioning rename escape hatch.\n     *\n     * When a page is renamed between versions (the URL slug changes), the\n     * newer version's frontmatter declares the slug it had in an older\n     * version. The framework uses this to link the pages as cross-version\n     * alternates and to emit a `<link rel=\"canonical\">` to the current\n     * version's URL.\n     *\n     * Example: `docs-v1/old-name.mdx` was renamed in v2 to `new-name.mdx`.\n     * On the new page (`docs/new-name.mdx`, current version), set:\n     *\n     *   previousSlug: old-name\n     *\n     * Now `/new-name` and `/v1/old-name` are linked as the same logical\n     * page in `<head>` alternates, and the v1 page's canonical points to\n     * `/new-name`.\n     *\n     * Accepts a single slug string (the page's id in the older version)\n     * or an array of strings when the page has been renamed across more\n     * than one version.\n     */\n    previousSlug: z\n      .union([z.string(), z.array(z.string())], {\n        error: '\"previousSlug\" must be a string or array of strings',\n      })\n      .optional(),\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\n/**\n * Build a customizable docs schema. Use this when composing schemas outside\n * the `docsCollection()` factory (e.g. multiple docs collections with\n * different shapes).\n */\nexport function defineDocSchema(config: DocSchemaConfig = {}) {\n  const base = baseDocSchema();\n  if (config.fields) {\n    return base.extend(config.fields);\n  }\n  return base;\n}\n\n/** Default docs schema. Equivalent to `defineDocSchema()`. */\nexport const docsSchema = defineDocSchema();\n\n/** Schema for partials (`<Render file=\"...\" />` snippets). */\nexport const partialsSchema = z\n  .object({\n    /**\n     * Declared parameters this partial accepts.\n     * Suffix with `?` for optional params: `[\"name\", \"deprecated?\"]`\n     */\n    params: z.array(z.string()).optional(),\n  })\n  .default({});\n\n// ---------------------------------------------------------------------------\n// Components collection — used by sites documenting their own UI components.\n// Pair with `componentsCollection()` from `nimbus-docs/content`. Authoring\n// pattern: hero `<Showcase>` block + `<Example>` blocks in the MDX body, with\n// `props` declared in frontmatter for a generated prop table.\n// ---------------------------------------------------------------------------\n\n/** One row in a component's `props` frontmatter array. */\nconst componentPropSchema = z.object({\n  name: z.string({ error: 'prop needs a \"name\"' }),\n  type: z.string({ error: 'prop needs a \"type\"' }),\n  defaultValue: z.string().optional(),\n  required: z.boolean().default(false),\n  description: z.string({ error: 'prop needs a \"description\"' }),\n});\n\nexport type ComponentProp = z.infer<typeof componentPropSchema>;\n\n/** Default schema for the components collection. */\nexport const componentsSchema = z.object({\n  title: z.string({\n    error: (iss) =>\n      iss.input === undefined\n        ? 'Missing \"title\" in frontmatter — display name used in the sidebar and page header.'\n        : `\"title\" must be a string, received ${typeof iss.input}`,\n  }),\n  tagline: z.string({\n    error: (iss) =>\n      iss.input === undefined\n        ? 'Missing \"tagline\" in frontmatter — one-sentence summary shown under the title.'\n        : `\"tagline\" must be a string, received ${typeof iss.input}`,\n  }),\n  props: z.array(componentPropSchema).default([]),\n});\n"],"mappings":"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"}

package/dist/types.d.ts

@@ -36,6 +36,99 @@ interface NimbusConfig {
    * without running Pagefind at build time.
    */
   search?: SearchConfig | false;
+  /**
+   * Versioned-docs manifest. Absent means the site is unversioned (the
+   * default; no behavior change). When set, declares:
+   *
+   *   - `current` — label for the primary `docs` collection (e.g. `"v3"`).
+   *     The current version's content lives in `src/content/docs/`; this
+   *     field is the *name* used in URLs / UI / sidebar — there is no
+   *     `docs-v3` collection.
+   *   - `others` — label list for non-current versions. Each entry `<slug>`
+   *     must correspond to a registered Astro collection named
+   *     `docs-<slug>` (e.g. `"v2"` → collection `docs-v2` at
+   *     `src/content/docs-v2/`). Order is preserved; the picker and any
+   *     ordered enumeration will use it as-is.
+   *   - `deprecated` — subset of `others` that should render deprecation
+   *     UX (banner + sidebar badge + search demotion). P0 stores the list;
+   *     the visible behavior lands in P3. Default `[]`.
+   *   - `hidden` — subset of `others` that should be URL-reachable but
+   *     omitted from the picker, search index, and any other surface that
+   *     enumerates "all versions." Default `[]`.
+   *
+   * P0 ships the data layer only. Picker UI, cross-version `<link rel="alternate">`,
+   * canonical pointers, and deprecation banners land in later phases.
+   */
+  versions?: VersionsConfig;
+}
+/**
+ * Resolved versions manifest. See `NimbusConfig.versions` for field meanings.
+ */
+interface VersionsConfig {
+  current: string;
+  others: string[];
+  deprecated?: string[];
+  hidden?: string[];
+}
+/**
+ * Return shape for `getVersions()`. Normalises optional fields to empty
+ * arrays so consumers don't branch on `undefined`. `all` is `[current,
+ * ...others]` in manifest order, useful for picker enumeration.
+ */
+interface ResolvedVersions {
+  current: string;
+  others: string[];
+  deprecated: string[];
+  hidden: string[];
+  all: string[];
+}
+/**
+ * A single page in the cross-version alternates graph. Returned by
+ * `getVersionAlternates()` as part of each entry's record.
+ */
+interface VersionPageRef {
+  /** Astro collection ID — `"docs"` or `"docs-<slug>"`. */
+  collection: string;
+  /** Version slug — `current` for `docs`, the suffix for `docs-<v>`. */
+  version: string;
+  /** Page slug (entry.id) within the collection. */
+  slug: string;
+  /** Resolved URL path with leading slash, no trailing slash. */
+  url: string;
+}
+/**
+ * Per-page record in the alternates table. `self` describes the entry
+ * being looked up; `alternates` lists every other entry in the same
+ * SEO-equivalence class; `canonical` points at the current-version
+ * sibling when one exists and isn't `self`.
+ */
+interface VersionAlternateRecord {
+  self: VersionPageRef;
+  alternates: VersionPageRef[];
+  canonical: VersionPageRef | null;
+}
+/** Build-time alternates table indexed by `${collection}:${entryId}`. */
+type VersionAlternatesTable = Record<string, VersionAlternateRecord>;
+/**
+ * Versioning status for a single page's collection. Returned by
+ * `getVersionStatus()`. Drives the deprecation banner, Pagefind
+ * facet filters, and hidden-version exclusion in the layout.
+ *
+ * Fields:
+ *   - `version` — the version slug this page belongs to (`current` for
+ *     `docs`, `v1`/`v2`/… for `docs-<slug>`).
+ *   - `isCurrent` — true when `version === versions.current`.
+ *   - `isDeprecated` — true when `version` is listed in `versions.deprecated`.
+ *     Triggers the deprecation banner + Pagefind `status:deprecated` filter.
+ *   - `isHidden` — true when `version` is listed in `versions.hidden`.
+ *     Hidden versions are URL-reachable but excluded from search and
+ *     any picker/listing surface.
+ */
+interface VersionStatus {
+  version: string;
+  isCurrent: boolean;
+  isDeprecated: boolean;
+  isHidden: boolean;
 }
 interface FeaturesConfig {
   search?: boolean;
@@ -73,6 +166,19 @@ interface HeadElement {
 }
 interface SidebarConfig {
   items?: SidebarConfigItem[];
+  /**
+   * How the sidebar rail filters the tree on each page.
+   *
+   * - `"full"` (default) — show the entire tree on every page. Best for
+   *   small / flat sites; pairs naturally with the header section-tab
+   *   strip when one exists.
+   * - `"section"` — scope to the current top-level section. Best for
+   *   large sites where the full rail would overflow; cross-section nav
+   *   must come from the header tabs.
+   *
+   * @default "full"
+   */
+  scope?: "full" | "section";
 }
 /**
  * A top-level section derived from the sidebar tree — used to render the
@@ -232,6 +338,17 @@ interface BasePageProps {
    * same prop without touching the layout.
    */
   lastUpdated?: Date;
+  /**
+   * Astro collection ID for this page (e.g. `"docs"`, `"docs-v1"`).
+   * Forwarded to `NimbusHead` so it can look up cross-version alternates
+   * and the canonical override. Pass `entry.collection` from your route.
+   */
+  collection?: string;
+  /**
+   * Astro entry id (slug) for this page. Forwarded to `NimbusHead` for
+   * the alternates lookup. Pass `entry.id` from your route.
+   */
+  entryId?: string;
 }
 /**
  * Props passed to a Nimbus docs layout (e.g. `DocsLayout.astro`).
@@ -270,5 +387,5 @@ interface DocsPageProps extends BasePageProps {
   prevNext: PrevNext;
 }
 //#endregion
-export { BadgeVariant, BannerProps, BasePageProps, Breadcrumb, DocsPageProps, FeaturesConfig, HeadElement, NimbusConfig, PrevNext, PrevNextLink, PrevNextOverrides, SearchConfig, SearchProvider, SearchResult, SidebarBadge, SidebarConfig, SidebarConfigItem, SidebarExternalLinkItem, SidebarGroupItem, SidebarItem, SidebarLinkItem, SidebarSection, TOCItem };
+export { BadgeVariant, BannerProps, BasePageProps, Breadcrumb, DocsPageProps, FeaturesConfig, HeadElement, NimbusConfig, PrevNext, PrevNextLink, PrevNextOverrides, ResolvedVersions, SearchConfig, SearchProvider, SearchResult, SidebarBadge, SidebarConfig, SidebarConfigItem, SidebarExternalLinkItem, SidebarGroupItem, SidebarItem, SidebarLinkItem, SidebarSection, TOCItem, VersionAlternateRecord, VersionAlternatesTable, VersionPageRef, VersionStatus, VersionsConfig };
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"mappings":"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"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nimbus-docs",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "type": "module",
   "description": "Docs, for humans and agents",

package/src/components/NimbusHead.astro

@@ -29,6 +29,11 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { config } from "virtual:nimbus/config";
+import {
+  getCollectionLlmsUrl,
+  getVersionAlternates,
+  getVersionStatus,
+} from "../index.js";
 import type { HeadElement } from "../types.js";
 
 export interface Props {
@@ -52,6 +57,16 @@ export interface Props {
   lastUpdated?: Date;
   /** Per-page head extras, appended after `config.head`. */
   head?: HeadElement[];
+  /**
+   * Astro collection ID for this page — used to look up cross-version
+   * alternates when versioning is configured. Pass `entry.collection`
+   * from your route. Optional: when omitted (e.g. on hand-built pages
+   * outside the docs collections), no alternate/canonical tags are
+   * emitted from the versioning layer.
+   */
+  collection?: string;
+  /** Astro entry id (slug) for this page. Pass `entry.id` from your route. */
+  entryId?: string;
 }
 
 const {
@@ -63,13 +78,60 @@ const {
   socialImage,
   lastUpdated,
   head: pageHead = [],
+  collection,
+  entryId,
 } = Astro.props;
 
 // ---- Derived values -------------------------------------------------------
 
 const hasSite = !!Astro.site;
+
+// Cross-version alternates and canonical override. When the page is part
+// of a versioned-docs class with a current-version sibling that isn't
+// `self`, `record.canonical` points to it — we emit that URL as the
+// canonical instead of the page's own URL, so search engines treat the
+// current version as authoritative.
+const versionRecord =
+  collection && entryId ? await getVersionAlternates(collection, entryId) : null;
+const versionCanonicalPath = versionRecord?.canonical?.url ?? null;
+
+// Hidden-version suppression. Hidden versions are URL-reachable but
+// excluded from every agent-discovery and SEO surface. When the page
+// belongs to a hidden version we strip:
+//   - the markdown alternate link (no `.md` route is guaranteed to exist
+//     for hidden pages, and even if one did, agents shouldn't be guided
+//     to it)
+//   - the LLM-index hint (the per-version `/<v>/llms.txt` is not emitted
+//     for hidden versions, so the link would 404)
+//   - cross-version `<link rel="alternate">` tags (other pages shouldn't
+//     advertise this hidden page either)
+// Canonical and `<meta robots>` are left alone — hidden pages still get
+// the normal `noindex` behavior the user opts into via frontmatter.
+const versionStatus =
+  collection ? await getVersionStatus(collection) : null;
+const isHiddenVersion = versionStatus?.isHidden === true;
+
+// Agent index hint — point readers' AI tooling at the right per-collection
+// llms.txt. Version pages point at `/v<n>/llms.txt`, non-primary
+// collection pages point at `/<collection>/llms.txt`, primary docs
+// pages point at the root `/llms.txt`. When `collection` is omitted
+// (hand-built routes outside the docs system), we fall back to the
+// root index. Hidden-version pages emit no LLM hint (see above).
+const llmsIndexPath =
+  isHiddenVersion
+    ? null
+    : collection
+      ? await getCollectionLlmsUrl(collection)
+      : "/llms.txt";
+const llmsIndexUrl =
+  llmsIndexPath && Astro.site
+    ? new URL(llmsIndexPath, Astro.site).href
+    : llmsIndexPath;
+
 const canonical = Astro.site
-  ? new URL(Astro.url.pathname, Astro.site).href
+  ? versionCanonicalPath
+    ? new URL(versionCanonicalPath, Astro.site).href
+    : new URL(Astro.url.pathname, Astro.site).href
   : null;
 
 const fullTitle = title !== config.title ? `${title} | ${config.title}` : title;
@@ -130,7 +192,24 @@ const mergedHead = [...(config.head ?? []), ...pageHead];
 <link rel="icon" type="image/svg+xml" href={faviconHref} />
 {hasSite && canonical && <link rel="canonical" href={canonical} />}
 {hasSite && <link rel="sitemap" href="/sitemap-index.xml" />}
-{markdownUrl && <link rel="alternate" type="text/markdown" href={markdownUrl} />}
+{markdownUrl && !isHiddenVersion && (
+  <link rel="alternate" type="text/markdown" href={markdownUrl} />
+)}
+{hasSite && llmsIndexUrl && (
+  <link
+    rel="alternate"
+    type="text/plain"
+    href={llmsIndexUrl}
+    title="LLM index"
+  />
+)}
+{!isHiddenVersion && versionRecord?.alternates.map((alt) => (
+  <link
+    rel="alternate"
+    data-version={alt.version}
+    href={Astro.site ? new URL(alt.url, Astro.site).href : alt.url}
+  />
+))}
 
 <meta property="og:title" content={fullTitle} />
 <meta property="og:type" content={ogType} />