nimbus-docs 0.0.2

package/dist/schemas.js

@@ -0,0 +1,110 @@
+import { z } from "astro/zod";
+
+//#region src/schemas.ts
+/**
+* Content schemas for Nimbus.
+*
+* `docsSchema` is the default frontmatter contract for the `docs` collection.
+* `partialsSchema` is the contract for `<Render file="..." />` partials.
+* `defineDocSchema(config)` returns a customizable schema for advanced users
+*   composing schemas outside the `docsCollection()` factory.
+*
+* Error messages target content authors, not framework developers.
+* Astro 6 ships Zod v4 via `astro/zod`. The v4 API uses a single `error`
+* field on every schema constructor — NOT v3's `required_error` /
+* `invalid_type_error` / `errorMap`.
+*/
+const sidebarBadgeSchema = z.union([z.string(), z.object({
+	text: z.string({ error: "sidebar badge needs a \"text\" field" }),
+	variant: z.enum([
+		"default",
+		"info",
+		"note",
+		"success",
+		"tip",
+		"warning",
+		"caution",
+		"danger"
+	], { error: "\"variant\" must be one of: default, info, note, success, tip, warning, caution, danger" }).default("default")
+})]);
+const sidebarFrontmatterSchema = z.object({
+	order: z.number({ error: "\"sidebar.order\" must be a number" }).optional(),
+	label: z.string({ error: "\"sidebar.label\" must be a string" }).optional(),
+	badge: sidebarBadgeSchema.optional(),
+	hidden: z.boolean({ error: "\"sidebar.hidden\" must be true or false" }).optional(),
+	hideChildren: z.boolean({ error: "\"sidebar.hideChildren\" must be true or false" }).optional()
+}).optional();
+const heroActionSchema = z.object({
+	text: z.string({ error: "hero action needs a \"text\" field" }),
+	link: z.string({ error: "hero action needs a \"link\" field" }),
+	variant: z.enum([
+		"primary",
+		"secondary",
+		"outline"
+	], { error: "hero action \"variant\" must be \"primary\", \"secondary\", or \"outline\"" }).default("primary"),
+	icon: z.string().optional()
+});
+const heroSchema = z.object({
+	title: z.string().optional(),
+	tagline: z.string().optional(),
+	actions: z.array(heroActionSchema).optional()
+}).optional();
+const prevNextFrontmatterSchema = z.union([
+	z.string(),
+	z.object({
+		link: z.string().optional(),
+		label: z.string().optional()
+	}),
+	z.literal(false)
+]).optional();
+const headElementSchema = z.object({
+	tag: z.enum([
+		"meta",
+		"link",
+		"script",
+		"style"
+	], { error: "head element \"tag\" must be \"meta\", \"link\", \"script\", or \"style\"" }),
+	attrs: z.record(z.string(), z.string()).default({}),
+	content: z.string().optional()
+});
+function baseDocSchema() {
+	return z.object({
+		title: z.string({ error: (iss) => iss.input === void 0 ? "Missing required \"title\" in frontmatter. Every doc needs:\n\n  ---\n  title: \"Your Page Title\"\n  ---" : `"title" must be a string, received ${typeof iss.input}` }),
+		description: z.string({ error: "\"description\" must be a string" }).optional(),
+		template: z.enum(["doc", "splash"], { error: "\"template\" must be \"doc\" or \"splash\"" }).default("doc"),
+		sidebar: sidebarFrontmatterSchema,
+		hero: heroSchema,
+		head: z.array(headElementSchema).default([]),
+		draft: z.boolean({ error: "\"draft\" must be true or false" }).default(false),
+		noindex: z.boolean({ error: "\"noindex\" must be true or false" }).default(false),
+		llms: z.boolean({ error: "\"llms\" must be true or false" }).default(true),
+		aiDeprioritize: z.boolean({ error: "\"aiDeprioritize\" must be true or false" }).default(false),
+		pagefind: z.boolean({ error: "\"pagefind\" must be true or false" }).default(true),
+		tableOfContents: z.object({
+			minHeadingLevel: z.number({ error: "\"minHeadingLevel\" must be a number (1-6)" }).int().min(1).max(6).default(2),
+			maxHeadingLevel: z.number({ error: "\"maxHeadingLevel\" must be a number (1-6)" }).int().min(1).max(6).default(3)
+		}).refine((v) => v.minHeadingLevel <= v.maxHeadingLevel, { message: "minHeadingLevel must be <= maxHeadingLevel" }).optional(),
+		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
+	});
+}
+/**
+* Build a customizable docs schema. Use this when composing schemas outside
+* the `docsCollection()` factory (e.g. multiple docs collections with
+* different shapes).
+*/
+function defineDocSchema(config = {}) {
+	const base = baseDocSchema();
+	if (config.fields) return base.extend(config.fields);
+	return base;
+}
+/** Default docs schema. Equivalent to `defineDocSchema()`. */
+const docsSchema = defineDocSchema();
+/** Schema for partials (`<Render file="..." />` snippets). */
+const partialsSchema = z.object({ params: z.array(z.string()).optional() }).default({});
+
+//#endregion
+export { defineDocSchema, docsSchema, partialsSchema };
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -0,0 +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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"}

package/dist/types.d.ts

@@ -0,0 +1,274 @@
+//#region src/types.d.ts
+/**
+ * Public type surface for `nimbus-docs/types`.
+ */
+interface NimbusConfig {
+  /** Canonical site URL, e.g. `https://docs.example.com`. */
+  site: string;
+  title: string;
+  description?: string;
+  /** Short text or symbol (max ~2 chars) used in the header logo. */
+  logo: string;
+  locale?: string;
+  /** Label for the "Home" breadcrumb / root link. */
+  homeLabel?: string;
+  /** Repo URL for header link. `null` to hide. */
+  github?: string | null;
+  /** Edit-link URL pattern. `{path}` is replaced with the doc's repo path. */
+  editPattern?: string | null;
+  /** Footer text. */
+  footer?: string;
+  /**
+   * Site-wide social/OG fallback image. Site-relative (e.g. `/og.png`) or
+   * absolute URL. Used when a page doesn't supply its own `socialImage`
+   * (via frontmatter or a build-time-generated card).
+   */
+  socialImage?: string;
+  /** Alt text for `socialImage`. Applied to og:image:alt + twitter:image:alt. */
+  socialImageAlt?: string;
+  /** Site-wide head elements (meta, link, script, style). */
+  head?: HeadElement[];
+  sidebar?: SidebarConfig;
+  features?: FeaturesConfig;
+  /**
+   * Search backend. Absent means Pagefind. `false` disables framework search
+   * plumbing. `{ provider: "custom" }` lets user code render a search UI
+   * without running Pagefind at build time.
+   */
+  search?: SearchConfig | false;
+}
+interface FeaturesConfig {
+  search?: boolean;
+  editLinks?: boolean;
+  pagination?: boolean;
+  toc?: boolean;
+}
+interface SearchConfig {
+  provider?: "pagefind" | "custom";
+}
+interface SearchResult {
+  /** Page title — shown as the primary result text. */
+  title: string;
+  /** Destination URL. */
+  url: string;
+  /** Excerpt with optional highlight markup. Providers should sanitize HTML. */
+  snippet?: string;
+  /** Heading-level matches within the page. */
+  subResults?: {
+    title: string;
+    url: string;
+  }[];
+}
+interface SearchProvider {
+  /** Optional lazy setup hook, called before the first search. */
+  init?(): Promise<void>;
+  search(query: string, opts?: {
+    signal?: AbortSignal;
+  }): Promise<SearchResult[]>;
+}
+interface HeadElement {
+  tag: "meta" | "link" | "script" | "style";
+  attrs?: Record<string, string>;
+  content?: string;
+}
+interface SidebarConfig {
+  items?: SidebarConfigItem[];
+}
+/**
+ * A top-level section derived from the sidebar tree — used to render the
+ * header tab strip (or any other cross-section navigation). One per
+ * top-level group; non-group items (links, externals) are skipped.
+ */
+interface SidebarSection {
+  /** Group label from `sidebar.items` (or the autogenerated directory name). */
+  label: string;
+  /** First link descendant's href — where the section "lives". */
+  href: string;
+  /** True when the current page is inside this section's tree. */
+  isActive: boolean;
+}
+type SidebarConfigItem = string | {
+  label: string;
+  link: string;
+  badge?: SidebarBadge;
+} | {
+  label?: string;
+  autogenerate: {
+    directory: string;
+  };
+  collapsed?: boolean;
+  badge?: SidebarBadge;
+} | {
+  label?: string;
+  /**
+   * Autogenerate from a named content collection. `getSidebar()` loads
+   * collections referenced by sidebar items automatically. `prefix`
+   * defaults to `/{collection}` (e.g. `/api` for `collection: "api"`)
+   * unless the collection is the primary `docs` collection, which mounts
+   * at root.
+   */
+  autogenerate: {
+    collection: string;
+    prefix?: string;
+  };
+  collapsed?: boolean;
+  badge?: SidebarBadge;
+} | {
+  label: string;
+  items: SidebarConfigItem[];
+  collapsed?: boolean;
+  badge?: SidebarBadge;
+};
+type BadgeVariant = "default" | "info" | "note" | "success" | "tip" | "warning" | "caution" | "danger";
+type SidebarBadge = string | {
+  text: string;
+  variant: BadgeVariant;
+};
+interface SidebarLinkItem {
+  type: "link";
+  label: string;
+  href: string;
+  isCurrent?: boolean;
+  badge?: SidebarBadge;
+  attrs?: Record<string, string>;
+  order: number;
+}
+interface SidebarExternalLinkItem {
+  type: "external";
+  label: string;
+  href: string;
+  badge?: SidebarBadge;
+  order: number;
+}
+interface SidebarGroupItem {
+  type: "group";
+  label: string;
+  order: number;
+  collapsed?: boolean;
+  badge?: SidebarBadge;
+  children: SidebarItem[];
+  _indexId?: string;
+}
+type SidebarItem = SidebarLinkItem | SidebarExternalLinkItem | SidebarGroupItem;
+interface TOCItem {
+  depth: number;
+  text: string;
+  slug: string;
+}
+interface Breadcrumb {
+  label: string;
+  href: string;
+}
+interface PrevNextLink {
+  label: string;
+  href: string;
+}
+interface PrevNext {
+  prev?: PrevNextLink;
+  next?: PrevNextLink;
+}
+interface PrevNextOverrides {
+  prev?: string | {
+    link?: string;
+    label?: string;
+  } | false;
+  next?: string | {
+    link?: string;
+    label?: string;
+  } | false;
+}
+/**
+ * Optional banner shown at the top of a doc page.
+ *
+ *   <Banner content="Heads up!" type="warning" />
+ *   <Banner content="..." dismissible={{ id: "v2-release", days: 7 }} />
+ */
+interface BannerProps {
+  content: string;
+  type?: "note" | "tip" | "caution" | "danger";
+  /** When set, users can dismiss the banner; their preference is remembered. */
+  dismissible?: {
+    /** Stable identifier — change this when the banner content meaningfully changes. */id: string; /** How long the dismissal sticks (default: forever). */
+    days?: number;
+  };
+}
+/**
+ * Metadata any Nimbus page hands its outer layout chrome.
+ *
+ * `BaseLayout` (the topmost shell — `<html>`, `<head>`, theme bootstrap,
+ * font preloads) renders the same handful of fields regardless of what
+ * kind of page it's wrapping. Specific page-shape layouts like
+ * `DocsLayout` extend this with their own additional contract (sidebar,
+ * TOC, breadcrumbs, etc. — see `DocsPageProps`).
+ *
+ * Every field is something the Nimbus framework knows how to handle:
+ *   - `head` entries get concatenated with `config.head` in the layout.
+ *   - `noindex` emits `<meta name="robots" content="noindex">`.
+ *   - `aiDeprioritize` signals AI crawlers via the conventional meta.
+ *   - `title` / `description` populate `<title>` / `<meta name="description">`.
+ */
+interface BasePageProps {
+  title: string;
+  description?: string;
+  /** Page-level head additions, merged with `config.head`. */
+  head?: HeadElement[];
+  /** Emit `<meta name="robots" content="noindex">`. */
+  noindex?: boolean;
+  /** Signal AI crawlers to deprioritize this page. */
+  aiDeprioritize?: boolean;
+  /** Absolute or site-relative URL for this page's markdown variant. */
+  markdownUrl?: string;
+  /**
+   * Page-level OG/Twitter image. Site-relative (e.g. `/og/welcome.png`) or
+   * absolute. Resolution lives in the user's page route — by the time it
+   * reaches the layout, this is either an explicit frontmatter override or
+   * a programmatically-generated card path. Falls back to
+   * `config.socialImage` when absent.
+   */
+  socialImage?: string;
+  /**
+   * ISO date for `article:modified_time`. Today this is sourced from
+   * frontmatter `lastUpdated`; a future git-based source can populate the
+   * same prop without touching the layout.
+   */
+  lastUpdated?: Date;
+}
+/**
+ * Props passed to a Nimbus docs layout (e.g. `DocsLayout.astro`).
+ *
+ * Extends `BasePageProps` with the additional fields a docs-style page
+ * needs: a sidebar tree, on-page TOC, breadcrumbs, prev/next links, plus
+ * docs-specific frontmatter like `template`, `banner`, `lastUpdated`.
+ *
+ * Every field is produced by either:
+ *   - the validated frontmatter schema (`docsSchema`), or
+ *   - a framework data helper (`getSidebar`, `getTOC`, `getBreadcrumbs`,
+ *     `getPrevNext`), or
+ *   - the validated config.
+ *
+ * Custom layouts can `Pick<>` the subset they need or `extends` to add
+ * project-specific extras.
+ */
+interface DocsPageProps extends BasePageProps {
+  /** Layout variant. `"splash"` skips the sidebar / TOC chrome. */
+  template?: "doc" | "splash";
+  /** Hide the search index entry for this page. */
+  pagefind?: boolean;
+  /** Don't render in production; treat as `noindex` in dev. */
+  draft?: boolean;
+  /** URL pointing at this page's source on the repo host (computed from `config.editPattern`). */
+  editUrl?: string;
+  /** Optional top-of-page banner. */
+  banner?: BannerProps;
+  /** From `getSidebar()`. */
+  sidebar: SidebarItem[];
+  /** From `getTOC()`. */
+  headings: TOCItem[];
+  /** From `getBreadcrumbs()`. */
+  breadcrumbs: Breadcrumb[];
+  /** From `getPrevNext()`. */
+  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 };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";;AAQA;;UAAiB,YAAA;EAyBR;EAvBP,IAAA;EACA,KAAA;EACA,WAAA;EA6BqB;EA3BrB,IAAA;EACA,MAAA;EAJA;EAMA,SAAA;EAHA;EAKA,MAAA;EAFA;EAIA,WAAA;EAAA;EAEA,MAAA;EAMA;;;;;EAAA,WAAA;EAMA;EAJA,cAAA;EAUA;EARA,IAAA,GAAO,WAAA;EACP,OAAA,GAAU,aAAA;EACV,QAAA,GAAW,cAAA;EASI;;;;;EAHf,MAAA,GAAS,YAAA;AAAA;AAAA,UAGM,cAAA;EACf,MAAA;EACA,SAAA;EACA,UAAA;EACA,GAAA;AAAA;AAAA,UAGe,YAAA;EACf,QAAA;AAAA;AAAA,UAGe,YAAA;;EAEf,KAAA;EAAA;EAEA,GAAA;EAEA;EAAA,OAAA;EAEe;EAAf,UAAA;IAAe,KAAA;IAAe,GAAA;EAAA;AAAA;AAAA,UAGf,cAAA;EAEN;EAAT,IAAA,KAAS,OAAA;EACT,MAAA,CAAO,KAAA,UAAe,IAAA;IAAS,MAAA,GAAS,WAAA;EAAA,IAAgB,OAAA,CAAQ,YAAA;AAAA;AAAA,UAGjD,WAAA;EACf,GAAA;EACA,KAAA,GAAQ,MAAA;EACR,OAAA;AAAA;AAAA,UAGe,aAAA;EACf,KAAA,GAAQ,iBAAA;AAAA;;;;AAPV;;UAeiB,cAAA;EAbD;EAed,KAAA;EAfA;EAiBA,IAAA;EAhBA;EAkBA,QAAA;AAAA;AAAA,KAGU,iBAAA;EAEN,KAAA;EAAe,IAAA;EAAc,KAAA,GAAQ,YAAA;AAAA;EAErC,KAAA;EACA,YAAA;IAAgB,SAAA;EAAA;EAChB,SAAA;EACA,KAAA,GAAQ,YAAA;AAAA;EAGR,KAAA;EAbI;AAGV;;;;;;EAkBM,YAAA;IAAgB,UAAA;IAAoB,MAAA;EAAA;EACpC,SAAA;EACA,KAAA,GAAQ,YAAA;AAAA;EAGR,KAAA;EACA,KAAA,EAAO,iBAAA;EACP,SAAA;EACA,KAAA,GAAQ,YAAA;AAAA;AAAA,KAOF,YAAA;AAAA,KAUA,YAAA;EAA0B,IAAA;EAAc,OAAA,EAAS,YAAA;AAAA;AAAA,UAE5C,eAAA;EACf,IAAA;EACA,KAAA;EACA,IAAA;EACA,SAAA;EACA,KAAA,GAAQ,YAAA;EACR,KAAA,GAAQ,MAAA;EACR,KAAA;AAAA;AAAA,UAGe,uBAAA;EACf,IAAA;EACA,KAAA;EACA,IAAA;EACA,KAAA,GAAQ,YAAA;EACR,KAAA;AAAA;AAAA,UAGe,gBAAA;EACf,IAAA;EACA,KAAA;EACA,KAAA;EACA,SAAA;EACA,KAAA,GAAQ,YAAA;EACR,QAAA,EAAU,WAAA;EACV,QAAA;AAAA;AAAA,KAGU,WAAA,GACR,eAAA,GACA,uBAAA,GACA,gBAAA;AAAA,UAMa,OAAA;EACf,KAAA;EACA,IAAA;EACA,IAAA;AAAA;AAAA,UAGe,UAAA;EACf,KAAA;EACA,IAAA;AAAA;AAAA,UAGe,YAAA;EACf,KAAA;EACA,IAAA;AAAA;AAAA,UAGe,QAAA;EACf,IAAA,GAAO,YAAA;EACP,IAAA,GAAO,YAAA;AAAA;AAAA,UAGQ,iBAAA;EACf,IAAA;IAAkB,IAAA;IAAe,KAAA;EAAA;EACjC,IAAA;IAAkB,IAAA;IAAe,KAAA;EAAA;AAAA;AA1CnC;;;;;;AAAA,UAuDiB,WAAA;EACf,OAAA;EACA,IAAA;EApDQ;EAsDR,WAAA;IArDU,oFAuDR,EAAA,UAtDM;IAwDN,IAAA;EAAA;AAAA;;;;;;;;;;;;AA5CJ;;;;UA+DiB,aAAA;EACf,KAAA;EACA,WAAA;EA9DI;EAgEJ,IAAA,GAAO,WAAA;EA7DQ;EA+Df,OAAA;;EAEA,cAAA;EA/DI;EAiEJ,WAAA;EA9D2B;;;;AAK7B;;;EAiEE,WAAA;EAhEA;;;;;EAsEA,WAAA,GAAc,IAAA;AAAA;;;;;;;;;;;;AAnDhB;;;;;UAsEiB,aAAA,SAAsB,aAAA;EAlErC;EAqEA,QAAA;EAjEE;EAmEF,QAAA;EAnEM;EAqEN,KAAA;EAlD4B;EAsD5B,OAAA;EA9BkB;EAgClB,MAAA,GAAS,WAAA;EAtDT;EA0DA,OAAA,EAAS,WAAA;EAxDF;EA0DP,QAAA,EAAU,OAAA;EAtDV;EAwDA,WAAA,EAAa,UAAA;EA9Cb;EAgDA,QAAA,EAAU,QAAA;AAAA"}

package/dist/types.js

@@ -0,0 +1 @@
+export {  };

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "nimbus-docs",
+  "version": "0.0.2",
+  "private": false,
+  "type": "module",
+  "description": "Docs, for humans and agents",
+  "keywords": [
+    "astro",
+    "documentation",
+    "docs",
+    "mdx",
+    "static-site"
+  ],
+  "homepage": "https://nimbus-docs.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MohamedH1998/nimbus-docs.git",
+    "directory": "packages/nimbus-docs"
+  },
+  "bugs": {
+    "url": "https://github.com/MohamedH1998/nimbus-docs/issues"
+  },
+  "license": "MIT",
+  "author": "Mohamed Hassan",
+  "bin": {
+    "nimbus": "./dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./content": {
+      "types": "./dist/content.d.ts",
+      "import": "./dist/content.js"
+    },
+    "./schemas": {
+      "types": "./dist/schemas.d.ts",
+      "import": "./dist/schemas.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./lib/pkgm": {
+      "types": "./dist/lib/pkgm.d.ts",
+      "import": "./dist/lib/pkgm.js"
+    },
+    "./components/NimbusHead.astro": "./src/components/NimbusHead.astro"
+  },
+  "files": [
+    "dist",
+    "src/components"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "astro": ">=6.4.0"
+  },
+  "dependencies": {
+    "@astrojs/markdown-satteri": "^0.2.1",
+    "@astrojs/mdx": "^6.0.0",
+    "@astrojs/sitemap": "^3.7.2",
+    "@clack/prompts": "^0.9.1",
+    "@shikijs/transformers": "^4.1.0",
+    "@vercel/detect-agent": "^1.2.3",
+    "mri": "^1.2.0"
+  },
+  "devDependencies": {
+    "astro": "^6.4.0",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.8.3"
+  }
+}

package/src/components/NimbusHead.astro

@@ -0,0 +1,161 @@
+---
+/**
+ * NimbusHead — the framework's SEO/head plumbing as a single component.
+ *
+ * Absorbs the ~50 lines of `<meta>`, `<link>`, OG/Twitter tags, JSON-LD,
+ * favicon, canonical, sitemap, and alternate-markdown wiring that every
+ * docs site needs but no content author edits. Reads from the validated
+ * nimbus config (via `virtual:nimbus/config`) and Astro page context.
+ *
+ * Render once inside a `<head>` in your layout, after the
+ * `<meta charset>` / `<meta viewport>` basics and any theme-FOUC
+ * inline script:
+ *
+ *     ---
+ *     import NimbusHead from "nimbus-docs/components/NimbusHead.astro";
+ *     const { title, description, ...rest } = Astro.props;
+ *     ---
+ *     <head>
+ *       <meta charset="utf-8" />
+ *       <meta name="viewport" content="width=device-width, initial-scale=1" />
+ *       <script is:inline>// theme FOUC inline script</script>
+ *       <NimbusHead {title} {description} {...rest} />
+ *     </head>
+ *
+ * SEO/OG fixes ship via framework version bump, not by every user
+ * re-doing their head tags. Roadmap row 7(a).
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { config } from "virtual:nimbus/config";
+import type { HeadElement } from "../types.js";
+
+export interface Props {
+  /** Page title — used for `<title>` and OG/Twitter title. */
+  title: string;
+  /** Falls back to `config.description` when absent. */
+  description?: string;
+  /** Emit `<meta name="robots" content="noindex">`. */
+  noindex?: boolean;
+  /** Emit `<meta name="ai-deprioritize" content="true">`. */
+  aiDeprioritize?: boolean;
+  /** Absolute or site-relative URL for the markdown variant of this page. */
+  markdownUrl?: string;
+  /**
+   * Per-page OG/Twitter image override. Site-relative (`/og/foo.png`) or
+   * absolute. Falls back to `config.socialImage`, then to `/opengraph.png`
+   * if it exists in `public/`, otherwise `/og.png`.
+   */
+  socialImage?: string;
+  /** Drives `<meta property="article:modified_time">` on non-home pages. */
+  lastUpdated?: Date;
+  /** Per-page head extras, appended after `config.head`. */
+  head?: HeadElement[];
+}
+
+const {
+  title,
+  description,
+  noindex,
+  aiDeprioritize,
+  markdownUrl,
+  socialImage,
+  lastUpdated,
+  head: pageHead = [],
+} = Astro.props;
+
+// ---- Derived values -------------------------------------------------------
+
+const hasSite = !!Astro.site;
+const canonical = Astro.site
+  ? new URL(Astro.url.pathname, Astro.site).href
+  : null;
+
+const fullTitle = title !== config.title ? `${title} | ${config.title}` : title;
+const resolvedDescription = description ?? config.description;
+const faviconHref = `${import.meta.env.BASE_URL}favicon.svg`;
+const lang = config.locale ?? "en";
+
+const isHomePage = Astro.url.pathname === "/";
+const ogType = isHomePage ? "website" : "article";
+
+// `process.cwd()` resolves to the consumer's project root at build time.
+// The check lets users drop a `public/opengraph.png` and have it picked
+// up as the default social image without touching config.
+const userOpenGraphImage = join(process.cwd(), "public", "opengraph.png");
+const defaultSocialImage = existsSync(userOpenGraphImage) ? "/opengraph.png" : "/og.png";
+const socialImagePath = socialImage ?? config.socialImage ?? defaultSocialImage;
+const ogImage = socialImagePath
+  ? Astro.site
+    ? new URL(socialImagePath, Astro.site).href
+    : socialImagePath
+  : null;
+const ogImageAlt = config.socialImageAlt;
+
+const structuredData = canonical
+  ? JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": isHomePage ? "WebSite" : "WebPage",
+      name: fullTitle,
+      ...(resolvedDescription ? { description: resolvedDescription } : {}),
+      url: canonical,
+      inLanguage: lang,
+      ...(ogImage ? { image: ogImage } : {}),
+      ...(isHomePage
+        ? {}
+        : {
+            isPartOf: {
+              "@type": "WebSite",
+              name: config.title,
+              url: Astro.site ? new URL("/", Astro.site).href : config.site,
+            },
+            ...(lastUpdated ? { dateModified: lastUpdated.toISOString() } : {}),
+          }),
+    })
+  : null;
+
+// Per-HTML last-element-wins semantics: page extras come after config
+// extras so per-page overrides win for any duplicated single-value tag.
+const mergedHead = [...(config.head ?? []), ...pageHead];
+---
+
+<title>{fullTitle}</title>
+
+<meta name="generator" content={Astro.generator} />
+{resolvedDescription && <meta name="description" content={resolvedDescription} />}
+{noindex && <meta name="robots" content="noindex" />}
+{aiDeprioritize && <meta name="ai-deprioritize" content="true" />}
+
+<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} />}
+
+<meta property="og:title" content={fullTitle} />
+<meta property="og:type" content={ogType} />
+<meta property="og:site_name" content={config.title} />
+<meta property="og:locale" content={lang} />
+{resolvedDescription && <meta property="og:description" content={resolvedDescription} />}
+{hasSite && canonical && <meta property="og:url" content={canonical} />}
+{ogImage && <meta property="og:image" content={ogImage} />}
+{ogImage && ogImageAlt && <meta property="og:image:alt" content={ogImageAlt} />}
+{ogImage && <meta property="og:image:width" content="1200" />}
+{ogImage && <meta property="og:image:height" content="630" />}
+{!isHomePage && lastUpdated && (
+  <meta property="article:modified_time" content={lastUpdated.toISOString()} />
+)}
+
+<meta name="twitter:card" content={ogImage ? "summary_large_image" : "summary"} />
+<meta name="twitter:title" content={fullTitle} />
+{resolvedDescription && <meta name="twitter:description" content={resolvedDescription} />}
+{ogImage && <meta name="twitter:image" content={ogImage} />}
+{ogImage && ogImageAlt && <meta name="twitter:image:alt" content={ogImageAlt} />}
+
+{structuredData && <script type="application/ld+json" set:html={structuredData} />}
+
+{mergedHead.map(({ tag: Tag, attrs = {}, content }) =>
+  content
+    ? <Tag {...attrs} set:html={content} />
+    : <Tag {...attrs} />
+)}