boltdocs 2.2.0 → 2.4.1

package/src/client/store/use-boltdocs-store.ts

@@ -5,7 +5,7 @@ interface BoltdocsState {
   currentLocale: string | undefined
   currentVersion: string | undefined
   hasHydrated: boolean
-  
+
   // Actions
   setLocale: (locale: string | undefined) => void
   setVersion: (version: string | undefined) => void
@@ -22,9 +22,10 @@ export const useBoltdocsStore = create<BoltdocsState>()(
       currentLocale: undefined,
       currentVersion: undefined,
       hasHydrated: false,
-      
+
       setLocale: (locale: string | undefined) => set({ currentLocale: locale }),
-      setVersion: (version: string | undefined) => set({ currentVersion: version }),
+      setVersion: (version: string | undefined) =>
+        set({ currentVersion: version }),
       setHasHydrated: (val: boolean) => set({ hasHydrated: val }),
     }),
     {
@@ -38,6 +39,6 @@ export const useBoltdocsStore = create<BoltdocsState>()(
       onRehydrateStorage: () => (state?: BoltdocsState) => {
         state?.setHasHydrated(true)
       },
-    }
-  )
+    },
+  ),
 )

package/src/client/theme/neutral.css

@@ -66,7 +66,36 @@
   --spacing-navbar: 3.5rem;
   --spacing-sidebar: 16rem;
   --spacing-toc: 14rem;
-  --spacing-content-max: 48rem;
+  --spacing-content-max: 54rem;
+
+  @keyframes pulse {
+    0%,
+    100% {
+      opacity: 1;
+    }
+    50% {
+      opacity: 0.5;
+    }
+  }
+
+  @keyframes fade-in {
+    from {
+      opacity: 0;
+      transform: translateY(10px);
+    }
+    to {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+}
+
+.animate-pulse {
+  animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+}
+
+.animate-fade-in {
+  animation: fade-in 0.5s ease-out forwards;
 }
 
 :root[data-theme="dark"],
@@ -94,9 +123,8 @@
   body {
     margin: 0;
     padding: 0;
-    height: 100%;
+    min-height: 100%;
     overflow-x: hidden;
-    overflow-y: hidden;
   }
 
   body {

package/src/client/types.ts

@@ -74,6 +74,8 @@ export interface CreateBoltdocsAppOptions {
   homePage?: React.ComponentType
   /** Custom external pages mapped by their route path */
   externalPages?: Record<string, React.ComponentType>
+  /** Optional custom layout for external pages */
+  externalLayout?: React.ComponentType<{ children: React.ReactNode }>
   /** Optional custom MDX components provided by plugins */
   components?: Record<string, React.ComponentType>
 }
@@ -167,6 +169,4 @@ export interface NavbarLink {
   active: boolean
   /** Optional icon or string for external link indication */
   to?: string
-  /** Nested items for NavigationMenu */
-  items?: NavbarLink[]
 }

package/src/node/{cli.ts → cli/build.ts}

@@ -1,27 +1,16 @@
-import { createServer, build, preview } from 'vite'
-import { createViteConfig, resolveConfig } from './index'
-import { getHtmlTemplate } from './plugin/html'
+import { build, preview } from 'vite'
+import { createViteConfig, resolveConfig } from '../index'
+import { getHtmlTemplate } from '../plugin/html'
 import path from 'path'
 import fs from 'fs'
+import * as ui from './ui'
 
 /**
- * Core logic for the Boltdocs CLI commands.
- * These functions wrap Vite's JS API to provide a seamless experience.
+ * Logic for the `boltdocs build` command.
+ * Prepares the production bundle and handles dynamic index.html generation.
+ *
+ * @param root - The project root directory
  */
-
-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')
@@ -35,9 +24,9 @@ export async function buildAction(root: string = process.cwd()) {
 
     const viteConfig = await createViteConfig(root, 'production')
     await build(viteConfig)
-    console.log('[boltdocs] Build completed successfully.')
+    ui.success('Build completed successfully.')
   } catch (e) {
-    console.error('[boltdocs] Build failed:', e)
+    ui.error('Build failed:', e)
     process.exit(1)
   } finally {
     if (createdIndexHtml && fs.existsSync(indexPath)) {
@@ -46,14 +35,19 @@ export async function buildAction(root: string = process.cwd()) {
   }
 }
 
+/**
+ * Logic for the `boltdocs preview` command.
+ * Serves the production build from the disk.
+ *
+ * @param root - The project root directory
+ */
 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)
+    ui.error('Failed to start preview server:', e)
     process.exit(1)
   }
 }
-

package/src/node/cli/dev.ts

@@ -0,0 +1,22 @@
+import { createServer } from 'vite'
+import { createViteConfig } from '../index'
+import * as ui from './ui'
+
+/**
+ * Logic for the `boltdocs dev` command.
+ * Starts a Vite development server and sets up HMR.
+ *
+ * @param root - The project root directory
+ */
+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) {
+    ui.error('Failed to start dev server:', e)
+    process.exit(1)
+  }
+}

package/src/node/cli/doctor.ts

@@ -0,0 +1,243 @@
+import path from 'path'
+import fs from 'fs'
+import fastGlob from 'fast-glob'
+import { resolveConfig } from '../config'
+import { parseFrontmatter, normalizePath } from '../utils'
+import * as ui from './ui'
+
+/**
+ * Interface representing a documentation hygiene issue.
+ */
+interface Issue {
+  level: 'high' | 'warning' | 'low'
+  message: string
+  suggestion?: string
+}
+
+/**
+ * Logic for the `boltdocs doctor` command.
+ * Scans the documentation directory for broken links, missing frontmatter,
+ * and orphaned translations.
+ *
+ * @param root - The project root directory
+ */
+export async function doctorAction(root: string = process.cwd()) {
+  const { colors } = ui
+  ui.info(
+    `${colors.bold}Running documentation health check...${colors.reset}\n`,
+  )
+  const start = performance.now()
+
+  try {
+    const config = await resolveConfig('docs', root)
+    const docsDir = path.resolve(root, 'docs')
+
+    if (!fs.existsSync(docsDir)) {
+      ui.error(`Documentation directory not found at ${docsDir}`)
+      process.exit(1)
+    }
+
+    const files = await fastGlob(['**/*.md', '**/*.mdx'], {
+      cwd: docsDir,
+      absolute: true,
+      suppressErrors: true,
+    })
+
+    let highCount = 0
+    let warningCount = 0
+    let lowCount = 0
+    const issuesMap = new Map<string, Issue[]>()
+
+    const addIssue = (file: string, issue: Issue) => {
+      const relPath = path.relative(docsDir, file)
+      let issues = issuesMap.get(relPath)
+      if (!issues) {
+        issues = []
+        issuesMap.set(relPath, issues)
+      }
+      issues.push(issue)
+      if (issue.level === 'high') highCount++
+      else if (issue.level === 'warning') warningCount++
+      else if (issue.level === 'low') lowCount++
+    }
+
+    const basePath = '/docs'
+
+    // 1. Scan for Frontmatter, Links, and Content Issues
+    for (const file of files) {
+      const { data, content } = parseFrontmatter(file)
+
+      // Frontmatter Validation
+      if (!data.title) {
+        addIssue(file, {
+          level: 'warning',
+          message: 'Missing "title" in frontmatter.',
+          suggestion:
+            'Add `title: Your Title` to the YAML frontmatter at the top of the file.',
+        })
+      }
+
+      if (!data.description) {
+        addIssue(file, {
+          level: 'low',
+          message: 'Missing "description" in frontmatter.',
+          suggestion:
+            'Adding a description helps with SEO and search previews.',
+        })
+      }
+
+      // Link Validation
+      const linkRegex = /\[.*?\]\((.*?)\)/g
+      const htmlLinkRegex = /<a\s+[^>]*href=["']([^"']+)["'][^>]*>/g
+      const links = [
+        ...content.matchAll(linkRegex),
+        ...content.matchAll(htmlLinkRegex),
+      ]
+
+      for (const match of links) {
+        let link = match[1]
+        if (
+          !link ||
+          link.startsWith('http') ||
+          link.startsWith('https') ||
+          link.startsWith('#') ||
+          link.startsWith('mailto:') ||
+          link.startsWith('tel:')
+        ) {
+          continue
+        }
+
+        link = link.split('#')[0]
+        if (!link) continue
+
+        let targetPath: string
+        if (link.startsWith('/')) {
+          let pathAfterBase = link
+          if (link.startsWith(basePath + '/') || link === basePath) {
+            pathAfterBase = link.substring(basePath.length)
+          }
+          targetPath = path.join(docsDir, pathAfterBase)
+        } else {
+          targetPath = path.resolve(path.dirname(file), link)
+        }
+
+        const extensions = ['', '.md', '.mdx', '/index.md', '/index.mdx']
+        let exists = false
+        for (const ext of extensions) {
+          const finalPath = targetPath + ext
+          if (fs.existsSync(finalPath) && fs.statSync(finalPath).isFile()) {
+            exists = true
+            break
+          }
+        }
+
+        if (!exists) {
+          addIssue(file, {
+            level: 'high',
+            message: `Broken internal link: "${link}"`,
+            suggestion: `Ensure the file exists at "${targetPath}". If it's a directory, ensure it has an "index.md" or "index.mdx".`,
+          })
+        }
+      }
+    }
+
+    // 2. Scan for Orphaned Translations
+    if (config.i18n) {
+      const { defaultLocale, locales } = config.i18n
+      const otherLocales = Object.keys(locales).filter(
+        (l) => l !== defaultLocale,
+      )
+
+      for (const file of files) {
+        const relPath = normalizePath(path.relative(docsDir, file))
+        const parts = relPath.split('/')
+
+        if (parts[0] === defaultLocale) {
+          const pathAfterLocale = parts.slice(1).join('/')
+          for (const locale of otherLocales) {
+            const localeParts = [locale, ...parts.slice(1)]
+            const targetLocaleFile = path.join(docsDir, ...localeParts)
+
+            if (!fs.existsSync(targetLocaleFile)) {
+              addIssue(file, {
+                level: 'warning',
+                message: `Missing translation for locale "${locale}"`,
+                suggestion: `Create a translated version of this file at "${locale}/${pathAfterLocale}".`,
+              })
+            }
+          }
+        }
+      }
+    }
+
+    // Final Reporting
+    if (issuesMap.size === 0) {
+      ui.success('All documentation files are healthy!\n')
+    } else {
+      for (const [file, issues] of issuesMap.entries()) {
+        console.log(`📄 ${colors.bold}${file}${colors.reset}`)
+
+        const sortedIssues = issues.sort((a, b) => {
+          const order = { high: 1, warning: 2, low: 3 }
+          return order[a.level] - order[b.level]
+        })
+
+        for (const issue of sortedIssues) {
+          let prefix = ''
+          let color = ''
+          if (issue.level === 'high') {
+            prefix = '❌'
+            color = colors.red
+          } else if (issue.level === 'warning') {
+            prefix = '⚠️'
+            color = colors.yellow
+          } else {
+            prefix = 'ℹ️'
+            color = colors.cyan
+          }
+
+          console.log(
+            `   ${color}${prefix} ${issue.level.toUpperCase()}:${colors.reset} ${issue.message}`,
+          )
+          if (issue.suggestion) {
+            console.log(
+              `      ${colors.gray}💡 Suggestion: ${issue.suggestion}${colors.reset}`,
+            )
+          }
+        }
+        console.log('')
+      }
+
+      console.log(`${colors.bold}Summary:${colors.reset}`)
+      console.log(
+        `   ${colors.red}${highCount} high-level errors${colors.reset}`,
+      )
+      console.log(`   ${colors.yellow}${warningCount} warnings${colors.reset}`)
+      console.log(
+        `   ${colors.cyan}${lowCount} minor improvements${colors.reset}\n`,
+      )
+
+      if (highCount > 0) {
+        ui.error(
+          'HIGH ERROR: Fix these to ensure your documentation builds correctly.',
+        )
+      }
+      if (warningCount > 0 || lowCount > 0) {
+        ui.info(
+          'TIP: Address warnings and suggestions for premium quality docs.',
+        )
+      }
+      console.log('')
+    }
+
+    const duration = performance.now() - start
+    ui.info(`Finished in ${duration.toFixed(2)}ms\n`)
+
+    if (highCount > 0) {
+      process.exit(1)
+    }
+  } catch (e) {
+    ui.error('Failed to run doctor check:', e)
+    process.exit(1)
+  }
+}

package/src/node/cli/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Boltdocs CLI Actions Module.
+ * This module exports all command-line actions used by the Boltdocs tool.
+ */
+
+export * from './dev'
+export * from './build'
+export * from './doctor'
+export * from './ui'

package/src/node/cli/ui.ts

@@ -0,0 +1,54 @@
+/**
+ * ANSI Escape sequences for terminal coloring and styling.
+ * Used to provide a premium and consistent CLI experience.
+ */
+export const colors = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  gray: '\x1b[90m',
+}
+
+/**
+ * Formats a message with the boltdocs prefix and provided styling.
+ *
+ * @param message - The content to log
+ * @param style - Optional ANSI style prefix
+ * @returns The formatted string
+ */
+export function formatLog(message: string, style: string = ''): string {
+  return `${style}${colors.bold}[boltdocs]${colors.reset} ${message}${colors.reset}`
+}
+
+/**
+ * Logs a standard informational message to the console.
+ *
+ * @param message - The message to display
+ */
+export function info(message: string) {
+  console.log(formatLog(message))
+}
+
+/**
+ * Logs an error message to the console with red styling.
+ *
+ * @param message - The error description
+ * @param error - Optional error object for stack tracing
+ */
+export function error(message: string, error?: any) {
+  console.error(formatLog(message, colors.red))
+  if (error) console.error(error)
+}
+
+/**
+ * Logs a success message to the console with green styling.
+ *
+ * @param message - The success description
+ */
+export function success(message: string) {
+  console.log(formatLog(message, colors.green))
+}

package/src/node/cli-entry.ts

@@ -1,24 +1,24 @@
 #!/usr/bin/env node
-import cac from "cac";
-import { devAction, buildAction, previewAction } from "./cli";
+import cac from 'cac'
+import {
+  devAction,
+  buildAction,
+  previewAction,
+  doctorAction,
+} from './cli/index'
 
-const cli = cac("boltdocs");
+const cli = cac('boltdocs')
 
-cli
-  .command("[root]", "Start development server")
-  .alias("dev")
-  .action(devAction);
+cli.command('[root]', 'Start development server').alias('dev').action(devAction)
 
-cli
-  .command("build [root]", "Build for production")
-  .action(buildAction);
+cli.command('build [root]', 'Build for production').action(buildAction)
 
-cli
-  .command("preview [root]", "Preview production build")
-  .action(previewAction);
+cli.command('preview [root]', 'Preview production build').action(previewAction)
 
-cli.help();
+cli.command('doctor [root]', 'Check documentation health').action(doctorAction)
+
+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.version('2.0.0')
 
-cli.parse();
+cli.parse()

package/src/node/config.ts

@@ -44,13 +44,6 @@ export interface BoltdocsThemeConfig {
     label: string | Record<string, string>
     /** URL path or external link */
     href: string
-    /** Nested items for NavigationMenu */
-    items?: 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 }>>
@@ -164,7 +157,7 @@ export interface BoltdocsVersionConfig {
 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'.
    */
@@ -222,8 +215,6 @@ export interface BoltdocsConfig {
   versions?: BoltdocsVersionsConfig
   /** Custom plugins for extending functionality */
   plugins?: BoltdocsPlugin[]
-  /** Map of custom external route paths to component file paths */
-  external?: Record<string, string>
   /** External integrations configuration */
   integrations?: BoltdocsIntegrationsConfig
   /** Configuration for the robots.txt file */
@@ -344,10 +335,6 @@ export async function resolveConfig(
     cleanThemeConfig.navbar = cleanThemeConfig.navbar.map((item: any) => ({
       label: item.label || item.text || '',
       href: item.href || item.link || item.to || '',
-      items: item.items?.map((sub: any) => ({
-        label: sub.label || sub.text || '',
-        href: sub.href || sub.link || sub.to || '',
-      })),
     }))
   }
 
@@ -362,7 +349,6 @@ export async function resolveConfig(
     versions: userConfig.versions,
     siteUrl: userConfig.siteUrl,
     plugins: userConfig.plugins || [],
-    external: userConfig.external,
     integrations: userConfig.integrations,
     robots: userConfig.robots,
     vite: userConfig.vite,

package/src/node/mdx/cache.ts

@@ -3,7 +3,7 @@ import { TransformCache } from '../cache'
 /**
  * Version identifier for the MDX plugin to invalidate cache if logic changes.
  */
-export const MDX_PLUGIN_VERSION = 'v3'
+export const MDX_PLUGIN_VERSION = 'v4'
 
 /**
  * Persistent cache for MDX transformations.

package/src/node/mdx/index.ts

@@ -9,6 +9,7 @@ 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'
 
 let mdxCacheLoaded = false
 let hits = 0
@@ -38,6 +39,7 @@ export function boltdocsMdxPlugin(
     remarkPlugins: [
       remarkGfm,
       remarkFrontmatter,
+      remarkCodeMeta,
       [remarkShiki, config],
       ...(extraRemarkPlugins as any[]),
     ],

package/src/node/mdx/rehype-shiki.ts

@@ -31,6 +31,11 @@ export function rehypeShiki(config?: BoltdocsConfig) {
         const lang = langMatch ? langMatch.slice(9) : 'text'
         const code = codeNode.children[0]?.value || ''
 
+        // Extract title from meta string (e.g., ```ts title="app.ts")
+        const meta: string = codeNode.data?.meta || codeNode.properties?.metastring || ''
+        const titleMatch = meta.match(/title\s*=\s*"([^"]*)"/)
+        const title = titleMatch ? titleMatch[1] : undefined
+
         const options: any = { lang }
         if (typeof codeTheme === 'object') {
           options.themes = {
@@ -46,6 +51,10 @@ export function rehypeShiki(config?: BoltdocsConfig) {
         // Inject highlighted HTML and mark as highlighted for CodeBlock component
         node.properties.dataHighlighted = 'true'
         node.properties.highlightedHtml = html
+        node.properties['data-lang'] = lang
+        if (title) {
+          node.properties.title = title
+        }
         node.children = []
       }
     })

package/src/node/mdx/remark-code-meta.ts

@@ -0,0 +1,35 @@
+import { visit } from 'unist-util-visit'
+
+/**
+ * Remark plugin that preserves code fence meta strings (e.g., title="file.ts")
+ * and the language identifier by copying them to hProperties so they survive
+ * the remark → rehype conversion and are accessible as props on the `<pre>` element.
+ *
+ * Usage in MDX: ```ts title="app.ts"
+ */
+export function remarkCodeMeta() {
+  return (tree: any) => {
+    visit(tree, 'code', (node: any) => {
+      node.data = node.data || {}
+      node.data.hProperties = node.data.hProperties || {}
+
+      // Always pass the lang through
+      if (node.lang) {
+        node.data.hProperties['data-lang'] = node.lang
+      }
+
+      if (!node.meta) return
+
+      const meta: string = node.meta
+
+      // Extract title="..." from the meta string
+      const titleMatch = meta.match(/title\s*=\s*"([^"]*)"/)
+      if (titleMatch) {
+        node.data.hProperties.title = titleMatch[1]
+      }
+
+      // Preserve the full meta string for other plugins
+      node.data.hProperties.metastring = meta
+    })
+  }
+}

package/src/node/mdx/remark-shiki.ts

@@ -32,7 +32,7 @@ export function remarkShiki(config?: BoltdocsConfig) {
           code = codeAttr.value
         } else if (codeAttr.value?.type === 'mdxJsxAttributeValueExpression') {
           const expr = codeAttr.value.value ?? ''
-          code = expr.match(/^[`'"](.+)[`'"]$/)?.[1] ?? expr
+          code = expr.match(/^[`'"]([\s\S]+)[`'"]$/)?.[1] ?? expr
         }
       }