@eqtylab/docs 0.3.5 → 0.5.0

package/dist/runtime/layouts/RedirectPage.astro

@@ -0,0 +1,19 @@
+---
+/** A one-line page for a release URL that has no copy of its own. Static hosting has no server redirects. */
+import DocsShell from './DocsShell.astro';
+
+interface Props {
+  to: string;
+  version: string | null;
+}
+
+const { to, version } = Astro.props;
+const label = version ?? 'the latest docs';
+---
+
+<DocsShell title="Redirecting" noIndex canonical={to} version={version ?? undefined}>
+  <meta slot="head" http-equiv="refresh" content={`0; url=${to}`} />
+  <main class="text-text-secondary mx-auto max-w-prose px-6 py-24 text-sm">
+    <p>This release's docs live at <a href={to}>{label}</a>.</p>
+  </main>
+</DocsShell>

package/dist/runtime/lib/mdx-components.ts

@@ -12,6 +12,7 @@ import {
   TableRow,
 } from '@eqtylab/equality';
 import CONFIG from 'virtual:eqty-docs/config';
+import pluginComponents from 'virtual:eqty-docs/plugin-components';
 
 import AlertBridge from '../components/AlertBridge.astro';
 import CodeFenceBridge from '../components/CodeFenceBridge.astro';
@@ -46,4 +47,6 @@ if (CONFIG.code?.highlighter === 'codeblock') {
   base.pre = CodeFenceBridge;
 }
 
-export const mdxComponents = base;
+// Plugin-contributed components (`docs({ plugins })`) land last, so a plugin can add a name or
+// replace one of the defaults.
+export const mdxComponents: Record<string, unknown> = { ...base, ...pluginComponents };

package/dist/runtime/lib/nav-data.ts

@@ -1,42 +1,64 @@
 /** Bridges the content collections into the pure nav builder. Needs `astro:content`, so it lives in the runtime tree. */
-import { breadcrumbsFor, buildNavTree, buildTocTree, prevNextFor } from '@eqtylab/docs/nav';
+import {
+  breadcrumbsFor,
+  buildNavTree,
+  buildTocTree,
+  flattenNav,
+  prevNextFor,
+} from '@eqtylab/docs/nav';
 import type { GroupConfig } from '@eqtylab/docs/nav';
+import { docsHref } from '@eqtylab/docs/paths';
 import type { DocsNavEntry, NavNode } from '@eqtylab/docs/types';
 import { getCollection } from 'astro:content';
 import CONFIG from 'virtual:eqty-docs/config';
 
 export { buildTocTree, breadcrumbsFor, prevNextFor };
 
-/** No `versionPrefix`: the version already lives in `base`, and adding it here doubles the segment. */
-export function pathContext() {
+/** The version is a route segment after the path prefix; latest has none. */
+export function pathContext(versionId?: string) {
   return {
     base: import.meta.env.BASE_URL,
     pathPrefix: CONFIG.pathPrefix,
+    versionPrefix: versionId,
   };
 }
 
-/** All docs entries, with drafts filtered out unless we're in `astro dev`. */
-export async function docsEntries() {
-  return getCollection('docs', ({ data }: { data: { draft?: boolean } }) =>
-    import.meta.env.DEV ? true : !data.draft
+/** Collection names for a version id, or for latest when undefined. */
+export function collectionsFor(versionId?: string): { docs: string; groups: string } {
+  if (!versionId) return { docs: 'docs', groups: 'docsGroups' };
+  const entry = CONFIG.versionManifest.find((v) => v.id === versionId);
+  if (!entry) throw new Error(`[@eqtylab/docs] unknown version id "${versionId}"`);
+  return { docs: `docs_${entry.suffix}`, groups: `docsGroups_${entry.suffix}` };
+}
+
+// `getCollection` is typed against the generated DataEntryMap, which cannot know names built at runtime.
+const anyCollection = getCollection as unknown as (
+  name: string,
+  filter?: (entry: { data: Record<string, unknown> }) => boolean
+) => Promise<never[]>;
+
+/** All entries of a version, with drafts filtered out unless we're in `astro dev`. */
+export async function docsEntries(versionId?: string) {
+  return anyCollection(collectionsFor(versionId).docs, ({ data }) =>
+    import.meta.env.DEV ? true : !(data as { draft?: boolean }).draft
   );
 }
 
-async function groupMap(): Promise<Map<string, GroupConfig>> {
+async function groupMap(versionId?: string): Promise<Map<string, GroupConfig>> {
   const map = new Map<string, GroupConfig>();
   try {
-    const groups = await getCollection('docsGroups');
-    for (const group of groups) {
-      map.set(group.id, group.data as GroupConfig);
+    const groups = await anyCollection(collectionsFor(versionId).groups);
+    for (const group of groups as Array<{ id: string; data: GroupConfig }>) {
+      map.set(group.id, group.data);
     }
   } catch {
-    // docsGroups is optional; no _group.yaml means alphabetical ordering.
+    // The groups collection is optional; no _group.yaml means alphabetical ordering.
   }
   return map;
 }
 
-export async function docsNav(currentPath: string): Promise<NavNode[]> {
-  const [entries, groups] = await Promise.all([docsEntries(), groupMap()]);
+export async function docsNav(currentPath: string, versionId?: string): Promise<NavNode[]> {
+  const [entries, groups] = await Promise.all([docsEntries(versionId), groupMap(versionId)]);
 
   const navEntries: DocsNavEntry[] = entries.map((entry) => ({
     id: entry.id,
@@ -52,9 +74,10 @@ export async function docsNav(currentPath: string): Promise<NavNode[]> {
     entries: navEntries,
     groups,
     currentPath,
-    paths: pathContext(),
+    paths: pathContext(versionId),
     defaultCollapsed: CONFIG.sidebar.collapsed,
     defaultSort: CONFIG.sidebar.sort,
+    defaultIndexLabel: CONFIG.sidebar.indexLabel,
     extra: (CONFIG.sidebar.extra ?? []) as NavNode[],
     onWarn: warnOnce,
   });
@@ -72,3 +95,9 @@ function deprecationBadge(deprecated: unknown) {
   if (!deprecated) return undefined;
   return { text: 'Deprecated', variant: 'warning' as const };
 }
+
+/** The first linkable page of a version. Version roots and switcher fallbacks land here. */
+export async function firstNavHref(versionId?: string): Promise<string> {
+  const tree = await docsNav('/', versionId);
+  return flattenNav(tree)[0]?.href ?? docsHref('', pathContext(versionId));
+}

package/dist/runtime/lib/versions-ui.ts

@@ -0,0 +1,12 @@
+/** Shapes the chrome receives. Computed at build in the route; the components hold no logic. */
+export interface SwitcherItem {
+  label: string;
+  href: string;
+  current: boolean;
+}
+
+export interface SwitcherData {
+  latest: SwitcherItem;
+  /** One group per major, newest first; items newest first. */
+  groups: Array<{ label: string; items: SwitcherItem[] }>;
+}

package/dist/runtime/routes/docs-md.ts

@@ -4,30 +4,69 @@ import type { APIRoute } from 'astro';
 import { getCollection } from 'astro:content';
 import CONFIG from 'virtual:eqty-docs/config';
 
+import { collectionsFor } from '../lib/nav-data.ts';
+
 export async function getStaticPaths() {
-  const entries = await getCollection(
-    'docs',
-    ({ data }: { data: { draft?: boolean; noIndex?: boolean } }) => !data.draft && !data.noIndex
-  );
-  return entries.map((entry) => ({
-    // An empty slug would emit a file literally called ".md".
-    params: { slug: idToPath(entry.id) || 'index' },
-    props: { entry },
-  }));
+  const visible = ({ data }: { data: { draft?: boolean; noIndex?: boolean } }) =>
+    !data.draft && !data.noIndex;
+  const anyCollection = getCollection as unknown as (
+    name: string,
+    f: typeof visible
+  ) => Promise<never[]>;
+  const versions: Array<string | undefined> = [
+    undefined,
+    ...CONFIG.versionManifest.map((v) => v.id),
+  ];
+  const out: Array<{ params: { slug: string }; props: { entry: unknown } }> = [];
+  for (const versionId of versions) {
+    const entries = (await anyCollection(collectionsFor(versionId).docs, visible)) as Array<{
+      id: string;
+    }>;
+    for (const entry of entries) {
+      // An empty slug would emit a file literally called ".md".
+      const page = idToPath(entry.id) || 'index';
+      out.push({ params: { slug: versionId ? `${versionId}/${page}` : page }, props: { entry } });
+    }
+  }
+  return out;
+}
+
+type Deprecated = boolean | { message?: string; replacedBy?: string } | undefined;
+
+/** Agents read the twin, not the rendered banner, so the deprecation has to travel with it. */
+function deprecationNotice(deprecated: Deprecated) {
+  if (!deprecated) return [];
+  const detail = typeof deprecated === 'object' ? deprecated : {};
+  const message = stripHtml(detail.message) ?? 'This page documents a deprecated feature.';
+  const replacedBy = detail.replacedBy ? ` Use ${stripHtml(detail.replacedBy)} instead.` : '';
+  return [`> **Deprecated** — ${message}${replacedBy}`, ''];
+}
+
+/** Frontmatter messages may carry authored HTML links, which are noise in plain Markdown. */
+function stripHtml(value?: string) {
+  return value?.replace(/<[^>]*>/g, '').trim() || undefined;
 }
 
 export const GET: APIRoute = ({ props }) => {
   const { entry } = props as {
-    entry: { body?: string; data: { title: string; description?: string } };
+    entry: {
+      body?: string;
+      data: { title: string; description?: string; deprecated?: Deprecated };
+    };
   };
 
   const frontmatter = ['---', `title: ${JSON.stringify(entry.data.title)}`];
   if (entry.data.description) {
     frontmatter.push(`description: ${JSON.stringify(entry.data.description)}`);
   }
+  if (entry.data.deprecated) {
+    frontmatter.push('deprecated: true');
+  }
   frontmatter.push(`source: ${JSON.stringify(CONFIG.title)}`, '---', '');
 
-  return new Response(frontmatter.join('\n') + (entry.body ?? ''), {
+  const body = [...deprecationNotice(entry.data.deprecated), entry.body ?? ''].join('\n');
+
+  return new Response(frontmatter.join('\n') + body, {
     headers: { 'Content-Type': 'text/markdown; charset=utf-8' },
   });
 };

package/dist/runtime/routes/docs.astro

@@ -1,92 +1,201 @@
 ---
-import { getCollection, render } from 'astro:content';
+import { render } from 'astro:content';
 import CONFIG from 'virtual:eqty-docs/config';
 import { docsHref, idToPath, joinPath, normalizePath } from '@eqtylab/docs/paths';
 import DocsPage from '../layouts/DocsPage.astro';
-import { breadcrumbsFor, buildTocTree, docsNav, pathContext, prevNextFor } from '../lib/nav-data.ts';
+import RedirectPage from '../layouts/RedirectPage.astro';
+import {
+  breadcrumbsFor,
+  buildTocTree,
+  docsEntries,
+  docsNav,
+  firstNavHref,
+  pathContext,
+  prevNextFor,
+} from '../lib/nav-data.ts';
 import { firstParagraph } from '../lib/summary.ts';
 import { mdxComponents } from '../lib/mdx-components.ts';
+import type { SwitcherData } from '../lib/versions-ui.ts';
 import PageFooter from '../chrome/PageFooter.astro';
 import Prose from '../chrome/Prose.astro';
 
+type Entry = Awaited<ReturnType<typeof docsEntries>>[number] & {
+  id: string;
+  body?: string;
+  filePath?: string;
+  data: Record<string, any>;
+};
+
 export async function getStaticPaths() {
-  const entries = await getCollection('docs', ({ data }: { data: { draft?: boolean } }) =>
-    import.meta.env.DEV ? true : !data.draft
+  const owned = new Set((CONFIG.ownedByConsumer ?? []).map(normalizePath));
+  // Astro does not de-duplicate injected routes against consumer pages. Latest only: a consumer cannot own a versioned path.
+  const latest = ((await docsEntries()) as Entry[]).filter(
+    (entry) => !owned.has(normalizePath(docsHref(entry.id, pathContext())))
+  );
+  const copies = await Promise.all(
+    CONFIG.versionManifest.map(async (v) => ({ v, entries: (await docsEntries(v.id)) as Entry[] }))
   );
 
-  const owned = new Set((CONFIG.ownedByConsumer ?? []).map(normalizePath));
+  const idsOf = new Map<string | undefined, Set<string>>([
+    [undefined, new Set(latest.map((e) => e.id))],
+  ]);
+  for (const { v, entries } of copies) idsOf.set(v.id, new Set(entries.map((e) => e.id)));
+  const roots = new Map<string | undefined, string>();
+  for (const v of CONFIG.versionManifest) roots.set(v.id, await firstNavHref(v.id));
+
+  const latestLabel = CONFIG.currentVersion ? CONFIG.currentVersion.id : 'latest';
+  const hrefFor = (versionId: string | undefined, id: string) =>
+    idsOf.get(versionId)?.has(id)
+      ? docsHref(id, pathContext(versionId))
+      : versionId
+        ? docsHref('', pathContext(versionId))
+        : docsHref('', pathContext());
 
-  return entries
-    // Astro does not de-duplicate injected routes against consumer pages.
-    .filter((entry) => !owned.has(normalizePath(docsHref(entry.id, pathContext()))))
-    .map((entry) => ({
+  const switcherFor = (versionId: string | undefined, id: string): SwitcherData | undefined => {
+    // Nothing to switch to until a release is tagged: a picker offering only the page you are
+    // already on is noise, and it displaces the header's control cluster.
+    if (!CONFIG.currentVersion || !CONFIG.versionManifest.length) return undefined;
+    const byMajor = new Map<string, SwitcherData['groups'][number]>();
+    for (const v of CONFIG.versionManifest) {
+      const major = `v${v.group.split('.')[0]}`;
+      if (!byMajor.has(major)) byMajor.set(major, { label: major, items: [] });
+      byMajor
+        .get(major)!
+        .items.push({ label: v.id, href: hrefFor(v.id, id), current: v.id === versionId });
+    }
+    return {
+      latest: { label: latestLabel, href: hrefFor(undefined, id), current: versionId === undefined },
+      groups: [...byMajor.values()],
+    };
+  };
+
+  return [
+    ...latest.map((entry) => ({
       // `undefined` (not '') is how a rest param matches the empty path.
       params: { slug: idToPath(entry.id) || undefined },
-      props: { entry },
-    }));
+      props: { entry, switcher: switcherFor(undefined, entry.id) },
+    })),
+    ...copies.flatMap(({ v, entries }) => [
+      ...entries.map((entry) => ({
+        params: { slug: `${v.id}/${idToPath(entry.id)}`.replace(/\/$/, '') },
+        props: {
+          entry,
+          version: v.id,
+          switcher: switcherFor(v.id, entry.id),
+          canonical: idsOf.get(undefined)!.has(entry.id)
+            ? docsHref(entry.id, pathContext())
+            : undefined,
+          latestHref: hrefFor(undefined, entry.id),
+          latestLabel,
+        },
+      })),
+      // 3.9.1 had no index.mdx, so without this the version root and every stub pointing at it would 404.
+      ...(idsOf.get(v.id)!.has('index')
+        ? []
+        : [{ params: { slug: v.id }, props: { redirectTo: roots.get(v.id)!, version: v.id } }]),
+    ]),
+    // Every target goes through docsHref so base and pathPrefix apply.
+    ...CONFIG.versionRedirects.map((r) => ({
+      params: { slug: r.id },
+      props: {
+        redirectTo: r.to
+          ? (roots.get(r.to) ?? docsHref('', pathContext(r.to)))
+          : docsHref('', pathContext()),
+        version: r.to,
+      },
+    })),
+  ];
+}
+
+interface Props {
+  entry?: Entry;
+  version?: string | null;
+  switcher?: SwitcherData;
+  canonical?: string;
+  latestHref?: string;
+  latestLabel?: string;
+  redirectTo?: string;
 }
 
-const { entry } = Astro.props;
-const { Content, headings } = await render(entry);
-
-const tocConfig = entry.data.tableOfContents ?? CONFIG.tableOfContents;
-const showToc = tocConfig !== false;
-const toc = showToc
-  ? buildTocTree(headings, {
-      minLevel: (tocConfig as { minLevel?: number })?.minLevel ?? 2,
-      maxLevel: (tocConfig as { maxLevel?: number })?.maxLevel ?? 3,
-    })
-  : [];
-
-const nav = await docsNav(Astro.url.pathname);
-const splash = entry.data.template === 'splash';
-
-// Trail is [group, ..., page]; a length of one means the page has no section above it.
-const trail = breadcrumbsFor(nav, Astro.url.pathname);
-const crumbs = trail.length > 1 ? trail.map((node) => node.label).join(' › ') : undefined;
-
-// Ancestors only. `crumbs` above keeps the page as well, because a search result row
-// needs the page name to identify itself. The two diverge on purpose.
-const renderedTrail = trail.slice(0, -1).map((node) => ({ label: node.label, href: node.href }));
-
-// Indexed only, never rendered: a page with no `description` still needs a result summary.
-const fallbackSummary = entry.data.description ? undefined : firstParagraph(entry.body);
-
-const { prev, next } = CONFIG.footer.showPrevNext ? prevNextFor(nav, Astro.url.pathname) : {};
-
-// `editUrl` is a base; the content path is appended. The slice is taken at the
-// consumer's own content directory, which is configurable.
-const contentPath = entry.filePath?.split(`${CONFIG.contentDir}/`).pop();
-const editHref =
-  CONFIG.footer.editUrl && contentPath
-    ? `${CONFIG.footer.editUrl.replace(/\/$/, '')}/${contentPath}`
-    : undefined;
-
-// File-shaped (/x/label.md) beside the directory-shaped page; 'index' must match docs-md.ts.
-const markdownHref = CONFIG.routing.markdownTwins
-  ? `${joinPath(import.meta.env.BASE_URL, CONFIG.pathPrefix, idToPath(entry.id) || 'index')}.md`
-  : undefined;
+const { entry, version, switcher, canonical, latestHref, latestLabel, redirectTo } = Astro.props;
 ---
 
-<DocsPage
-  title={entry.data.title}
-  description={entry.data.description}
-  nav={nav}
-  toc={toc}
-  showToc={showToc}
-  splash={splash}
->
-  <Prose
-    title={entry.data.title}
-    description={entry.data.description}
-    deprecated={entry.data.deprecated}
-    markdownHref={markdownHref}
-    source={entry.body}
-    crumbs={crumbs}
-    trail={renderedTrail}
-    fallbackSummary={fallbackSummary}
-  >
-    <Content components={mdxComponents} />
-  </Prose>
-  {!splash && <PageFooter prev={prev} next={next} editHref={editHref} text={CONFIG.footer.text} />}
-</DocsPage>
+{redirectTo && <RedirectPage to={redirectTo} version={version ?? null} />}
+{
+  !redirectTo &&
+    entry &&
+    (async () => {
+      const { Content, headings } = await render(entry as never);
+
+      const tocConfig = entry.data.tableOfContents ?? CONFIG.tableOfContents;
+      const showToc = tocConfig !== false;
+      const toc = showToc
+        ? buildTocTree(headings, {
+            minLevel: (tocConfig as { minLevel?: number })?.minLevel ?? 2,
+            maxLevel: (tocConfig as { maxLevel?: number })?.maxLevel ?? 3,
+          })
+        : [];
+
+      const nav = await docsNav(Astro.url.pathname, version ?? undefined);
+      const splash = entry.data.template === 'splash';
+
+      const trail = breadcrumbsFor(nav, Astro.url.pathname);
+      const crumbs = trail.length > 1 ? trail.map((node) => node.label).join(' › ') : undefined;
+
+      // Ancestors only. `crumbs` above keeps the page as well, because a search result row
+      // needs the page name to identify itself. The two diverge on purpose.
+      const renderedTrail = trail.slice(0, -1).map((node) => ({ label: node.label, href: node.href }));
+
+      // Indexed only, never rendered: a page with no `description` still needs a result summary.
+      const fallbackSummary = entry.data.description ? undefined : firstParagraph(entry.body);
+
+      const { prev, next } = CONFIG.footer.showPrevNext ? prevNextFor(nav, Astro.url.pathname) : {};
+
+      // Old versions are read-only and their files live in the cache, so the split below would
+      // return the whole cache path and produce a bogus link. Latest only.
+      const contentPath = version ? undefined : entry.filePath?.split(`${CONFIG.contentDir}/`).pop();
+      const editHref =
+        CONFIG.footer.editUrl && contentPath
+          ? `${CONFIG.footer.editUrl.replace(/\/$/, '')}/${contentPath}`
+          : undefined;
+
+      // File-shaped (/v3.9/x/label.md) beside the directory-shaped page; 'index' must match docs-md.ts.
+      const markdownHref = CONFIG.routing.markdownTwins
+        ? `${joinPath(import.meta.env.BASE_URL, CONFIG.pathPrefix, version ?? undefined, idToPath(entry.id) || 'index')}.md`
+        : undefined;
+
+      return (
+        <DocsPage
+          title={entry.data.title}
+          description={entry.data.description}
+          nav={nav}
+          toc={toc}
+          showToc={showToc}
+          splash={splash}
+          version={version ?? undefined}
+          switcher={switcher}
+          noIndex={Boolean(version)}
+          canonical={canonical}
+          latestHref={latestHref}
+          latestLabel={latestLabel}
+        >
+          <Prose
+            title={entry.data.title}
+            description={entry.data.description}
+            deprecated={entry.data.deprecated}
+            markdownHref={markdownHref}
+            source={entry.body}
+            crumbs={crumbs}
+            trail={renderedTrail}
+            fallbackSummary={fallbackSummary}
+            version={version ?? undefined}
+          >
+            <Content components={mdxComponents} />
+          </Prose>
+          {!splash && (
+            <PageFooter prev={prev} next={next} editHref={editHref} text={CONFIG.footer.text} />
+          )}
+        </DocsPage>
+      );
+    })()
+}

package/dist/runtime/routes/llms-txt.ts

@@ -26,8 +26,9 @@ export const GET: APIRoute = async (ctx) => {
     '',
     ...sorted.map((entry) => {
       const href = docsHref(entry.id, paths).replace(/\/$/, '');
+      const prefix = entry.data.deprecated ? ' (deprecated)' : '';
       const suffix = entry.data.description ? `: ${entry.data.description}` : '';
-      return `- [${entry.data.title}](${origin}${href}.md)${suffix}`;
+      return `- [${entry.data.title}](${origin}${href}.md)${prefix}${suffix}`;
     }),
     '',
   ];

package/dist/runtime/routes/not-found.astro

@@ -8,9 +8,36 @@ import NotFoundBody from '../chrome/NotFoundBody.tsx';
 const homeHref = withBase(CONFIG.pathPrefix ? `/${CONFIG.pathPrefix}/` : '/', {
   base: import.meta.env.BASE_URL,
 });
+
+// One static file serves every miss, so the version has to be read from the URL in the browser.
+// The tables ride in a JSON script rather than `define:vars`, which would force `is:inline` and
+// a second copy of the matching logic that nothing tests.
+const fallback = {
+  base: import.meta.env.BASE_URL,
+  pathPrefix: CONFIG.pathPrefix,
+  copyIds: CONFIG.versionManifest.map((v) => v.id),
+  redirects: CONFIG.versionRedirects,
+};
 ---
 
 <DocsShell title="Page not found" noIndex>
   <Header />
+  <script
+    type="application/json"
+    data-eq-docs-fallback
+    is:inline
+    set:html={JSON.stringify(fallback)}
+  />
   <NotFoundBody homeHref={homeHref} client:load />
 </DocsShell>
+
+<script>
+  import { resolveVersionedPath } from '@eqtylab/docs/paths';
+
+  const source = document.querySelector('[data-eq-docs-fallback]')?.textContent;
+  if (source) {
+    const target = resolveVersionedPath(location.pathname, JSON.parse(source));
+    // A reader who typed a real release URL should reach the page, not the 404 body.
+    if (target && target !== location.pathname) location.replace(target);
+  }
+</script>

package/dist/schema.d.ts

@@ -69,6 +69,7 @@ export declare function groupSchema(): z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
     icon: z.ZodOptional<z.ZodString>;
     order: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    indexLabel: z.ZodOptional<z.ZodString>;
     sort: z.ZodOptional<z.ZodEnum<{
         alpha: "alpha";
         filename: "filename";

package/dist/schema.js

@@ -1,3 +1,3 @@
-export { badgeSchema, docsSchema, groupLinkSchema, groupSchema } from './chunk-IWKZQ4CW.js';
+export { badgeSchema, docsSchema, groupLinkSchema, groupSchema } from './chunk-VNQZJMDO.js';
 //# sourceMappingURL=schema.js.map
 //# sourceMappingURL=schema.js.map

package/dist/types.d.ts

@@ -45,16 +45,25 @@ export interface DocsNavEntry {
     hidden?: boolean;
     draft?: boolean;
 }
-/** Extension point for generated sections (OpenAPI reference, changelogs, ...). */
+/**
+ * Extension point for generated sections (OpenAPI reference, changelogs, ...). Passed to
+ * `docs({ plugins })`; `setup` runs inside `astro:config:setup`, after the framework has planned
+ * its own routes.
+ */
 export interface DocsPlugin {
     name: string;
     setup(ctx: DocsPluginContext): void | Promise<void>;
 }
 export interface DocsPluginContext {
-    /** Push a top-level group into the sidebar. Appended after folder-derived nodes. */
+    /** Push a top-level group into the sidebar. Appended after folder-derived nodes and `sidebar.extra`. */
     addNavGroup(group: NavNode): void;
-    /** Merge entries into the route-level MDX component map. */
-    addMdxComponents(map: Record<string, unknown>): void;
-    /** Raw `astro:config:setup` params: injectRoute, updateConfig, addWatchFile, logger. */
+    /**
+     * Add components to the route-level MDX component map, by name. Each value is a module
+     * specifier (a package export or an absolute path) whose default export is the component;
+     * the runtime imports it, so a component object cannot be passed here. A plugin's entry
+     * replaces a default of the same name.
+     */
+    addMdxComponents(map: Record<string, string>): void;
+    /** Raw `astro:config:setup` params: config, injectRoute, updateConfig, addWatchFile, logger. */
     astro: unknown;
 }

package/dist/versions.d.ts

@@ -0,0 +1,37 @@
+/** Pure. Turns a tag list into the copies to build and the release URLs that redirect to them. */
+export type Granularity = 'major' | 'minor' | 'patch';
+export interface ParsedTag {
+    tag: string;
+    major: number;
+    minor: number;
+    patch: number;
+    version: string;
+}
+export interface VersionCopy {
+    id: string;
+    suffix: string;
+    group: string;
+    tag: string;
+}
+/** `to: null` means latest, i.e. `/`. */
+export interface VersionRedirect {
+    id: string;
+    to: string | null;
+}
+export interface VersionSelection {
+    /** Newest first. */
+    copies: VersionCopy[];
+    redirects: VersionRedirect[];
+    /** Tags that did not parse as MAJOR.MINOR.PATCH, prereleases included. */
+    skipped: string[];
+    /** Parsed tags above `current`. */
+    above: string[];
+}
+export declare function parseTag(tag: string): ParsedTag | null;
+export declare function compareTags(a: ParsedTag, b: ParsedTag): number;
+export declare function groupOf(v: ParsedTag, granularity: Granularity): string;
+export declare function idOf(group: string): string;
+/** Collection names are identifiers, so `v3.9` becomes `v3_9`. */
+export declare function suffixOf(id: string): string;
+export declare function highestTag(tags: string[]): ParsedTag | null;
+export declare function selectVersions(tags: string[], current: string, granularity: Granularity, skippedGroups?: string[]): VersionSelection;