@kenjura/ursa 0.49.0 → 0.51.0

package/CHANGELOG.md

@@ -1,7 +1,29 @@
+# 0.51.0
+2025-12-21
+
+- Existing .html files are no longer overwritten by generated documents.
+
+# 0.50.0
+2025-12-21
+
+### Performance Optimizations
+- **CSS Path Caching**: Implemented caching for `findStyleCss()` lookups during generation. Reduces redundant filesystem walks for documents in the same directory tree.
+- **Template Replacement Optimization**: Changed from 8 sequential `string.replace()` calls to a single regex pass, reducing intermediate string allocations.
+- **Wikitext Regex Pre-compilation**: Pre-compiled ~40 regex patterns at module load time instead of compiling on every `wikiToHtml()` call.
+
+### New Features
+- **Static File Watch**: `ursa serve` now watches for new/changed static files (images, fonts, PDFs, etc.) and automatically copies them to output without requiring a full rebuild.
+
+### Bug Fixes
+- **Menu Folder Expansion**: Fixed issue where navigating to `/folder` wouldn't auto-expand the menu, but `/folder/index.html` would. Both now behave consistently by normalizing trailing slashes in URL comparison.
+
+
 # 0.49.0
 2025-12-20
 
 - Fixed more instances of false inactive links, this time in wikitext files (.txt)
+- **Auto-Index Style Fix**: Auto-generated index pages now correctly inherit `style.css` from parent folders, just like normal documents
+- **Clean Build Fix**: The `--clean` flag now properly clears the output directory before generation. Previously it only ignored the hash cache, which could leave stale files (like old auto-generated indexes) that would block new generation.
 
 
 # 0.48.0

package/README.md

@@ -65,6 +65,8 @@ Start a development server that:
 - `--output, -o` - Output directory for generated site (default: "output")
 - `--port, -p` - Port for development server (default: 8080, serve command only)
 - `--whitelist, -w` - Path to whitelist file containing patterns for files to include
+- `--exclude, -e` - Folders to exclude: comma-separated paths relative to source, or path to file with one folder per line
+- `--clean` - Clear output directory and ignore cache, forcing full regeneration
 
 ### Whitelist File Format
 
@@ -94,6 +96,34 @@ important-document
 classes/wizard
 ```
 
+### Exclude Option
+
+The `--exclude` option allows you to skip certain folders during generation. This can be specified as:
+
+1. **Comma-separated paths** directly on the command line:
+```bash
+ursa content --exclude=archive,drafts,old-content
+ursa serve content --exclude=test,backup
+```
+
+2. **A file path** containing one folder per line:
+```bash
+ursa content --exclude=exclude-list.txt
+```
+
+The exclude file format is similar to the whitelist:
+
+```text
+# Comments start with # and are ignored
+# Empty lines are also ignored
+
+# Folders to exclude (relative to source)
+archive
+drafts
+old-content/v1
+test/fixtures
+```
+
 ### Large Workloads
 
 For sites with many documents (hundreds or thousands), you may need to increase Node.js memory limits:

package/meta/menu.js

@@ -206,8 +206,9 @@ document.addEventListener('DOMContentLoaded', () => {
         if (!item.href) return false;
         const currentHref = window.location.pathname;
         // Normalize paths for comparison - decode URI components to handle spaces and special chars
-        const normalizedItemHref = decodeURIComponent(item.href).replace(/\/index\.html$/, '').replace(/\.html$/, '');
-        const normalizedCurrentHref = decodeURIComponent(currentHref).replace(/\/index\.html$/, '').replace(/\.html$/, '');
+        // Also strip trailing slashes and /index.html for consistent comparison
+        const normalizedItemHref = decodeURIComponent(item.href).replace(/\/index\.html$/, '').replace(/\.html$/, '').replace(/\/$/, '');
+        const normalizedCurrentHref = decodeURIComponent(currentHref).replace(/\/index\.html$/, '').replace(/\.html$/, '').replace(/\/$/, '');
         return normalizedItemHref === normalizedCurrentHref;
     }
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@kenjura/ursa",
   "author": "Andrew London <andrew@kenjura.com>",
   "type": "module",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "description": "static site generator from MD/wikitext/YML",
   "main": "lib/index.js",
   "bin": {

package/src/helper/wikitextHelper.js

@@ -2,6 +2,48 @@ import { getImageTag } from './WikiImage.js';
 
 let instance = {};
 
+// Pre-compiled regex patterns for better performance
+// These are created once at module load time instead of on every call
+const REGEX = {
+  menuStyle: /^_(menu|style)/,
+  hasH1: /^=([^=\n]+)=/,
+  noH1: /^__NOH1__/,
+  noH1Replace: /__NOH1__/g,
+  nowiki: /<nowiki>([\d\D]*?)<\/nowiki>/g,
+  codeBlock: /^ ([^\n]*)$/gm,
+  htmlTag: /<\/?[A-Za-z][^>]*>/g,
+  h3: /^===([^=\n]+)===/gm,
+  h2: /^==([^=\n]+)==/gm,
+  h1: /^=([^=\n]+)=/gm,
+  numberedList: /(\n|^)#([\d\D]*?)(\n(?!#)|$)/g,
+  bulletList: /(\n|^)\*([\d\D]*?)(\n(?!\*)|$)/g,
+  ddDt: /^;([^:\n]*)\n?(?::(.*))?/gm,
+  dd: /^:(.*)/m,
+  hr: /---/g,
+  boldItalic: /'''''([^']+)'''''/g,
+  bold: /'''([^']+)'''/g,
+  italic: /''([^']+)''/g,
+  embiggen3: /\+\+\+([^\+]+)\+\+\+/g,
+  embiggen2: /\+\+([^\+]+)\+\+/g,
+  table: /\{\|([\d\D]*?)\|\}/g,
+  indent3: /^\.\.\.(.*)$/gm,
+  indent2: /^\.\.(.*)$/gm,
+  indent1: /^\.(.*)$/gm,
+  wikiLink1: /\[\[([^\[\]\|#]*)(?:(\|[^\]\|#]*)+)?(?:#([^\]\|#]*))?\]\]/g,
+  wikiLink2: /\[\[([^\[\]\|#\n]*)((\|[^\]\|#\n]*)+)?(?:#([^\]\|#\n]*))?\]\]/g,
+  externalLink: /\[([^\]\n ]*)(?: ([^\]\n]+))?\]/g,
+  paragraph: /^[^\$\n].*$/gm,
+  emptyP: /<p><\/p>/g,
+  superscript: /\^([^\^]*)\^/g,
+  nowikiRestore: /\$NOWIKI_(\d*)\$/g,
+  codeRestore: /\$CODE_(\d*)\$/g,
+  codeJoin: /<\/code>\s*<code>/g,
+  htmlRestore: /\$HTML_(\d*)\$/g,
+  sectionH1: /(?:<h1>)([^\|<]*)(?:\|([^<\|]*))?(?:\|([^<]*))?(?:<\/h1>)([\d\D]*?)(?=<h1|$)/g,
+  sectionH2: /(?:<h2>)([^\|<]*)(?:\|([^<\|]*))?(?:\|([^<]*))?(?:<\/h2>)([\d\D]*?)(?=<h2|<\!--SECTION-END|$)/g,
+  tocHeader: /(?:<h(\d)>)([^<]*)(?:<\/h\1>)/g,
+};
+
 export function wikiToHtml({ wikitext, articleName, args } = {}) {
   if (!args) args = { db: "noDB", noSection: true, noTOC: true };
   if (!wikitext) return "nothing to render";
@@ -18,93 +60,77 @@ export function wikiToHtml({ wikitext, articleName, args } = {}) {
   // 1 - add title if none present
   if (
     !args.noH1 &&
-    !articleName.match(/^_(menu|style)/) &&
-    !html.match(/^=([^=\n]+)=/) &&
-    !html.match(/^__NOH1__/)
+    !articleName.match(REGEX.menuStyle) &&
+    !html.match(REGEX.hasH1) &&
+    !html.match(REGEX.noH1)
   )
     html = "=" + articleName.replace(/^_/, "") + "=\n" + html;
-  html = html.replace(/__NOH1__/g, "");
+  html = html.replace(REGEX.noH1Replace, "");
 
   // basic formatting ------------------------------------------
   // nowiki
-  html = html.replace(/<nowiki>([\d\D]*?)<\/nowiki>/g, processNoWiki);
-  html = html.replace(/^ ([^\n]*)$/gm, processCodeBlock);
-  html = html.replace(/<\/?[A-Za-z][^>]*>/g, processHTML);
+  html = html.replace(REGEX.nowiki, processNoWiki);
+  html = html.replace(REGEX.codeBlock, processCodeBlock);
+  html = html.replace(REGEX.htmlTag, processHTML);
   //html = html.replace( /{(?!\|)([^\|]+\|)?([^}]*)}/g , processJSON );
   // headers
-  html = html.replace(/^===([^=\n]+)===/gm, "<h3>$1</h3>");
-  html = html.replace(/^==([^=\n]+)==/gm, "<h2>$1</h2>");
-  html = html.replace(/^=([^=\n]+)=/gm, "<h1>$1</h1>");
+  html = html.replace(REGEX.h3, "<h3>$1</h3>");
+  html = html.replace(REGEX.h2, "<h2>$1</h2>");
+  html = html.replace(REGEX.h1, "<h1>$1</h1>");
 
   // bullets
-  html = html.replace(/(\n|^)#([\d\D]*?)(\n(?!#)|$)/g, processNumberedLists);
-  html = html.replace(/(\n|^)\*([\d\D]*?)(\n(?!\*)|$)/g, processBullets);
+  html = html.replace(REGEX.numberedList, processNumberedLists);
+  html = html.replace(REGEX.bulletList, processBullets);
 
   // dd/dt
-  html = html.replace(
-    /^;([^:\n]*)\n?(?::(.*))?/gm,
-    "<dl><dt>$1</dt><dd>$2</dd></dl>"
-  );
-  html = html.replace(/^:(.*)/m, "<dd>$1</dd>\n");
+  html = html.replace(REGEX.ddDt, "<dl><dt>$1</dt><dd>$2</dd></dl>");
+  html = html.replace(REGEX.dd, "<dd>$1</dd>\n");
   // hr
-  html = html.replace(/---/g, "<hr>");
+  html = html.replace(REGEX.hr, "<hr>");
   // inline
-  html = html.replace(/'''''([^']+)'''''/g, "<b><i>$1</i></b>");
-  html = html.replace(/'''([^']+)'''/g, "<b>$1</b>");
-  html = html.replace(/''([^']+)''/g, "<i>$1</i>");
+  html = html.replace(REGEX.boldItalic, "<b><i>$1</i></b>");
+  html = html.replace(REGEX.bold, "<b>$1</b>");
+  html = html.replace(REGEX.italic, "<i>$1</i>");
   // html = html.replace( /''(.*?)''/g , '<i>$1</i>' );
   // strikethrough
   // html = html.replace( /--(.*?)--/g , '<strike>$1</strike>' );
   // embiggen
-  html = html.replace(
-    /\+\+\+([^\+]+)\+\+\+/g,
-    '<span style="font-size: 200%;">$1</span>'
-  );
-  html = html.replace(
-    /\+\+([^\+]+)\+\+/g,
-    '<span style="font-size: 150%;">$1</span>'
-  );
+  html = html.replace(REGEX.embiggen3, '<span style="font-size: 200%;">$1</span>');
+  html = html.replace(REGEX.embiggen2, '<span style="font-size: 150%;">$1</span>');
   // tables
-  html = html.replace(/\{\|([\d\D]*?)\|\}/g, processTable);
+  html = html.replace(REGEX.table, processTable);
   // div/indent
-  html = html.replace(/^\.\.\.(.*)$/gm, '<div class="indent2">$1</div>');
-  html = html.replace(/^\.\.(.*)$/gm, '<div class="indent1">$1</div>');
-  html = html.replace(/^\.(.*)$/gm, "<div>$1</div>");
+  html = html.replace(REGEX.indent3, '<div class="indent2">$1</div>');
+  html = html.replace(REGEX.indent2, '<div class="indent1">$1</div>');
+  html = html.replace(REGEX.indent1, "<div>$1</div>");
   // links
-  html = html.replace(
-    /\[\[([^\[\]\|#]*)(?:(\|[^\]\|#]*)+)?(?:#([^\]\|#]*))?\]\]/g,
-    processLink
-  );
-  html = html.replace(
-    /\[\[([^\[\]\|#\n]*)((\|[^\]\|#\n]*)+)?(?:#([^\]\|#\n]*))?\]\]/g,
-    processLink
-  );
-  html = html.replace(/\[([^\]\n ]*)(?: ([^\]\n]+))?\]/g, processExternalLink);
+  html = html.replace(REGEX.wikiLink1, processLink);
+  html = html.replace(REGEX.wikiLink2, processLink);
+  html = html.replace(REGEX.externalLink, processExternalLink);
 
   // code
   // html = html.replace( /^ (.*)$/mg , '<code>$1</code>' );
   // paragraphs
   html = html.trim();
   // html = html.replace( /^.*$/gm , processParagraphs );
-  html = html.replace(/^[^\$\n].*$/gm, processParagraphs);
-  html = html.replace(/<p><\/p>/g, "");
+  html = html.replace(REGEX.paragraph, processParagraphs);
+  html = html.replace(REGEX.emptyP, "");
   // beautify HTML
   //html = beautifyHTML(html);
 
   // superscript
-  html = html.replace(/\^([^\^]*)\^/g, "<sup>$1</sup>");
+  html = html.replace(REGEX.superscript, "<sup>$1</sup>");
 
   // restore nowiki blocks
-  html = html.replace(/\$NOWIKI_(\d*)\$/g, processNoWikiRestore);
-  html = html.replace(/\$CODE_(\d*)\$/g, processCodeBlockRestore);
-  html = html.replace(/<\/code>\s*<code>/g, "\n");
-  html = html.replace(/\$HTML_(\d*)\$/g, processHTMLRestore);
+  html = html.replace(REGEX.nowikiRestore, processNoWikiRestore);
+  html = html.replace(REGEX.codeRestore, processCodeBlockRestore);
+  html = html.replace(REGEX.codeJoin, "\n");
+  html = html.replace(REGEX.htmlRestore, processHTMLRestore);
   //html = html.replace( /\$JSON_(\d*)\$/g , processJSONRestore );
 
   // WORKING CODE for sectioning h1 and h2
   if (!args.noSection) {
-    var find =
-      /(?:<h1>)([^\|<]*)(?:\|([^<\|]*))?(?:\|([^<]*))?(?:<\/h1>)([\d\D]*?)(?=<h1|$)/g;
+    var find = REGEX.sectionH1;
     var replace =
       '\
 			<div class="sectionOuter sectionOuter1 $2" style="$3">\
@@ -132,9 +158,8 @@ export function wikiToHtml({ wikitext, articleName, args } = {}) {
       return em.replace(find, replace);
     });
 
-    var find =
-      /(?:<h2>)([^\|<]*)(?:\|([^<\|]*))?(?:\|([^<]*))?(?:<\/h2>)([\d\D]*?)(?=<h2|<\!--SECTION-END|$)/g;
-    var replace =
+    find = REGEX.sectionH2;
+    replace =
       '\
 	    		<div class="sectionOuter2 $2">\
 	    			<h2>$1</h2>\
@@ -149,7 +174,7 @@ export function wikiToHtml({ wikitext, articleName, args } = {}) {
 
   // adding IDs to headers for TOC seeks
   if (!args.noTOC) {
-    var find = /(?:<h(\d)>)([^<]*)(?:<\/h\1>)/g;
+    var find = REGEX.tocHeader;
     var replace = '<h$1 id="$2">$2</h$1>';
     html = html.replace(find, function (em, g1, g2) {
       var id = g2.replace(/\s/g, "_");

package/src/jobs/generate.js

@@ -32,6 +32,7 @@ export function clearWatchCache() {
   watchModeCache.validPaths = null;
   watchModeCache.hashCache = null;
   watchModeCache.isInitialized = false;
+  cssPathCache.clear(); // Also clear CSS path cache
   console.log('Watch cache cleared');
 }
 
@@ -169,6 +170,9 @@ import { createWhitelistFilter } from "../helper/whitelistFilter.js";
 const DEFAULT_TEMPLATE_NAME =
   process.env.DEFAULT_TEMPLATE_NAME ?? "default-template";
 
+// Cache for CSS path lookups to avoid repeated filesystem walks
+const cssPathCache = new Map();
+
 /**
  * Parse exclude option - can be comma-separated paths or a file path
  * @param {string} excludeOption - The exclude option value
@@ -248,6 +252,12 @@ export async function generate({
   const output = resolve(_output) + "/";
   console.log({ source, meta, output });
 
+  // Clear output directory when --clean is specified
+  if (_clean) {
+    progress.log(`Clean build: clearing output directory ${output}`);
+    await emptyDir(output);
+  }
+
   const allSourceFilenamesUnfiltered = await recurse(source, [() => false]);
   
   // Apply include filter (existing functionality)
@@ -299,6 +309,15 @@ export async function generate({
     (filename) => isDirectory(filename)
   )).filter((filename) => !filename.match(hiddenOrSystemDirs) && !isFolderHidden(filename, source));
 
+  // Build set of existing HTML files in source directory (these should not be overwritten)
+  const htmlExtensions = /\.html$/;
+  const existingHtmlFiles = new Set(
+    allSourceFilenames
+      .filter(f => f.match(htmlExtensions) && !f.match(hiddenOrSystemDirs))
+      .map(f => f.replace(source, '')) // Store relative paths for easy lookup
+  );
+  progress.log(`Found ${existingHtmlFiles.size} existing HTML files in source`);
+
   // Build set of valid internal paths for link validation (must be before menu)
   // Pass directories to ensure folder links are valid (auto-index generates index.html for all folders)
   const validPaths = buildValidPaths(allSourceFilenamesThatAreArticles, source, allSourceFilenamesThatAreDirectories);
@@ -381,6 +400,14 @@ export async function generate({
         content: '' // Content excerpts built lazily to save memory
       });
       
+      // Check if a corresponding .html file already exists in source directory
+      const outputHtmlRelative = relativePath.startsWith('/') ? relativePath.slice(1) : relativePath;
+      if (existingHtmlFiles.has(outputHtmlRelative)) {
+        progress.log(`⚠️  Warning: Skipping ${shortFile} - would overwrite existing ${outputHtmlRelative} in source`);
+        skippedCount++;
+        return;
+      }
+
       // Check if file needs regeneration
       const needsRegen = _clean || needsRegeneration(file, rawBody, hashCache);
       
@@ -415,9 +442,15 @@ export async function generate({
       });
 
       // Find nearest style.css or _style.css up the tree and copy to output
+      // Use cache to avoid repeated filesystem walks for same directory
       let styleLink = "";
       try {
-        const cssPath = await findStyleCss(resolve(_source, dir));
+        const dirKey = resolve(_source, dir);
+        let cssPath = cssPathCache.get(dirKey);
+        if (cssPath === undefined) {
+          cssPath = await findStyleCss(dirKey);
+          cssPathCache.set(dirKey, cssPath); // Cache null results too
+        }
         if (cssPath) {
           // Calculate output path for the CSS file (mirrors source structure)
           const cssOutputPath = cssPath.replace(source, output);
@@ -446,9 +479,8 @@ export async function generate({
         throw new Error(`Template not found. Requested: "${requestedTemplateName || DEFAULT_TEMPLATE_NAME}". Available templates: ${Object.keys(templates).join(', ') || 'none'}`);
       }
 
-      // Build final HTML with all replacements in a single chain to reduce intermediate strings
-      let finalHtml = template;
-      // Use a map of replacements to minimize string allocations
+      // Build final HTML with all replacements in a single regex pass
+      // This avoids creating 8 intermediate strings
       const replacements = {
         "${title}": title,
         "${menu}": menu,
@@ -459,9 +491,9 @@ export async function generate({
         "${searchIndex}": "[]", // Placeholder - search index written separately as JSON file
         "${footer}": footer
       };
-      for (const [key, value] of Object.entries(replacements)) {
-        finalHtml = finalHtml.replace(key, value);
-      }
+      // Single-pass replacement using regex alternation
+      const pattern = /\$\{(title|menu|meta|transformedMetadata|body|styleLink|searchIndex|footer)\}/g;
+      let finalHtml = template.replace(pattern, (match) => replacements[match] ?? match);
 
       // Resolve links and mark broken internal links as inactive
       finalHtml = markInactiveLinks(finalHtml, validPaths, docUrlPath, false);
@@ -585,16 +617,23 @@ export async function generate({
   // Clear directory index cache to free memory before processing static files
   dirIndexCache.clear();
 
-  // copy all static files (i.e. images) with batched concurrency
+  // copy all static files (images and existing HTML files) with batched concurrency
   const imageExtensions = /\.(jpg|jpeg|png|gif|webp|svg|ico)/; // static asset extensions
   const allSourceFilenamesThatAreImages = allSourceFilenames.filter(
     (filename) => filename.match(imageExtensions)
   );
-  const totalStatic = allSourceFilenamesThatAreImages.length;
+  
+  // Also copy existing HTML files from source to output (they're treated as static)
+  const allSourceFilenamesThatAreHtml = allSourceFilenames.filter(
+    (filename) => filename.match(/\.html$/) && !filename.match(hiddenOrSystemDirs)
+  );
+  
+  const allStaticFiles = [...allSourceFilenamesThatAreImages, ...allSourceFilenamesThatAreHtml];
+  const totalStatic = allStaticFiles.length;
   let processedStatic = 0;
   let copiedStatic = 0;
-  progress.log(`Processing ${totalStatic} static files...`);
-  await processBatched(allSourceFilenamesThatAreImages, async (file) => {
+  progress.log(`Processing ${totalStatic} static files (${allSourceFilenamesThatAreImages.length} images, ${allSourceFilenamesThatAreHtml.length} HTML)...`);
+  await processBatched(allStaticFiles, async (file) => {
     try {
       processedStatic++;
       const shortFile = file.replace(source, '');
@@ -624,7 +663,7 @@ export async function generate({
 
   // Automatic index generation for folders without index.html
   progress.log(`Checking for missing index files...`);
-  await generateAutoIndices(output, allSourceFilenamesThatAreDirectories, source, templates, menu, footer, allSourceFilenamesThatAreArticles);
+  await generateAutoIndices(output, allSourceFilenamesThatAreDirectories, source, templates, menu, footer, allSourceFilenamesThatAreArticles, copiedCssFiles, existingHtmlFiles);
 
   // Save the hash cache to .ursa folder in source directory
   if (hashCache.size > 0) {
@@ -689,8 +728,11 @@ export async function generate({
  * @param {object} templates - Template map
  * @param {string} menu - Rendered menu HTML
  * @param {string} footer - Footer HTML
+ * @param {string[]} generatedArticles - List of source article paths that were generated
+ * @param {Set<string>} copiedCssFiles - Set of CSS files already copied to output
+ * @param {Set<string>} existingHtmlFiles - Set of existing HTML files in source (relative paths)
  */
-async function generateAutoIndices(output, directories, source, templates, menu, footer, generatedArticles) {
+async function generateAutoIndices(output, directories, source, templates, menu, footer, generatedArticles, copiedCssFiles, existingHtmlFiles) {
   // Alternate index file names to look for (in priority order)
   const INDEX_ALTERNATES = ['_index.html', 'home.html', '_home.html'];
   
@@ -719,6 +761,7 @@ async function generateAutoIndices(output, directories, source, templates, menu,
   
   let generatedCount = 0;
   let renamedCount = 0;
+  let skippedHtmlCount = 0;
   
   for (const dir of outputDirs) {
     const indexPath = join(dir, 'index.html');
@@ -728,7 +771,15 @@ async function generateAutoIndices(output, directories, source, templates, menu,
       continue;
     }
     
-    // Skip if index.html already exists (e.g., created by previous run)
+    // Check if there's an existing index.html in the source directory (don't overwrite it)
+    const sourceDir = dir.replace(outputNorm, sourceNorm);
+    const relativeIndexPath = join(sourceDir, 'index.html').replace(sourceNorm + '/', '');
+    if (existingHtmlFiles && existingHtmlFiles.has(relativeIndexPath)) {
+      skippedHtmlCount++;
+      continue; // Don't overwrite existing source HTML
+    }
+    
+    // Skip if index.html already exists in output (e.g., created by previous run)
     if (existsSync(indexPath)) {
       continue;
     }
@@ -794,6 +845,31 @@ async function generateAutoIndices(output, directories, source, templates, menu,
           continue;
         }
         
+        // Find nearest style.css for this directory
+        let styleLink = "";
+        try {
+          // Map output dir back to source dir to find style.css
+          const sourceDir = dir.replace(outputNorm, sourceNorm);
+          const cssPath = await findStyleCss(sourceDir);
+          if (cssPath) {
+            // Calculate output path for the CSS file (mirrors source structure)
+            const cssOutputPath = cssPath.replace(sourceNorm, outputNorm);
+            const cssUrlPath = '/' + cssPath.replace(sourceNorm, '');
+            
+            // Copy CSS file if not already copied
+            if (!copiedCssFiles.has(cssPath)) {
+              const cssContent = await readFile(cssPath, 'utf8');
+              await outputFile(cssOutputPath, cssContent);
+              copiedCssFiles.add(cssPath);
+            }
+            
+            // Generate link tag
+            styleLink = `<link rel="stylesheet" href="${cssUrlPath}" />`;
+          }
+        } catch (e) {
+          // ignore CSS lookup errors
+        }
+        
         let finalHtml = template;
         const replacements = {
           "${menu}": menu,
@@ -802,7 +878,7 @@ async function generateAutoIndices(output, directories, source, templates, menu,
           "${title}": folderDisplayName,
           "${meta}": "{}",
           "${transformedMetadata}": "",
-          "${styleLink}": "",
+          "${styleLink}": styleLink,
           "${footer}": footer
         };
         for (const [key, value] of Object.entries(replacements)) {
@@ -818,8 +894,12 @@ async function generateAutoIndices(output, directories, source, templates, menu,
     }
   }
   
-  if (generatedCount > 0 || renamedCount > 0) {
-    progress.done('Auto-index', `${generatedCount} generated, ${renamedCount} promoted`);
+  if (generatedCount > 0 || renamedCount > 0 || skippedHtmlCount > 0) {
+    let summary = `${generatedCount} generated, ${renamedCount} promoted`;
+    if (skippedHtmlCount > 0) {
+      summary += `, ${skippedHtmlCount} skipped (existing HTML)`;
+    }
+    progress.done('Auto-index', summary);
   } else {
     progress.log(`Auto-index: All folders already have index.html`);
   }

package/src/serve.js

@@ -1,11 +1,11 @@
 import express from "express";
 import watch from "node-watch";
 import { generate, regenerateSingleFile, clearWatchCache } from "./jobs/generate.js";
-import { join, resolve } from "path";
+import { join, resolve, dirname } from "path";
 import fs from "fs";
 import { promises } from "fs";
 import { outputFile } from "fs-extra";
-const { readdir, mkdir, readFile } = promises;
+const { readdir, mkdir, readFile, copyFile } = promises;
 
 // Debounce timer and lock for preventing concurrent regenerations
 let debounceTimer = null;
@@ -33,6 +33,33 @@ async function copyCssFile(cssPath, sourceDir, outputDir) {
   }
 }
 
+// Static file extensions that should be copied (images, fonts, etc.)
+const STATIC_FILE_EXTENSIONS = /\.(jpg|jpeg|png|gif|webp|svg|ico|woff|woff2|ttf|eot|pdf|mp3|mp4|webm|ogg)$/i;
+
+/**
+ * Copy a single static file to the output directory
+ * @param {string} filePath - Absolute path to the static file
+ * @param {string} sourceDir - Source directory root
+ * @param {string} outputDir - Output directory root
+ */
+async function copyStaticFile(filePath, sourceDir, outputDir) {
+  const startTime = Date.now();
+  const relativePath = filePath.replace(sourceDir, '');
+  const outputPath = join(outputDir, relativePath);
+  
+  try {
+    // Ensure directory exists
+    await mkdir(dirname(outputPath), { recursive: true });
+    
+    // Copy the file
+    await copyFile(filePath, outputPath);
+    const elapsed = Date.now() - startTime;
+    return { success: true, message: `Copied ${relativePath} in ${elapsed}ms` };
+  } catch (e) {
+    return { success: false, message: `Error copying static file: ${e.message}` };
+  }
+}
+
 /**
  * Configurable serve function for CLI and library use
  */
@@ -90,8 +117,8 @@ export async function serve({
     filter: (f, skip) => {
       // Skip .ursa folder (contains hash cache that gets updated during generation)
       if (/[\/\\]\.ursa[\/\\]?/.test(f)) return skip;
-      // Only watch relevant file types
-      return /\.(js|json|css|html|md|txt|yml|yaml)$/.test(f);
+      // Watch article files, config files, and static assets
+      return /\.(js|json|css|html|md|txt|yml|yaml|jpg|jpeg|png|gif|webp|svg|ico|woff|woff2|ttf|eot|pdf|mp3|mp4|webm|ogg)$/i.test(f);
     }
   }, async (evt, name) => {
     // Skip if we're already regenerating
@@ -124,6 +151,40 @@ export async function serve({
       return;
     }
     
+    // Static files (images, fonts, etc.): just copy the file
+    const isStaticFile = name && STATIC_FILE_EXTENSIONS.test(name);
+    if (isStaticFile) {
+      console.log(`\n🖼️  Static file ${evt === 'remove' ? 'removed' : 'changed'}: ${name}`);
+      isRegenerating = true;
+      try {
+        if (evt === 'remove') {
+          // Delete the file from output
+          const relativePath = name.replace(sourceDir, '');
+          const outputPath = join(outputDir, relativePath);
+          try {
+            await promises.unlink(outputPath);
+            console.log(`✅ Removed ${relativePath}`);
+          } catch (e) {
+            if (e.code !== 'ENOENT') {
+              console.log(`⚠️ Error removing file: ${e.message}`);
+            }
+          }
+        } else {
+          const result = await copyStaticFile(name, sourceDir + '/', outputDir + '/');
+          if (result.success) {
+            console.log(`✅ ${result.message}`);
+          } else {
+            console.log(`⚠️ ${result.message}`);
+          }
+        }
+      } catch (error) {
+        console.error("Error handling static file:", error.message);
+      } finally {
+        isRegenerating = false;
+      }
+      return;
+    }
+    
     if (isMenuChange || isConfigChange) {
       console.log(`\n📦 ${isMenuChange ? 'Menu' : 'Config'} change detected: ${name}`);
       console.log("Full rebuild required...");