botdocs 0.1.1 → 0.3.0

package/README.md

@@ -1,5 +1,7 @@
 # Botdocs
 
+[![npm version](https://img.shields.io/npm/v/botdocs.svg)](https://www.npmjs.com/package/botdocs)
+
 Convert markdown documentation into beautiful static sites with AI-powered semantic search — no backend required.
 
 ## Features
@@ -33,8 +35,35 @@ botdocs ./docs -o ./public
 
 # Verbose logging
 botdocs ./docs -v
+
+# Use a specific theme
+botdocs ./docs -t material
+
+# Custom config file
+botdocs ./docs -c ./my-config.json
+
+# Combine multiple options
+botdocs ./docs -o ./public -t slate -v
 ```
 
+### CLI Options
+
+| Option | Alias | Description | Default |
+|--------|-------|-------------|---------|
+| `--output <dir>` | `-o` | Output directory for generated site | `output` |
+| `--no-chat` | | Disable AI chatbot functionality | `false` |
+| `--config <file>` | `-c` | Path to config file | `botdocs.config.json` |
+| `--theme <theme>` | `-t` | Theme to use | `classic` |
+| `--verbose` | `-v` | Enable verbose logging | `false` |
+
+### Available Themes
+
+- **classic** - Clean, professional theme (default)
+- **material** - Material Design theme
+- **minimal** - Clean, minimalist theme
+- **slate** - Dark slate theme
+- **modern** - Modern documentation theme
+
 ## Configuration
 
 Create `botdocs.config.json` in your docs directory:
@@ -43,15 +72,31 @@ Create `botdocs.config.json` in your docs directory:
 {
   "title": "My Documentation",
   "description": "Project docs",
+  "theme": "classic",
+  "attribution": true,
   "chat": { "enabled": true },
   "build": {
     "chunkSize": 500,
     "chunkOverlap": 50,
-    "topK": 5
+    "topK": 3
   }
 }
 ```
 
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `title` | string | `"Documentation"` | Site title |
+| `description` | string | `"Project documentation"` | Site description |
+| `theme` | string | `"classic"` | Theme to use (classic, material, minimal, slate, modern) |
+| `attribution` | boolean | `true` | Show "Built with Botdocs" footer link |
+| `chat.enabled` | boolean | `true` | Enable AI chatbot |
+| `chat.welcomeMessage` | string | `"Ask me anything about the docs!"` | Chatbot welcome message |
+| `build.chunkSize` | number | `500` | Text chunk size for embeddings |
+| `build.chunkOverlap` | number | `50` | Overlap between chunks |
+| `build.topK` | number | `3` | Number of results to return |
+
 ## Front Matter
 
 ```markdown

package/dist/src/builder/chunker.d.ts

@@ -17,7 +17,7 @@ export declare class Chunker {
     /**
      * Chunk a document into semantically meaningful pieces
      */
-    chunkDocument(doc: ProcessedDocument): TextChunk[];
+    chunkDocument(doc: ProcessedDocument, fileHash?: string): TextChunk[];
     /**
      * Create a chunk with metadata
      */
@@ -37,5 +37,5 @@ export declare class Chunker {
     /**
      * Chunk multiple documents
      */
-    chunkDocuments(documents: ProcessedDocument[]): TextChunk[];
+    chunkDocuments(documents: ProcessedDocument[], fileHashes?: Map<string, string>): TextChunk[];
 }

package/dist/src/builder/chunker.js

@@ -12,7 +12,7 @@ export class Chunker {
     /**
      * Chunk a document into semantically meaningful pieces
      */
-    chunkDocument(doc) {
+    chunkDocument(doc, fileHash) {
         const chunks = [];
         const lines = doc.content.split('\n');
         let currentChunk = [];
@@ -47,7 +47,7 @@ export class Chunker {
             if (headingMatch) {
                 // Save current chunk if it exists
                 if (currentChunk.length > 0) {
-                    chunks.push(this.createChunk(currentChunk.join('\n'), doc, currentHeading));
+                    chunks.push(this.createChunk(currentChunk.join('\n'), doc, currentHeading, fileHash));
                 }
                 // Start new chunk with this heading
                 currentHeading = headingMatch[2];
@@ -60,7 +60,7 @@ export class Chunker {
                 if (tokenCount >= this.options.maxChunkSize) {
                     // Split chunk
                     const chunkText = currentChunk.join('\n');
-                    chunks.push(this.createChunk(chunkText, doc, currentHeading));
+                    chunks.push(this.createChunk(chunkText, doc, currentHeading, fileHash));
                     // Create overlap for next chunk
                     const overlapLines = this.getOverlapLines(currentChunk, this.options.chunkOverlap);
                     currentChunk = overlapLines;
@@ -69,14 +69,14 @@ export class Chunker {
         }
         // Add final chunk
         if (currentChunk.length > 0) {
-            chunks.push(this.createChunk(currentChunk.join('\n'), doc, currentHeading));
+            chunks.push(this.createChunk(currentChunk.join('\n'), doc, currentHeading, fileHash));
         }
         return chunks.filter((chunk) => chunk.text.trim().length > 0);
     }
     /**
      * Create a chunk with metadata
      */
-    createChunk(text, doc, heading) {
+    createChunk(text, doc, heading, fileHash) {
         return {
             text: text.trim(),
             metadata: {
@@ -85,6 +85,7 @@ export class Chunker {
                 heading,
                 headingId: heading ? this.slugify(heading) : undefined,
                 url: doc.url,
+                fileHash,
             },
         };
     }
@@ -128,10 +129,11 @@ export class Chunker {
     /**
      * Chunk multiple documents
      */
-    chunkDocuments(documents) {
+    chunkDocuments(documents, fileHashes) {
         const allChunks = [];
         for (const doc of documents) {
-            const chunks = this.chunkDocument(doc);
+            const fileHash = fileHashes?.get(doc.relativePath);
+            const chunks = this.chunkDocument(doc, fileHash);
             allChunks.push(...chunks);
         }
         return allChunks;

package/dist/src/builder/index.js

@@ -13,7 +13,7 @@ const __dirname = dirname(__filename);
  * Main build orchestrator
  */
 export async function build(options) {
-    const { inputDir, outputDir, chatEnabled, configPath, verbose } = options;
+    const { inputDir, outputDir, chatEnabled, configPath, verbose, theme } = options;
     // Validate input directory
     if (!existsSync(inputDir)) {
         throw new Error(`Input directory does not exist: ${inputDir}`);
@@ -25,6 +25,10 @@ export async function build(options) {
         config.chat = config.chat || {};
         config.chat.enabled = chatEnabled;
     }
+    // Override theme if specified in CLI
+    if (theme) {
+        config.theme = theme;
+    }
     if (verbose) {
         console.log('Configuration:', JSON.stringify(config, null, 2));
     }
@@ -107,9 +111,12 @@ export async function build(options) {
     console.log('Copying styles...');
     // From dist/src/builder, go to project root, then to src/styles
     const stylesDir = resolve(__dirname, '../../../src/styles');
+    const themesDir = join(stylesDir, 'themes');
     const outputCssDir = join(assetsDir, 'css');
-    // Combine all CSS files into one bundle
-    const cssFiles = ['main.css', 'themes.css', 'chat.css'];
+    // Determine which theme to use
+    const selectedTheme = config.theme || defaultConfig.theme || 'classic';
+    // Combine CSS files: base styles + selected theme + chat
+    const cssFiles = ['themes.css', 'chat.css'];
     let bundledCss = '';
     for (const cssFile of cssFiles) {
         const cssPath = join(stylesDir, cssFile);
@@ -117,6 +124,21 @@ export async function build(options) {
             bundledCss += readFileSync(cssPath, 'utf-8') + '\n\n';
         }
     }
+    // Add selected theme CSS
+    const themePath = join(themesDir, `${selectedTheme}.css`);
+    if (existsSync(themePath)) {
+        bundledCss += readFileSync(themePath, 'utf-8') + '\n\n';
+        if (verbose) {
+            console.log(`Using theme: ${selectedTheme}`);
+        }
+    }
+    else {
+        console.warn(`Theme '${selectedTheme}' not found, falling back to classic`);
+        const fallbackPath = join(themesDir, 'classic.css');
+        if (existsSync(fallbackPath)) {
+            bundledCss += readFileSync(fallbackPath, 'utf-8') + '\n\n';
+        }
+    }
     writeFileSync(join(outputCssDir, 'bundle.css'), bundledCss, 'utf-8');
     if (verbose) {
         console.log('Styles copied');

package/dist/src/builder/site-generator.js

@@ -92,6 +92,7 @@ export class SiteGenerator {
                 content,
                 navigation: this.renderNavigation(navigation, doc.url),
                 chatEnabled: config.chat?.enabled,
+                attribution: config.attribution !== false, // defaults to true
             });
             // Write HTML file
             const outputPath = join(outputDir, doc.relativePath.replace(/\.md$/, '.html'));

package/dist/src/builder/vector-db-builder.d.ts

@@ -10,9 +10,21 @@ export declare class VectorDBBuilder {
     private embedder;
     constructor(options?: VectorDBBuilderOptions);
     /**
-     * Build vector database from documents
+     * Build vector database from documents (with incremental build support)
      */
     build(documents: ProcessedDocument[], outputDir: string, verbose?: boolean): Promise<VectorDatabase>;
+    /**
+     * Load existing vector database from disk
+     */
+    private loadExistingDatabase;
+    /**
+     * Build a map of sourceFile -> chunks for quick lookup
+     */
+    private buildCacheMap;
+    /**
+     * Hash file content for change detection
+     */
+    private hashContent;
     /**
      * Generate unique ID for a chunk
      */

package/dist/src/builder/vector-db-builder.js

@@ -1,6 +1,6 @@
 import { Chunker } from './chunker.js';
 import { Embedder } from './embedder.js';
-import { writeFileSync } from 'fs';
+import { writeFileSync, existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { createHash } from 'crypto';
 export class VectorDBBuilder {
@@ -14,43 +14,130 @@ export class VectorDBBuilder {
         this.embedder = new Embedder(options.modelName);
     }
     /**
-     * Build vector database from documents
+     * Build vector database from documents (with incremental build support)
      */
     async build(documents, outputDir, verbose = false) {
         if (verbose) {
             console.log('Building vector database...');
         }
-        // Step 1: Chunk documents
-        console.log('Chunking documents...');
-        const chunks = this.chunker.chunkDocuments(documents);
-        console.log(`Created ${chunks.length} chunks`);
-        // Step 2: Generate embeddings
-        console.log('Generating embeddings...');
-        await this.embedder.initialize();
-        const texts = chunks.map((chunk) => chunk.text);
-        const embeddings = await this.embedder.embedBatch(texts, 10);
-        // Step 3: Create document chunks with embeddings
-        const documentChunks = chunks.map((chunk, index) => ({
-            id: this.generateChunkId(chunk.text, chunk.metadata.sourceFile, index),
-            text: chunk.text,
-            embedding: embeddings[index],
-            metadata: chunk.metadata,
-        }));
-        // Step 4: Create vector database
+        const outputPath = join(outputDir, 'vector-db.json');
+        // Step 1: Load existing vector database for incremental builds
+        const existingDB = this.loadExistingDatabase(outputPath, verbose);
+        const cachedChunks = this.buildCacheMap(existingDB);
+        // Step 2: Hash documents and determine what needs rebuilding
+        const fileHashes = new Map();
+        const changedDocs = [];
+        const unchangedDocs = [];
+        for (const doc of documents) {
+            const hash = this.hashContent(doc.content);
+            fileHashes.set(doc.relativePath, hash);
+            const cachedDocChunks = cachedChunks.get(doc.relativePath);
+            if (cachedDocChunks && cachedDocChunks[0]?.metadata.fileHash === hash) {
+                unchangedDocs.push(doc);
+                if (verbose) {
+                    console.log(`  ✓ Cached: ${doc.relativePath}`);
+                }
+            }
+            else {
+                changedDocs.push(doc);
+                if (verbose) {
+                    console.log(`  ⟳ Changed: ${doc.relativePath}`);
+                }
+            }
+        }
+        console.log(`Unchanged: ${unchangedDocs.length}, Changed: ${changedDocs.length}, Total: ${documents.length}`);
+        // Step 3: Reuse cached chunks for unchanged documents
+        const reusedChunks = [];
+        for (const doc of unchangedDocs) {
+            const chunks = cachedChunks.get(doc.relativePath);
+            if (chunks) {
+                reusedChunks.push(...chunks);
+            }
+        }
+        // Step 4: Process changed documents only
+        let newChunks = [];
+        if (changedDocs.length > 0) {
+            console.log('Chunking changed documents...');
+            const chunks = this.chunker.chunkDocuments(changedDocs, fileHashes);
+            console.log(`Created ${chunks.length} chunks from ${changedDocs.length} changed documents`);
+            // Generate embeddings only for changed documents
+            console.log('Generating embeddings for changed documents...');
+            await this.embedder.initialize();
+            const texts = chunks.map((chunk) => chunk.text);
+            const embeddings = await this.embedder.embedBatch(texts, 10);
+            // Create document chunks with embeddings
+            newChunks = chunks.map((chunk, index) => ({
+                id: this.generateChunkId(chunk.text, chunk.metadata.sourceFile, index),
+                text: chunk.text,
+                embedding: embeddings[index],
+                metadata: chunk.metadata,
+            }));
+        }
+        else {
+            console.log('No changes detected - reusing all cached embeddings');
+        }
+        // Step 5: Merge cached and new chunks
+        const allChunks = [...reusedChunks, ...newChunks];
+        // Step 6: Create vector database
         const vectorDB = {
             version: '1.0',
             model: this.embedder.getModelName(),
             dimension: this.embedder.getDimension(),
-            chunks: documentChunks,
+            chunks: allChunks,
         };
-        // Step 5: Write to file
-        const outputPath = join(outputDir, 'vector-db.json');
+        // Step 7: Write to file
         writeFileSync(outputPath, JSON.stringify(vectorDB, null, 2), 'utf-8');
         console.log(`Vector database saved: ${outputPath}`);
-        console.log(`Total chunks: ${vectorDB.chunks.length}`);
+        console.log(`Total chunks: ${vectorDB.chunks.length} (${reusedChunks.length} cached, ${newChunks.length} new)`);
         console.log(`Embedding dimension: ${vectorDB.dimension}`);
         return vectorDB;
     }
+    /**
+     * Load existing vector database from disk
+     */
+    loadExistingDatabase(outputPath, verbose) {
+        if (!existsSync(outputPath)) {
+            if (verbose) {
+                console.log('No existing vector database found - performing full build');
+            }
+            return null;
+        }
+        try {
+            const content = readFileSync(outputPath, 'utf-8');
+            const db = JSON.parse(content);
+            if (verbose) {
+                console.log(`Loaded existing vector database with ${db.chunks.length} chunks`);
+            }
+            return db;
+        }
+        catch (error) {
+            console.warn('Failed to load existing vector database - performing full build');
+            return null;
+        }
+    }
+    /**
+     * Build a map of sourceFile -> chunks for quick lookup
+     */
+    buildCacheMap(db) {
+        const cache = new Map();
+        if (!db) {
+            return cache;
+        }
+        for (const chunk of db.chunks) {
+            const sourceFile = chunk.metadata.sourceFile;
+            if (!cache.has(sourceFile)) {
+                cache.set(sourceFile, []);
+            }
+            cache.get(sourceFile).push(chunk);
+        }
+        return cache;
+    }
+    /**
+     * Hash file content for change detection
+     */
+    hashContent(content) {
+        return createHash('md5').update(content).digest('hex');
+    }
     /**
      * Generate unique ID for a chunk
      */

package/dist/src/cli/index.js

@@ -18,6 +18,7 @@ program
     .option('-o, --output <dir>', 'Output directory for generated site', defaultOptions.output)
     .option('--no-chat', 'Disable AI chatbot functionality')
     .option('-c, --config <file>', 'Path to config file (botdocs.config.json)')
+    .option('-t, --theme <theme>', 'Theme to use (classic, material, minimal, slate, modern)', defaultOptions.theme)
     .option('-v, --verbose', 'Enable verbose logging')
     .action(async (input, options) => {
     try {
@@ -28,6 +29,7 @@ program
             console.log(`Input: ${inputDir}`);
             console.log(`Output: ${outputDir}`);
             console.log(`Chat enabled: ${!options.noChat}`);
+            console.log(`Theme: ${options.theme || defaultOptions.theme}`);
         }
         await build({
             inputDir,
@@ -35,6 +37,7 @@ program
             chatEnabled: !options.noChat,
             configPath: options.config,
             verbose: options.verbose || false,
+            theme: options.theme,
         });
         console.log('Build complete!');
         console.log(`Site generated at: ${outputDir}`);

package/dist/src/cli/options.d.ts

@@ -1,7 +1,9 @@
+export type Theme = 'classic' | 'material' | 'minimal' | 'slate' | 'modern';
 export interface CliOptions {
     output?: string;
     noChat?: boolean;
     config?: string;
     verbose?: boolean;
+    theme?: Theme;
 }
 export declare const defaultOptions: Partial<CliOptions>;

package/dist/src/cli/options.js

@@ -2,4 +2,5 @@ export const defaultOptions = {
     output: 'output',
     noChat: false,
     verbose: false,
+    theme: 'classic',
 };

package/dist/src/types/config.d.ts

@@ -1,9 +1,9 @@
+export type Theme = 'classic' | 'material' | 'minimal' | 'slate' | 'modern';
 export interface BotdocsConfig {
     title?: string;
     description?: string;
-    theme?: {
-        primaryColor?: string;
-    };
+    theme?: Theme;
+    attribution?: boolean;
     chat?: {
         enabled?: boolean;
         welcomeMessage?: string;
@@ -20,5 +20,6 @@ export interface BuildOptions {
     chatEnabled: boolean;
     configPath?: string;
     verbose: boolean;
+    theme?: Theme;
 }
 export declare const defaultConfig: BotdocsConfig;

package/dist/src/types/config.js

@@ -1,9 +1,8 @@
 export const defaultConfig = {
     title: 'Documentation',
     description: 'Project documentation',
-    theme: {
-        primaryColor: '#3b82f6',
-    },
+    theme: 'classic',
+    attribution: true,
     chat: {
         enabled: true,
         welcomeMessage: 'Ask me anything about the docs!',
@@ -11,6 +10,6 @@ export const defaultConfig = {
     build: {
         chunkSize: 500,
         chunkOverlap: 50,
-        topK: 5,
+        topK: 3,
     },
 };

package/dist/src/types/vector-db.d.ts

@@ -6,6 +6,7 @@ export interface ChunkMetadata {
     url: string;
     startLine?: number;
     endLine?: number;
+    fileHash?: string;
 }
 export interface DocumentChunk {
     id: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "botdocs",
-  "version": "0.1.1",
-  "description": "An npm CLI tool that converts markdown documentation into a static website with an optional client-side AI chatbot",
+  "version": "0.3.0",
+  "description": "CLI tool that converts markdown documentation into a static website with an optional client-side AI chatbot",
   "author": "usr-wwelsh <https://wwel.sh>",
   "license": "MIT",
   "bin": {

package/src/styles/main.css

@@ -503,6 +503,29 @@ img {
   font-size: 0.875rem;
 }
 
+/* Footer Attribution */
+.botdocs-attribution {
+  margin-top: 4rem;
+  padding-top: 2rem;
+  border-top: 1px solid var(--border-color);
+  text-align: center;
+  font-size: 0.875rem;
+  color: var(--text-secondary);
+  opacity: 0.8;
+}
+
+.botdocs-attribution a {
+  color: var(--text-secondary);
+  text-decoration: none;
+  font-weight: 500;
+  transition: color 0.2s;
+}
+
+.botdocs-attribution a:hover {
+  color: var(--link-color);
+  text-decoration: none;
+}
+
 /* Responsive */
 @media (max-width: 768px) {
   .sidebar {