boltdocs 2.5.4 → 2.5.6

package/src/node/config.ts

@@ -1,382 +0,0 @@
-import path from 'path'
-import fs from 'fs'
-import { loadConfigFromFile, type Plugin as VitePlugin } from 'vite'
-import { BoltdocsConfigSchema } from './schema/config'
-import { ValidationError } from './errors'
-import type {
-  PluginLifecycleHooks,
-  PluginPermission,
-} from './plugins/plugin-types'
-
-/**
- * Represents a single social link in the configuration.
- */
-export interface BoltdocsSocialLink {
-  /** Identifier for the icon (e.g., 'github') */
-  icon: 'discord' | 'x' | 'github' | 'bluesky' | string
-  /** The URL the social link points to */
-  link: string
-}
-
-/**
- * Configuration for the site footer.
- */
-export interface BoltdocsFooterConfig {
-  /** Text to display in the footer (HTML is supported) */
-  text?: string
-}
-
-/**
- * Theme-specific configuration options governing the appearance and navigation of the site.
- */
-export interface BoltdocsThemeConfig {
-  /** The global title of the documentation site (can be translated) */
-  title?: string | Record<string, string>
-  /** The global description of the site (can be translated) */
-  description?: string | Record<string, string>
-  /** URL path to the site logo or an object for light/dark versions */
-  logo?:
-    | string
-    | {
-        dark: string
-        light: string
-        alt?: string
-        width?: number
-        height?: number
-      }
-  /** Items to display in the top navigation bar */
-  navbar?: Array<{
-    /** Text to display (can be a string or a map of translations) */
-    label: string | Record<string, string>
-    /** URL path or external link */
-    href: string
-  }>
-  /** Items to display in the sidebar, organized optionally by group URLs */
-  sidebar?: Record<string, Array<{ text: string; link: string }>>
-  /** Social links to display in the navigation bar */
-  socialLinks?: BoltdocsSocialLink[]
-  /** Site footer configuration */
-  footer?: BoltdocsFooterConfig
-  /** Whether to show breadcrumbs navigation (default: true) */
-  breadcrumbs?: boolean
-  /** URL template for 'Edit this page'. Use :path as a placeholder. */
-  editLink?: string
-  /** URL for the 'Community help' link. */
-  communityHelp?: string
-  /** The current version of the project (e.g., 'v2.8.9'). Displayed in the Navbar. */
-  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
-  /**
-   * Top-level tabs for organizing documentation groups.
-   * Tab discovery uses the (tab-id) directory syntax.
-   */
-  tabs?: Array<{
-    id: string
-    /** Text to display (can be a string or a map of translations) */
-    text: string | Record<string, string>
-    icon?: string
-  }>
-  /**
-   * The syntax highlighting theme for code blocks.
-   * Supports any Shiki theme name (e.g., 'github-dark', 'one-dark-pro', 'aurora-x').
-   * Can also be an object for multiple themes (e.g., { light: 'github-light', dark: 'github-dark' }).
-   * Default: { light: 'github-light', dark: 'one-dark-pro' }
-   */
-  codeTheme?: string | { light: string; dark: string }
-  /**
-   * Configuration for the 'Copy Markdown' button.
-   * Can be a boolean or an object with text and icon.
-   * Default: true
-   */
-  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 a specific locale.
- */
-export interface BoltdocsLocaleConfig {
-  /** The display name of the locale */
-  label?: string
-  /** The text direction (ltr or rtl) */
-  direction?: 'ltr' | 'rtl'
-  /** The HTML lang attribute value (e.g., 'en-US') */
-  htmlLang?: string
-  /** The calendar system to use (e.g., 'gregory') */
-  calendar?: string
-}
-
-/**
- * Configuration for internationalization (i18n).
- */
-export interface BoltdocsI18nConfig {
-  /** The default locale (e.g., 'en') */
-  defaultLocale: string
-  /** Available locales and their basic display names (e.g., { en: 'English', es: 'Español' }) */
-  locales: Record<string, string>
-  /** Detailed configuration for each locale */
-  localeConfigs?: Record<string, BoltdocsLocaleConfig>
-}
-
-/**
- * Configuration for a specific documentation version.
- */
-export interface BoltdocsVersionConfig {
-  /** The display name of the version (e.g., 'v2.0') */
-  label: string
-  /** The URL path prefix for the version (e.g., '2.0') */
-  path: string
-}
-
-/**
- * Configuration for documentation versioning.
- */
-export interface BoltdocsVersionsConfig {
-  /** The default version path (e.g., 'v2') */
-  defaultVersion: string
-  /**
-   * Optional prefix for all version paths (e.g., 'v').
-   * If set to 'v', version '1.1' will be available at '/docs/v1.1'.
-   */
-  prefix?: string
-  /** Available versions configurations */
-  versions: BoltdocsVersionConfig[]
-}
-
-/**
- * Defines a Boltdocs plugin that can extend the build process and client-side functionality.
- */
-export interface BoltdocsPlugin {
-  /** A unique name for the plugin */
-  name: string
-  /** Whether to run this plugin before or after default ones (optional) */
-  enforce?: 'pre' | 'post'
-  /** Version of the plugin (optional) */
-  version?: string
-  /** Minimum compatible Boltdocs version (optional, semver range) */
-  boltdocsVersion?: string
-  /** List of permissions this plugin requires to operate */
-  permissions?: PluginPermission[]
-  /** Optional remark plugins to add to the MDX pipeline */
-  remarkPlugins?: unknown[]
-  /** Optional rehype plugins to add to the MDX pipeline */
-  rehypePlugins?: unknown[]
-  /** Optional Vite plugins to inject into the build process */
-  vitePlugins?: VitePlugin[]
-  /** Optional custom React components to register in MDX. Map of Name -> Module Path. */
-  components?: Record<string, string>
-  /** Implementation of lifecycle hooks */
-  hooks?: PluginLifecycleHooks
-}
-
-/**
- * Configuration for security-related settings.
- */
-export interface BoltdocsSecurityConfig {
-  /** Map of standard security headers to override or supplement defaults */
-  headers?: Record<string, string>
-  /** Whether to enable Content Security Policy (CSP) generation (default: false) */
-  enableCSP?: boolean
-  /** Additional custom headers to inject into responses */
-  customHeaders?: Record<string, string>
-}
-
-/**
- * The root configuration object for Boltdocs.
- */
-export interface BoltdocsConfig {
-  /** The base URL of the site, used for generating the sitemap */
-  siteUrl?: string
-  /** 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 */
-  versions?: BoltdocsVersionsConfig
-  /** Custom plugins for extending functionality */
-  plugins?: BoltdocsPlugin[]
-  /** Configuration for the robots.txt file */
-  robots?: BoltdocsRobotsConfig
-  /** Security-related settings and headers */
-  security?: BoltdocsSecurityConfig
-  /** Low-level Vite configuration overrides */
-  vite?: import('vite').InlineConfig
-}
-
-export function defineConfig(config: BoltdocsConfig): BoltdocsConfig {
-  return config
-}
-
-export const CONFIG_FILES = [
-  'boltdocs.config.js',
-  'boltdocs.config.mjs',
-  'boltdocs.config.ts',
-]
-
-/**
- * Small helper to handle partial config objects from user input.
- */
-interface RawUserConfig
-  extends Partial<BoltdocsConfig>,
-    Partial<BoltdocsThemeConfig> {
-  favicon?: string
-  ogImage?: string
-  security?: BoltdocsSecurityConfig
-}
-
-/**
- * Loads user's configuration file (e.g., `boltdocs.config.js` or `boltdocs.config.ts`) if it exists,
- * merges it with the default configuration, and returns the final `BoltdocsConfig`.
- *
- * @param docsDir - The directory containing the documentation files
- * @param root - The project root directory (defaults to process.cwd())
- * @returns The merged configuration object
- */
-export async function resolveConfig(
-  docsDir: string,
-  root: string = process.cwd(),
-): Promise<BoltdocsConfig> {
-  const projectRoot = root
-
-  const defaults: BoltdocsConfig = {
-    docsDir: path.resolve(docsDir),
-    theme: {
-      title: 'Boltdocs',
-      description: 'A Vite documentation framework',
-      navbar: [
-        { label: 'Home', href: '/' },
-        { label: 'Documentation', href: '/docs' },
-      ],
-      codeTheme: {
-        light: 'github-light',
-        dark: 'github-dark',
-      },
-      poweredBy: true,
-      breadcrumbs: true,
-    },
-  }
-
-  let userConfig: RawUserConfig = {}
-
-  // Try to load user config
-  for (const filename of CONFIG_FILES) {
-    const configPath = path.resolve(projectRoot, filename)
-    if (fs.existsSync(configPath)) {
-      try {
-        const loaded = await loadConfigFromFile(
-          { command: 'serve', mode: 'development' },
-          configPath,
-          projectRoot,
-        )
-        if (loaded) {
-          userConfig = loaded.config as RawUserConfig
-          break
-        }
-      } catch (e) {
-        console.warn(`[boltdocs] Failed to load config from ${filename}:`, e)
-      }
-    }
-  }
-
-  const themeConfigFromTop: BoltdocsThemeConfig = {
-    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,
-  }
-
-  const userThemeConfig: BoltdocsThemeConfig = {
-    ...themeConfigFromTop,
-    ...(userConfig.theme || {}),
-  }
-
-  const cleanThemeConfig = Object.fromEntries(
-    Object.entries(userThemeConfig).filter(([_, v]) => v !== undefined),
-  ) as BoltdocsThemeConfig
-  if (cleanThemeConfig.navbar) {
-    cleanThemeConfig.navbar = cleanThemeConfig.navbar.map((item: any) => ({
-      label: item.label || item.text || '',
-      href: item.href || item.link || item.to || '',
-    }))
-  }
-
-  const finalConfig: BoltdocsConfig = {
-    docsDir: path.resolve(docsDir),
-    homePage: userConfig.homePage,
-    theme: {
-      ...defaults.theme,
-      ...cleanThemeConfig,
-    },
-    i18n: userConfig.i18n,
-    versions: userConfig.versions,
-    siteUrl: userConfig.siteUrl,
-    plugins: userConfig.plugins || [],
-    robots: userConfig.robots,
-    security: userConfig.security,
-    vite: userConfig.vite,
-  }
-
-  // Validate the final configuration
-  const validation = BoltdocsConfigSchema.safeParse(finalConfig)
-  if (!validation.success) {
-    const errorMessages = validation.error.issues
-      .map((err: any) => {
-        const path = err.path.join('.')
-        return `  - ${path}: ${err.message}`
-      })
-      .join('\n')
-
-    throw new ValidationError(
-      `Invalid Boltdocs configuration:\n${errorMessages}`,
-    )
-  }
-
-  return validation.data as BoltdocsConfig
-}

package/src/node/errors.ts

@@ -1,44 +0,0 @@
-/**
- * Base class for all security-related violations in Boltdocs.
- */
-export class SecurityViolationError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'SecurityViolationError';
-    // Ensure the prototype is set correctly for instanceof checks in older TS versions
-    Object.setPrototypeOf(this, SecurityViolationError.prototype);
-  }
-}
-
-/**
- * Specifically for directory traversal attempts and related filesystem breaches.
- */
-export class PathTraversalError extends SecurityViolationError {
-  constructor(message: string) {
-    super(message);
-    this.name = 'PathTraversalError';
-    Object.setPrototypeOf(this, PathTraversalError.prototype);
-  }
-}
-
-/**
- * Specifically for invalid or malicious character encoding in paths.
- */
-export class EncodingSecurityError extends SecurityViolationError {
-  constructor(message: string) {
-    super(message);
-    this.name = 'EncodingSecurityError';
-    Object.setPrototypeOf(this, EncodingSecurityError.prototype);
-  }
-}
-
-/**
- * Specifically for schema or size validation failures in inputs (like frontmatter).
- */
-export class ValidationError extends SecurityViolationError {
-  constructor(message: string) {
-    super(message);
-    this.name = 'ValidationError';
-    Object.setPrototypeOf(this, ValidationError.prototype);
-  }
-}

package/src/node/index.ts

@@ -1,84 +0,0 @@
-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/index'
-import { SECURITY_HEADERS } from './security/headers'
-import { getCSPHeader } from './security/csp'
-import type { BoltdocsPluginOptions } from './plugin/index'
-
-import { resolveConfig } from './config'
-
-export default async function boltdocs(
-  options?: BoltdocsPluginOptions,
-): Promise<Plugin[]> {
-  const docsDir = options?.docsDir || 'docs'
-  const config = await resolveConfig(docsDir)
-
-  // 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 isProd = mode === 'production'
-
-  // Prepare security headers
-  const securityHeaders: Record<string, string> = isProd
-    ? { ...SECURITY_HEADERS }
-    : {}
-  if (config.security?.enableCSP) {
-    securityHeaders['Content-Security-Policy'] = getCSPHeader(config)
-  }
-
-  const viteConfig: InlineConfig = {
-    root,
-    mode,
-    plugins: [
-      react(),
-      tailwindcss(),
-      await boltdocs({
-        docsDir: config.docsDir,
-        homePage: config.homePage,
-      }),
-    ],
-    server: {
-      headers: {
-        ...securityHeaders,
-        ...config.vite?.server?.headers,
-      },
-      ...config.vite?.server,
-    },
-    preview: {
-      headers: {
-        ...securityHeaders,
-        ...config.vite?.preview?.headers,
-      },
-      ...config.vite?.preview,
-    },
-    ...config.vite,
-  }
-
-  return viteConfig
-}
-
-export type { BoltdocsPluginOptions }
-export { generateStaticPages } from './ssg'
-export type { SSGOptions } from './ssg'
-export type { RouteMeta } from './routes'
-export type { BoltdocsConfig, BoltdocsThemeConfig, BoltdocsPlugin } from './config'
-export { resolveConfig, defineConfig } from './config'
-
-export * from './plugins'

package/src/node/mdx/cache.ts

@@ -1,12 +0,0 @@
-import { TransformCache } from '../cache'
-
-/**
- * Version identifier for the MDX plugin to invalidate cache if logic changes.
- */
-export const MDX_PLUGIN_VERSION = 'v4'
-
-/**
- * Persistent cache for MDX transformations.
- * Saves results to `.boltdocs/transform-mdx.json.gz`.
- */
-export const mdxCache = new TransformCache('mdx')

package/src/node/mdx/highlighter.ts

@@ -1,47 +0,0 @@
-import { createHighlighter } from 'shiki'
-import type { Highlighter } from 'shiki'
-
-let shikiHighlighter: Highlighter | null = null
-
-/**
- * Retrieves or initializes the Shiki highlighter instance.
- * Supports dual-theme configurations (light/dark).
- *
- * @param codeTheme - Theme configuration (string for single, object for dual).
- * @returns A promise resolving to the highlighter instance.
- */
-export async function getShikiHighlighter(codeTheme: any) {
-  if (shikiHighlighter) return shikiHighlighter
-
-  const themes =
-    typeof codeTheme === 'object'
-      ? [codeTheme.light, codeTheme.dark]
-      : [codeTheme ?? 'github-dark']
-
-  // Fallbacks for standard themes
-  ;['github-light', 'github-dark'].forEach((t) => {
-    if (!themes.includes(t)) themes.push(t)
-  })
-
-  // Initialize with a core set of languages first to speed up boot
-  shikiHighlighter = await createHighlighter({
-    themes,
-    langs: [
-      'tsx',
-      'jsx',
-      'ts',
-      'js',
-      'json',
-      'md',
-      'mdx',
-      'css',
-      'html',
-      'bash',
-      'sh',
-      'yaml',
-      'yml',
-    ],
-  })
-
-  return shikiHighlighter
-}

package/src/node/mdx/index.ts

@@ -1,122 +0,0 @@
-import mdxPlugin from '@mdx-js/rollup'
-import remarkGfm from 'remark-gfm'
-import remarkFrontmatter from 'remark-frontmatter'
-import rehypeSlug from 'rehype-slug'
-import type { Plugin } from 'vite'
-import crypto from 'crypto'
-
-import type { BoltdocsConfig } from '../config'
-import { mdxCache, MDX_PLUGIN_VERSION } from './cache'
-import { remarkShiki } from './remark-shiki'
-import { rehypeShiki } from './rehype-shiki'
-import { remarkCodeMeta } from './remark-code-meta'
-import { PluginSandbox } from '../plugins'
-
-let mdxCacheLoaded = false
-let hits = 0
-let total = 0
-
-/**
- * Configures the MDX compiler for Vite using `@mdx-js/rollup`.
- * Includes standard remark and rehype plugins for GitHub Flavored Markdown (GFM),
- * frontmatter extraction, and auto-linking headers.
- *
- * Also wraps the plugin with a persistent cache to avoid re-compiling unchanged MDX files.
- *
- * @param config - The Boltdocs configuration containing custom plugins
- * @param compiler - The MDX compiler plugin (for testing)
- * @returns A Vite plugin configured for MDX parsing with caching
- */
-export function boltdocsMdxPlugin(
-  config?: BoltdocsConfig,
-  compiler = mdxPlugin,
-): Plugin {
-  const extraRemarkPlugins =
-    config?.plugins?.flatMap((p) => {
-      const caps = PluginSandbox.getSanitizedCapabilities(p as any)
-      return caps.remarkPlugins || []
-    }) || []
-  const extraRehypePlugins =
-    config?.plugins?.flatMap((p) => {
-      const caps = PluginSandbox.getSanitizedCapabilities(p as any)
-      return caps.rehypePlugins || []
-    }) || []
-
-  const baseMdxPlugin = compiler({
-    remarkPlugins: [
-      remarkGfm,
-      remarkFrontmatter,
-      remarkCodeMeta,
-      [remarkShiki, config],
-      ...(extraRemarkPlugins as any[]),
-    ],
-    rehypePlugins: [
-      rehypeSlug,
-      [rehypeShiki, config],
-      ...(extraRehypePlugins as any[]),
-    ],
-    jsxRuntime: 'automatic',
-  }) as Plugin
-
-  return {
-    ...baseMdxPlugin,
-    name: 'vite-plugin-boltdocs-mdx',
-
-    async buildStart() {
-      hits = 0
-      total = 0
-      if (!mdxCacheLoaded) {
-        mdxCache.load()
-        mdxCacheLoaded = true
-      }
-      // @ts-ignore
-      if (baseMdxPlugin.buildStart) {
-        // @ts-ignore
-        await baseMdxPlugin.buildStart.call(this)
-      }
-    },
-
-    async transform(code, id, options) {
-      if (!id.endsWith('.md') && !id.endsWith('.mdx')) {
-        // @ts-ignore
-        return baseMdxPlugin.transform?.call(this, code, id, options)
-      }
-
-      console.log(`[boltdocs] Transforming MDX: ${id}`)
-      total++
-      // Create a cache key based on path, content, and plugin version
-      const contentHash = crypto.createHash('md5').update(code).digest('hex')
-      const cacheKey = `${id}:${contentHash}:${MDX_PLUGIN_VERSION}`
-
-      const cached = mdxCache.get(cacheKey)
-      if (cached) {
-        hits++
-        return { code: cached, map: null }
-      }
-
-      // @ts-ignore
-      const result = await baseMdxPlugin.transform.call(this, code, id, options)
-
-      if (result && typeof result === 'object' && result.code) {
-        mdxCache.set(cacheKey, result.code)
-      }
-
-      return result
-    },
-
-    async buildEnd() {
-      if (total > 0) {
-        console.log(
-          `[boltdocs] MDX Cache Performance: ${hits}/${total} hits (${Math.round((hits / total) * 100) || 0}%)`,
-        )
-      }
-      mdxCache.save()
-      await mdxCache.flush()
-      // @ts-ignore
-      if (baseMdxPlugin.buildEnd) {
-        // @ts-ignore
-        await baseMdxPlugin.buildEnd.call(this)
-      }
-    },
-  }
-}