boltdocs 1.10.2 → 2.0.0

package/src/node/routes/sorter.ts

@@ -1,4 +1,4 @@
-import { RouteMeta } from "./types";
+import type { RouteMeta } from './types'
 
 /**
  * Sorts an array of generated routes.
@@ -11,32 +11,32 @@ import { RouteMeta } from "./types";
 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;
+    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);
+      return compareByGroupPosition(a, b)
     }
 
     // Same group: sort by item position
-    return compareByPosition(a, b);
-  });
+    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);
+    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!);
+    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

@@ -4,41 +4,41 @@
  */
 export interface RouteMeta {
   /** The final URL path for the route (e.g., '/docs/guide/start') */
-  path: string;
+  path: string
   /** The absolute filesystem path to the source markdown/mdx file */
-  componentPath: string;
+  componentPath: string
   /** The title of the page, usually extracted from frontmatter or the filename */
-  title: string;
+  title: string
   /** The relative path from the docs directory, used for edit links */
-  filePath: string;
+  filePath: string
   /** Optional description of the page (for SEO/meta tags) */
-  description?: string;
+  description?: string
   /** Optional explicit position for ordering in the sidebar */
-  sidebarPosition?: number;
+  sidebarPosition?: number
   /** The group (directory) this route belongs to */
-  group?: string;
+  group?: string
   /** The display title for the route's group */
-  groupTitle?: string;
+  groupTitle?: string
   /** Optional explicit position for ordering the group itself */
-  groupPosition?: number;
+  groupPosition?: number
   /** Optional icon for the route's group */
-  groupIcon?: string;
+  groupIcon?: string
   /** Extracted markdown headings for search indexing */
-  headings?: { level: number; text: string; id: string }[];
+  headings?: { level: number; text: string; id: string }[]
   /** The locale this route belongs to, if i18n is configured */
-  locale?: string;
+  locale?: string
   /** The version this route belongs to, if versioning is configured */
-  version?: string;
+  version?: string
   /** Optional badge to display next to the sidebar item (e.g., 'New', 'Experimental') */
-  badge?: string | { text: string; expires?: string };
+  badge?: string | { text: string; expires?: string }
   /** Optional icon to display (Lucide icon name or raw SVG) */
-  icon?: string;
+  icon?: string
   /** The tab this route belongs to, if tabs are configured */
-  tab?: string;
+  tab?: string
   /** The extracted plain-text content of the page for search indexing */
-  _content?: string;
+  _content?: string
   /** The raw markdown content of the page */
-  _rawContent?: string;
+  _rawContent?: string
 }
 
 /**
@@ -47,15 +47,15 @@ export interface RouteMeta {
  */
 export interface ParsedDocFile {
   /** The core route metadata without group-level details (inferred later) */
-  route: Omit<RouteMeta, "group" | "groupTitle" | "groupPosition">;
+  route: Omit<RouteMeta, 'group' | 'groupTitle' | 'groupPosition'>
   /** The base directory of the file (used to group files together) */
-  relativeDir?: string;
+  relativeDir?: string
   /** Whether this file is the index file for its directory group */
-  isGroupIndex: boolean;
+  isGroupIndex: boolean
   /** If this is a group index, any specific frontmatter metadata dictating the group's title and position */
-  groupMeta?: { title: string; position?: number; icon?: string };
+  groupMeta?: { title: string; position?: number; icon?: string }
   /** Extracted group position from the directory name if it has a numeric prefix */
-  inferredGroupPosition?: number;
+  inferredGroupPosition?: number
   /** Extracted tab name from the directory name if it follows the (tab-name) syntax */
-  inferredTab?: string;
+  inferredTab?: string
 }

package/src/node/ssg/index.ts

@@ -1,21 +1,21 @@
-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 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";
+import type { SSGOptions } from './options'
+import { replaceMetaTags } from './meta'
+import { generateSitemap } from './sitemap'
 
 // Re-export options for consumers
-export type { SSGOptions };
+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);
+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.
@@ -24,40 +24,66 @@ const _require = createRequire(import.meta.url);
  * @param options - Configuration for paths and site metadata
  */
 export async function generateStaticPages(options: SSGOptions): Promise<void> {
-  const { docsDir, docsDirName, outDir, config } = options;
-  const routes = await generateRoutes(docsDir, config);
-  const siteTitle = config?.themeConfig?.title || "Boltdocs";
-  const siteDescription = config?.themeConfig?.description || "";
+  const { docsDir, docsDirName, 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");
+  const ssrModulePath = path.resolve(_dirname, '../client/ssr.js')
   if (!fs.existsSync(ssrModulePath)) {
     console.error(
-      "[boltdocs] SSR module not found at",
+      '[boltdocs] SSR module not found at',
       ssrModulePath,
-      "- Did you build the core package?",
-    );
-    return;
+      '- Did you build the core package?',
+    )
+    return
   }
-  const { render } = _require(ssrModulePath);
+
+  // Mock require so Node doesn't choke on virtual modules compiled externally
+  const Module = _require('module')
+  const originalRequire = Module.prototype.require
+  ;(Module.prototype as any).require = function (id: string, ...args: any[]) {
+    if (id === 'virtual:boltdocs-layout') {
+      return {
+        __esModule: true,
+        default: function SSG_Virtual_Layout(props: any) {
+          try {
+            const client = originalRequire.apply(this, [path.resolve(_dirname, '../client/index.js')])
+            const Comp = client.DefaultLayout || (({ children }: any) => children)
+            const React = originalRequire.apply(this, ['react'])
+            return React.createElement(Comp, props)
+          } catch (e) {
+            return props.children
+          }
+        }
+      }
+    }
+    return originalRequire.apply(this, [id, ...args])
+  }
+
+  const { render } = _require(ssrModulePath)
+
+  // Restore require after loading the module
+  ;(Module.prototype as any).require = originalRequire
 
   // Read the built index.html as template
-  const templatePath = path.join(outDir, "index.html");
+  const templatePath = path.join(outDir, 'index.html')
   if (!fs.existsSync(templatePath)) {
-    console.warn("[boltdocs] No index.html found in outDir, skipping SSG.");
-    return;
+    console.warn('[boltdocs] No index.html found in outDir, skipping SSG.')
+    return
   }
-  const template = fs.readFileSync(templatePath, "utf-8");
+  const template = fs.readFileSync(templatePath, 'utf-8')
 
   // 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;
+      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
+      const fakeModules: Record<string, any> = {}
+      fakeModules[`/${docsDirName}/${route.filePath}`] = { default: () => null } // Mock MDX component
 
       try {
         const appHtml = await render({
@@ -67,40 +93,40 @@ export async function generateStaticPages(options: SSGOptions): Promise<void> {
           docsDirName: docsDirName,
           modules: fakeModules,
           homePage: undefined, // No custom home page for now
-        });
+        })
 
         const html = replaceMetaTags(template, {
           title: escapeHtml(pageTitle),
           description: escapeHtml(pageDescription),
         })
-          .replace("<!--app-html-->", appHtml)
-          .replace(`<div id="root"></div>`, `<div id="root">${appHtml}</div>`);
+          .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 });
+        const routeDir = path.join(outDir, route.path)
+        await fs.promises.mkdir(routeDir, { recursive: true })
         await fs.promises.writeFile(
-          path.join(routeDir, "index.html"),
+          path.join(routeDir, 'index.html'),
           html,
-          "utf-8",
-        );
-      } catch (e) {
-        console.error(`[boltdocs] Error SSR rendering route ${route.path}:`, e);
+          'utf-8',
+        )
+      } catch (e: any) {
+        console.error(`[boltdocs] Error SSR rendering route ${route.path}:`, e ? e.stack || e : e)
       }
     }),
-  );
+  )
 
   // Generate sitemap.xml
   const sitemap = generateSitemap(
     routes.map((r) => r.path),
     config,
-  );
-  fs.writeFileSync(path.join(outDir, "sitemap.xml"), sitemap, "utf-8");
+  )
+  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();
+  const { flushCache } = await import('../cache')
+  await flushCache()
 }

package/src/node/ssg/meta.ts

@@ -1,4 +1,4 @@
-import { escapeHtml } from "../utils";
+import { escapeHtml } from '../utils'
 
 /**
  * Replaces placeholder or default meta tags in the HTML template with page-specific values.
@@ -11,8 +11,8 @@ export function replaceMetaTags(
   html: string,
   meta: { title: string; description: string },
 ): string {
-  const title = escapeHtml(meta.title);
-  const description = escapeHtml(meta.description);
+  const title = escapeHtml(meta.title)
+  const description = escapeHtml(meta.description)
 
   return html
     .replace(/<title>.*?<\/title>/, `<title>${title}</title>`)
@@ -29,5 +29,5 @@ export function replaceMetaTags(
     .replace(
       /(<meta name="twitter:description" content=")[^"]*(")/,
       `$1${description}$2`,
-    );
+    )
 }

package/src/node/ssg/options.ts

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

package/src/node/ssg/sitemap.ts

@@ -1,5 +1,5 @@
-import { BoltdocsConfig } from "../config";
-import { escapeXml } from "../utils";
+import type { BoltdocsConfig } from '../config'
+import { escapeXml } from '../utils'
 
 /**
  * Generates a standard XML sitemap for search engine crawlers.
@@ -12,20 +12,20 @@ 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 baseUrl = config?.siteUrl?.replace(/\/$/, '') || 'https://example.com'
+  const today = new Date().toISOString().split('T')[0]
 
-  const rootEntries = [{ url: "/", priority: "1.0", changefreq: "daily" }];
+  const rootEntries = [{ url: '/', priority: '1.0', changefreq: 'daily' }]
 
   if (config?.i18n) {
-    const defaultLocale = config.i18n.defaultLocale;
+    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",
-        });
+          priority: '1.0',
+          changefreq: 'daily',
+        })
       }
     }
   }
@@ -34,10 +34,10 @@ export function generateSitemap(
     ...rootEntries,
     ...routePaths.map((p) => ({
       url: p,
-      priority: "0.8",
-      changefreq: "weekly",
+      priority: '0.8',
+      changefreq: 'weekly',
     })),
-  ];
+  ]
 
   return `<?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
@@ -50,6 +50,6 @@ ${entries
     <priority>${e.priority}</priority>
   </url>`,
   )
-  .join("\n")}
-</urlset>`;
+  .join('\n')}
+</urlset>`
 }

package/src/node/utils.ts

@@ -1,5 +1,6 @@
-import fs from "fs";
-import matter from "gray-matter";
+import fs from 'fs'
+import matter from 'gray-matter'
+import DOMPurify from 'isomorphic-dompurify'
 
 /**
  * Normalizes a file path by replacing Windows backslashes with forward slashes.
@@ -9,7 +10,7 @@ import matter from "gray-matter";
  * @returns The normalized path using forward slashes
  */
 export function normalizePath(p: string): string {
-  return p.replace(/\\/g, "/");
+  return p.replace(/\\/g, '/')
 }
 
 /**
@@ -19,7 +20,7 @@ export function normalizePath(p: string): string {
  * @returns The name without the numeric prefix
  */
 export function stripNumberPrefix(name: string): string {
-  return name.replace(/^\d+\./, "");
+  return name.replace(/^\d+\./, '')
 }
 
 /**
@@ -29,8 +30,8 @@ export function stripNumberPrefix(name: string): string {
  * @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;
+  const match = name.match(/^(\d+)\./)
+  return match ? parseInt(match[1], 10) : undefined
 }
 
 /**
@@ -40,7 +41,7 @@ export function extractNumberPrefix(name: string): number | undefined {
  * @returns True if the file ends with .md or .mdx, false otherwise
  */
 export function isDocFile(filePath: string): boolean {
-  return /\.mdx?$/.test(filePath);
+  return /\.mdx?$/.test(filePath)
 }
 
 /**
@@ -53,9 +54,9 @@ export function isDocFile(filePath: string): boolean {
  */
 export function getFileMtime(filePath: string): number {
   try {
-    return fs.statSync(filePath).mtimeMs;
+    return fs.statSync(filePath).mtimeMs
   } catch {
-    return 0;
+    return 0
   }
 }
 
@@ -67,12 +68,12 @@ export function getFileMtime(filePath: string): number {
  * @returns An object containing the parsed metadata (`data`) and the raw markdown (`content`)
  */
 export function parseFrontmatter(filePath: string): {
-  data: Record<string, any>;
-  content: string;
+  data: Record<string, any>
+  content: string
 } {
-  const raw = fs.readFileSync(filePath, "utf-8");
-  const { data, content } = matter(raw);
-  return { data, content };
+  const raw = fs.readFileSync(filePath, 'utf-8')
+  const { data, content } = matter(raw)
+  return { data, content }
 }
 
 /**
@@ -84,11 +85,11 @@ export function parseFrontmatter(filePath: string): {
  */
 export function escapeHtml(str: string): string {
   return str
-    .replace(/&/g, "&amp;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&apos;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;");
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
 }
 
 /**
@@ -98,7 +99,7 @@ export function escapeHtml(str: string): string {
  * @returns The escaped string
  */
 export function escapeXml(str: string): string {
-  return escapeHtml(str);
+  return escapeHtml(str)
 }
 
 /**
@@ -111,29 +112,51 @@ export function escapeXml(str: string): string {
  */
 export function fileToRoutePath(relativePath: string): string {
   // Strip number prefixes from every segment
-  let cleanedPath = relativePath.split("/").map(stripNumberPrefix).join("/");
+  let cleanedPath = relativePath.split('/').map(stripNumberPrefix).join('/')
 
   // Remove trailing slash if present
-  let routePath = cleanedPath.replace(/\/$/, "");
+  let routePath = cleanedPath.replace(/\/$/, '')
 
-  routePath = routePath.replace(/\.mdx?$/, "");
+  routePath = routePath.replace(/\.mdx?$/, '')
 
   // Handle index files → directory root
-  if (routePath === "index" || routePath.endsWith("/index")) {
-    routePath = routePath.replace(/index$/, "");
+  if (routePath === 'index' || routePath.endsWith('/index')) {
+    routePath = routePath.replace(/index$/, '')
   }
 
   // Ensure leading slash
-  if (!routePath.startsWith("/")) {
-    routePath = "/" + routePath;
+  if (!routePath.startsWith('/')) {
+    routePath = '/' + routePath
   }
 
   // Remove trailing slash (except for root '/')
-  if (routePath.length > 1 && routePath.endsWith("/")) {
-    routePath = routePath.slice(0, -1);
+  if (routePath.length > 1 && routePath.endsWith('/')) {
+    routePath = routePath.slice(0, -1)
   }
 
-  return routePath;
+  return routePath
+}
+
+/**
+ * Sanitizes an HTML string using DOMPurify to prevent XSS.
+ * By default, it allows a safe subset of HTML tags.
+ *
+ * @param html - The raw HTML string
+ * @returns The sanitized HTML
+ */
+export function sanitizeHtml(html: string): string {
+  return DOMPurify.sanitize(html)
+}
+
+/**
+ * Strips all HTML tags from a string, returning only the text content.
+ * Uses DOMPurify for secure and complete tag removal.
+ *
+ * @param html - The string containing HTML tags
+ * @returns The plain text content
+ */
+export function stripHtmlTags(html: string): string {
+  return DOMPurify.sanitize(html, { ALLOWED_TAGS: [], KEEP_CONTENT: true })
 }
 
 /**
@@ -144,5 +167,5 @@ export function fileToRoutePath(relativePath: string): string {
  * @returns The capitalized string
  */
 export function capitalize(str: string): string {
-  return str.charAt(0).toUpperCase() + str.slice(1);
+  return str.charAt(0).toUpperCase() + str.slice(1)
 }

package/tsconfig.json

@@ -1,21 +1,26 @@
 {
-    "compilerOptions": {
-        "target": "ES2022",
-        "module": "ESNext",
-        "moduleResolution": "Bundler",
-        "esModuleInterop": true,
-        "strict": true,
-        "skipLibCheck": true,
-        "jsx": "react-jsx",
-        "declaration": true,
-        "outDir": "dist"
-    },
-    "include": [
-        "src"
-    ],
-    "exclude": [
-        "node_modules",
-        "dist",
-        "src/node/cli"
-    ]
-}
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "jsx": "react-jsx",
+    "declaration": true,
+    "outDir": "dist",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"],
+      "@client/*": ["src/client/*"],
+      "@node/*": ["src/node/*"],
+      "@theme/*": ["src/client/theme/*"],
+      "@components/*": ["src/client/components/*"],
+      "@integrations/*": ["src/client/integrations/*"],
+      "@hooks/*": ["src/client/hooks/*"],
+      "@primitives/*": ["src/client/components/primitives/*"]
+    }
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "src/node/cli"]
+}