boltdocs 1.10.2 → 1.11.0

package/src/node/routes/parser.ts

@@ -1,7 +1,7 @@
-import path from "path";
-import GithubSlugger from "github-slugger";
-import { BoltdocsConfig } from "../config";
-import { ParsedDocFile } from "./types";
+import path from 'path'
+import GithubSlugger from 'github-slugger'
+import type { BoltdocsConfig } from '../config'
+import type { ParsedDocFile } from './types'
 import {
   normalizePath,
   parseFrontmatter,
@@ -9,16 +9,19 @@ import {
   capitalize,
   stripNumberPrefix,
   extractNumberPrefix,
-  escapeHtml,
-} from "../utils";
+} from '../utils'
 
 /**
  * Parses a single Markdown/MDX file and extracts its metadata for routing.
  * Checks frontmatter for explicit titles, descriptions, and sidebar positions.
  *
+ * Also performs security validation to prevent path traversal and basic
+ * XSS sanitization for metadata and headings.
+ *
  * @param file - The absolute path to the file
  * @param docsDir - The root documentation directory (e.g., 'docs')
  * @param basePath - The base URL path for the routes (default: '/docs')
+ * @param config - The Boltdocs configuration for versions and i18n
  * @returns A parsed structure ready for route assembly and caching
  */
 export function parseDocFile(
@@ -28,138 +31,138 @@ export function parseDocFile(
   config?: BoltdocsConfig,
 ): ParsedDocFile {
   // Security: Prevent path traversal
-  const decodedFile = decodeURIComponent(file);
-  const absoluteFile = path.resolve(decodedFile);
-  const absoluteDocsDir = path.resolve(docsDir);
+  const decodedFile = decodeURIComponent(file)
+  const absoluteFile = path.resolve(decodedFile)
+  const absoluteDocsDir = path.resolve(docsDir)
   const relativePath = normalizePath(
     path.relative(absoluteDocsDir, absoluteFile),
-  );
+  )
 
   if (
-    relativePath.startsWith("../") ||
-    relativePath === ".." ||
-    absoluteFile.includes("\0")
+    relativePath.startsWith('../') ||
+    relativePath === '..' ||
+    absoluteFile.includes('\0')
   ) {
     throw new Error(
       `Security breach: File is outside of docs directory or contains null bytes: ${file}`,
-    );
+    )
   }
 
-  const { data, content } = parseFrontmatter(file);
-  let parts = relativePath.split("/");
+  const { data, content } = parseFrontmatter(file)
+  let parts = relativePath.split('/')
 
-  let locale: string | undefined;
-  let version: string | undefined;
+  let locale: string | undefined
+  let version: string | undefined
 
   // Level 1: Check for version
   if (config?.versions && parts.length > 0) {
-    const potentialVersion = parts[0];
+    const potentialVersion = parts[0]
     if (config.versions.versions[potentialVersion]) {
-      version = potentialVersion;
-      parts = parts.slice(1);
+      version = potentialVersion
+      parts = parts.slice(1)
     }
   }
 
   // Level 2: Check for locale
   if (config?.i18n && parts.length > 0) {
-    const potentialLocale = parts[0];
+    const potentialLocale = parts[0]
     if (config.i18n.locales[potentialLocale]) {
-      locale = potentialLocale;
-      parts = parts.slice(1);
+      locale = potentialLocale
+      parts = parts.slice(1)
     }
   }
 
   // Level 3: Check for Tab hierarchy (name)
-  let inferredTab: string | undefined;
+  let inferredTab: string | undefined
   if (parts.length > 0) {
-    const tabMatch = parts[0].match(/^\((.+)\)$/);
+    const tabMatch = parts[0].match(/^\((.+)\)$/)
     if (tabMatch) {
-      inferredTab = tabMatch[1].toLowerCase();
-      parts = parts.slice(1);
+      inferredTab = tabMatch[1].toLowerCase()
+      parts = parts.slice(1)
     }
   }
 
-  const cleanRelativePath = parts.join("/");
+  const cleanRelativePath = parts.join('/')
 
-  let cleanRoutePath: string;
+  let cleanRoutePath: string
   if (data.permalink) {
     // If a permalink is specified, ensure it starts with a slash
-    cleanRoutePath = data.permalink.startsWith("/")
+    cleanRoutePath = data.permalink.startsWith('/')
       ? data.permalink
-      : `/${data.permalink}`;
+      : `/${data.permalink}`
   } else {
-    cleanRoutePath = fileToRoutePath(cleanRelativePath || "index.md");
+    cleanRoutePath = fileToRoutePath(cleanRelativePath || 'index.md')
   }
 
-  let finalPath = basePath;
+  let finalPath = basePath
   if (version) {
-    finalPath += "/" + version;
+    finalPath += '/' + version
   }
   if (locale) {
-    finalPath += "/" + locale;
+    finalPath += '/' + locale
   }
-  finalPath += cleanRoutePath === "/" ? "" : cleanRoutePath;
+  finalPath += cleanRoutePath === '/' ? '' : cleanRoutePath
 
-  if (!finalPath || finalPath === "") finalPath = "/";
+  if (!finalPath || finalPath === '') finalPath = '/'
 
-  const rawFileName = parts[parts.length - 1];
-  const cleanFileName = stripNumberPrefix(rawFileName);
+  const rawFileName = parts[parts.length - 1]
+  const cleanFileName = stripNumberPrefix(rawFileName)
   const inferredTitle = stripNumberPrefix(
     path.basename(file, path.extname(file)),
-  );
+  )
   const sidebarPosition =
-    data.sidebarPosition ?? extractNumberPrefix(rawFileName);
+    data.sidebarPosition ?? extractNumberPrefix(rawFileName)
 
-  const rawDirName = parts.length >= 2 ? parts[0] : undefined;
-  const cleanDirName = rawDirName ? stripNumberPrefix(rawDirName) : undefined;
+  const rawDirName = parts.length >= 2 ? parts[0] : undefined
+  const cleanDirName = rawDirName ? stripNumberPrefix(rawDirName) : undefined
 
-  const isGroupIndex = parts.length >= 2 && /^index\.mdx?$/.test(cleanFileName);
+  const isGroupIndex = parts.length >= 2 && /^index\.mdx?$/.test(cleanFileName)
 
-  const headings: { level: number; text: string; id: string }[] = [];
-  const slugger = new GithubSlugger();
-  const headingsRegex = /^(#{2,4})\s+(.+)$/gm;
-  let match;
+  const headings: { level: number; text: string; id: string }[] = []
+  const slugger = new GithubSlugger()
+  const headingsRegex = /^(#{2,4})\s+(.+)$/gm
+  let match
   while ((match = headingsRegex.exec(content)) !== null) {
-    const level = match[1].length;
+    const level = match[1].length
     // Strip simple markdown formatting specifically for the plain-text search index
     const text = match[2]
-      .replace(/\[([^\]]+)\]\([^\)]+\)/g, "$1")
-      .replace(/[_*`]/g, "")
-      .trim();
-    const id = slugger.slug(text);
+      .replace(/\[([^\]]+)\]\([^\)]+\)/g, '$1')
+      .replace(/[_*`]/g, '')
+      .trim()
+    const id = slugger.slug(text)
     // Security: Sanitize heading text for XSS
-    headings.push({ level, text, id });
+    const sanitizedText = text
+      .replace(/<script\b[^>]*>([\s\S]*?)<\/script>/gim, '')
+      .replace(/<[^>]+on\w+="[^"]*"/gim, '')
+      .replace(/<img[^>]+>/gim, '')
+      .trim()
+    headings.push({ level, text: sanitizedText, id })
   }
 
-  const sanitizedTitle = data.title ? data.title : inferredTitle;
-  let sanitizedDescription = data.description
-    ? data.description
-    : "";
+  const sanitize = (str: string) =>
+    str.replace(/<script\b[^>]*>([\s\S]*?)<\/script>/gim, '').trim()
+
+  const sanitizedTitle = data.title ? sanitize(data.title) : inferredTitle
+  let sanitizedDescription = data.description ? sanitize(data.description) : ''
 
   // If no description is provided, extract a summary from the content
   if (!sanitizedDescription && content) {
-    const summary = content
-      .replace(/^#+.*$/gm, "") // Remove headers
-      .replace(/\[([^\]]+)\]\([^\)]+\)/g, "$1") // Simplify links
-      .replace(/[_*`]/g, "") // Remove formatting
-      .replace(/\n+/g, " ") // Normalize whitespace
-      .trim()
-      .slice(0, 160);
-    sanitizedDescription = summary;
+    sanitizedDescription = sanitize(
+      content
+        .replace(/^#+.*$/gm, '') // Remove headers
+        .replace(/\[([^\]]+)\]\([^\)]+\)/g, '$1') // Simplify links
+        .replace(/[_*`]/g, '') // Remove formatting
+        .replace(/\s+/g, ' ') // Normalize whitespace
+        .trim()
+        .slice(0, 160),
+    )
   }
 
-  const sanitizedBadge = data.badge ? data.badge : undefined;
-  const icon = data.icon ? String(data.icon) : undefined;
+  const sanitizedBadge = data.badge ? sanitize(data.badge) : undefined
+  const icon = data.icon ? String(data.icon) : undefined
 
   // Extract full content as plain text for search indexing
-  const plainText = content
-    .replace(/^#+.*$/gm, "") // Remove headers
-    .replace(/\[([^\]]+)\]\([^\)]+\)/g, "$1") // Simplify links
-    .replace(/<[^>]+>/g, "") // Remove HTML/JSX tags
-    .replace(/\{[^\}]+\}/g, "") // Remove JS expressions/curly braces
-    .replace(/[_*`]/g, "") // Remove formatting
-    .replace(/\n+/g, " ") // Normalize whitespace
-    .trim();
+  const plainText = parseContentToPlainText(content)
 
   return {
     route: {
@@ -183,10 +186,10 @@ export function parseDocFile(
     inferredTab,
     groupMeta: isGroupIndex
       ? {
-          title: 
+          title:
             data.groupTitle ||
-              data.title ||
-              (cleanDirName ? capitalize(cleanDirName) : ""),
+            data.title ||
+            (cleanDirName ? capitalize(cleanDirName) : ''),
           position:
             data.groupPosition ??
             data.sidebarPosition ??
@@ -197,5 +200,27 @@ export function parseDocFile(
     inferredGroupPosition: rawDirName
       ? extractNumberPrefix(rawDirName)
       : undefined,
-  };
+  }
+}
+
+/**
+ * Sanitizes a string by removing script tags for basic XSS protection.
+ */
+function sanitize(str: string): string {
+  return str.replace(/<script\b[^>]*>([\s\S]*?)<\/script>/gim, '').trim()
+}
+
+/**
+ * Converts markdown content to plain text for search indexing.
+ * Strips headers, links, tags, and formatting.
+ */
+function parseContentToPlainText(content: string): string {
+  return content
+    .replace(/^#+.*$/gm, '') // Remove headers
+    .replace(/\[([^\]]+)\]\([^\)]+\)/g, '$1') // Simplify links
+    .replace(/<[^>]+>/g, '') // Remove HTML/JSX tags
+    .replace(/\{[^\}]+\}/g, '') // Remove JS expressions/curly braces
+    .replace(/[_*`]/g, '') // Remove formatting
+    .replace(/\s+/g, ' ') // Normalize whitespace
+    .trim()
 }

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,40 @@ 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);
+  const { render } = _require(ssrModulePath)
 
   // 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[route.componentPath] = { default: () => {} } // Mock MDX component
 
       try {
         const appHtml = await render({
@@ -67,40 +67,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",
-        );
+          'utf-8',
+        )
       } catch (e) {
-        console.error(`[boltdocs] Error SSR rendering route ${route.path}:`, 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");
+  )
+  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
 }