@sullux/markdown-docs 1.0.0 → 1.0.2

package/README.md

@@ -6,33 +6,98 @@ Built on `@sullux/markdown-compiler` and `@sullux/markdown-html`, `@sullux/markd
 
 ## Core Features
 
-* **GitBook `SUMMARY.md` Support:** Automatically parses `SUMMARY.md` navigation lists into sidebar navigation menus (with auto-discovery fallback if `SUMMARY.md` is omitted).
-* **Zero Dependencies:** Pure Vanilla JS implementation with zero external packages.
+* **GitBook `SUMMARY.md` Support:** Automatically parses `SUMMARY.md` navigation lists and `## Section` headers into sidebar navigation menus (with directory auto-discovery fallback if `SUMMARY.md` is omitted).
+* **Zero Dependencies:** Pure Vanilla JS implementation using Node.js built-ins.
+* **Declarative Site Configuration (`docs.yaml`):** Comprehensive YAML configuration file support for logos, themes, external links, favicons, and base URLs.
+* **Dual Light/Dark Branding:** Supports dual logos (`logo.light`, `logo.dark`) and dual color schemes with native OS system dark mode detection and client-side manual toggle persistence.
 * **Client-Side Search:** Auto-generates a lightweight JSON search index and embedded client-side search UI.
-* **Responsive Layout:** Clean GitBook-inspired UI with collapsible sidebar navigation, dark/light theme toggle, and mobile support.
-* **Rich Component Support:** Supports all `@sullux/markdown-html` features including code syntax highlighting, callout boxes (`> [!NOTE]`, `{% hint %}`), GFM tables, and custom image dimensions.
-* **Static Asset Copying:** Automatically copies non-markdown assets (PNGs, SVGs, PDFs) directly to the output directory.
+* **Responsive 3-Column Layout:** Sticky header with top search bar, left navigation sidebar, center content stream, and right page outline (TOC) with responsive slide-in drawers for mobile.
+* **Rich Component Support:** Supports code syntax highlighting, callout boxes (`> [!NOTE]`, `{% hint %}`), GFM tables, and custom image dimensions.
+* **Static Asset Copying:** Automatically copies non-Markdown assets (images, SVGs, PDFs) directly to the output directory.
 
-## Installation & CLI Usage
+## CLI Usage
 
 ```bash
-# Global installation or via npx
-npm install -g @sullux/markdown-docs
+# Generate site using default docs.yaml configuration in ./docs
+markdown-docs -i ./docs -o ./_site
 
-# Generate site from a docs directory
-markdown-docs -i ./docs -o ./_site -t "Project Documentation"
+# Build with a custom base URL for CI/CD environments
+markdown-docs -i ./docs -o ./_site -b "/my-app-docs/"
 ```
 
 ### CLI Options
 
 | Flag | Long Flag | Description | Default |
 | :--- | :--- | :--- | :--- |
-| `-i` | `--input` | Input Markdown docs directory | Current working directory |
-| `-o` | `--output` | Output directory | `<input>/_site` |
-| `-t` | `--title` | Documentation site title | Directory name |
-| | `--baseUrl` | Base URL prefix for links | `""` |
+| `-i` | `--input` | Path to input Markdown docs directory | Current working directory |
+| `-o` | `--output` | Path to output build directory | `<input>/_site` |
+| `-b` | `--base-url` | Base URL prefix for links and deployment | `""` |
+| `-t` | `--title` | Site title override (overrides `docs.yaml`) | `title` in `docs.yaml` |
+| `-c` | `--config` | Custom path to config file | `<input>/docs.yaml` |
 | `-h` | `--help` | Display CLI help menu | |
 
+---
+
+## Site Configuration (`docs.yaml`)
+
+You can configure your documentation site by placing a `docs.yaml` (or `docs.yml` / `docs.json`) file in your input documentation directory.
+
+### Example `docs.yaml`
+
+```yaml
+# Site Title (Optional: omit or leave empty for logo-only headers)
+title: "BucketDB"
+
+# Output directory (Optional: can also be passed via CLI)
+output: "_site"
+
+# Base URL prefix (Optional: useful for GitHub Pages or subdirectory hosting)
+baseUrl: "/docs"
+
+# Brand Logo (Supports single path/SVG, or dual light/dark images)
+logo:
+  light: "assets/logo-light.svg"
+  dark: "assets/logo-dark.svg"
+
+# Favicon Asset Path or URL
+favicon: "assets/favicon.ico"
+
+# External Header Navigation Links
+links:
+  - title: "GitHub"
+    url: "https://github.com/sullux/coms"
+  - title: "API Spec"
+    url: "https://api.example.com"
+
+# Theme Color Overrides
+theme:
+  light:
+    bg: "#ffffff"
+    accent: "#2563eb"
+    codeBg: "#f8fafc"
+    codeText: "#0f172a"
+  dark:
+    bg: "#121316"
+    accent: "#3b82f6"
+    codeBg: "#0a0b0e"
+    codeText: "#f3f4f6"
+```
+
+### Configuration Options Reference
+
+| Property | Type | Description | Default |
+| :--- | :--- | :--- | :--- |
+| `title` | `string` | Product or site name displayed in header & `<title>` tag. Leave empty (`""`) or omit when using a logo image containing the product name. | `""` |
+| `output` | `string` | Relative or absolute path to output build directory. | `<input>/_site` |
+| `baseUrl` | `string` | Base URL path prefix for hosting in subdirectories. | `""` |
+| `logo` | `string \| object` | Asset path/SVG string, or `{ light: "...", dark: "..." }` object for automatic theme switching. | `""` |
+| `favicon` | `string` | Asset path or URL to icon file. | Default book emoji (`📚`) |
+| `links` | `array` | Header external links array `[{ title: "...", url: "..." }]`. | `[]` |
+| `theme.light` | `object` | Light theme color overrides (`bg`, `accent`, `codeBg`, `codeText`). | Built-in light colors |
+| `theme.dark` | `object` | Dark theme color overrides (`bg`, `accent`, `codeBg`, `codeText`). | Built-in dark colors |
+
+---
+
 ## Programmatic API Usage
 
 ```javascript
@@ -41,30 +106,12 @@ const { generateSite } = require('@sullux/markdown-docs')
 const result = generateSite({
   input: './docs',
   output: './dist',
-  title: 'Sullux API Docs',
+  baseUrl: '/docs',
 })
 
 console.log(`Generated ${result.pageCount} pages at ${result.output}`)
 ```
 
-## Folder Topography
-
-```
-packages/markdown-docs/
-├── bin/
-│   └── cli.js            # Executable CLI entrypoint
-├── lib/
-│   ├── config.js         # Option and CLI argument parser
-│   ├── summary.js        # SUMMARY.md parser and directory scanner
-│   ├── layout.js         # Responsive HTML page template generator
-│   ├── theme.js          # Embedded GitBook CSS styles
-│   ├── search.js         # Client-side search index and JS script
-│   ├── assets.js         # Static asset copy utility
-│   └── site.js           # Site generation coordinator
-├── index.js              # Package API entrypoint
-└── package.json          # Package manifest
-```
-
 ## Running Unit Tests
 
 ```bash

package/bin/cli.js

@@ -10,8 +10,9 @@ Usage: markdown-docs [options]
 Options:
   -i, --input <dir>      Path to input Markdown docs directory (default: CWD)
   -o, --output <dir>     Path to output directory (default: <input>/_site)
-  -t, --title <title>    Site title
-  --baseUrl <url>        Base URL prefix for links
+  -b, --base-url <url>   Base URL prefix for build/deployment
+  -t, --title <title>    Site title (overrides title in docs.yaml)
+  -c, --config <file>    Path to config file (default: <input>/docs.yaml)
   -h, --help             Show help documentation
 `)
 }

package/lib/config.js

@@ -1,34 +1,66 @@
+const fs = require('node:fs')
 const path = require('node:path')
+const { parse } = require('@sullux/markdown-compiler')
+const { parseYaml } = require('./yaml')
 
 const parseArgs = (args = []) => {
   const options = {}
   for (let i = 0; i < args.length; i++) {
     const arg = args[i]
-    if (arg === '-i' || arg === '--input') {
-      options.input = args[++i]
-    } else if (arg === '-o' || arg === '--output') {
-      options.output = args[++i]
-    } else if (arg === '-t' || arg === '--title') {
-      options.title = args[++i]
-    } else if (arg === '--logo') {
-      options.logo = args[++i]
-    } else if (arg === '--baseUrl') {
-      options.baseUrl = args[++i]
-    } else if (arg === '-h' || arg === '--help') {
-      options.help = true
-    }
+    if (arg === '-i' || arg === '--input') options.input = args[++i]
+    else if (arg === '-o' || arg === '--output') options.output = args[++i]
+    else if (arg === '-b' || arg === '--base-url' || arg === '--baseUrl') options.baseUrl = args[++i]
+    else if (arg === '-t' || arg === '--title') options.title = args[++i]
+    else if (arg === '-c' || arg === '--config') options.config = args[++i]
+    else if (arg === '-h' || arg === '--help') options.help = true
   }
   return options
 }
 
+const loadFileConfig = (inputDir, customConfigPath) => {
+  const configFile = customConfigPath ? path.resolve(customConfigPath) : null
+  const candidates = configFile ? [configFile] : [
+    path.join(inputDir, 'docs.yaml'),
+    path.join(inputDir, 'docs.yml'),
+    path.join(inputDir, 'docs.json'),
+  ]
+
+  for (const file of candidates) {
+    if (fs.existsSync(file)) {
+      try {
+        const content = fs.readFileSync(file, 'utf8')
+        if (file.endsWith('.json')) return JSON.parse(content)
+        return parseYaml(content)
+      } catch (e) {
+        return {}
+      }
+    }
+  }
+
+  const summaryPath = path.join(inputDir, 'SUMMARY.md')
+  if (fs.existsSync(summaryPath)) {
+    const ast = parse(fs.readFileSync(summaryPath, 'utf8'))
+    if (ast.frontmatter && Object.keys(ast.frontmatter).length > 0) {
+      return ast.frontmatter
+    }
+  }
+
+  return {}
+}
+
 const normalizeConfig = (opts = {}) => {
   const input = path.resolve(opts.input || process.cwd())
-  const output = path.resolve(opts.output || path.join(input, '_site'))
-  const title = opts.title || path.basename(input)
-  const baseUrl = opts.baseUrl || ''
-  const logo = opts.logo || ''
+  const fileConfig = loadFileConfig(input, opts.config)
+
+  const output = path.resolve(opts.output || fileConfig.output || path.join(input, '_site'))
+  const title = opts.title !== undefined ? opts.title : (fileConfig.title !== undefined ? fileConfig.title : '')
+  const baseUrl = opts.baseUrl !== undefined ? opts.baseUrl : (fileConfig.baseUrl !== undefined ? fileConfig.baseUrl : '')
+  const logo = fileConfig.logo || opts.logo || ''
+  const favicon = fileConfig.favicon || opts.favicon || ''
+  const links = fileConfig.links || opts.links || []
+  const theme = { ...(fileConfig.theme || {}), ...(opts.theme || {}) }
 
-  return { input, output, title, baseUrl, logo }
+  return { input, output, title, baseUrl, logo, favicon, links, theme }
 }
 
-module.exports = { parseArgs, normalizeConfig }
+module.exports = { parseArgs, normalizeConfig, loadFileConfig }

package/lib/icons.js

@@ -0,0 +1,10 @@
+const SVGS = {
+  hamburger: `<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><line x1="4" y1="6" x2="20" y2="6"/><line x1="4" y1="12" x2="20" y2="12"/><line x1="4" y1="18" x2="20" y2="18"/></svg>`,
+  pageIndex: `<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><line x1="4" y1="5" x2="20" y2="5"/><line x1="4" y1="12" x2="4" y2="19"/><line x1="8" y1="12" x2="20" y2="12"/><line x1="8" y1="18" x2="20" y2="18"/></svg>`,
+  close: `<svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>`,
+  sun: `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><circle cx="12" cy="12" r="5"/><line x1="12" y1="1" x2="12" y2="3"/><line x1="12" y1="21" x2="12" y2="23"/><line x1="4.22" y1="4.22" x2="5.64" y2="5.64"/><line x1="18.36" y1="18.36" x2="19.78" y2="19.78"/><line x1="1" y1="12" x2="3" y2="12"/><line x1="21" y1="12" x2="23" y2="12"/><line x1="4.22" y1="19.78" x2="5.64" y2="18.36"/><line x1="18.36" y1="5.64" x2="19.78" y2="4.22"/></svg>`,
+  system: `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><rect x="2" y="3" width="20" height="14" rx="2"/><line x1="8" y1="21" x2="16" y2="21"/><line x1="12" y1="17" x2="12" y2="21"/></svg>`,
+  moon: `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg>`,
+}
+
+module.exports = { SVGS }

package/lib/layout.js

@@ -1,53 +1,95 @@
+const path = require('node:path')
 const { getCss } = require('./theme')
 const { getSearchScript } = require('./search')
+const { SVGS } = require('./icons')
 
-const renderNavItems = (items, currentHref, baseUrl = '') => {
-  if (!items || items.length === 0) return ''
-  return `<ul class="nav-list">\n` + items.map((item) => {
-    const isActive = item.href === currentHref ? ' active' : ''
-    const itemHref = item.href ? `${baseUrl}${item.href.replace(/\.md$/, '.html')}` : '#'
-    const subNav = item.children ? renderNavItems(item.children, currentHref, baseUrl) : ''
-    return `<li class="nav-item">
-      <a href="${itemHref}" class="nav-link${isActive}">${item.title}</a>
-      ${subNav}
-    </li>\n`
-  }).join('') + `</ul>\n`
+const calcRelativeHref = (currentHref, targetHref) => targetHref ? (path.relative(path.dirname(currentHref), targetHref.replace(/\.md$/, '.html')) || './') : '#'
+
+const renderNavTree = (items, currentHref) => {
+  if (!items?.length) return ''
+  let html = '', group = []
+  const flushGroup = () => {
+    if (!group.length) return ''
+    const list = `<ul class="nav-list">\n` + group.map((item) => {
+      const active = item.href === currentHref ? ' active' : ''
+      const href = calcRelativeHref(currentHref, item.href)
+      const sub = item.children?.length ? renderNavTree(item.children, currentHref) : ''
+      return `<li class="nav-item"><a href="${href}" class="nav-link${active}">${item.title}</a>${sub ? `<div class="nav-sub">${sub}</div>` : ''}</li>\n`
+    }).join('') + `</ul>\n`
+    group = []
+    return list
+  }
+  for (const item of items) {
+    if (item.type === 'section') {
+      html += `${flushGroup()}<div class="nav-section-title">${item.title}</div>\n`
+      if (item.items?.length) html += renderNavTree(item.items, currentHref)
+    } else group.push(item)
+  }
+  return html + flushGroup()
+}
+
+const renderTocList = (toc) => toc?.length ? `<div class="toc-title">On this page</div>\n<ul class="toc-list">\n` + toc.map((i) => `<li class="toc-item level-${i.level}"><a href="#${i.id}" class="toc-link" onclick="closeAllDrawers()">${i.title}</a></li>`).join('') + `</ul>\n` : ''
+
+const resolveAssetHref = (currentHref, assetPath) => (!assetPath || assetPath.startsWith('http') || assetPath.startsWith('<svg') || assetPath.startsWith('data:') || assetPath.startsWith('/')) ? assetPath : calcRelativeHref(currentHref, assetPath.replace(/^\.\//, ''))
+
+const renderSingleLogo = (logo, modeClass, title, currentHref) => logo ? (typeof logo === 'string' && logo.startsWith('<svg') ? logo : `<img src="${resolveAssetHref(currentHref, logo)}" alt="${title || 'Logo'}" class="${modeClass ? `brand-logo ${modeClass}` : 'brand-logo'}" />`) : ''
+
+const renderBrandLogo = (logo, title, currentHref) => {
+  const titleSpan = title ? `<span>${title}</span>` : ''
+  if (!logo) return title ? `📚 ${title}` : '📚'
+  if (typeof logo === 'string') return `${renderSingleLogo(logo, '', title, currentHref)}${titleSpan}`
+  if (typeof logo === 'object') return `${renderSingleLogo(logo.light, 'logo-light', title, currentHref)}${renderSingleLogo(logo.dark, 'logo-dark', title, currentHref)}${titleSpan}`
+  return title ? `📚 ${title}` : '📚'
 }
 
-const renderPageLayout = ({ title, navTree, contentHtml, currentHref, baseUrl = '' }) => {
-  const sidebarNav = renderNavItems(navTree, currentHref, baseUrl)
-
-  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>
-  <style>${getCss()}</style>
-</head>
-<body>
-  <aside class="app-sidebar">
-    <a href="${baseUrl}index.html" class="app-title">${title}</a>
-    <div class="search-box">
-      <input type="text" id="doc-search" class="search-input" placeholder="Search docs..." />
-      <div id="search-results" class="search-results"></div>
-    </div>
-    <nav class="app-nav">
-      ${sidebarNav}
-    </nav>
-  </aside>
-  <main class="app-main">
-    <header class="app-header">
-      <span class="header-title">${title}</span>
-      <button class="theme-toggle" onclick="document.body.toggleAttribute('data-theme', document.body.hasAttribute('data-theme') ? '' : 'dark')">Theme</button>
-    </header>
-    <article class="app-content">
-      ${contentHtml}
-    </article>
-  </main>
+const renderFavicon = (f) => f ? `<link rel="icon" href="${f}" />` : `<link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>📚</text></svg>">`
+
+const renderHeaderLinks = (links = []) => links?.length ? `<div class="header-links">` + links.map((l) => `<a href="${l.url}" target="_blank" rel="noopener" class="header-link">${l.title} ↗</a>`).join('') + `</div>` : ''
+
+const renderPageLayout = ({ title, siteTitle, navTree, toc, contentHtml, currentHref, logo, favicon, links, theme }) => {
+  const sidebarNav = renderNavTree(navTree, currentHref)
+  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>${renderFavicon(favicon)}<style>${getCss(theme)}</style>
+  <script>
+    function setThemeMode(m) {
+      try { localStorage.setItem('sullux-theme-mode', m); } catch(e) {}
+      if (m === 'light' || m === 'dark') document.documentElement.setAttribute('data-theme', m); else document.documentElement.removeAttribute('data-theme');
+      document.querySelectorAll('.theme-opt').forEach(function(b) { b.classList.toggle('active', b.getAttribute('data-mode') === m); });
+    }
+    function toggleDrawer(id) {
+      var d = document.getElementById(id), b = document.getElementById('drawer-backdrop'), open = d?.classList.contains('open');
+      closeAllDrawers(); if (!open && d && b) { d.classList.add('open'); b.classList.add('open'); }
+    }
+    function closeAllDrawers() { document.querySelectorAll('.app-sidebar, .app-toc, .drawer-backdrop').forEach(function(e) { e.classList.remove('open'); }); }
+    (function() {
+      var m = 'system'; try { m = localStorage.getItem('sullux-theme-mode') || 'system'; } catch(e) {}
+      if (m === 'light' || m === 'dark') document.documentElement.setAttribute('data-theme', m);
+    })();
+    window.addEventListener('DOMContentLoaded', function() { setThemeMode(localStorage.getItem('sullux-theme-mode') || 'system'); });
+  </script>
+</head><body>
+  <header class="top-header">
+    <div class="header-left"><button class="header-btn hamburger-btn" onclick="toggleDrawer('sidebar-drawer')" aria-label="Toggle navigation">${SVGS.hamburger}</button><a href="${calcRelativeHref(currentHref, 'index.html')}" class="header-brand">${renderBrandLogo(logo, siteTitle, currentHref)}</a></div>
+    <div class="header-center"><div class="search-box"><input type="text" id="doc-search" class="search-input" placeholder="Search docs..." /><div id="search-results" class="search-results"></div></div></div>
+    <div class="header-right">${renderHeaderLinks(links)}<button class="header-btn page-index-btn" onclick="toggleDrawer('toc-drawer')" aria-label="Toggle page outline">${SVGS.pageIndex}</button></div>
+  </header>
+  <div class="app-container">
+    <aside id="sidebar-drawer" class="app-sidebar"><div class="drawer-header"><span class="drawer-title">Navigation</span><button class="drawer-close" onclick="closeAllDrawers()">${SVGS.close}</button></div><nav class="app-nav">${sidebarNav}</nav></aside>
+    <main class="app-main"><article class="app-article">${contentHtml}</article></main>
+    <aside id="toc-drawer" class="app-toc">
+      <div class="drawer-header"><span class="drawer-title">Page Outline</span><button class="drawer-close" onclick="closeAllDrawers()">${SVGS.close}</button></div>
+      ${renderTocList(toc)}
+      <div class="theme-picker">
+        <button class="theme-opt" data-mode="light" onclick="setThemeMode('light')" title="Light">${SVGS.sun}</button>
+        <button class="theme-opt" data-mode="system" onclick="setThemeMode('system')" title="System">${SVGS.system}</button>
+        <button class="theme-opt" data-mode="dark" onclick="setThemeMode('dark')" title="Dark">${SVGS.moon}</button>
+      </div>
+    </aside>
+  </div>
+  <div id="drawer-backdrop" class="drawer-backdrop" onclick="closeAllDrawers()"></div>
   ${getSearchScript()}
-</body>
-</html>`
+</body></html>`
 }
 
-module.exports = { renderPageLayout }
+module.exports = { renderPageLayout, calcRelativeHref }

package/lib/site.js

@@ -1,69 +1,65 @@
 const fs = require('node:fs')
 const path = require('node:path')
+const { parse } = require('@sullux/markdown-compiler')
 const { markdownToHtml } = require('@sullux/markdown-html')
 const { normalizeConfig } = require('./config')
 const { getNavigationTree } = require('./summary')
+const { extractToc } = require('./toc')
 const { renderPageLayout } = require('./layout')
 const { copyAssets } = require('./assets')
 
 const collectMarkdownFiles = (dir, rootDir = dir) => {
   const files = []
-  const entries = fs.readdirSync(dir, { withFileTypes: true })
-
-  for (const entry of entries) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === '_site') continue
     const fullPath = path.join(dir, entry.name)
-
-    if (entry.isDirectory()) {
-      files.push(...collectMarkdownFiles(fullPath, rootDir))
-    } else if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== 'SUMMARY.md') {
-      const relPath = path.relative(rootDir, fullPath)
-      files.push({ fullPath, relPath })
+    if (entry.isDirectory()) files.push(...collectMarkdownFiles(fullPath, rootDir))
+    else if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== 'SUMMARY.md') {
+      files.push({ fullPath, relPath: path.relative(rootDir, fullPath) })
     }
   }
-
   return files
 }
 
+const ensureIndexHtml = (outputDir, generatedPages) => {
+  if (generatedPages.some((p) => p === 'index.md')) return
+  const readmePath = path.join(outputDir, 'README.html'), indexPath = path.join(outputDir, 'index.html')
+  if (fs.existsSync(readmePath)) fs.copyFileSync(readmePath, indexPath)
+  else if (generatedPages.length > 0) {
+    const firstHtmlPath = path.join(outputDir, generatedPages[0].replace(/\.md$/, '.html'))
+    if (fs.existsSync(firstHtmlPath)) fs.copyFileSync(firstHtmlPath, indexPath)
+  }
+}
+
 const generateSite = (options = {}) => {
   const config = normalizeConfig(options)
-  if (!fs.existsSync(config.input)) {
-    throw new Error(`Input directory does not exist: ${config.input}`)
-  }
+  if (!fs.existsSync(config.input)) throw new Error(`Input directory does not exist: ${config.input}`)
 
   fs.mkdirSync(config.output, { recursive: true })
-  const navTree = getNavigationTree(config.input)
-  const mdFiles = collectMarkdownFiles(config.input)
-  const searchIndex = []
+  const navTree = getNavigationTree(config.input), mdFiles = collectMarkdownFiles(config.input), searchIndex = []
 
   for (const file of mdFiles) {
     const rawMd = fs.readFileSync(file.fullPath, 'utf8')
-    const contentHtml = markdownToHtml(rawMd)
-
-    const relHtmlPath = file.relPath.replace(/\.md$/, '.html')
-    const outHtmlPath = path.join(config.output, relHtmlPath)
+    const ast = parse(rawMd), toc = extractToc(ast), rawHtml = markdownToHtml(rawMd)
+    const contentHtml = rawHtml.replace(/href="([^":#]+)\.md(#.*?)?"/g, 'href="$1.html$2"')
+    const relHtmlPath = file.relPath.replace(/\.md$/, '.html'), outHtmlPath = path.join(config.output, relHtmlPath)
 
     fs.mkdirSync(path.dirname(outHtmlPath), { recursive: true })
 
-    const pageTitle = `${file.relPath.replace(/\.md$/, '')} - ${config.title}`
+    const pageTitle = config.title ? `${file.relPath.replace(/\.md$/, '')} - ${config.title}` : file.relPath.replace(/\.md$/, '')
+
     const fullHtml = renderPageLayout({
-      title: pageTitle,
-      navTree,
-      contentHtml,
-      currentHref: file.relPath,
-      baseUrl: config.baseUrl,
+      title: pageTitle, siteTitle: config.title,
+      navTree, toc, contentHtml, currentHref: file.relPath,
+      logo: config.logo, favicon: config.favicon, links: config.links, theme: config.theme,
     })
 
     fs.writeFileSync(outHtmlPath, fullHtml, 'utf8')
-
     const plainText = rawMd.replace(/[#*`_\[\]()\-]/g, ' ').replace(/\s+/g, ' ').trim()
-    searchIndex.push({
-      title: file.relPath.replace(/\.md$/, ''),
-      href: relHtmlPath,
-      content: plainText.slice(0, 300),
-    })
+    searchIndex.push({ title: file.relPath.replace(/\.md$/, ''), href: relHtmlPath, content: plainText.slice(0, 300) })
   }
 
+  ensureIndexHtml(config.output, mdFiles.map((f) => f.relPath))
   fs.writeFileSync(path.join(config.output, 'search-index.json'), JSON.stringify(searchIndex, null, 2))
   copyAssets(config.input, config.output)
 

package/lib/summary.js

@@ -4,22 +4,33 @@ const { parse } = require('@sullux/markdown-compiler')
 
 const parseSummaryMd = (content) => {
   const ast = parse(content)
-  const items = []
+  const nav = []
+  let currentSection = null
 
   for (const block of ast.blocks) {
-    if (block.type === 'bulletList' || block.type === 'orderedList') {
+    if (block.type === 'header' && block.level > 1) {
+      const sectionTitle = block.children ? block.children.map((c) => c.value || '').join('') : ''
+      currentSection = { type: 'section', title: sectionTitle, items: [] }
+      nav.push(currentSection)
+    } else if (block.type === 'bulletList' || block.type === 'orderedList') {
+      const listItems = []
       for (const itemNodes of block.items || []) {
         for (const node of itemNodes) {
           if (node.type === 'link') {
             const title = node.children ? node.children.map((c) => c.value || '').join('') : ''
-            items.push({ title, href: node.url, children: [] })
+            listItems.push({ title, href: node.url, children: [] })
           }
         }
       }
+      if (currentSection) {
+        currentSection.items.push(...listItems)
+      } else {
+        nav.push(...listItems)
+      }
     }
   }
 
-  return items
+  return nav
 }
 
 const scanDir = (dir, rootDir = dir) => {
@@ -34,10 +45,11 @@ const scanDir = (dir, rootDir = dir) => {
     if (entry.isDirectory()) {
       const children = scanDir(fullPath, rootDir)
       if (children.length > 0) {
-        items.push({ title: entry.name, href: '', children })
+        const title = entry.name.replace(/[-_]/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase())
+        items.push({ type: 'section', title, items: children })
       }
     } else if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== 'SUMMARY.md') {
-      const title = entry.name.replace(/\.md$/, '')
+      const title = entry.name.replace(/\.md$/, '').replace(/[-_]/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase())
       items.push({ title, href: relPath, children: [] })
     }
   }
@@ -48,8 +60,7 @@ const scanDir = (dir, rootDir = dir) => {
 const getNavigationTree = (inputDir) => {
   const summaryPath = path.join(inputDir, 'SUMMARY.md')
   if (fs.existsSync(summaryPath)) {
-    const content = fs.readFileSync(summaryPath, 'utf8')
-    return parseSummaryMd(content)
+    return parseSummaryMd(fs.readFileSync(summaryPath, 'utf8'))
   }
   return scanDir(inputDir)
 }