botdocs 0.3.0 → 0.4.0

package/dist/src/builder/embedder.js

@@ -1,4 +1,4 @@
-import { pipeline, env } from '@xenova/transformers';
+import { pipeline, env } from '@huggingface/transformers';
 // Disable local model loading - use Hugging Face
 env.allowLocalModels = false;
 export class Embedder {

package/dist/src/builder/index.js

@@ -20,6 +20,11 @@ export async function build(options) {
     }
     // Load config
     const config = loadConfig(configPath, inputDir);
+    // customCss resolves relative to wherever the config file actually lives,
+    // not inputDir — inputDir is often a regenerated staging directory.
+    const configDir = configPath && existsSync(configPath)
+        ? dirname(resolve(configPath))
+        : inputDir;
     // Override chat enabled setting if specified in CLI
     if (chatEnabled !== undefined) {
         config.chat = config.chat || {};
@@ -139,6 +144,19 @@ export async function build(options) {
             bundledCss += readFileSync(fallbackPath, 'utf-8') + '\n\n';
         }
     }
+    // Append user-supplied custom CSS last so it overrides theme rules of equal specificity
+    if (config.customCss) {
+        const customCssPath = resolve(configDir, config.customCss);
+        if (existsSync(customCssPath)) {
+            bundledCss += readFileSync(customCssPath, 'utf-8') + '\n';
+            if (verbose) {
+                console.log(`Appended custom CSS: ${customCssPath}`);
+            }
+        }
+        else {
+            console.warn(`customCss file not found: ${customCssPath}`);
+        }
+    }
     writeFileSync(join(outputCssDir, 'bundle.css'), bundledCss, 'utf-8');
     if (verbose) {
         console.log('Styles copied');

package/dist/src/builder/markdown-processor.d.ts

@@ -4,13 +4,20 @@ export declare class MarkdownProcessor {
     private shikiInitialized;
     constructor();
     private escapeHtml;
+    private decodeHtmlEntities;
     private setupShiki;
     /**
      * Process a markdown file and extract front matter
      */
     processFile(filePath: string, inputDir: string, content: string): Promise<ProcessedDocument>;
     /**
-     * Extract title from markdown content (first h1) or filename
+     * Extract title from markdown content (first h1) or filename.
+     *
+     * Checks, in order: a markdown `# ` heading, an HTML `<h1>` tag (common
+     * when the heading wraps a logo image), and a lone banner image's alt
+     * text (READMEs that open with `![Project Name](banner.svg)` instead of
+     * a text heading). All matching skips fenced code blocks so shell
+     * comments like `# Start the server:` aren't mistaken for headings.
      */
     private extractTitle;
     /**

package/dist/src/builder/markdown-processor.js

@@ -9,7 +9,7 @@ import sub from 'markdown-it-sub';
 import sup from 'markdown-it-sup';
 import { bundledLanguages, getHighlighter } from 'shiki';
 import matter from 'gray-matter';
-import { relative, basename } from 'path';
+import { relative, basename, dirname } from 'path';
 export class MarkdownProcessor {
     md;
     shikiInitialized = false;
@@ -65,6 +65,15 @@ export class MarkdownProcessor {
             .replace(/"/g, '"')
             .replace(/'/g, ''');
     }
+    decodeHtmlEntities(text) {
+        return text
+            .replace(/ /g, ' ')
+            .replace(/&/g, '&')
+            .replace(/&lt;/g, '<')
+            .replace(/&gt;/g, '>')
+            .replace(/&quot;/g, '"')
+            .replace(/&#0?39;/g, "'");
+    }
     async setupShiki() {
         if (this.shikiInitialized)
             return;
@@ -129,16 +138,40 @@ export class MarkdownProcessor {
         };
     }
     /**
-     * Extract title from markdown content (first h1) or filename
+     * Extract title from markdown content (first h1) or filename.
+     *
+     * Checks, in order: a markdown `# ` heading, an HTML `<h1>` tag (common
+     * when the heading wraps a logo image), and a lone banner image's alt
+     * text (READMEs that open with `![Project Name](banner.svg)` instead of
+     * a text heading). All matching skips fenced code blocks so shell
+     * comments like `# Start the server:` aren't mistaken for headings.
      */
     extractTitle(content, relativePath) {
-        const h1Match = content.match(/^#\s+(.+)$/m);
+        const withoutCodeFences = content.replace(/^```[\s\S]*?^```/gm, '');
+        const h1Match = withoutCodeFences.match(/^#\s+(.+)$/m);
         if (h1Match) {
-            return h1Match[1];
+            return h1Match[1].trim();
+        }
+        const htmlH1Match = withoutCodeFences.match(/<h1[^>]*>([\s\S]*?)<\/h1>/i);
+        if (htmlH1Match) {
+            const text = this.decodeHtmlEntities(htmlH1Match[1].replace(/<[^>]+>/g, ''))
+                .replace(/\s+/g, ' ')
+                .trim();
+            if (text) {
+                return text;
+            }
+        }
+        const bannerImageMatch = withoutCodeFences.match(/^!\[([^\]]+)\]\([^)]*\)\s*$/m);
+        if (bannerImageMatch) {
+            return bannerImageMatch[1].trim();
         }
-        // Fallback to filename
-        return basename(relativePath, '.md')
-            .replace(/-/g, ' ')
+        // Fallback to filename, or the parent directory name for README/index
+        // files where the filename itself carries no useful title.
+        const base = basename(relativePath, '.md');
+        const parentDir = basename(dirname(relativePath));
+        const name = /^(readme|index)$/i.test(base) && parentDir !== '.' ? parentDir : base;
+        return name
+            .replace(/[-_]/g, ' ')
             .replace(/\b\w/g, (char) => char.toUpperCase());
     }
     /**

package/dist/src/builder/site-generator.d.ts

@@ -10,13 +10,28 @@ export declare class SiteGenerator {
      */
     generate(inputDir: string, outputDir: string, config: BotdocsConfig): Promise<ProcessedDocument[]>;
     /**
-     * Build navigation structure from documents
+     * Build navigation structure from documents, grouping by top-level
+     * folder so e.g. every doc under `path-of-python/` (its README plus
+     * anything in `path-of-python/docs/`) nests under one "Path of Python"
+     * entry instead of interleaving flat with every other folder's pages.
+     * Files at the root (no folder) stay flat, top-level entries.
      */
     private buildNavigation;
     /**
-     * Render navigation HTML
+     * Render navigation HTML. Folder groups only expand their children when
+     * the current page is the group's root or one of its children — every
+     * other page sees the group collapsed to a single link that leads to
+     * its root README.
      */
     private renderNavigation;
+    /**
+     * Compute prev/next page links that walk the top-level navigation
+     * (root README to root README) rather than the flat, alphabetical
+     * document list — so paging from a folder's root never dips into that
+     * folder's children. Paging from within a group's children walks those
+     * siblings first, then rolls into the next top-level entry.
+     */
+    private buildPageSequence;
     /**
      * Get all processed documents
      */

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

@@ -1,10 +1,13 @@
 import { readFileSync, writeFileSync, readdirSync, mkdirSync, cpSync } from 'fs';
-import { join, dirname, resolve } from 'path';
+import { join, dirname, resolve, basename } from 'path';
 import { MarkdownProcessor } from './markdown-processor.js';
 import { TemplateEngine } from './template-engine.js';
 import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
+function stripHtml(value) {
+    return value.replace(/<[^>]*>/g, '');
+}
 export class SiteGenerator {
     processor;
     templateEngine;
@@ -42,6 +45,7 @@ export class SiteGenerator {
         this.documents.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
         // Generate navigation
         const navigation = this.buildNavigation(this.documents);
+        const pageSequence = this.buildPageSequence(navigation);
         // Load templates from source directory (not dist)
         // From dist/src/builder, go to project root, then to src/templates
         const templatesDir = resolve(__dirname, '../../../src/templates');
@@ -54,8 +58,7 @@ export class SiteGenerator {
             const doc = this.documents[i];
             const isIndex = doc.relativePath === 'README.md' || doc.relativePath === 'index.md';
             // Prepare navigation data
-            const prevDoc = i > 0 ? this.documents[i - 1] : null;
-            const nextDoc = i < this.documents.length - 1 ? this.documents[i + 1] : null;
+            const adjacent = pageSequence.get(doc.url);
             // Render document content
             const contentTemplate = isIndex ? indexTemplate : docPageTemplate;
             const content = this.templateEngine.renderWithLoops(contentTemplate, {
@@ -70,23 +73,17 @@ export class SiteGenerator {
                         url: d.url,
                     }))
                     : undefined,
-                prevPage: prevDoc
-                    ? {
-                        title: prevDoc.metadata.title,
-                        url: prevDoc.url,
-                    }
-                    : undefined,
-                nextPage: nextDoc
-                    ? {
-                        title: nextDoc.metadata.title,
-                        url: nextDoc.url,
-                    }
-                    : undefined,
+                prevPage: adjacent?.prev,
+                nextPage: adjacent?.next,
             });
             // Render full page with layout
             const html = this.templateEngine.renderWithLoops(layoutTemplate, {
                 title: doc.metadata.title || 'Documentation',
-                description: doc.metadata.description || config.description || '',
+                // The template engine doesn't escape interpolated values, so
+                // config.description may contain markup (e.g. a hotlink) meant
+                // for the visible siteDescription below — strip it here since
+                // this one lands inside a <meta content="..."> attribute.
+                description: stripHtml(doc.metadata.description || config.description || ''),
                 siteTitle: config.title || 'Documentation',
                 siteDescription: config.description || '',
                 content,
@@ -112,22 +109,52 @@ export class SiteGenerator {
         return this.documents;
     }
     /**
-     * Build navigation structure from documents
+     * Build navigation structure from documents, grouping by top-level
+     * folder so e.g. every doc under `path-of-python/` (its README plus
+     * anything in `path-of-python/docs/`) nests under one "Path of Python"
+     * entry instead of interleaving flat with every other folder's pages.
+     * Files at the root (no folder) stay flat, top-level entries.
      */
     buildNavigation(documents) {
         const nav = [];
+        const groups = new Map();
         for (const doc of documents) {
             const parts = doc.relativePath.split('/');
-            const title = doc.metadata.title || parts[parts.length - 1].replace(/\.md$/, '');
-            nav.push({
-                title,
-                url: doc.url,
-            });
+            const title = doc.metadata.title || basename(doc.relativePath, '.md');
+            const isRootIndex = doc.relativePath === 'README.md' || doc.relativePath === 'index.md';
+            if (parts.length === 1) {
+                if (!isRootIndex) {
+                    nav.push({ title, url: doc.url });
+                }
+                continue;
+            }
+            const folder = parts[0];
+            const restOfPath = parts.slice(1).join('/');
+            const isFolderIndex = restOfPath === 'README.md' || restOfPath === 'index.md';
+            let group = groups.get(folder);
+            if (!group) {
+                group = {
+                    title: folder.replace(/[-_]/g, ' ').replace(/\b\w/g, (char) => char.toUpperCase()),
+                    url: doc.url,
+                    children: [],
+                };
+                groups.set(folder, group);
+                nav.push(group);
+            }
+            if (isFolderIndex) {
+                group.url = doc.url;
+            }
+            else {
+                group.children.push({ title, url: doc.url });
+            }
         }
         return nav;
     }
     /**
-     * Render navigation HTML
+     * Render navigation HTML. Folder groups only expand their children when
+     * the current page is the group's root or one of its children — every
+     * other page sees the group collapsed to a single link that leads to
+     * its root README.
      */
     renderNavigation(items, currentUrl) {
         if (items.length === 0)
@@ -135,10 +162,14 @@ export class SiteGenerator {
         let html = '<ul class="nav-list">';
         for (const item of items) {
             const isActive = item.url === currentUrl;
-            const activeClass = isActive ? ' class="active"' : '';
-            html += `<li${activeClass}>`;
-            html += `<a href="${item.url}"${activeClass}>${item.title}</a>`;
-            if (item.children && item.children.length > 0) {
+            const hasChildren = !!item.children && item.children.length > 0;
+            const isExpanded = hasChildren && (isActive || item.children.some((child) => child.url === currentUrl));
+            const liClasses = [isActive && 'active', hasChildren && 'nav-group']
+                .filter(Boolean)
+                .join(' ');
+            html += `<li${liClasses ? ` class="${liClasses}"` : ''}>`;
+            html += `<a href="${item.url}"${isActive ? ' class="active"' : ''}>${item.title}</a>`;
+            if (isExpanded) {
                 html += this.renderNavigation(item.children, currentUrl);
             }
             html += '</li>';
@@ -146,6 +177,30 @@ export class SiteGenerator {
         html += '</ul>';
         return html;
     }
+    /**
+     * Compute prev/next page links that walk the top-level navigation
+     * (root README to root README) rather than the flat, alphabetical
+     * document list — so paging from a folder's root never dips into that
+     * folder's children. Paging from within a group's children walks those
+     * siblings first, then rolls into the next top-level entry.
+     */
+    buildPageSequence(navigation) {
+        const positions = new Map();
+        const asLink = (item) => ({ title: item.title, url: item.url });
+        for (let i = 0; i < navigation.length; i++) {
+            const item = navigation[i];
+            const prevTop = i > 0 ? asLink(navigation[i - 1]) : undefined;
+            const nextTop = i < navigation.length - 1 ? asLink(navigation[i + 1]) : undefined;
+            positions.set(item.url, { prev: prevTop, next: nextTop });
+            const children = item.children ?? [];
+            for (let j = 0; j < children.length; j++) {
+                const prev = j === 0 ? asLink(item) : asLink(children[j - 1]);
+                const next = j < children.length - 1 ? asLink(children[j + 1]) : nextTop;
+                positions.set(children[j].url, { prev, next });
+            }
+        }
+        return positions;
+    }
     /**
      * Get all processed documents
      */

package/dist/src/cli/index.js

@@ -18,7 +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('-t, --theme <theme>', 'Theme to use (classic, material, minimal, slate, modern); overrides config file if set')
     .option('-v, --verbose', 'Enable verbose logging')
     .action(async (input, options) => {
     try {
@@ -29,7 +29,7 @@ program
             console.log(`Input: ${inputDir}`);
             console.log(`Output: ${outputDir}`);
             console.log(`Chat enabled: ${!options.noChat}`);
-            console.log(`Theme: ${options.theme || defaultOptions.theme}`);
+            console.log(`Theme override: ${options.theme || '(none — using config file or default)'}`);
         }
         await build({
             inputDir,

package/dist/src/cli/options.js

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

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

@@ -3,6 +3,7 @@ export interface BotdocsConfig {
     title?: string;
     description?: string;
     theme?: Theme;
+    customCss?: string;
     attribution?: boolean;
     chat?: {
         enabled?: boolean;