boltdocs 2.5.5 → 2.6.0

package/src/node/security/headers.ts

@@ -1,27 +0,0 @@
-/**
- * Standard Security Headers for hardened web applications.
- * Recommended by OWASP and industry best practices to prevent common web attacks.
- * 
- * These can be applied as middleware in HTTP servers or as metadata in SSG deployments.
- */
-export const SECURITY_HEADERS = {
-  /** Prevents MIME type sniffing by the browser. */
-  'X-Content-Type-Options': 'nosniff',
-  
-  /** Prevents the page from being embedded in iframes (anti-clickjacking). */
-  'X-Frame-Options': 'DENY',
-  
-  /** Enables XSS filtering in modern browsers (legacy support). */
-  'X-XSS-Protection': '1; mode=block',
-  
-  /** Controls how much referrer information is sent with requests. */
-  'Referrer-Policy': 'strict-origin-when-cross-origin',
-  
-  /** Restricts access to sensitive browser features (camera, mic, geo). */
-  'Permissions-Policy': 'camera=(), microphone=(), geolocation=()',
-  
-  /** Enforces HTTPS for the domain and all subdomains for 1 year. */
-  'Strict-Transport-Security': 'max-age=31536000; includeSubDomains',
-} as const;
-
-export type SecurityHeaderKey = keyof typeof SECURITY_HEADERS;

package/src/node/ssg/index.ts

@@ -1,205 +0,0 @@
-import fs from 'fs'
-import path from 'path'
-import { generateRoutes } from '../routes'
-import { escapeHtml, getTranslated } from '../utils'
-import { fileURLToPath } from 'url'
-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 }
-
-// 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, docsDirName, outDir, config } = options
-  const routes = await generateRoutes(docsDir, config)
-
-  // Detect external routes to include in SSG
-  const externalModulePath = ['tsx', 'ts', 'jsx', 'js']
-    .map((ext) => path.resolve(docsDir, `pages-external/index.${ext}`))
-    .find((p) => fs.existsSync(p))
-
-  if (externalModulePath) {
-    try {
-      // We use a simple way to get the keys of the 'pages' export
-      // Since we can't easily execute TSX in this context without a bundler,
-      // we'll at least try to generate placeholder pages for them
-      // OR we can try to use 'esbuild' to get the exports
-      const content = fs.readFileSync(externalModulePath, 'utf-8')
-      const pagesMatch = content.match(/pages\s*:\s*{([^}]+)}/s)
-      if (pagesMatch) {
-        const paths = pagesMatch[1]
-          .split(',')
-          .map((line) => line.split(':')[0].trim().replace(/['"]/g, ''))
-          .filter((p) => p && p.startsWith('/'))
-
-        for (const p of paths) {
-          if (!routes.some((r) => r.path === p)) {
-            routes.push({
-              path: p,
-              title: p.slice(1).charAt(0).toUpperCase() + p.slice(2),
-              filePath: '',
-              componentPath: '',
-              _content: '',
-            } as any)
-          }
-        }
-      }
-
-      // Always include home page if it might be custom
-      if (content.includes('homePage') && !routes.some((r) => r.path === '/')) {
-        routes.push({
-          path: '/',
-          title: 'Home',
-          filePath: '',
-          componentPath: '',
-          _content: '',
-        } as any)
-      }
-    } catch (e) {
-      console.warn('[boltdocs] Failed to parse external routes for SSG:', e)
-    }
-  }
-
-  // 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
-  }
-
-  // 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.startsWith('virtual:boltdocs-')) {
-      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
-            }
-          },
-        }
-      }
-
-      if (id === 'virtual:boltdocs-mdx-components') {
-        return { __esModule: true, default: {} }
-      }
-
-      if (id === 'virtual:boltdocs-config') {
-        return { __esModule: true, default: config }
-      }
-
-      // Safe fallback for other virtual modules
-      return { __esModule: true, default: id.includes('routes') ? [] : {} }
-    }
-    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)) {
-    console.warn('[boltdocs] No index.html found in outDir, skipping SSG.')
-    return
-  }
-  const template = fs.readFileSync(templatePath, 'utf-8')
-
-  // Generate an HTML file for each route concurrently
-  await Promise.all(
-    routes.map(async (route) => {
-      const siteTitle =
-        getTranslated(config?.theme?.title, route.locale) || 'Boltdocs'
-      const siteDescription =
-        getTranslated(config?.theme?.description, route.locale) || ''
-      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[`/${docsDirName}/${route.filePath}`] = { default: () => null } // Mock MDX component
-
-      try {
-        const appHtml = await render({
-          path: route.path,
-          routes: routes,
-          config: config || {},
-          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>`)
-
-        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: 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')
-
-  // 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 + robots.txt`,
-  )
-
-  // Ensure all cache operations (like index persistence) are finished
-  const { flushCache } = await import('../cache')
-  await flushCache()
-}

package/src/node/ssg/meta.ts

@@ -1,33 +0,0 @@
-import { escapeHtml } from '../utils'
-
-/**
- * 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 {
-  const title = escapeHtml(meta.title)
-  const description = escapeHtml(meta.description)
-
-  return html
-    .replace(/<title>.*?<\/title>/, `<title>${title}</title>`)
-    .replace(
-      /(<meta name="description" content=")[^"]*(")/,
-      `$1${description}$2`,
-    )
-    .replace(/(<meta property="og:title" content=")[^"]*(")/, `$1${title}$2`)
-    .replace(
-      /(<meta property="og:description" content=")[^"]*(")/,
-      `$1${description}$2`,
-    )
-    .replace(/(<meta name="twitter:title" content=")[^"]*(")/, `$1${title}$2`)
-    .replace(
-      /(<meta name="twitter:description" content=")[^"]*(")/,
-      `$1${description}$2`,
-    )
-}

package/src/node/ssg/options.ts

@@ -1,15 +0,0 @@
-import type { BoltdocsConfig } from '../config'
-
-/**
- * Options for the Static Site Generation process.
- */
-export interface SSGOptions {
-  /** The root directory containing markdown documentation files */
-  docsDir: string
-  /** The name of the documentation directory (e.g. 'docs') */
-  docsDirName: 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/robots.ts

@@ -1,53 +0,0 @@
-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/ssg/sitemap.ts

@@ -1,55 +0,0 @@
-import type { BoltdocsConfig } from '../config'
-import { escapeXml } from '../utils'
-
-/**
- * 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>${escapeXml(baseUrl)}${escapeXml(e.url)}</loc>
-    <lastmod>${today}</lastmod>
-    <changefreq>${e.changefreq}</changefreq>
-    <priority>${e.priority}</priority>
-  </url>`,
-  )
-  .join('\n')}
-</urlset>`
-}