boltdocs 1.11.0 → 2.1.0

package/src/node/config.ts

@@ -63,6 +63,15 @@ export interface BoltdocsThemeConfig {
   version?: string
   /** The GitHub repository in the format 'owner/repo' to fetch and display star count. */
   githubRepo?: string
+  /**
+   * URL path to the site favicon.
+   * If not specified, the logo will be used if available.
+   */
+  favicon?: string
+  /**
+   * The Open Graph image URL to display when the site is shared on social media.
+   */
+  ogImage?: string
   /** Whether to show the 'Powered by LiteDocs' badge in the sidebar (default: true) */
   poweredBy?: boolean
   /**
@@ -85,6 +94,24 @@ export interface BoltdocsThemeConfig {
   copyMarkdown?: boolean | { text?: string; icon?: string }
 }
 
+/**
+ * Configuration for the robots.txt file.
+ */
+export type BoltdocsRobotsConfig =
+  | string
+  | {
+      /** User-agent rules */
+      rules?: Array<{
+        userAgent: string
+        /** Paths allowed to be crawled */
+        allow?: string | string[]
+        /** Paths disallowed to be crawled */
+        disallow?: string | string[]
+      }>
+      /** Sitemaps to include in the robots.txt */
+      sitemaps?: string[]
+    }
+
 /**
  * Configuration for internationalization (i18n).
  */
@@ -142,10 +169,12 @@ export interface BoltdocsIntegrationsConfig {
 export interface BoltdocsConfig {
   /** The base URL of the site, used for generating the sitemap */
   siteUrl?: string
-  /** Configuration pertaining to the UI and appearance */
-  themeConfig?: BoltdocsThemeConfig
   /** The root directory containing markdown documentation files (default: 'docs') */
   docsDir?: string
+  /** Path to a custom HomePage component */
+  homePage?: string
+  /** Configuration pertaining to the UI and appearance */
+  theme?: BoltdocsThemeConfig
   /** Configuration for internationalization */
   i18n?: BoltdocsI18nConfig
   /** Configuration for documentation versioning */
@@ -156,6 +185,16 @@ export interface BoltdocsConfig {
   external?: Record<string, string>
   /** External integrations configuration */
   integrations?: BoltdocsIntegrationsConfig
+  /** Configuration for the robots.txt file */
+  robots?: BoltdocsRobotsConfig
+  /** Low-level Vite configuration overrides */
+  vite?: import('vite').InlineConfig
+  /** @deprecated Use theme instead */
+  themeConfig?: BoltdocsThemeConfig
+}
+
+export function defineConfig(config: BoltdocsConfig): BoltdocsConfig {
+  return config
 }
 
 export const CONFIG_FILES = [
@@ -169,7 +208,10 @@ export const CONFIG_FILES = [
  */
 interface RawUserConfig
   extends Partial<BoltdocsConfig>,
-    Partial<BoltdocsThemeConfig> {}
+    Partial<BoltdocsThemeConfig> {
+  favicon?: string
+  ogImage?: string
+}
 
 /**
  * Loads user's configuration file (e.g., `boltdocs.config.js` or `boltdocs.config.ts`) if it exists,
@@ -187,7 +229,7 @@ export async function resolveConfig(
 
   const defaults: BoltdocsConfig = {
     docsDir: path.resolve(docsDir),
-    themeConfig: {
+    theme: {
       title: 'Boltdocs',
       description: 'A Vite documentation framework',
       navbar: [
@@ -230,18 +272,28 @@ export async function resolveConfig(
     title: userConfig.title,
     description: userConfig.description,
     logo: userConfig.logo,
+    favicon: userConfig.favicon,
+    ogImage: userConfig.ogImage,
     navbar: userConfig.navbar,
     sidebar: userConfig.sidebar,
     socialLinks: userConfig.socialLinks,
     footer: userConfig.footer,
     githubRepo: userConfig.githubRepo,
     tabs: userConfig.tabs,
+    codeTheme: userConfig.codeTheme,
+    copyMarkdown: userConfig.copyMarkdown,
+    breadcrumbs: userConfig.breadcrumbs,
+    poweredBy: userConfig.poweredBy,
+    communityHelp: userConfig.communityHelp,
+    version: userConfig.version,
+    editLink: userConfig.editLink
   }
 
-  // User can define properties at top level or inside themeConfig
+  // User can define properties at top level or inside themeConfig/theme
   const userThemeConfig: BoltdocsThemeConfig = {
     ...themeConfigFromTop,
     ...(userConfig.themeConfig || {}),
+    ...(userConfig.theme || {}),
   }
 
   // Clean undefined properties
@@ -263,13 +315,10 @@ export async function resolveConfig(
 
   return {
     docsDir: path.resolve(docsDir),
-    themeConfig: {
-      ...defaults.themeConfig,
+    homePage: userConfig.homePage,
+    theme: {
+      ...defaults.theme,
       ...cleanThemeConfig,
-      codeTheme:
-        cleanThemeConfig.codeTheme ||
-        (userConfig.themeConfig || userConfig).codeTheme ||
-        defaults.themeConfig?.codeTheme,
     },
     i18n: userConfig.i18n,
     versions: userConfig.versions,
@@ -277,5 +326,8 @@ export async function resolveConfig(
     plugins: userConfig.plugins || [],
     external: userConfig.external,
     integrations: userConfig.integrations,
+    robots: userConfig.robots,
+    vite: userConfig.vite,
   }
 }
+

package/src/node/index.ts

@@ -1,9 +1,11 @@
-import type { Plugin } from 'vite'
+import type { Plugin, InlineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
 import { boltdocsPlugin } from './plugin/index'
 import { boltdocsMdxPlugin } from './mdx'
 import type { BoltdocsPluginOptions } from './plugin/index'
 
-import { resolveConfig } from './config'
+import { resolveConfig, type BoltdocsConfig } from './config'
 
 export default async function boltdocs(
   options?: BoltdocsPluginOptions,
@@ -11,7 +13,40 @@ export default async function boltdocs(
   const docsDir = options?.docsDir || 'docs'
   const config = await resolveConfig(docsDir)
 
-  return [...boltdocsPlugin(options, config), boltdocsMdxPlugin(config)]
+  // Merge options with config
+  const mergedOptions: BoltdocsPluginOptions = {
+    ...options,
+    homePage: options?.homePage || config.homePage,
+  }
+
+  return [...boltdocsPlugin(mergedOptions, config), boltdocsMdxPlugin(config)]
+}
+
+/**
+ * Generates the complete Vite configuration for a Boltdocs project.
+ * This is used by the Boltdocs CLI to run Vite without a user-defined vite.config.ts.
+ */
+export async function createViteConfig(
+  root: string,
+  mode: 'development' | 'production' = 'development',
+): Promise<InlineConfig> {
+  const config = await resolveConfig('docs', root)
+
+  const viteConfig: InlineConfig = {
+    root,
+    mode,
+    plugins: [
+      react(),
+      tailwindcss(),
+      await boltdocs({
+        docsDir: config.docsDir,
+        homePage: config.homePage,
+      }),
+    ],
+    ...config.vite,
+  }
+
+  return viteConfig
 }
 
 export type { BoltdocsPluginOptions }
@@ -19,3 +54,4 @@ export { generateStaticPages } from './ssg'
 export type { SSGOptions } from './ssg'
 export type { RouteMeta } from './routes'
 export type { BoltdocsConfig, BoltdocsThemeConfig } from './config'
+export { resolveConfig, defineConfig } from './config'

package/src/node/plugin/entry.ts

@@ -2,6 +2,7 @@ import { normalizePath } from '../utils'
 import type { BoltdocsConfig } from '../config'
 import type { BoltdocsPluginOptions } from './types'
 import path from 'path'
+import fs from 'fs'
 
 /**
  * Generates the raw source code for the virtual entry file (`\0virtual:boltdocs-entry`).
@@ -18,6 +19,11 @@ export function generateEntryCode(
   const homeImport = options.homePage
     ? `import HomePage from '${normalizePath(options.homePage)}';`
     : ''
+  
+  // Auto-import index.css if it exists
+  const cssPath = path.resolve(process.cwd(), 'index.css')
+  const cssImport = fs.existsSync(cssPath) ? "import './index.css';" : ''
+
   const homeOption = options.homePage ? 'homePage: HomePage,' : ''
   const pluginComponents =
     config?.plugins?.flatMap((p) => Object.entries(p.components || {})) || []
@@ -54,6 +60,7 @@ import { createBoltdocsApp as _createApp } from 'boltdocs/client';
 import _routes from 'virtual:boltdocs-routes';
 import _config from 'virtual:boltdocs-config';
 import _user_mdx_components from 'virtual:boltdocs-mdx-components';
+${cssImport}
 ${homeImport}
 ${componentImports}
 ${externalImports}

package/src/node/plugin/html.ts

@@ -1,27 +1,61 @@
 import type { BoltdocsConfig } from '../config'
 
+/**
+ * Provides a default HTML template if none is found in the project root.
+ */
+export function getHtmlTemplate(config: BoltdocsConfig): string {
+  const title = config.theme?.title || config.themeConfig?.title || 'Boltdocs'
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>${title}</title>
+</head>
+<body>
+  <div id="root"></div>
+</body>
+</html>`
+}
+
 /**
  * Injects OpenGraph, Twitter, and generic SEO meta tags into the final HTML output.
  * Also ensures the virtual entry file is injected if it's missing (e.g., standard Vite index.html).
  *
- * @param html - The original HTML string
- * @param config - The resolved Boltdocs configuration containing site metadata
- * @returns The modified HTML string with injected tags
+ * @param html - {string} The original HTML string
+ * @param config - {BoltdocsConfig} The resolved Boltdocs configuration containing site metadata
+ * @returns {string} The modified HTML string with injected tags
  */
 export function injectHtmlMeta(html: string, config: BoltdocsConfig): string {
-  const title = config.themeConfig?.title || 'Boltdocs'
-  const description = config.themeConfig?.description || ''
+  const theme = config.theme || config.themeConfig
+  const title = theme?.title || 'Boltdocs'
+  const description = theme?.description || ''
+
+  // Determine favicon
+  let favicon = theme?.favicon
+  if (!favicon && theme?.logo) {
+    if (typeof theme.logo === 'string') {
+      favicon = theme.logo
+    } else {
+      favicon = theme.logo.light || theme.logo.dark
+    }
+  }
 
   const seoTags = [
+    favicon ? `<link rel="icon" href="${favicon}">` : '',
     `<meta name="description" content="${description}">`,
     `<meta property="og:title" content="${title}">`,
     `<meta property="og:description" content="${description}">`,
+    theme?.ogImage ? `<meta property="og:image" content="${theme.ogImage}">` : '',
     `<meta property="og:type" content="website">`,
-    `<meta name="twitter:card" content="summary">`,
+    `<meta name="twitter:card" content="summary_large_image">`,
     `<meta name="twitter:title" content="${title}">`,
     `<meta name="twitter:description" content="${description}">`,
+    theme?.ogImage ? `<meta name="twitter:image" content="${theme.ogImage}">` : '',
     `<meta name="generator" content="Boltdocs">`,
-  ].join('\n    ')
+  ]
+    .filter(Boolean)
+    .join('\n    ')
 
   const themeScript = `
     <script>
@@ -41,10 +75,16 @@ export function injectHtmlMeta(html: string, config: BoltdocsConfig): string {
     </script>
   `
 
-  html = html.replace(/<title>.*?<\/title>/, `<title>${title}</title>`)
+  // Use regex to replace title or inject it if missing
+  if (html.includes('<title>')) {
+    html = html.replace(/<title>.*?<\/title>/, `<title>${title}</title>`)
+  } else {
+    html = html.replace('</head>', `  <title>${title}</title>\n  </head>`)
+  }
+
   html = html.replace('</head>', `    ${seoTags}\n${themeScript}  </head>`)
 
-  if (!html.includes('src/main')) {
+  if (!html.includes('src/main') && !html.includes('virtual:boltdocs-entry')) {
     html = html.replace(
       '</body>',
       '  <script type="module">import "virtual:boltdocs-entry";</script>\n  </body>',

package/src/node/plugin/index.ts

@@ -5,12 +5,13 @@ import { resolveConfig, type BoltdocsConfig, CONFIG_FILES } from '../config'
 import { generateStaticPages } from '../ssg'
 import { normalizePath, isDocFile } from '../utils'
 import path from 'path'
-
 import type { BoltdocsPluginOptions } from './types'
 import { generateEntryCode } from './entry'
-import { injectHtmlMeta } from './html'
+import { injectHtmlMeta, getHtmlTemplate } from './html'
+import { generateRobotsTxt } from '../ssg/robots'
 import fs from 'fs'
 
+
 export * from './types'
 
 /**
@@ -63,7 +64,44 @@ export function boltdocsPlugin(
       },
 
       configureServer(server) {
-        // Explicitly watch config files and mdx-components to trigger server restarts or module invalidations
+        // Serve robots.txt from config
+        server.middlewares.use((req, res, next) => {
+          if (req.url === '/robots.txt') {
+            const robots = generateRobotsTxt(config)
+            res.statusCode = 200
+            res.setHeader('Content-Type', 'text/plain')
+            res.end(robots)
+            return
+          }
+          next()
+        })
+
+        // Serve default HTML if index.html is missing
+        server.middlewares.use(async (req, res, next) => {
+          const url = req.url?.split('?')[0] || '/'
+          const accept = req.headers.accept || ''
+
+          if (
+            accept.includes('text/html') &&
+            !url.includes('.') // Simple check for assets
+          ) {
+            const indexPath = path.resolve(process.cwd(), 'index.html')
+            if (!fs.existsSync(indexPath)) {
+              let html = getHtmlTemplate(config)
+              html = injectHtmlMeta(html, config)
+              html = await server.transformIndexHtml(req.url || '/', html)
+              res.statusCode = 200
+              res.setHeader('Content-Type', 'text/html')
+              res.end(html)
+              return
+            }
+          }
+
+          next()
+        })
+
+        // Explicitly watch config files...
+
         const configPaths = CONFIG_FILES.map((c) =>
           path.resolve(process.cwd(), c),
         )
@@ -172,6 +210,7 @@ export function boltdocsPlugin(
         }
         if (id === '\0virtual:boltdocs-config') {
           const clientConfig = {
+            theme: config?.theme,
             themeConfig: config?.themeConfig,
             integrations: config?.integrations,
             i18n: config?.i18n,
@@ -262,7 +301,6 @@ export default DefaultLayout;`
         plugins: [
           {
             name: 'preset-default',
-            params: { overrides: { removeViewBox: false } },
           },
         ] as any,
       },

package/src/node/routes/parser.ts

@@ -9,6 +9,8 @@ import {
   capitalize,
   stripNumberPrefix,
   extractNumberPrefix,
+  sanitizeHtml,
+  stripHtmlTags,
 } from '../utils'
 
 /**
@@ -118,47 +120,47 @@ export function parseDocFile(
 
   const isGroupIndex = parts.length >= 2 && /^index\.mdx?$/.test(cleanFileName)
 
-  const headings: { level: number; text: string; id: string }[] = []
   const slugger = new GithubSlugger()
+  const headings: { level: number; text: string; id: string }[] = []
   const headingsRegex = /^(#{2,4})\s+(.+)$/gm
+
   let match
   while ((match = headingsRegex.exec(content)) !== null) {
     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)
-    // Security: Sanitize heading text for XSS
-    const sanitizedText = text
-      .replace(/<script\b[^>]*>([\s\S]*?)<\/script>/gim, '')
-      .replace(/<[^>]+on\w+="[^"]*"/gim, '')
-      .replace(/<img[^>]+>/gim, '')
+    const rawText = match[2]
+      .replace(/\[([^\]]+)\]\([^\)]+\)/g, '$1') // Strip markdown links
+      .replace(/[_*`]/g, '') // Strip markdown formatting
       .trim()
+
+    const sanitizedText = sanitizeHtml(rawText).trim()
+    const id = slugger.slug(sanitizedText)
+
     headings.push({ level, text: sanitizedText, id })
   }
 
-  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) : ''
+  const sanitizedTitle = data.title
+    ? sanitizeHtml(String(data.title))
+    : inferredTitle
+  let sanitizedDescription = data.description
+    ? sanitizeHtml(String(data.description))
+    : ''
 
   // If no description is provided, extract a summary from the content
   if (!sanitizedDescription && content) {
-    sanitizedDescription = sanitize(
+    const plainExcerpt = stripHtmlTags(
       content
         .replace(/^#+.*$/gm, '') // Remove headers
         .replace(/\[([^\]]+)\]\([^\)]+\)/g, '$1') // Simplify links
         .replace(/[_*`]/g, '') // Remove formatting
-        .replace(/\s+/g, ' ') // Normalize whitespace
-        .trim()
-        .slice(0, 160),
+        .replace(/\s+/g, ' '), // Normalize whitespace
     )
+      .trim()
+      .slice(0, 160)
+
+    sanitizedDescription = plainExcerpt
   }
 
-  const sanitizedBadge = data.badge ? sanitize(data.badge) : undefined
+  const sanitizedBadge = data.badge ? sanitizeHtml(String(data.badge)) : undefined
   const icon = data.icon ? String(data.icon) : undefined
 
   // Extract full content as plain text for search indexing
@@ -203,24 +205,17 @@ export function parseDocFile(
   }
 }
 
-/**
- * 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
+  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(/\s+/g, ' ') // Normalize whitespace
-    .trim()
+
+  return stripHtmlTags(plainText).trim()
 }

package/src/node/ssg/index.ts

@@ -8,6 +8,7 @@ import { createRequire } from 'module'
 import type { SSGOptions } from './options'
 import { replaceMetaTags } from './meta'
 import { generateSitemap } from './sitemap'
+import { generateRobotsTxt } from './robots'
 
 // Re-export options for consumers
 export type { SSGOptions }
@@ -39,8 +40,34 @@ export async function generateStaticPages(options: SSGOptions): Promise<void> {
     )
     return
   }
+
+  // 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')
   if (!fs.existsSync(templatePath)) {
@@ -57,7 +84,7 @@ export async function generateStaticPages(options: SSGOptions): Promise<void> {
 
       // 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
+      fakeModules[`/${docsDirName}/${route.filePath}`] = { default: () => null } // Mock MDX component
 
       try {
         const appHtml = await render({
@@ -83,8 +110,8 @@ export async function generateStaticPages(options: SSGOptions): Promise<void> {
           html,
           'utf-8',
         )
-      } catch (e) {
-        console.error(`[boltdocs] Error SSR rendering route ${route.path}:`, e)
+      } catch (e: any) {
+        console.error(`[boltdocs] Error SSR rendering route ${route.path}:`, e ? e.stack || e : e)
       }
     }),
   )
@@ -96,8 +123,12 @@ export async function generateStaticPages(options: SSGOptions): Promise<void> {
   )
   fs.writeFileSync(path.join(outDir, 'sitemap.xml'), sitemap, 'utf-8')
 
+  // Generate robots.txt
+  const robots = generateRobotsTxt(config!)
+  fs.writeFileSync(path.join(outDir, 'robots.txt'), robots, 'utf-8')
+
   console.log(
-    `[boltdocs] Generated ${routes.length} static pages + sitemap.xml`,
+    `[boltdocs] Generated ${routes.length} static pages + sitemap.xml + robots.txt`,
   )
 
   // Ensure all cache operations (like index persistence) are finished

package/src/node/ssg/robots.ts

@@ -0,0 +1,50 @@
+import type { BoltdocsConfig } from '../config'
+
+/**
+ * Generates the content for a robots.txt file based on the Boltdocs configuration.
+ *
+ * @param config - The resolved Boltdocs configuration
+ * @returns The formatted robots.txt string
+ */
+export function generateRobotsTxt(config: BoltdocsConfig): string {
+  if (typeof config.robots === 'string') {
+    return config.robots
+  }
+
+  const siteUrl = config.siteUrl?.replace(/\/$/, '') || ''
+  const robots = config.robots || {}
+  const rules = (robots as any).rules || [
+    {
+      userAgent: '*',
+      allow: '/',
+    },
+  ]
+  const sitemaps = (robots as any).sitemaps || (siteUrl ? [`${siteUrl}/sitemap.xml`] : [])
+
+  let content = ''
+
+  for (const rule of rules) {
+    content += `User-agent: ${rule.userAgent}\n`
+    
+    if (rule.disallow) {
+      const disallows = Array.isArray(rule.disallow) ? rule.disallow : [rule.disallow]
+      for (const d of disallows) {
+        content += `Disallow: ${d}\n`
+      }
+    }
+    
+    if (rule.allow) {
+      const allows = Array.isArray(rule.allow) ? rule.allow : [rule.allow]
+      for (const a of allows) {
+        content += `Allow: ${a}\n`
+      }
+    }
+    content += '\n'
+  }
+
+  for (const sitemap of sitemaps) {
+    content += `Sitemap: ${sitemap}\n`
+  }
+
+  return content.trim()
+}

package/src/node/utils.ts

@@ -1,5 +1,6 @@
 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.
@@ -136,6 +137,28 @@ export function fileToRoutePath(relativePath: string): string {
   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 })
+}
+
 /**
  * Capitalizes the first letter of a given string.
  * Used primarily for generating default group titles.