boltdocs 2.0.0 → 2.1.1

package/dist/{use-routes-BefRXY3v.d.ts → use-routes-8Iei6jTp.d.mts}

@@ -1,5 +1,4 @@
-import { B as BoltdocsConfig } from './config-CX4l-ZNp.js';
-import { C as ComponentRoute } from './types-BuZWFT7r.js';
+import { C as ComponentRoute, B as BoltdocsConfig } from './types-Cp21DHI6.mjs';
 
 /**
  * Hook to access the framework's routing state.

package/dist/{use-routes-5bAtAAYX.d.mts → use-routes-xLhumjbV.d.ts}

@@ -1,5 +1,4 @@
-import { B as BoltdocsConfig } from './config-CX4l-ZNp.mjs';
-import { C as ComponentRoute } from './types-CvT-SGbK.mjs';
+import { C as ComponentRoute, B as BoltdocsConfig } from './types-Cp21DHI6.js';
 
 /**
  * Hook to access the framework's routing state.

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "boltdocs",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "A lightweight documentation generator for React projects.",
   "main": "dist/node/index.js",
   "module": "dist/node/index.mjs",
   "types": "dist/node/index.d.ts",
+  "bin": {
+    "boltdocs": "bin/boltdocs.js"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -53,6 +56,9 @@
   "dependencies": {
     "@mdx-js/react": "^3.1.1",
     "@mdx-js/rollup": "^3.1.1",
+    "@tailwindcss/vite": "^4.2.2",
+    "@vitejs/plugin-react": "^4.2.1",
+    "cac": "^7.0.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "codesandbox": "^2.2.3",

package/src/client/components/ui-base/breadcrumbs.tsx

@@ -12,10 +12,11 @@ import { useConfig } from '@client/app/config-context'
 export function Breadcrumbs() {
   const { crumbs, activeRoute } = useBreadcrumbs()
   const config = useConfig()
+  const themeConfig = config.theme || config.themeConfig || {}
 
   if (crumbs.length === 0) return null
 
-  if (!config.themeConfig?.breadcrumbs) return null
+  if (!themeConfig?.breadcrumbs) return null
 
   return (
     <BreadcrumbsRoot>

package/src/client/components/ui-base/navbar.tsx

@@ -24,7 +24,7 @@ export function Navbar() {
   const { links, title, logo, logoProps, github, social, config } = useNavbar()
   const { routes, allRoutes, currentVersion, currentLocale } = useRoutes()
   const { pathname } = useLocation()
-  const { themeConfig } = useConfig()
+  const themeConfig = config.theme || config.themeConfig || {}
 
   const hasTabs = themeConfig?.tabs && themeConfig.tabs.length > 0
 
@@ -76,10 +76,10 @@ export function Navbar() {
         </NavbarPrimitive.NavbarRight>
       </NavbarPrimitive.Content>
 
-      {pathname !== '/' && hasTabs && config.themeConfig?.tabs && (
+      {pathname !== '/' && hasTabs && themeConfig?.tabs && (
         <div className="w-full border-b border-border-subtle bg-bg-main">
           <Tabs
-            tabs={config.themeConfig.tabs}
+            tabs={themeConfig.tabs}
             routes={allRoutes || routes || []}
           />
         </div>

package/src/client/components/ui-base/sidebar.tsx

@@ -67,6 +67,7 @@ export function Sidebar({
   config: BoltdocsConfig
 }) {
   const { groups, ungrouped, activePath } = useSidebar(routes)
+  const themeConfig = config.theme || config.themeConfig || {}
 
   return (
     <SidebarPrimitive.SidebarRoot>
@@ -94,7 +95,7 @@ export function Sidebar({
         />
       ))}
 
-      {config.themeConfig?.poweredBy && (
+      {themeConfig?.poweredBy && (
         <div className="mt-auto pt-8">
           <PoweredBy />
         </div>

package/src/client/hooks/use-navbar.ts

@@ -8,7 +8,7 @@ export function useNavbar() {
   const { theme } = useTheme()
   const location = useLocation()
 
-  const themeConfig = config.themeConfig || {}
+  const themeConfig = config.theme || config.themeConfig || {}
   const title = themeConfig.title || 'Boltdocs'
   const rawLinks = themeConfig.navbar || []
   const socialLinks = themeConfig.socialLinks || []

package/src/node/cli-entry.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import cac from "cac";
+import { devAction, buildAction, previewAction } from "./cli";
+
+const cli = cac("boltdocs");
+
+cli
+  .command("[root]", "Start development server")
+  .alias("dev")
+  .action(devAction);
+
+cli
+  .command("build [root]", "Build for production")
+  .action(buildAction);
+
+cli
+  .command("preview [root]", "Preview production build")
+  .action(previewAction);
+
+cli.help();
+// This will be replaced at build time or package publishing, but hardcoded to 2.0.0 for now
+cli.version("2.0.0");
+
+cli.parse();

package/src/node/cli.ts

@@ -0,0 +1,59 @@
+import { createServer, build, preview } from 'vite'
+import { createViteConfig, resolveConfig } from './index'
+import { getHtmlTemplate } from './plugin/html'
+import path from 'path'
+import fs from 'fs'
+
+/**
+ * Core logic for the Boltdocs CLI commands.
+ * These functions wrap Vite's JS API to provide a seamless experience.
+ */
+
+export async function devAction(root: string = process.cwd()) {
+  try {
+    const viteConfig = await createViteConfig(root, 'development')
+    const server = await createServer(viteConfig)
+    await server.listen()
+    server.printUrls()
+    server.bindCLIShortcuts({ print: true })
+  } catch (e) {
+    console.error('[boltdocs] Failed to start dev server:', e)
+    process.exit(1)
+  }
+}
+
+export async function buildAction(root: string = process.cwd()) {
+  let createdIndexHtml = false
+  const indexPath = path.resolve(root, 'index.html')
+
+  try {
+    if (!fs.existsSync(indexPath)) {
+      const config = await resolveConfig('docs', root)
+      fs.writeFileSync(indexPath, getHtmlTemplate(config), 'utf-8')
+      createdIndexHtml = true
+    }
+
+    const viteConfig = await createViteConfig(root, 'production')
+    await build(viteConfig)
+    console.log('[boltdocs] Build completed successfully.')
+  } catch (e) {
+    console.error('[boltdocs] Build failed:', e)
+    process.exit(1)
+  } finally {
+    if (createdIndexHtml && fs.existsSync(indexPath)) {
+      fs.unlinkSync(indexPath)
+    }
+  }
+}
+
+export async function previewAction(root: string = process.cwd()) {
+  try {
+    const viteConfig = await createViteConfig(root, 'production')
+    const previewServer = await preview(viteConfig)
+    previewServer.printUrls()
+  } catch (e) {
+    console.error('[boltdocs] Failed to start preview server:', e)
+    process.exit(1)
+  }
+}
+

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,

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 }
@@ -122,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()
+}