@eqtylab/docs 0.3.5 → 0.5.0

package/README.md

@@ -52,7 +52,13 @@ collapsed: false
 
 - Children listed in `order` come first, in that order.
 - Everything unlisted appends alphabetically by sidebar label (`sort: filename` or `manual` to change that).
-- `index.mdx` in a folder becomes that folder's own landing page.
+- A section's overview always leads it, whether that is the folder's `index.mdx`, a page named
+  `overview`, or one titled "Overview" - alphabetical order would otherwise bury it mid-list.
+- `index.mdx` in a folder becomes that folder's own page, listed first in the group as
+  **Overview**. A section header only expands - it is never a link - because not every
+  section has an index, and a header that navigates only sometimes teaches the wrong habit.
+  Rename that row with `indexLabel` on the group, or globally with `sidebar.indexLabel`.
+  The content root's `index.mdx` is the site landing page and stays out of the sidebar.
 - A typo in `order` produces a build **warning naming the file and the token** rather than silently
   reordering, and the schema is `.strict()` so an unknown key fails the build.
 
@@ -213,6 +219,38 @@ wired in: `docsEntries` and `pathContext` alongside `docsNav` in `nav-data.ts`,
 `prevNextFor` / `buildTocTree` re-exported from there, and `mdxComponents` in `mdx-components.ts`
 for rendering a collection entry through the same component map.
 
+## Plugins
+
+A plugin is code that runs while Astro reads your config, so it can generate a whole section of
+the site: an API reference from an OpenAPI document, a changelog from git, anything that is
+pages plus a place in the sidebar. Pass instances to `docs({ plugins })`:
+
+```js
+docs({
+  title: 'My Docs',
+  plugins: [openApiReference({ spec: './public/openapi.yaml' })],
+});
+```
+
+A plugin is `{ name, setup(ctx) }`. `setup` runs inside `astro:config:setup`, after the framework
+has planned its own routes, and receives:
+
+- `ctx.astro` — the raw hook params: `config`, `injectRoute`, `updateConfig`, `addWatchFile`,
+  `logger`. Inject a route per generated page; its entrypoint can import
+  `@eqtylab/docs/layouts/DocsPage.astro`, `@eqtylab/docs/chrome/Prose.astro` and the helpers in
+  `@eqtylab/docs/lib/*`, so a generated page gets the same chrome as an authored one.
+- `ctx.addNavGroup(group)` — a `NavNode` appended to the top of the sidebar, after the
+  folder-derived groups and `sidebar.extra`. It is static: for current-page state, or to nest
+  the group inside an authored section, build the tree in your route instead and pass it to
+  `DocsPage`.
+- `ctx.addMdxComponents({ Name: specifier })` — components every MDX page can use without an
+  import, by module specifier (a package export or an absolute path) whose default export is the
+  component. The runtime imports them through a virtual module, which is why a component object
+  cannot be passed. A plugin's entry replaces a default of the same name.
+
+A malformed entry, or a component passed as an object, fails the build with a message naming
+the plugin rather than registering nothing.
+
 ## Building the Search Index
 
 Full-text search uses the built HTML, via [Pagefind](https://pagefind.app). The integration
@@ -236,20 +274,47 @@ cannot drift apart.
 The control itself is a command palette in the header, opened by click, `⌘K` or `/`. Fill the
 header's `search` slot to replace it, or set `search.provider: 'none'` to drop it entirely.
 
-## Versioned deploys
+## Versions
 
-`base` must be literal in Astro's config at build time, so it is threaded by environment variable:
+On by default. With release tags in the repository (`v1.2.3`, one per release), the build makes
+one frozen copy of the docs per older group and serves it under `/v<group>/`, adds a switcher to
+the header, a banner and `noindex` to every old page, and scopes search to the page's version.
+Every release tag that is not a copy of its own redirects to its group's copy. Without tags it
+is dormant and the build is unchanged.
 
-| Variable            | Meaning                                                                    |
-| ------------------- | -------------------------------------------------------------------------- |
-| `DOCS_BASE`         | Astro's `base` — `/`, `/v3.1/`, `/repo/v3.1/`                              |
-| `DOCS_VERSION_ROOT` | Directory holding all version directories (tracked separately from `base`) |
-| `DOCS_VERSION`      | This build's version id, e.g. `3.1`                                        |
-| `DOCS_IS_LATEST`    | `true` for the canonical build served at root                              |
+```js
+docs({
+  versions: {
+    current: '4.0.0', // defaults to the highest matching tag
+    tags: 'v*', // git tag glob; tags not ending in MAJOR.MINOR.PATCH are skipped
+    granularity: 'minor', // 'major' (default) | 'minor' | 'patch'
+  },
+});
+// or
+docs({ versions: false });
+```
 
-Every internal URL flows through `@eqtylab/docs/paths`, and authored markdown links are rewritten by
-a rehype plugin — Astro does not do this itself, so without it every root-relative link in content
-would 404 in a sub-path build.
+What to know:
+
+- `current` is never read from your `package.json`. Set it from the product you document, or
+  leave it to the highest tag.
+- A tag counts when it **ends** in `MAJOR.MINOR.PATCH`. Any prefix is allowed, so `v1.2.3`,
+  `1.2.3`, `sdk-v1.2.3` and `@scope/pkg@1.2.3` all work. Prereleases and anything else are
+  skipped with a warning naming the tag.
+- CI needs the tags: check out with `fetch-depth: 0`.
+- If a tag lands one deploy after its bump and `current` is inferred, the `/` label is one
+  release behind for that deploy. The content is current; the label heals on the next tag.
+- An archived page is a document, not an app. Prose, headings, tables and code samples are
+  kept; live component examples are not rendered, because an old page's imports bind it to
+  today's library. The banner says so.
+- Old versions are read-only. A wrong page is fixed by a new tag.
+- Moving `granularity` between `minor` and `patch` does not break published URLs: every grouping
+  coarser than the one you set also resolves, so `/v3/` and `/v3.9/` both work at either setting.
+  Moving **to `major` does** break them. Only groupings at or coarser than the setting are emitted,
+  so at `major` nothing emits `v3.9` and every published `/v3.9/` URL retires.
+
+The `DOCS_BASE` family of environment variables still exists for consumers who deploy each
+version as a separate build under its own `base`; this feature does not use them.
 
 ## Development
 

package/dist/{chunk-VJN3HXKM.js → chunk-LNQV7TVH.js}

@@ -13,7 +13,7 @@ function ensureTrailingSlash(href) {
   if (isUnrewritable(href)) return href;
   const [path, rest = ""] = href.split(/(?=[?#])/, 2);
   if (path.endsWith("/")) return href;
-  if (/\.[a-z0-9]+$/i.test(path)) return href;
+  if (/\.[a-z0-9]*[a-z][a-z0-9]*$/i.test(path)) return href;
   return path + "/" + rest;
 }
 function idToPath(id) {
@@ -32,11 +32,11 @@ function withBase(path, ctx) {
   return joinPath(ctx.base, path);
 }
 function docsHref(id, ctx) {
-  return ensureTrailingSlash(joinPath(ctx.base, ctx.versionPrefix, ctx.pathPrefix, idToPath(id)));
+  return ensureTrailingSlash(joinPath(ctx.base, ctx.pathPrefix, ctx.versionPrefix, idToPath(id)));
 }
 function stripBase(pathname, ctx) {
   let rest = normalizePath(pathname);
-  for (const prefix of [ctx.base, ctx.versionPrefix, ctx.pathPrefix]) {
+  for (const prefix of [ctx.base, ctx.pathPrefix, ctx.versionPrefix]) {
     if (!prefix) continue;
     const norm = normalizePath(joinPath(prefix));
     if (norm === "/") continue;
@@ -53,7 +53,19 @@ function isAncestor(currentPathname, target) {
   const t = normalizePath(target);
   return t === "/" ? current === "/" : current === t || current.startsWith(t + "/");
 }
+function resolveVersionedPath(pathname, opts) {
+  const rest = stripBase(pathname, { base: opts.base, pathPrefix: opts.pathPrefix });
+  const segments = rest.replace(/^\/+|\/+$/g, "").split("/");
+  const first = segments[0];
+  if (!first || !/^v\d/.test(first)) return null;
+  const tail = segments.slice(1).join("/");
+  const reapply = (version, page) => ensureTrailingSlash(joinPath(opts.base, opts.pathPrefix, version, page));
+  if (opts.copyIds.includes(first)) return reapply(first, "");
+  const redirect = opts.redirects.find((r) => r.id === first);
+  if (!redirect) return null;
+  return reapply(redirect.to ?? "", tail);
+}
 
-export { docsHref, ensureTrailingSlash, idToPath, isActive, isAncestor, isExternalHref, joinPath, normalizePath, stripBase, withBase };
-//# sourceMappingURL=chunk-VJN3HXKM.js.map
-//# sourceMappingURL=chunk-VJN3HXKM.js.map
+export { docsHref, ensureTrailingSlash, idToPath, isActive, isAncestor, isExternalHref, joinPath, normalizePath, resolveVersionedPath, stripBase, withBase };
+//# sourceMappingURL=chunk-LNQV7TVH.js.map
+//# sourceMappingURL=chunk-LNQV7TVH.js.map

package/dist/chunk-LNQV7TVH.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/paths.ts"],"names":[],"mappings":"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","file":"chunk-LNQV7TVH.js","sourcesContent":["/** Every URL the framework emits goes through here; nothing else may concatenate a path. */\n\n/** Join path segments, collapsing duplicate slashes, always leading with one. */\nexport function joinPath(...parts: Array<string | undefined | null>): string {\n  const joined = parts.filter((p): p is string => typeof p === 'string' && p.length > 0).join('/');\n  return '/' + joined.replace(/^\\/+/, '').replace(/\\/{2,}/g, '/');\n}\n\n/** True for anything we must not rewrite: protocol, protocol-relative, fragment, or query. */\nexport function isExternalHref(href: string): boolean {\n  return /^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith('//');\n}\n\nfunction isUnrewritable(href: string): boolean {\n  return isExternalHref(href) || href.startsWith('#') || href.startsWith('?');\n}\n\nexport function ensureTrailingSlash(href: string): string {\n  if (isUnrewritable(href)) return href;\n  const [path, rest = ''] = href.split(/(?=[?#])/, 2);\n  if (path.endsWith('/')) return href;\n  // Never slash something that looks like a file (/llms.txt, /a.md). The extension must carry a\n  // letter: a version id ends `.9`, and treating `/v3.9` as a file drops the slash from every\n  // version root, costing a host redirect and breaking exact-match comparisons against it.\n  if (/\\.[a-z0-9]*[a-z][a-z0-9]*$/i.test(path)) return href;\n  return path + '/' + rest;\n}\n\n/** Astro gives the root `index.mdx` the id \"index\", not \"\". */\nexport function idToPath(id: string): string {\n  return id === 'index' ? '' : id;\n}\n\n/** Trim trailing slashes for comparison. Keeps a bare \"/\" intact. */\nexport function normalizePath(path: string): string {\n  let decoded = path;\n  try {\n    decoded = decodeURI(path);\n  } catch {\n    // Malformed percent-encoding: compare the raw value.\n  }\n  return decoded.replace(/\\/+$/, '') || '/';\n}\n\nexport interface PathContext {\n  /** Astro's `import.meta.env.BASE_URL`. Always has a leading slash. */\n  base: string;\n  /** Mounted-at prefix for docs pages, e.g. \"docs\". Usually empty. */\n  pathPrefix?: string;\n  /** Version segment for an older copy, e.g. \"v3.9\". Empty for latest. */\n  versionPrefix?: string;\n}\n\n/** Prefix a site-absolute path with `base`. For assets: favicons, logos, og images. */\nexport function withBase(path: string, ctx: PathContext): string {\n  if (isUnrewritable(path)) return path;\n  return joinPath(ctx.base, path);\n}\n\n/** The public URL for a docs collection entry id. The version rides in the route's slug, so it follows the prefix. */\nexport function docsHref(id: string, ctx: PathContext): string {\n  return ensureTrailingSlash(joinPath(ctx.base, ctx.pathPrefix, ctx.versionPrefix, idToPath(id)));\n}\n\n/** Remove `base` (and path/version prefixes) from a pathname, yielding a docs-relative path. */\nexport function stripBase(pathname: string, ctx: PathContext): string {\n  let rest = normalizePath(pathname);\n  for (const prefix of [ctx.base, ctx.pathPrefix, ctx.versionPrefix]) {\n    if (!prefix) continue;\n    const norm = normalizePath(joinPath(prefix));\n    if (norm === '/') continue;\n    if (rest === norm) return '/';\n    if (rest.startsWith(norm + '/')) rest = rest.slice(norm.length);\n  }\n  return rest || '/';\n}\n\n/** Whether `target` is the page currently being viewed. Base-aware, slash-insensitive. */\nexport function isActive(currentPathname: string, target: string): boolean {\n  return normalizePath(currentPathname) === normalizePath(target);\n}\n\n/** Whether `target` is the current page or an ancestor of it. Drives group expansion. */\nexport function isAncestor(currentPathname: string, target: string): boolean {\n  const current = normalizePath(currentPathname);\n  const t = normalizePath(target);\n  return t === '/' ? current === '/' : current === t || current.startsWith(t + '/');\n}\n\ninterface VersionFallback {\n  base: string;\n  pathPrefix?: string;\n  /** Ids of versions that have a real copy built. */\n  copyIds: string[];\n  redirects: Array<{ id: string; to: string | null }>;\n}\n\n/**\n * Where to send a reader whose URL named a release with no page of its own.\n *\n * Static hosting emits a file per URL, and stubs are emitted for bare release URLs only, so\n * `/v3.2.4/` resolves while `/v3.2.4/components/button/` reaches the not-found page. Per-page\n * stubs would be roughly 3,000 files that grow with every release; this recovers the same\n * destination from one page, and unlike the bare stub it keeps the page the reader asked for.\n *\n * Returns null when the path names no version, which is an ordinary 404.\n */\nexport function resolveVersionedPath(pathname: string, opts: VersionFallback): string | null {\n  const rest = stripBase(pathname, { base: opts.base, pathPrefix: opts.pathPrefix });\n  const segments = rest.replace(/^\\/+|\\/+$/g, '').split('/');\n  const first = segments[0];\n  if (!first || !/^v\\d/.test(first)) return null;\n\n  const tail = segments.slice(1).join('/');\n  const reapply = (version: string, page: string) =>\n    ensureTrailingSlash(joinPath(opts.base, opts.pathPrefix, version, page));\n\n  // The version exists but this page does not: its root forwards to that version's first page.\n  // Sending the reader to latest instead would silently show them a different release.\n  if (opts.copyIds.includes(first)) return reapply(first, '');\n\n  const redirect = opts.redirects.find((r) => r.id === first);\n  if (!redirect) return null;\n  return reapply(redirect.to ?? '', tail);\n}\n"]}

package/dist/chunk-OM7745ZQ.js

@@ -0,0 +1,77 @@
+import path from 'path';
+import { visit } from 'unist-util-visit';
+
+// src/internal/rehype-base-url.ts
+var URL_ATTRS = ["href", "src", "poster"];
+var SRCSET_ATTRS = ["srcSet", "srcset"];
+function trimSlashes(s) {
+  return s.replace(/^\/+|\/+$/g, "");
+}
+function prefixOf(base, pathPrefix, version) {
+  const parts = [base, pathPrefix, version].map((p) => p ? trimSlashes(p) : "").filter(Boolean);
+  return parts.length ? "/" + parts.join("/") : "";
+}
+function shouldRewrite(value, prefix) {
+  if (!value.startsWith("/")) return false;
+  if (value.startsWith("//")) return false;
+  if (prefix && (value === prefix || value.startsWith(prefix + "/"))) return false;
+  return true;
+}
+function rewrite(value, base, pathPrefix, version) {
+  const full = prefixOf(base, pathPrefix, version);
+  if (!full || !shouldRewrite(value, full)) return value;
+  const pp = pathPrefix ? "/" + trimSlashes(pathPrefix) : "";
+  if (pp && (value === pp || value.startsWith(pp + "/"))) {
+    const rest = value.slice(pp.length);
+    return prefixOf(base, pathPrefix, version) + rest;
+  }
+  return full + value;
+}
+function rewriteSrcset(value, base, pathPrefix, version) {
+  return value.split(",").map((candidate) => {
+    const trimmed = candidate.trim();
+    if (!trimmed) return candidate;
+    const [url, ...descriptors] = trimmed.split(/\s+/);
+    return [rewrite(url, base, pathPrefix, version), ...descriptors].join(" ");
+  }).join(", ");
+}
+function versionFromPath(filePath, versionsDir) {
+  if (!filePath || !versionsDir) return void 0;
+  const rel = path.relative(versionsDir, filePath);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) return void 0;
+  return rel.split(path.sep)[0] || void 0;
+}
+function rehypeBaseUrl(options) {
+  const base = options.base || "/";
+  return function transformer(tree, file) {
+    const version = versionFromPath(file?.path ?? file?.history?.[0], options.versionsDir);
+    if (base === "/" && !version) return;
+    visit(tree, "element", (node) => {
+      const props = node.properties;
+      if (!props) return;
+      for (const attr of URL_ATTRS) {
+        const value = props[attr];
+        if (typeof value === "string") {
+          props[attr] = rewrite(value, base, options.pathPrefix, version);
+        }
+      }
+      for (const attr of SRCSET_ATTRS) {
+        const value = props[attr];
+        if (typeof value === "string") {
+          props[attr] = rewriteSrcset(value, base, options.pathPrefix, version);
+        }
+      }
+    });
+  };
+}
+function rewriteHtmlBase(html, base, pathPrefix, version) {
+  if ((!base || base === "/") && !version) return html;
+  return html.replace(
+    /\b(href|src)=("|')(\/(?!\/)[^"']*)\2/g,
+    (_match, attr, quote, url) => `${attr}=${quote}${rewrite(url, base, pathPrefix, version)}${quote}`
+  );
+}
+
+export { rehypeBaseUrl, rewriteHtmlBase, versionFromPath };
+//# sourceMappingURL=chunk-OM7745ZQ.js.map
+//# sourceMappingURL=chunk-OM7745ZQ.js.map

package/dist/chunk-OM7745ZQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/rehype-base-url.ts"],"names":[],"mappings":"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","file":"chunk-OM7745ZQ.js","sourcesContent":["/**\n * Prefixes root-relative URLs with Astro's `base`, which Astro does not do for authored\n * markdown links, and with the page's version segment when the file is an extracted copy.\n */\nimport path from 'node:path';\nimport { visit } from 'unist-util-visit';\n\ninterface ElementNode {\n  type: string;\n  properties?: Record<string, unknown>;\n}\n\nconst URL_ATTRS = ['href', 'src', 'poster'];\nconst SRCSET_ATTRS = ['srcSet', 'srcset'];\n\nfunction trimSlashes(s: string): string {\n  return s.replace(/^\\/+|\\/+$/g, '');\n}\n\n/** `/site/` + `docs` + `v3.9` → `/site/docs/v3.9`. Empty parts vanish. Returns '' when nothing applies. */\nfunction prefixOf(\n  base: string,\n  pathPrefix: string | undefined,\n  version: string | undefined\n): string {\n  const parts = [base, pathPrefix, version].map((p) => (p ? trimSlashes(p) : '')).filter(Boolean);\n  return parts.length ? '/' + parts.join('/') : '';\n}\n\nfunction shouldRewrite(value: string, prefix: string): boolean {\n  if (!value.startsWith('/')) return false;\n  if (value.startsWith('//')) return false; // protocol-relative\n  if (prefix && (value === prefix || value.startsWith(prefix + '/'))) return false;\n  return true;\n}\n\n/**\n * When the URL already carries the path prefix (`/docs/x`), the version goes after it (`/docs/v3.9/x`),\n * matching the injected route `${pathPrefix}/[...slug]`.\n */\nfunction rewrite(\n  value: string,\n  base: string,\n  pathPrefix: string | undefined,\n  version: string | undefined\n): string {\n  const full = prefixOf(base, pathPrefix, version);\n  if (!full || !shouldRewrite(value, full)) return value;\n  const pp = pathPrefix ? '/' + trimSlashes(pathPrefix) : '';\n  if (pp && (value === pp || value.startsWith(pp + '/'))) {\n    const rest = value.slice(pp.length);\n    return prefixOf(base, pathPrefix, version) + rest;\n  }\n  return full + value;\n}\n\nfunction rewriteSrcset(value: string, base: string, pathPrefix?: string, version?: string): string {\n  return value\n    .split(',')\n    .map((candidate) => {\n      const trimmed = candidate.trim();\n      if (!trimmed) return candidate;\n      const [url, ...descriptors] = trimmed.split(/\\s+/);\n      return [rewrite(url as string, base, pathPrefix, version), ...descriptors].join(' ');\n    })\n    .join(', ');\n}\n\n/** The version id when `filePath` sits under `<versionsDir>/<id>/`, else undefined. */\nexport function versionFromPath(\n  filePath: string | undefined,\n  versionsDir: string | undefined\n): string | undefined {\n  if (!filePath || !versionsDir) return undefined;\n  const rel = path.relative(versionsDir, filePath);\n  if (rel.startsWith('..') || path.isAbsolute(rel)) return undefined;\n  return rel.split(path.sep)[0] || undefined;\n}\n\nexport function rehypeBaseUrl(options: {\n  base: string;\n  pathPrefix?: string;\n  versionsDir?: string;\n}) {\n  const base = options.base || '/';\n\n  return function transformer(tree: unknown, file?: { path?: string; history?: string[] }) {\n    const version = versionFromPath(file?.path ?? file?.history?.[0], options.versionsDir);\n    if (base === '/' && !version) return;\n\n    visit(tree as never, 'element', (node: ElementNode) => {\n      const props = node.properties;\n      if (!props) return;\n\n      for (const attr of URL_ATTRS) {\n        const value = props[attr];\n        if (typeof value === 'string') {\n          props[attr] = rewrite(value, base, options.pathPrefix, version);\n        }\n      }\n\n      for (const attr of SRCSET_ATTRS) {\n        const value = props[attr];\n        if (typeof value === 'string') {\n          props[attr] = rewriteSrcset(value, base, options.pathPrefix, version);\n        }\n      }\n    });\n  };\n}\n\n/** Same, for authored HTML strings in frontmatter. */\nexport function rewriteHtmlBase(\n  html: string,\n  base: string,\n  pathPrefix?: string,\n  version?: string\n): string {\n  if ((!base || base === '/') && !version) return html;\n  return html.replace(\n    /\\b(href|src)=(\"|')(\\/(?!\\/)[^\"']*)\\2/g,\n    (_match, attr: string, quote: string, url: string) =>\n      `${attr}=${quote}${rewrite(url, base, pathPrefix, version)}${quote}`\n  );\n}\n"]}

package/dist/{chunk-IWKZQ4CW.js → chunk-VNQZJMDO.js}

@@ -54,6 +54,8 @@ function groupSchema() {
     icon: z.string().optional(),
     /** Immediate-child filesystem names (not titles), in display order. */
     order: z.array(z.string()).default([]),
+    /** Label for the row linking to this folder's own `index.mdx`. Defaults to `sidebar.indexLabel`. */
+    indexLabel: z.string().optional(),
     /** Children absent from `order`: alpha by label (default), by filename, or manual (dropped from the sidebar). */
     sort: z.enum(["alpha", "filename", "manual"]).optional(),
     collapsed: z.boolean().optional(),
@@ -64,5 +66,5 @@ function groupSchema() {
 }
 
 export { badgeSchema, docsSchema, groupLinkSchema, groupSchema };
-//# sourceMappingURL=chunk-IWKZQ4CW.js.map
-//# sourceMappingURL=chunk-IWKZQ4CW.js.map
+//# sourceMappingURL=chunk-VNQZJMDO.js.map
+//# sourceMappingURL=chunk-VNQZJMDO.js.map

package/dist/chunk-VNQZJMDO.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts"],"names":[],"mappings":"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","file":"chunk-VNQZJMDO.js","sourcesContent":["/** `z` must come from `astro/zod`: a different zod instance breaks Astro's collection validation. */\nimport { z } from 'astro/zod';\n\nexport const badgeSchema = () =>\n  z.object({\n    text: z.string(),\n    variant: z\n      .enum(['primary', 'secondary', 'neutral', 'success', 'warning', 'danger'])\n      .default('neutral'),\n  });\n\nconst deprecatedSchema = () =>\n  z.union([\n    z.boolean(),\n    z.object({\n      message: z.string().optional(),\n      replacedBy: z.string().optional(),\n    }),\n  ]);\n\nconst tocSchema = () =>\n  z.object({\n    minLevel: z.number().int().min(1).max(6).default(2),\n    maxLevel: z.number().int().min(1).max(6).default(3),\n  });\n\n/** Page frontmatter. Ordering lives in `_group.yaml`, not here. */\nexport function docsSchema() {\n  return z.object({\n    title: z.string(),\n    description: z.string().optional(),\n    /** Overrides `title` in the sidebar only. */\n    navLabel: z.string().optional(),\n    /** Lucide icon name. */\n    icon: z.string().optional(),\n    badge: badgeSchema().optional(),\n    /** Omit from the sidebar. The page still builds and is still reachable. */\n    hidden: z.boolean().default(false),\n    /** Excluded from builds entirely, but visible in `astro dev`. */\n    draft: z.boolean().default(false),\n    deprecated: deprecatedSchema().default(false),\n    /** 'doc' gets sidebar + TOC; 'splash' is full-bleed with neither. */\n    template: z.enum(['doc', 'splash']).default('doc'),\n    tableOfContents: z.union([tocSchema(), z.literal(false)]).optional(),\n    /** Opt out of the markdown twin and the search index for this page. */\n    noIndex: z.boolean().default(false),\n    prev: z.union([z.boolean(), z.string()]).optional(),\n    next: z.union([z.boolean(), z.string()]).optional(),\n  });\n}\n\nexport const groupLinkSchema = () =>\n  z.object({\n    label: z.string(),\n    href: z.string(),\n    /** Inferred from the href when omitted. */\n    external: z.boolean().optional(),\n    icon: z.string().optional(),\n    badge: badgeSchema().optional(),\n    attrs: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).default({}),\n  });\n\n/** `_group.yaml`. `.strict()` is load-bearing: a typo in an ordering file must fail, not be ignored. */\nexport function groupSchema() {\n  return z\n    .object({\n      label: z.string().optional(),\n      icon: z.string().optional(),\n      /** Immediate-child filesystem names (not titles), in display order. */\n      order: z.array(z.string()).default([]),\n      /** Label for the row linking to this folder's own `index.mdx`. Defaults to `sidebar.indexLabel`. */\n      indexLabel: z.string().optional(),\n      /** Children absent from `order`: alpha by label (default), by filename, or manual (dropped from the sidebar). */\n      sort: z.enum(['alpha', 'filename', 'manual']).optional(),\n      collapsed: z.boolean().optional(),\n      hidden: z.boolean().default(false),\n      badge: badgeSchema().optional(),\n      links: z.array(groupLinkSchema()).default([]),\n    })\n    .strict();\n}\n\nexport type DocsFrontmatter = z.infer<ReturnType<typeof docsSchema>>;\nexport type GroupFrontmatter = z.infer<ReturnType<typeof groupSchema>>;\n"]}

package/dist/{chunk-K7PJRTK3.js → chunk-X4LT7ASQ.js}

@@ -35,6 +35,11 @@ var docsConfigSchema = z.object({
     collapsed: z.boolean().default(false),
     /** Default append order for children absent from a group's `order`. */
     sort: z.enum(["alpha", "filename", "manual"]).default("alpha"),
+    /**
+     * Label for the row that links to a section's own `index.mdx`. A section header is
+     * never a link - it only expands - so the index page needs a row of its own.
+     */
+    indexLabel: z.string().default("Overview"),
     /** Extra top-level nodes, appended after folder-derived ones. */
     extra: z.array(z.any()).default([])
   }).prefault({}),
@@ -93,8 +98,30 @@ var docsConfigSchema = z.object({
   clientScripts: z.array(z.string()).default([]),
   /** Install @astrojs/mdx, @astrojs/react and Tailwind when absent. */
   autoIntegrations: z.boolean().default(true),
-  /** Versioning. Left permissive here; the versioning workstream owns the shape. */
-  versions: z.any().optional(),
+  /**
+   * On by default; `false` turns it off. Must be `.prefault`, never `.default`: Zod 4 short-circuits
+   * `.default` without parsing, so a consumer who writes nothing would receive a bare `{}` carrying
+   * neither `tags` nor `granularity`, and the build would select nothing with no error.
+   */
+  versions: z.union(
+    [
+      z.literal(false),
+      z.object({
+        /** The documented product's version, e.g. '4.0.0'. Defaults to the highest tag matching `tags`. */
+        current: z.string().optional(),
+        /** Git tag glob for releases. Tags that are not MAJOR.MINOR.PATCH are skipped with a warning. */
+        tags: z.string().default("v*"),
+        /** One frozen copy per major, per minor, or per release. Releases without a copy redirect to theirs. */
+        granularity: z.enum(["major", "minor", "patch"]).default("major")
+      }).prefault({})
+    ],
+    {
+      // A union reports its own failure and drops the inner path, so a typo in `granularity`
+      // would surface as "versions: Invalid input". Spelling the contract out here is what keeps
+      // a misconfigured docsite failing loudly rather than silently versioning nothing.
+      error: "expected false, or an object with optional current, tags and granularity (major | minor | patch)"
+    }
+  ).prefault({}),
   /** Generated-section plugins (OpenAPI reference, changelogs, ...). */
   plugins: z.array(z.any()).default([])
 });
@@ -109,5 +136,5 @@ ${issues}`);
 }
 
 export { docsConfigSchema, resolveConfig };
-//# sourceMappingURL=chunk-K7PJRTK3.js.map
-//# sourceMappingURL=chunk-K7PJRTK3.js.map
+//# sourceMappingURL=chunk-X4LT7ASQ.js.map
+//# sourceMappingURL=chunk-X4LT7ASQ.js.map

package/dist/chunk-X4LT7ASQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config.ts"],"names":[],"mappings":"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","file":"chunk-X4LT7ASQ.js","sourcesContent":["/** Integration options: the whole consumer-facing configuration surface. */\nimport { z } from 'astro/zod';\n\nconst headerLink = z.object({\n  label: z.string(),\n  href: z.string(),\n  /**\n   * A Lucide name like `BookOpen`, or a path to an SVG in `public/` like\n   * `/github.svg`. An SVG must be white: light mode inverts it.\n   */\n  icon: z.string().optional(),\n  external: z.boolean().optional(),\n});\n\nexport const docsConfigSchema = z.object({\n  /** Site name, shown in the header and used as the `<title>` suffix. */\n  title: z.string(),\n  description: z.string().optional(),\n  /** Path to a favicon, relative to `public/`. Base is applied automatically. */\n  favicon: z.string().default('/favicon.svg'),\n\n  /**\n   * The header mark. Without one the header falls back to `title` as text. Either\n   * way a constant \"Docs\" label follows it, and `title` heads the sidebar.\n   */\n  logo: z\n    .object({\n      src: z.string(),\n      /** Name the company: the brand link reads as this plus \"Docs\". */\n      alt: z.string().default(''),\n    })\n    .optional(),\n\n  /** Content directory, relative to `src/`. */\n  contentDir: z.string().default('content/docs'),\n\n  /** Mount docs under a sub-path, e.g. 'docs' for /docs/*. Empty means the site root. */\n  pathPrefix: z.string().default(''),\n\n  sidebar: z\n    .object({\n      /** Default collapse state for groups with no explicit `collapsed`. */\n      collapsed: z.boolean().default(false),\n      /** Default append order for children absent from a group's `order`. */\n      sort: z.enum(['alpha', 'filename', 'manual']).default('alpha'),\n      /**\n       * Label for the row that links to a section's own `index.mdx`. A section header is\n       * never a link - it only expands - so the index page needs a row of its own.\n       */\n      indexLabel: z.string().default('Overview'),\n      /** Extra top-level nodes, appended after folder-derived ones. */\n      extra: z.array(z.any()).default([]),\n    })\n    .prefault({}),\n\n  header: z\n    .object({\n      links: z.array(headerLink).default([]),\n      showThemeToggle: z.boolean().default(true),\n    })\n    .prefault({}),\n\n  footer: z\n    .object({\n      /** Base URL for \"Edit this page\"; the content path is appended. */\n      editUrl: z.string().optional(),\n      showPrevNext: z.boolean().default(true),\n      text: z.string().optional(),\n    })\n    .prefault({}),\n\n  tableOfContents: z\n    .union([\n      z.object({\n        minLevel: z.number().int().min(1).max(6).default(2),\n        maxLevel: z.number().int().min(1).max(6).default(3),\n      }),\n      z.literal(false),\n    ])\n    .prefault({}),\n\n  code: z\n    .object({\n      /** 'codeblock' renders fences through Equality's CodeBlock; 'shiki' uses Astro's Shiki. */\n      highlighter: z.enum(['codeblock', 'shiki']).default('codeblock'),\n      /** Shiki themes; only consulted when `highlighter` is 'shiki'. */\n      themes: z\n        .object({ light: z.string(), dark: z.string() })\n        .default({ light: 'github-light', dark: 'github-dark' }),\n      wrap: z.boolean().default(false),\n      langs: z.array(z.string()).default([]),\n    })\n    .prefault({}),\n\n  search: z\n    .object({\n      /** 'pagefind' indexes the built HTML. Dev serves that index, so it needs one build. */\n      provider: z.enum(['pagefind', 'none']).default('pagefind'),\n    })\n    .prefault({}),\n\n  routing: z\n    .object({\n      /** Inject the catch-all docs route. Disable to own routing entirely. */\n      injectPages: z.boolean().default(true),\n      /** Emit a `.md` twin per page plus `/llms.txt`. */\n      markdownTwins: z.boolean().default(true),\n      notFound: z.boolean().default(true),\n    })\n    .prefault({}),\n\n  theme: z\n    .object({\n      /** 'global' puts tokens on <html>; 'scoped' wraps in a ThemeProvider. */\n      mode: z.enum(['global', 'scoped']).default('global'),\n      /** Persist the reader's choice to localStorage. */\n      persist: z.boolean().default(true),\n    })\n    .prefault({}),\n\n  /**\n   * Stylesheets loaded on every docs page. A project-relative path ('./src/styles/site.css')\n   * or a package specifier. Resolved against the project root, so dev and build agree.\n   */\n  customCss: z.array(z.string()).default([]),\n\n  /**\n   * Client modules loaded on every docs page. Bundled rather than served as-is, so they may\n   * import from node_modules - which is what a script mutating rendered text needs, since it\n   * has to call Equality's `scheduleHighlight` afterwards to repaint code blocks.\n   */\n  clientScripts: z.array(z.string()).default([]),\n\n  /** Install @astrojs/mdx, @astrojs/react and Tailwind when absent. */\n  autoIntegrations: z.boolean().default(true),\n\n  /**\n   * On by default; `false` turns it off. Must be `.prefault`, never `.default`: Zod 4 short-circuits\n   * `.default` without parsing, so a consumer who writes nothing would receive a bare `{}` carrying\n   * neither `tags` nor `granularity`, and the build would select nothing with no error.\n   */\n  versions: z\n    .union(\n      [\n        z.literal(false),\n        z\n          .object({\n            /** The documented product's version, e.g. '4.0.0'. Defaults to the highest tag matching `tags`. */\n            current: z.string().optional(),\n            /** Git tag glob for releases. Tags that are not MAJOR.MINOR.PATCH are skipped with a warning. */\n            tags: z.string().default('v*'),\n            /** One frozen copy per major, per minor, or per release. Releases without a copy redirect to theirs. */\n            granularity: z.enum(['major', 'minor', 'patch']).default('major'),\n          })\n          .prefault({}),\n      ],\n      {\n        // A union reports its own failure and drops the inner path, so a typo in `granularity`\n        // would surface as \"versions: Invalid input\". Spelling the contract out here is what keeps\n        // a misconfigured docsite failing loudly rather than silently versioning nothing.\n        error:\n          'expected false, or an object with optional current, tags and granularity (major | minor | patch)',\n      }\n    )\n    .prefault({}),\n\n  /** Generated-section plugins (OpenAPI reference, changelogs, ...). */\n  plugins: z.array(z.any()).default([]),\n});\n\nexport type DocsUserConfig = z.input<typeof docsConfigSchema>;\nexport type DocsConfig = z.output<typeof docsConfigSchema>;\n\nexport function resolveConfig(user: DocsUserConfig): DocsConfig {\n  const result = docsConfigSchema.safeParse(user);\n  if (!result.success) {\n    const issues = result.error.issues\n      .map((i) => `  - ${i.path.join('.') || '(root)'}: ${i.message}`)\n      .join('\\n');\n    throw new Error(`[@eqtylab/docs] Invalid configuration:\\n${issues}`);\n  }\n  return result.data;\n}\n"]}

package/dist/config.d.ts

@@ -17,6 +17,7 @@ export declare const docsConfigSchema: z.ZodObject<{
             filename: "filename";
             manual: "manual";
         }>>;
+        indexLabel: z.ZodDefault<z.ZodString>;
         extra: z.ZodDefault<z.ZodArray<z.ZodAny>>;
     }, z.core.$strip>>;
     header: z.ZodPrefault<z.ZodObject<{
@@ -70,7 +71,15 @@ export declare const docsConfigSchema: z.ZodObject<{
     customCss: z.ZodDefault<z.ZodArray<z.ZodString>>;
     clientScripts: z.ZodDefault<z.ZodArray<z.ZodString>>;
     autoIntegrations: z.ZodDefault<z.ZodBoolean>;
-    versions: z.ZodOptional<z.ZodAny>;
+    versions: z.ZodPrefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodPrefault<z.ZodObject<{
+        current: z.ZodOptional<z.ZodString>;
+        tags: z.ZodDefault<z.ZodString>;
+        granularity: z.ZodDefault<z.ZodEnum<{
+            major: "major";
+            minor: "minor";
+            patch: "patch";
+        }>>;
+    }, z.core.$strip>>]>>;
     plugins: z.ZodDefault<z.ZodArray<z.ZodAny>>;
 }, z.core.$strip>;
 export type DocsUserConfig = z.input<typeof docsConfigSchema>;

package/dist/config.js

@@ -1,3 +1,3 @@
-export { docsConfigSchema, resolveConfig } from './chunk-K7PJRTK3.js';
+export { docsConfigSchema, resolveConfig } from './chunk-X4LT7ASQ.js';
 //# sourceMappingURL=config.js.map
 //# sourceMappingURL=config.js.map