blume 0.5.3 → 0.5.4

package/src/core/navigation.ts

@@ -6,7 +6,6 @@ import type {
   SidebarItemConfig,
 } from "./schema.ts";
 import type {
-  NavChromeVariant,
   NavNode,
   Navigation,
   NavSelector,
@@ -346,7 +345,6 @@ const buildConfigSidebar = (
 export const buildNavigation = (
   pages: PageRecord[],
   options: {
-    chromeVariants?: NavChromeVariant[];
     folderMeta: Map<string, FolderMeta>;
     selectors?: NavSelector[];
     tabs?: NavTab[];
@@ -363,7 +361,6 @@ export const buildNavigation = (
     sharedFolderMeta?: Map<string, FolderMeta>;
   }
 ): Navigation => {
-  const chromeVariants = options.chromeVariants ?? [];
   const selectors = options.selectors ?? [];
   const tabs = options.tabs ?? [];
   const metaPrefix = options.metaPrefix ?? "";
@@ -377,7 +374,6 @@ export const buildNavigation = (
 
   if (options.sidebar) {
     return {
-      chromeVariants,
       selectors,
       sidebar: buildConfigSidebar(options.sidebar, byRoute),
       tabs,
@@ -385,7 +381,6 @@ export const buildNavigation = (
   }
 
   return {
-    chromeVariants,
     selectors,
     sidebar: buildFileSystemSidebar(
       pages,

package/src/core/project-graph.ts

@@ -1,5 +1,4 @@
 import { loadConfig } from "./config.ts";
-import type { ConfigBridge } from "./config.ts";
 import { buildContentGraph } from "./graph.ts";
 import { i18nDiagnostics } from "./i18n.ts";
 import {
@@ -69,8 +68,6 @@ export interface BlumeProject {
   diagnostics: Diagnostic[];
   /** The instantiated content sources, for lazy entry reads (search/AI/raw). */
   sources: ContentSource[];
-  /** Set when serving a foreign docs config (e.g. Mintlify) without migrating. */
-  bridge: ConfigBridge | null;
 }
 
 /**
@@ -97,7 +94,6 @@ export const scanProject = async (
   const configResult = await loadConfig(root, {
     devServerUrl: options.devServerUrl,
   });
-  const { bridge } = configResult;
   const config = applyConfigOverrides(configResult.config, options.overrides);
   const context = resolveProjectContext(root, config, {
     runtimeDir: options.runtimeDir,
@@ -179,7 +175,6 @@ export const scanProject = async (
   const i18nWarnings = config.i18n ? i18nDiagnostics(pages, config.i18n) : [];
 
   return {
-    bridge,
     config,
     context,
     diagnostics: [

package/src/core/schema.ts

@@ -99,25 +99,15 @@ const pageMetaBaseSchema = z
     deprecated: z.boolean().default(false),
     description: z.string().optional(),
     draft: z.boolean().default(false),
-    groups: z.union([z.string(), z.array(z.string())]).optional(),
     hidden: z.boolean().default(false),
-    hideApiMarker: z.boolean().default(false),
-    hideFooterPagination: z.boolean().optional(),
     icon: iconName.optional(),
-    iconType: z.string().optional(),
-    keywords: z.array(z.string()).optional(),
     /** Overrides the git-derived last-modified date when `lastModified` is on. */
     lastModified: dateSchema.optional(),
-    mode: z.string().optional(),
     noindex: z.boolean().default(false),
-    public: z.boolean().optional(),
-    rss: z.boolean().optional(),
     search: searchMetaSchema.default({}),
     seo: seoMetaSchema.default({}),
     sidebar: sidebarMetaSchema.default({}),
-    sidebarTitle: z.string().optional(),
     slug: z.string().optional(),
-    tag: z.string().optional(),
     title: z.string().optional(),
     type: z.string().default("doc"),
   })
@@ -160,45 +150,41 @@ export type FolderMeta = z.infer<typeof folderMetaSchema>;
 // Project config (blume.config.ts)
 // ---------------------------------------------------------------------------
 
-const logoConfigSchema = z.union([
+/** The logo mark: a single image path/URL, or light/dark variants with alt text. */
+const logoImageSchema = z.union([
   z.string(),
   z
     .object({
       alt: z.string().optional(),
       dark: z.string().optional(),
-      href: z.string().optional(),
       light: z.string().optional(),
     })
     .strict(),
 ]);
 
-const faviconConfigSchema = z.union([
+/**
+ * Site logo. A bare string is the image shorthand. The object form splits the
+ * brand into an optional `image` mark and optional wordmark `text` so a site can
+ * show an image-only logo (a mark with the wordmark baked in), a text-only logo,
+ * or both. Omit `text` to fall back to the site title; set `text: ""` to render
+ * the mark alone. `href` overrides the brand link (defaults to `/`).
+ */
+const logoConfigSchema = z.union([
   z.string(),
   z
     .object({
-      dark: z.string().optional(),
-      light: z.string().optional(),
+      href: z.string().optional(),
+      image: logoImageSchema.optional(),
+      text: z.string().optional(),
     })
     .strict(),
 ]);
 
-const bannerColorSchema = z
-  .object({
-    dark: z.string().optional(),
-    light: z.string().optional(),
-  })
-  .strict()
-  .refine((value) => value.dark !== undefined || value.light !== undefined, {
-    message: "Banner color requires at least one of light or dark.",
-  });
-
 /** Site-wide announcement banner: a string, or text with an optional link. */
 const bannerConfigSchema = z.union([
   z.string(),
   z
     .object({
-      /** Background color override (Mintlify compatibility). */
-      color: bannerColorSchema.optional(),
       content: z.string(),
       /** Show a dismiss button; the choice is remembered per visitor. */
       dismissible: z.boolean().default(false),
@@ -208,8 +194,6 @@ const bannerConfigSchema = z.union([
         .object({ href: z.string(), text: z.string() })
         .strict()
         .optional(),
-      /** Tone (Mintlify compatibility). */
-      type: z.enum(["info", "warning", "critical"]).optional(),
     })
     .strict(),
 ]);
@@ -329,30 +313,6 @@ const githubReleasesSourceSchema = z
   })
   .strict();
 
-/**
- * In-place Mintlify content (`docs.json` + MDX). Powers "bridge mode": Blume
- * reads an unconverted Mintlify project, transforming each page to Blume MDX at
- * scan time. Injected automatically by `loadConfig` when a `docs.json` is found
- * and no `blume.config.*` exists; can also be configured explicitly.
- */
-const mintlifySourceSchema = z
-  .object({
-    /** Absolute path of the `docs.json`/`mint.json`, watched for changes in dev. */
-    configFile: z.string().optional(),
-    /** Patterns excluded from page discovery (Mintlify defaults are merged in). */
-    exclude: z.array(z.string()).default([]),
-    /** Glob patterns for Mintlify content files. */
-    include: z.array(z.string()).default(["**/*.{md,mdx}"]),
-    /** Namespaces the source's routes under `/<prefix>/`. */
-    prefix: z.string().optional(),
-    /** Content root, absolute or relative to the project root (Mintlify: `.`). */
-    root: z.string().default("."),
-    type: z.literal("mintlify"),
-    /** `docs.json` variables, inlined into content (`{{name}}`) at scan time. */
-    variables: z.record(z.string(), z.string()).default({}),
-  })
-  .strict();
-
 /**
  * A user-provided `ContentSource` instance, passed straight through from
  * `blume.config.ts`. This is the extension point that lets adapters with custom
@@ -377,7 +337,6 @@ const contentSourceSchema = z.discriminatedUnion("type", [
   githubReleasesSourceSchema,
   sanitySourceSchema,
   notionSourceSchema,
-  mintlifySourceSchema,
   customSourceSchema,
 ]);
 
@@ -386,13 +345,6 @@ export type ContentSourceConfig = z.infer<typeof contentSourceSchema>;
 
 const contentConfigSchema = z
   .object({
-    /**
-     * Extra top-level directories (relative to the project root) served as
-     * static assets at the site root, alongside `public/`. Lets projects keep
-     * root-served asset folders in place — e.g. a Mintlify migration keeps
-     * `images/` where it is instead of relocating it under `public/`.
-     */
-    assets: z.array(z.string()).default([]),
     defaultType: z.string().default("doc"),
     exclude: z.array(z.string()).default(["**/_*", "**/.*"]),
     include: z.array(z.string()).default(["**/*.{md,mdx}"]),
@@ -483,10 +435,6 @@ const sidebarItemSchema: z.ZodType<SidebarItemConfig> = z.lazy(() =>
   ])
 );
 
-const variablesConfigSchema = z
-  .record(z.string().regex(/^[A-Za-z0-9-]+$/u), z.string())
-  .default({});
-
 /** A curated Google Font slug (see `theme/fonts.ts`). */
 const fontSlug = z.string().refine(isFontSlug, (value) => ({
   message: `Unknown font "${value}". Supported fonts: ${FONT_SLUGS.join(", ")}.`,
@@ -499,7 +447,6 @@ const themeConfigSchema = z
     action: z.string().optional(),
     background: z.string().optional(),
     backgroundDark: z.string().optional(),
-    backgroundDecoration: z.enum(["gradient", "grid", "windows"]).optional(),
     backgroundImage: z.string().optional(),
     backgroundImageDark: z.string().optional(),
     fonts: z
@@ -584,7 +531,6 @@ const searchConfigSchema = z
       .default({}),
     mixedbread: mixedbreadSearchSchema.optional(),
     oramaCloud: oramaCloudSearchSchema.optional(),
-    prompt: z.string().optional(),
     provider: z.enum(searchProviders).default("orama"),
     typesense: typesenseSearchSchema.optional(),
   })
@@ -644,16 +590,8 @@ const aiConfigSchema = z
   })
   .strict();
 
-const chromeVariantSchema = z
-  .object({
-    banner: bannerConfigSchema.optional(),
-    path: z.string(),
-  })
-  .strict();
-
 const navigationConfigSchema = z
   .object({
-    chromeVariants: z.array(chromeVariantSchema).default([]),
     /** Show a GitHub repo link in the header (requires `github` configured). */
     repo: z.boolean().default(true),
     selectors: z.array(navSelectorSchema).default([]),
@@ -824,7 +762,6 @@ const rssConfigSchema = z
 /** Discoverability features: OG images, feeds, sitemap, structured data. */
 const seoConfigSchema = z
   .object({
-    metatags: z.record(z.string(), z.string()).default({}),
     og: ogConfigSchema.default({}),
     /** Generate robots.txt (with a Sitemap reference when available). */
     robots: z.boolean().default(true),
@@ -1001,17 +938,6 @@ const tocConfigSchema = z
     };
   });
 
-/**
- * Which icon library bare `icon` names resolve against (mirrors Mintlify's
- * `icons.library`). Names can always opt into a specific set with an explicit
- * `prefix:name` (`lucide:rocket`, `fa6-brands:github`) regardless of this.
- */
-const iconsConfigSchema = z
-  .object({
-    library: z.enum(["lucide", "fontawesome", "tabler"]).default("lucide"),
-  })
-  .strict();
-
 export const blumeConfigSchema = z
   .object({
     ai: aiConfigSchema.default({}),
@@ -1036,11 +962,9 @@ export const blumeConfigSchema = z
      */
     examples: z.string().default("examples"),
     export: exportConfigSchema.default(false),
-    favicon: faviconConfigSchema.optional(),
     feedback: z.boolean().default(true),
     github: githubConfigSchema.optional(),
     i18n: i18nConfigSchema.optional(),
-    icons: iconsConfigSchema.default({}),
     lastModified: lastModifiedConfigSchema.default(false),
     logo: logoConfigSchema.optional(),
     markdown: markdownConfigSchema.default({}),
@@ -1053,7 +977,6 @@ export const blumeConfigSchema = z
     theme: themeConfigSchema.default({}),
     title: z.string().default("Documentation"),
     toc: tocConfigSchema,
-    variables: variablesConfigSchema,
   })
   .strict();
 

package/src/core/sources/resolve.ts

@@ -7,7 +7,6 @@ import type { ProjectContext } from "../types.ts";
 import { filesystemSource } from "./filesystem.ts";
 import { githubReleasesSource } from "./github-releases.ts";
 import { mdxRemoteSource } from "./mdx-remote.ts";
-import { mintlifySource } from "./mintlify.ts";
 import { notionSource } from "./notion.ts";
 import { sanitySource } from "./sanity.ts";
 import type { ContentSource, SourceContext } from "./types.ts";
@@ -64,18 +63,6 @@ const buildSource = (
       root: def.root,
     });
   }
-  if (def.type === "mintlify") {
-    return mintlifySource({
-      configFile: def.configFile,
-      exclude: def.exclude,
-      include: def.include,
-      name,
-      prefix: def.prefix,
-      projectRoot: context.root,
-      root: def.root,
-      variables: def.variables,
-    });
-  }
   if (def.type === "custom") {
     // A user-provided instance manages its own context/caching; we only ensure
     // its name is unique across the project for id namespacing.

package/src/core/sources/watch.ts

@@ -2,8 +2,9 @@ import type { WatchListener } from "node:fs";
 
 /**
  * Directory segments a recursive dev watcher must never react to. When a
- * source's content root is the project root — a migrated `.`-rooted project or a
- * Mintlify bridge — a naive recursive `fs.watch` also sees Blume's own `.blume/`
+ * source's content root is the project root — a `.`-rooted layout, or an
+ * all-staged project (openapi/notion/github-releases/…) with no filesystem
+ * source — a naive recursive `fs.watch` also sees Blume's own `.blume/`
  * output, which the dev server rewrites on every render (e.g.
  * `.blume/.astro/data-store.json`). Left unfiltered, each such write re-triggers
  * a rescan + runtime regeneration whose writes land back under `.blume/` and

package/src/core/types.ts

@@ -173,24 +173,17 @@ export interface NavSelectorItem {
   tag?: string;
 }
 
-/** Top-level Mintlify-style partition selectors. */
+/** Top-level partition selectors (products, versions, languages). */
 export interface NavSelector {
   label: string;
   kind: "dropdown" | "language" | "product" | "version";
   items: NavSelectorItem[];
 }
 
-/** Chrome overrides used when the current route belongs to a nav partition. */
-export interface NavChromeVariant {
-  path: string;
-  banner?: ResolvedConfig["banner"];
-}
-
 /** The complete navigation model derived from the content graph. */
 export interface Navigation {
   tabs: NavTab[];
   selectors: NavSelector[];
-  chromeVariants: NavChromeVariant[];
   sidebar: NavNode[];
   /** Repo URL for the header link, or null when hidden (`navigation.repo`). */
   repoUrl?: string | null;

package/src/openapi/parse.ts

@@ -1,8 +1,10 @@
-import { readFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { setTimeout as sleep } from "node:timers/promises";
 
 import { normalize, upgrade } from "@scalar/openapi-parser";
 import { isAbsolute, join } from "pathe";
 
+import { hashText } from "../core/sources/cache.ts";
 import type { ApiDocument } from "./model.ts";
 
 /**
@@ -10,39 +12,220 @@ import type { ApiDocument } from "./model.ts";
  * (`@scalar/openapi-parser`) to read a spec (YAML or JSON), then upgrade Swagger
  * 2.0 / OpenAPI 3.0 documents to 3.1 so the renderer only handles one shape.
  * Internal `$ref`s are deliberately left in place (see `model.ts`).
+ *
+ * Remote (`http(s)`) specs are fetched defensively — bounded per attempt, retried
+ * on transient failures, proxy-aware, and cached on disk — mirroring the
+ * resilience the external link checker (`core/links.ts`) and the Notion source
+ * (`core/sources/notion.ts`) already have. A bare `fetch` is the classic "curl
+ * works but the build doesn't" gap: it ignores `*_PROXY`, has no timeout, and
+ * dies on a single cold-start blip.
  */
 
 const URL_SPEC = /^https?:\/\//u;
 
+const FETCH_TIMEOUT_MS = 15_000;
+const MAX_ATTEMPTS = 3;
+const BASE_BACKOFF_MS = 500;
+const SECOND_MS = 1000;
+// Worth another try: request timeout, too-early, rate-limited, and the 5xx range.
+const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+const USER_AGENT = "blume (+https://github.com/haydenbleasel/blume)";
+const PROXY_ENV_VARS = [
+  "HTTP_PROXY",
+  "http_proxy",
+  "HTTPS_PROXY",
+  "https_proxy",
+  "ALL_PROXY",
+  "all_proxy",
+];
+
 export interface ParsedSpec {
   document: ApiDocument;
   warnings: string[];
 }
 
+/** Where and whether to cache a remote spec's text between runs. */
+export interface SpecFetchOptions {
+  /** Dir for a last-good on-disk copy of a remote spec (offline fallback). */
+  cacheDir?: string;
+  /**
+   * Re-fetch even when a cached copy exists. Builds/sync refresh; dev is
+   * cache-first for fast, offline-tolerant restarts (see `SourceContext`).
+   */
+  refresh?: boolean;
+}
+
+/**
+ * Route Node's global `fetch` through an HTTP(S) proxy the first time a remote
+ * spec is fetched with one configured. Node's built-in `fetch` ignores `*_PROXY`
+ * on its own; undici's env proxy agent, installed on the shared global-dispatcher
+ * symbol, wires it in without replacing `fetch` (so tests can still stub it).
+ * Best-effort and lazy: no proxy env means no undici import at all, and an
+ * unavailable undici just leaves the direct connection in place.
+ */
+let proxyInstalled = false;
+const ensureProxyDispatcher = async (): Promise<void> => {
+  // Only memoize a successful install: with no proxy configured we cheaply
+  // re-check each time, so a proxy set later in the process still takes effect.
+  if (proxyInstalled || !PROXY_ENV_VARS.some((name) => process.env[name])) {
+    return;
+  }
+  try {
+    const { EnvHttpProxyAgent, setGlobalDispatcher } = await import("undici");
+    setGlobalDispatcher(new EnvHttpProxyAgent());
+    proxyInstalled = true;
+  } catch {
+    // No proxy support available; fall back to a direct connection.
+  }
+};
+
+/** `Retry-After` in ms when the server sent a sane one, else undefined. */
+const retryAfterMs = (response: Response): number | undefined => {
+  const header = response.headers.get("retry-after");
+  const seconds = header ? Number(header) : Number.NaN;
+  return Number.isFinite(seconds) && seconds > 0
+    ? seconds * SECOND_MS
+    : undefined;
+};
+
+/** One fetch attempt, normalized: the body text, or a (maybe-retryable) error. */
+type Attempt =
+  | { text: string }
+  | { error: Error; retryable: boolean; retryAfter?: number };
+
+const attemptFetch = async (spec: string): Promise<Attempt> => {
+  try {
+    const response = await fetch(spec, {
+      headers: {
+        accept: "application/json, application/yaml, text/yaml, */*",
+        "user-agent": USER_AGENT,
+      },
+      redirect: "follow",
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (response.ok) {
+      return { text: await response.text() };
+    }
+    return {
+      error: new Error(`${spec} -> ${response.status} ${response.statusText}`),
+      retryAfter: retryAfterMs(response),
+      retryable: RETRYABLE_STATUS.has(response.status),
+    };
+  } catch (error) {
+    // Network error, DNS/TLS failure, or an aborted (timed-out) request — all
+    // transient by nature, so worth a retry.
+    return {
+      error: error instanceof Error ? error : new Error(String(error)),
+      retryable: true,
+    };
+  }
+};
+
+/** Fetch a remote spec's text, retrying transient failures with backoff. */
+const fetchSpecText = async (spec: string): Promise<string> => {
+  await ensureProxyDispatcher();
+  let last: Attempt = {
+    error: new Error(`Could not fetch ${spec}`),
+    retryable: false,
+  };
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1) {
+    // oxlint-disable-next-line no-await-in-loop -- sequential retry attempts
+    last = await attemptFetch(spec);
+    if ("text" in last) {
+      return last.text;
+    }
+    if (!last.retryable || attempt === MAX_ATTEMPTS - 1) {
+      throw last.error;
+    }
+    // oxlint-disable-next-line no-await-in-loop -- back off before retrying
+    await sleep(last.retryAfter ?? BASE_BACKOFF_MS * 2 ** attempt);
+  }
+  throw last.error;
+};
+
+const cacheFileFor = (cacheDir: string, spec: string): string =>
+  join(cacheDir, `spec-${hashText(spec)}.cache`);
+
+const readCache = async (file: string): Promise<string | undefined> => {
+  try {
+    return await readFile(file, "utf-8");
+  } catch {
+    return undefined;
+  }
+};
+
+const writeCache = async (
+  dir: string,
+  file: string,
+  text: string
+): Promise<void> => {
+  try {
+    await mkdir(dir, { recursive: true });
+    await writeFile(file, text, "utf-8");
+  } catch {
+    // Best-effort cache; a write failure must not fail the load.
+  }
+};
+
 /** Read a spec's raw text from an `http(s)` URL or a local (project-relative) path. */
-const readSpecText = async (spec: string, root: string): Promise<string> => {
-  if (URL_SPEC.test(spec)) {
-    const response = await fetch(spec);
-    if (!response.ok) {
-      throw new Error(`${spec} -> ${response.status} ${response.statusText}`);
+const readSpecText = async (
+  spec: string,
+  root: string,
+  options: SpecFetchOptions
+): Promise<{ text: string; warnings: string[] }> => {
+  if (!URL_SPEC.test(spec)) {
+    const absolute = isAbsolute(spec) ? spec : join(root, spec);
+    return { text: await readFile(absolute, "utf-8"), warnings: [] };
+  }
+
+  const cacheFile = options.cacheDir
+    ? cacheFileFor(options.cacheDir, spec)
+    : undefined;
+
+  // Cache-first in dev: serve the last-good snapshot without touching the network.
+  if (cacheFile && options.refresh === false) {
+    const cached = await readCache(cacheFile);
+    if (cached !== undefined) {
+      return { text: cached, warnings: [] };
+    }
+  }
+
+  try {
+    const text = await fetchSpecText(spec);
+    if (options.cacheDir && cacheFile) {
+      await writeCache(options.cacheDir, cacheFile, text);
+    }
+    return { text, warnings: [] };
+  } catch (error) {
+    // A transient outage falls back to the last good fetch, with a warning.
+    if (cacheFile) {
+      const cached = await readCache(cacheFile);
+      if (cached !== undefined) {
+        return {
+          text: cached,
+          warnings: [
+            `Could not fetch ${spec} (${(error as Error).message}); using the last cached copy.`,
+          ],
+        };
+      }
     }
-    return await response.text();
+    throw error;
   }
-  const absolute = isAbsolute(spec) ? spec : join(root, spec);
-  return await readFile(absolute, "utf-8");
 };
 
 /**
  * Read, normalize, and upgrade a spec to an OpenAPI 3.1 document. Throws when the
- * spec can't be read; callers turn that into a source diagnostic rather than a
- * hard failure so a broken spec doesn't take down the whole build.
+ * spec can't be read and no cache is available; callers turn that into a source
+ * diagnostic (an error in build, a warning in dev) rather than a hard failure so
+ * a broken spec doesn't take down the whole build.
  */
 export const parseSpec = async (
   spec: string,
-  root: string
+  root: string,
+  options: SpecFetchOptions = {}
 ): Promise<ParsedSpec> => {
-  const text = await readSpecText(spec, root);
+  const { text, warnings } = await readSpecText(spec, root, options);
   const normalized = normalize(text);
   const { specification } = upgrade(normalized);
-  return { document: specification as ApiDocument, warnings: [] };
+  return { document: specification as ApiDocument, warnings };
 };

package/src/openapi/render-mdx.ts

@@ -73,13 +73,47 @@ export const operationMdx = (
   };
 };
 
-export const overviewMdx = (spec: ApiSpecData): RenderedPage => ({
-  body: withDescription(
-    spec.description,
-    `<ApiOverview source="${spec.slug}" />`
-  ),
-  data: {
-    sidebar: { label: "Overview" },
-    title: spec.title || spec.label,
-  },
-});
+export const overviewMdx = (spec: ApiSpecData): RenderedPage => {
+  // Tag sections: declared tags in spec order, then any tag an operation
+  // references that isn't declared under `tags`. The section headings are
+  // emitted as real markdown `##` (not markup inside a component) so the
+  // markdown pipeline gives them ids, permalink anchors, and table-of-contents
+  // entries; only the operation-link list defers to a component.
+  const operations = Object.values(spec.operations);
+  const sections = [...spec.tags];
+  const known = new Set(spec.tags.map((tag) => tag.slug));
+  for (const operation of operations) {
+    if (!known.has(operation.tagSlug)) {
+      known.add(operation.tagSlug);
+      sections.push({
+        description: "",
+        name: operation.tag,
+        slug: operation.tagSlug,
+      });
+    }
+  }
+  const tagSections = sections
+    .filter((tag) =>
+      operations.some((operation) => operation.tagSlug === tag.slug)
+    )
+    .map((tag) =>
+      [
+        `## ${mdxSafe(tag.name)}`,
+        ...(tag.description.trim() ? [mdxSafe(tag.description.trim())] : []),
+        `<ApiTagOperations source="${spec.slug}" tag="${tag.slug}" />`,
+      ].join("\n\n")
+    );
+  return {
+    body: [
+      withDescription(
+        spec.description,
+        `<ApiOverview source="${spec.slug}" />`
+      ),
+      ...tagSections,
+    ].join("\n\n"),
+    data: {
+      sidebar: { label: "Overview" },
+      title: spec.title || spec.label,
+    },
+  };
+};