boltdocs 1.0.0

package/src/node/routes/types.ts

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

package/src/node/ssg/index.ts

@@ -0,0 +1,110 @@
+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`,
+  );
+}

package/src/node/ssg/meta.ts

@@ -0,0 +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`,
+    );
+}

package/src/node/ssg/options.ts

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

package/src/node/ssg/sitemap.ts

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

package/src/node/utils.ts

@@ -0,0 +1,134 @@
+import fs from "fs";
+import matter from "gray-matter";
+
+/**
+ * Normalizes a file path by replacing Windows backslashes with forward slashes.
+ * Ensures consistent path handling across different operating systems.
+ *
+ * @param p - The file path to normalize
+ * @returns The normalized path using forward slashes
+ */
+export function normalizePath(p: string): string {
+  return p.replace(/\\/g, "/");
+}
+
+/**
+ * Strips a numeric prefix from a file or directory name (e.g., '1.guide' -> 'guide').
+ *
+ * @param name - The name to strip
+ * @returns The name without the numeric prefix
+ */
+export function stripNumberPrefix(name: string): string {
+  return name.replace(/^\d+\./, "");
+}
+
+/**
+ * Extracts the numeric prefix from a file or directory name if it exists.
+ *
+ * @param name - The name to parse
+ * @returns The extracted number, or undefined if none exists
+ */
+export function extractNumberPrefix(name: string): number | undefined {
+  const match = name.match(/^(\d+)\./);
+  return match ? parseInt(match[1], 10) : undefined;
+}
+
+/**
+ * Checks if a given file path points to a Markdown or MDX file.
+ *
+ * @param filePath - The path to check
+ * @returns True if the file ends with .md or .mdx, false otherwise
+ */
+export function isDocFile(filePath: string): boolean {
+  return /\.mdx?$/.test(filePath);
+}
+
+/**
+ * Retrieves the modification time (mtime) of a file in milliseconds.
+ * Useful for caching strategies to detect if a file has changed.
+ * Returns 0 if the file doesn't exist or cannot be accessed.
+ *
+ * @param filePath - The absolute path to the file
+ * @returns The modification time in milliseconds, or 0 on error
+ */
+export function getFileMtime(filePath: string): number {
+  try {
+    return fs.statSync(filePath).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Parses frontmatter and markdown content from a file synchronously.
+ * Uses `gray-matter` for parsing. Returns the parsed data and the remaining markdown content.
+ *
+ * @param filePath - The absolute path to the markdown/mdx file
+ * @returns An object containing the parsed metadata (`data`) and the raw markdown (`content`)
+ */
+export function parseFrontmatter(filePath: string): {
+  data: Record<string, any>;
+  content: string;
+} {
+  const raw = fs.readFileSync(filePath, "utf-8");
+  const { data, content } = matter(raw);
+  return { data, content };
+}
+
+/**
+ * Escapes special HTML characters in a string to prevent XSS and ensure
+ * safe injection into HTML attributes or text content.
+ *
+ * @param str - The raw string to escape
+ * @returns The escaped string
+ */
+export function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/**
+ * Converts a file path relative to the `docsDir` into a URL route path.
+ * Handles removing extensions, converting `index` files to directory roots,
+ * and ensuring proper slash formatting.
+ *
+ * @param relativePath - The file path relative to the documentation source directory (e.g., 'guide/index.md')
+ * @returns The corresponding route path (e.g., '/guide')
+ */
+export function fileToRoutePath(relativePath: string): string {
+  // Strip number prefixes from every segment
+  let cleanedPath = relativePath.split("/").map(stripNumberPrefix).join("/");
+
+  let routePath = cleanedPath.replace(/\.mdx?$/, "");
+
+  // Handle index files → directory root
+  if (routePath === "index" || routePath.endsWith("/index")) {
+    routePath = routePath.replace(/index$/, "");
+  }
+
+  // Ensure leading slash
+  if (!routePath.startsWith("/")) {
+    routePath = "/" + routePath;
+  }
+
+  // Remove trailing slash (except for root '/')
+  if (routePath.length > 1 && routePath.endsWith("/")) {
+    routePath = routePath.slice(0, -1);
+  }
+
+  return routePath;
+}
+
+/**
+ * Capitalizes the first letter of a given string.
+ * Used primarily for generating default group titles.
+ *
+ * @param str - The string to capitalize
+ * @returns The capitalized string
+ */
+export function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "ESNext",
+        "moduleResolution": "Node",
+        "esModuleInterop": true,
+        "strict": true,
+        "skipLibCheck": true,
+        "jsx": "react-jsx",
+        "declaration": true,
+        "outDir": "dist"
+    },
+    "include": [
+        "src"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist",
+    ]
+}

package/tsup.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: [
+    "src/node/index.ts",
+    "src/node/cli/index.ts",
+    "src/client/index.ts",
+    "src/client/ssr.tsx",
+  ],
+  format: ["cjs", "esm"],
+  dts: true,
+  tsconfig: "./tsconfig.json",
+  clean: true,
+  external: [
+    "vite",
+    "react",
+    "react-dom",
+    "react-router-dom",
+    "virtual:boltdocs-routes",
+    "virtual:boltdocs-config",
+  ],
+});