boltdocs 1.0.4 → 1.3.1

package/src/node/routes/sorter.ts

@@ -1,42 +1,42 @@
-import { RouteMeta } from "./types";
-
-/**
- * Sorts an array of generated routes.
- * Ungrouped items come first. Items within the same group are sorted by position, then alphabetically.
- * Groups are sorted relative to each other by their group position, then alphabetically.
- *
- * @param routes - The unsorted routes
- * @returns A new array of sorted routes suitable for sidebar generation
- */
-export function sortRoutes(routes: RouteMeta[]): RouteMeta[] {
-  return routes.sort((a, b) => {
-    // Ungrouped first
-    if (!a.group && !b.group) return compareByPosition(a, b);
-    if (!a.group) return -1;
-    if (!b.group) return 1;
-
-    // Different groups: sort by group position
-    if (a.group !== b.group) {
-      return compareByGroupPosition(a, b);
-    }
-
-    // Same group: sort by item position
-    return compareByPosition(a, b);
-  });
-}
-
-function compareByPosition(a: RouteMeta, b: RouteMeta): number {
-  if (a.sidebarPosition !== undefined && b.sidebarPosition !== undefined)
-    return a.sidebarPosition - b.sidebarPosition;
-  if (a.sidebarPosition !== undefined) return -1;
-  if (b.sidebarPosition !== undefined) return 1;
-  return a.title.localeCompare(b.title);
-}
-
-function compareByGroupPosition(a: RouteMeta, b: RouteMeta): number {
-  if (a.groupPosition !== undefined && b.groupPosition !== undefined)
-    return a.groupPosition - b.groupPosition;
-  if (a.groupPosition !== undefined) return -1;
-  if (b.groupPosition !== undefined) return 1;
-  return (a.groupTitle || a.group!).localeCompare(b.groupTitle || b.group!);
-}
+import { RouteMeta } from "./types";
+
+/**
+ * Sorts an array of generated routes.
+ * Ungrouped items come first. Items within the same group are sorted by position, then alphabetically.
+ * Groups are sorted relative to each other by their group position, then alphabetically.
+ *
+ * @param routes - The unsorted routes
+ * @returns A new array of sorted routes suitable for sidebar generation
+ */
+export function sortRoutes(routes: RouteMeta[]): RouteMeta[] {
+  return routes.sort((a, b) => {
+    // Ungrouped first
+    if (!a.group && !b.group) return compareByPosition(a, b);
+    if (!a.group) return -1;
+    if (!b.group) return 1;
+
+    // Different groups: sort by group position
+    if (a.group !== b.group) {
+      return compareByGroupPosition(a, b);
+    }
+
+    // Same group: sort by item position
+    return compareByPosition(a, b);
+  });
+}
+
+function compareByPosition(a: RouteMeta, b: RouteMeta): number {
+  if (a.sidebarPosition !== undefined && b.sidebarPosition !== undefined)
+    return a.sidebarPosition - b.sidebarPosition;
+  if (a.sidebarPosition !== undefined) return -1;
+  if (b.sidebarPosition !== undefined) return 1;
+  return a.title.localeCompare(b.title);
+}
+
+function compareByGroupPosition(a: RouteMeta, b: RouteMeta): number {
+  if (a.groupPosition !== undefined && b.groupPosition !== undefined)
+    return a.groupPosition - b.groupPosition;
+  if (a.groupPosition !== undefined) return -1;
+  if (b.groupPosition !== undefined) return 1;
+  return (a.groupTitle || a.group!).localeCompare(b.groupTitle || b.group!);
+}

package/src/node/routes/types.ts

@@ -1,49 +1,49 @@
-/**
- * Metadata representing a single documentation route.
- * This information is used to build the client-side router and the sidebar navigation.
- */
-export interface RouteMeta {
-  /** The final URL path for the route (e.g., '/docs/guide/start') */
-  path: string;
-  /** The absolute filesystem path to the source markdown/mdx file */
-  componentPath: string;
-  /** The title of the page, usually extracted from frontmatter or the filename */
-  title: string;
-  /** The relative path from the docs directory, used for edit links */
-  filePath: string;
-  /** Optional description of the page (for SEO/meta tags) */
-  description?: string;
-  /** Optional explicit position for ordering in the sidebar */
-  sidebarPosition?: number;
-  /** The group (directory) this route belongs to */
-  group?: string;
-  /** The display title for the route's group */
-  groupTitle?: string;
-  /** Optional explicit position for ordering the group itself */
-  groupPosition?: number;
-  /** Extracted markdown headings for search indexing */
-  headings?: { level: number; text: string; id: string }[];
-  /** The locale this route belongs to, if i18n is configured */
-  locale?: string;
-  /** The version this route belongs to, if versioning is configured */
-  version?: string;
-  /** Optional badge to display next to the sidebar item (e.g., 'New', 'Experimental') */
-  badge?: string | { text: string; expires?: string };
-}
-
-/**
- * Internal representation of a parsed documentation file before finalizing groups.
- * Stored in the file cache to avoid re-parsing unchanged files.
- */
-export interface ParsedDocFile {
-  /** The core route metadata without group-level details (inferred later) */
-  route: Omit<RouteMeta, "group" | "groupTitle" | "groupPosition">;
-  /** The base directory of the file (used to group files together) */
-  relativeDir?: string;
-  /** Whether this file is the index file for its directory group */
-  isGroupIndex: boolean;
-  /** If this is a group index, any specific frontmatter metadata dictating the group's title and position */
-  groupMeta?: { title: string; position?: number };
-  /** Extracted group position from the directory name if it has a numeric prefix */
-  inferredGroupPosition?: number;
-}
+/**
+ * Metadata representing a single documentation route.
+ * This information is used to build the client-side router and the sidebar navigation.
+ */
+export interface RouteMeta {
+  /** The final URL path for the route (e.g., '/docs/guide/start') */
+  path: string;
+  /** The absolute filesystem path to the source markdown/mdx file */
+  componentPath: string;
+  /** The title of the page, usually extracted from frontmatter or the filename */
+  title: string;
+  /** The relative path from the docs directory, used for edit links */
+  filePath: string;
+  /** Optional description of the page (for SEO/meta tags) */
+  description?: string;
+  /** Optional explicit position for ordering in the sidebar */
+  sidebarPosition?: number;
+  /** The group (directory) this route belongs to */
+  group?: string;
+  /** The display title for the route's group */
+  groupTitle?: string;
+  /** Optional explicit position for ordering the group itself */
+  groupPosition?: number;
+  /** Extracted markdown headings for search indexing */
+  headings?: { level: number; text: string; id: string }[];
+  /** The locale this route belongs to, if i18n is configured */
+  locale?: string;
+  /** The version this route belongs to, if versioning is configured */
+  version?: string;
+  /** Optional badge to display next to the sidebar item (e.g., 'New', 'Experimental') */
+  badge?: string | { text: string; expires?: string };
+}
+
+/**
+ * Internal representation of a parsed documentation file before finalizing groups.
+ * Stored in the file cache to avoid re-parsing unchanged files.
+ */
+export interface ParsedDocFile {
+  /** The core route metadata without group-level details (inferred later) */
+  route: Omit<RouteMeta, "group" | "groupTitle" | "groupPosition">;
+  /** The base directory of the file (used to group files together) */
+  relativeDir?: string;
+  /** Whether this file is the index file for its directory group */
+  isGroupIndex: boolean;
+  /** If this is a group index, any specific frontmatter metadata dictating the group's title and position */
+  groupMeta?: { title: string; position?: number };
+  /** Extracted group position from the directory name if it has a numeric prefix */
+  inferredGroupPosition?: number;
+}

package/src/node/ssg/index.ts

@@ -1,110 +1,114 @@
-import fs from "fs";
-import path from "path";
-import { generateRoutes } from "../routes";
-import { escapeHtml } from "../utils";
-import { fileURLToPath } from "url";
-import { createRequire } from "module";
-
-import { SSGOptions } from "./options";
-import { replaceMetaTags } from "./meta";
-import { generateSitemap } from "./sitemap";
-
-// Re-export options for consumers
-export type { SSGOptions };
-
-// Polyfill __dirname and require for ESM
-const _filename = fileURLToPath(import.meta.url);
-const _dirname = path.dirname(_filename);
-const _require = createRequire(import.meta.url);
-
-/**
- * Generates static HTML files and a \`sitemap.xml\` for all documentation routes.
- * Called automatically in the \`closeBundle\` hook of the Vite plugin during a production build.
- *
- * @param options - Configuration for paths and site metadata
- */
-export async function generateStaticPages(options: SSGOptions): Promise<void> {
-  const { docsDir, outDir, config } = options;
-  const routes = await generateRoutes(docsDir, config);
-  const siteTitle = config?.themeConfig?.title || "Boltdocs";
-  const siteDescription = config?.themeConfig?.description || "";
-
-  // Resolve the SSR module (compiled by tsup)
-  const ssrModulePath = path.resolve(_dirname, "../client/ssr.js");
-  if (!fs.existsSync(ssrModulePath)) {
-    console.error(
-      "[boltdocs] SSR module not found at",
-      ssrModulePath,
-      "- Did you build the core package?",
-    );
-    return;
-  }
-  const { render } = _require(ssrModulePath);
-
-  // Read the built index.html as template
-  const templatePath = path.join(outDir, "index.html");
-  if (!fs.existsSync(templatePath)) {
-    console.warn("[boltdocs] No index.html found in outDir, skipping SSG.");
-    return;
-  }
-  const template = fs.readFileSync(templatePath, "utf-8");
-
-  // Load user's homePage if configured
-  let homePageComp;
-  if ((config as any)?._homePagePath) {
-    try {
-      // Simplistic: if there's a custom home page compiled, we'd need it available to SSR.
-      // In a full framework this is complex, but for Boltdocs we assume it's bundled if needed.
-    } catch (e) {}
-  }
-
-  // Generate an HTML file for each route concurrently
-  await Promise.all(
-    routes.map(async (route) => {
-      const pageTitle = `${route.title} | ${siteTitle}`;
-      const pageDescription = route.description || siteDescription;
-
-      // We mock the modules for SSR so it doesn't crash trying to dynamically import
-      const fakeModules: Record<string, any> = {};
-      fakeModules[route.componentPath] = { default: () => {} }; // Mock MDX component
-
-      try {
-        const appHtml = await render({
-          path: route.path,
-          routes: routes,
-          config: config || {},
-          modules: fakeModules,
-          homePage: homePageComp,
-        });
-
-        const html = replaceMetaTags(template, {
-          title: escapeHtml(pageTitle),
-          description: escapeHtml(pageDescription),
-        })
-          .replace("<!--app-html-->", appHtml)
-          .replace(`<div id="root"></div>`, `<div id="root">${appHtml}</div>`);
-
-        const routeDir = path.join(outDir, route.path);
-        await fs.promises.mkdir(routeDir, { recursive: true });
-        await fs.promises.writeFile(
-          path.join(routeDir, "index.html"),
-          html,
-          "utf-8",
-        );
-      } catch (e) {
-        console.error(`[boltdocs] Error SSR rendering route ${route.path}:`, e);
-      }
-    }),
-  );
-
-  // Generate sitemap.xml
-  const sitemap = generateSitemap(
-    routes.map((r) => r.path),
-    config,
-  );
-  fs.writeFileSync(path.join(outDir, "sitemap.xml"), sitemap, "utf-8");
-
-  console.log(
-    `[boltdocs] Generated ${routes.length} static pages + sitemap.xml`,
-  );
-}
+import fs from "fs";
+import path from "path";
+import { generateRoutes } from "../routes";
+import { escapeHtml } from "../utils";
+import { fileURLToPath } from "url";
+import { createRequire } from "module";
+
+import { SSGOptions } from "./options";
+import { replaceMetaTags } from "./meta";
+import { generateSitemap } from "./sitemap";
+
+// Re-export options for consumers
+export type { SSGOptions };
+
+// Polyfill __dirname and require for ESM
+const _filename = fileURLToPath(import.meta.url);
+const _dirname = path.dirname(_filename);
+const _require = createRequire(import.meta.url);
+
+/**
+ * Generates static HTML files and a \`sitemap.xml\` for all documentation routes.
+ * Called automatically in the \`closeBundle\` hook of the Vite plugin during a production build.
+ *
+ * @param options - Configuration for paths and site metadata
+ */
+export async function generateStaticPages(options: SSGOptions): Promise<void> {
+  const { docsDir, outDir, config } = options;
+  const routes = await generateRoutes(docsDir, config);
+  const siteTitle = config?.themeConfig?.title || "Boltdocs";
+  const siteDescription = config?.themeConfig?.description || "";
+
+  // Resolve the SSR module (compiled by tsup)
+  const ssrModulePath = path.resolve(_dirname, "../client/ssr.js");
+  if (!fs.existsSync(ssrModulePath)) {
+    console.error(
+      "[boltdocs] SSR module not found at",
+      ssrModulePath,
+      "- Did you build the core package?",
+    );
+    return;
+  }
+  const { render } = _require(ssrModulePath);
+
+  // Read the built index.html as template
+  const templatePath = path.join(outDir, "index.html");
+  if (!fs.existsSync(templatePath)) {
+    console.warn("[boltdocs] No index.html found in outDir, skipping SSG.");
+    return;
+  }
+  const template = fs.readFileSync(templatePath, "utf-8");
+
+  // Load user's homePage if configured
+  let homePageComp;
+  if ((config as any)?._homePagePath) {
+    try {
+      // Simplistic: if there's a custom home page compiled, we'd need it available to SSR.
+      // In a full framework this is complex, but for Boltdocs we assume it's bundled if needed.
+    } catch (e) {}
+  }
+
+  // Generate an HTML file for each route concurrently
+  await Promise.all(
+    routes.map(async (route) => {
+      const pageTitle = `${route.title} | ${siteTitle}`;
+      const pageDescription = route.description || siteDescription;
+
+      // We mock the modules for SSR so it doesn't crash trying to dynamically import
+      const fakeModules: Record<string, any> = {};
+      fakeModules[route.componentPath] = { default: () => {} }; // Mock MDX component
+
+      try {
+        const appHtml = await render({
+          path: route.path,
+          routes: routes,
+          config: config || {},
+          modules: fakeModules,
+          homePage: homePageComp,
+        });
+
+        const html = replaceMetaTags(template, {
+          title: escapeHtml(pageTitle),
+          description: escapeHtml(pageDescription),
+        })
+          .replace("<!--app-html-->", appHtml)
+          .replace(`<div id="root"></div>`, `<div id="root">${appHtml}</div>`);
+
+        const routeDir = path.join(outDir, route.path);
+        await fs.promises.mkdir(routeDir, { recursive: true });
+        await fs.promises.writeFile(
+          path.join(routeDir, "index.html"),
+          html,
+          "utf-8",
+        );
+      } catch (e) {
+        console.error(`[boltdocs] Error SSR rendering route ${route.path}:`, e);
+      }
+    }),
+  );
+
+  // Generate sitemap.xml
+  const sitemap = generateSitemap(
+    routes.map((r) => r.path),
+    config,
+  );
+  fs.writeFileSync(path.join(outDir, "sitemap.xml"), sitemap, "utf-8");
+
+  console.log(
+    `[boltdocs] Generated ${routes.length} static pages + sitemap.xml`,
+  );
+
+  // Ensure all cache operations (like index persistence) are finished
+  const { flushCache } = await import("../cache");
+  await flushCache();
+}

package/src/node/ssg/meta.ts

@@ -1,34 +1,34 @@
-/**
- * Replaces placeholder or default meta tags in the HTML template with page-specific values.
- *
- * @param html - The base HTML template string
- * @param meta - An object containing the derived `title` and `description` for the specific page
- * @returns The final HTML string for that specific page
- */
-export function replaceMetaTags(
-  html: string,
-  meta: { title: string; description: string },
-): string {
-  return html
-    .replace(/<title>.*?<\/title>/, `<title>${meta.title}</title>`)
-    .replace(
-      /(<meta name="description" content=")[^"]*(")/,
-      `$1${meta.description}$2`,
-    )
-    .replace(
-      /(<meta property="og:title" content=")[^"]*(")/,
-      `$1${meta.title}$2`,
-    )
-    .replace(
-      /(<meta property="og:description" content=")[^"]*(")/,
-      `$1${meta.description}$2`,
-    )
-    .replace(
-      /(<meta name="twitter:title" content=")[^"]*(")/,
-      `$1${meta.title}$2`,
-    )
-    .replace(
-      /(<meta name="twitter:description" content=")[^"]*(")/,
-      `$1${meta.description}$2`,
-    );
-}
+/**
+ * Replaces placeholder or default meta tags in the HTML template with page-specific values.
+ *
+ * @param html - The base HTML template string
+ * @param meta - An object containing the derived `title` and `description` for the specific page
+ * @returns The final HTML string for that specific page
+ */
+export function replaceMetaTags(
+  html: string,
+  meta: { title: string; description: string },
+): string {
+  return html
+    .replace(/<title>.*?<\/title>/, `<title>${meta.title}</title>`)
+    .replace(
+      /(<meta name="description" content=")[^"]*(")/,
+      `$1${meta.description}$2`,
+    )
+    .replace(
+      /(<meta property="og:title" content=")[^"]*(")/,
+      `$1${meta.title}$2`,
+    )
+    .replace(
+      /(<meta property="og:description" content=")[^"]*(")/,
+      `$1${meta.description}$2`,
+    )
+    .replace(
+      /(<meta name="twitter:title" content=")[^"]*(")/,
+      `$1${meta.title}$2`,
+    )
+    .replace(
+      /(<meta name="twitter:description" content=")[^"]*(")/,
+      `$1${meta.description}$2`,
+    );
+}

package/src/node/ssg/options.ts

@@ -1,13 +1,13 @@
-import { BoltdocsConfig } from "../config";
-
-/**
- * Options for the Static Site Generation process.
- */
-export interface SSGOptions {
-  /** The root directory containing markdown documentation files */
-  docsDir: string;
-  /** The output directory where Vite placed the compiled `index.html` and assets */
-  outDir: string;
-  /** Pre-resolved config (avoids re-resolving during the SSG phase) */
-  config?: BoltdocsConfig;
-}
+import { BoltdocsConfig } from "../config";
+
+/**
+ * Options for the Static Site Generation process.
+ */
+export interface SSGOptions {
+  /** The root directory containing markdown documentation files */
+  docsDir: string;
+  /** The output directory where Vite placed the compiled `index.html` and assets */
+  outDir: string;
+  /** Pre-resolved config (avoids re-resolving during the SSG phase) */
+  config?: BoltdocsConfig;
+}

package/src/node/ssg/sitemap.ts

@@ -1,54 +1,54 @@
-import { BoltdocsConfig } from "../config";
-
-/**
- * Generates a standard XML sitemap for search engine crawlers.
- *
- * @param routePaths - An array of existing URL paths (e.g., ['/docs/intro', '/docs/setup'])
- * @param config - The Boltdocs configuration containing i18n and siteUrl settings
- * @returns The formatted XML sitemap string
- */
-export function generateSitemap(
-  routePaths: string[],
-  config?: BoltdocsConfig,
-): string {
-  const baseUrl = config?.siteUrl?.replace(/\/$/, "") || "https://example.com";
-  const today = new Date().toISOString().split("T")[0];
-
-  const rootEntries = [{ url: "/", priority: "1.0", changefreq: "daily" }];
-
-  if (config?.i18n) {
-    const defaultLocale = config.i18n.defaultLocale;
-    for (const locale of Object.keys(config.i18n.locales)) {
-      if (locale !== defaultLocale) {
-        rootEntries.push({
-          url: `/${locale}/`,
-          priority: "1.0",
-          changefreq: "daily",
-        });
-      }
-    }
-  }
-
-  const entries = [
-    ...rootEntries,
-    ...routePaths.map((p) => ({
-      url: p,
-      priority: "0.8",
-      changefreq: "weekly",
-    })),
-  ];
-
-  return `<?xml version="1.0" encoding="UTF-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
-${entries
-  .map(
-    (e) => `  <url>
-    <loc>${baseUrl}${e.url}</loc>
-    <lastmod>${today}</lastmod>
-    <changefreq>${e.changefreq}</changefreq>
-    <priority>${e.priority}</priority>
-  </url>`,
-  )
-  .join("\n")}
-</urlset>`;
-}
+import { BoltdocsConfig } from "../config";
+
+/**
+ * Generates a standard XML sitemap for search engine crawlers.
+ *
+ * @param routePaths - An array of existing URL paths (e.g., ['/docs/intro', '/docs/setup'])
+ * @param config - The Boltdocs configuration containing i18n and siteUrl settings
+ * @returns The formatted XML sitemap string
+ */
+export function generateSitemap(
+  routePaths: string[],
+  config?: BoltdocsConfig,
+): string {
+  const baseUrl = config?.siteUrl?.replace(/\/$/, "") || "https://example.com";
+  const today = new Date().toISOString().split("T")[0];
+
+  const rootEntries = [{ url: "/", priority: "1.0", changefreq: "daily" }];
+
+  if (config?.i18n) {
+    const defaultLocale = config.i18n.defaultLocale;
+    for (const locale of Object.keys(config.i18n.locales)) {
+      if (locale !== defaultLocale) {
+        rootEntries.push({
+          url: `/${locale}/`,
+          priority: "1.0",
+          changefreq: "daily",
+        });
+      }
+    }
+  }
+
+  const entries = [
+    ...rootEntries,
+    ...routePaths.map((p) => ({
+      url: p,
+      priority: "0.8",
+      changefreq: "weekly",
+    })),
+  ];
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${entries
+  .map(
+    (e) => `  <url>
+    <loc>${baseUrl}${e.url}</loc>
+    <lastmod>${today}</lastmod>
+    <changefreq>${e.changefreq}</changefreq>
+    <priority>${e.priority}</priority>
+  </url>`,
+  )
+  .join("\n")}
+</urlset>`;
+}