@kenjura/ursa 0.9.0 → 0.32.0

package/CHANGELOG.md

@@ -1,3 +1,166 @@
+# 0.32
+2025-12-10
+
+- Using .ursa folder in source directory for content hash cache
+- Added --clean flag to ignore cache and regenerate all files
+- Set up npm config for public package publishing
+
+# 0.31
+2025-12-09
+
+- Added URL property to JSON directory indices
+- Ensured directory indices are recursive
+
+# 0.30
+2025-12-07
+
+- Fixed broken link detection to correctly identify broken internal links
+
+# 0.29.0
+2025-12-07
+
+- New nav-main style, two-levels only (but supports any depth), looks way better
+
+# 0.28.0
+2025-12-07
+
+- Added broken link detection and styles
+- Fixed hole in "serve" logic that didn't regenerate style.css
+
+# 0.27.0
+2025-12-07
+
+- Capitalizing nav-main labels
+
+# 0.26.0
+2025-12-06
+- Fixed global nav styles in desktop
+- Updated main nav style to match TOC
+
+# 0.25.0
+
+2025-12-06
+
+- Enhanced mobile navigation with hamburger toggle that changes to X when menu is open
+- Improved button accessibility with dynamic aria-label updates
+
+# 0.24.0
+
+2025-12-06
+
+- Added support for index files in folder links
+- Folders with index.md/txt/yml now link to /folder/index.html
+- Folders without index files render as non-clickable text
+
+# 0.23.0
+
+2025-12-04
+
+- Implemented incremental build support with content hashing
+- Source file changes now only regenerate modified files
+- Meta file changes still trigger full rebuild
+- Added .content-hashes.json cache for tracking file changes
+
+# 0.22.0
+
+2025-12-04
+
+- New Notion-style nav-main sidebar design
+- Added folder/document icons with custom icon support
+- Collapsible menu items with expand arrows
+- Responsive flexbox layout for nav-global
+
+# 0.21.0
+
+2025-12-01
+
+- Enhanced error handling for template retrieval
+- Better error messages when templates are not found
+
+# 0.20.0
+
+2025-12-01
+
+- Added fault tolerance to generate command
+- Individual file errors no longer stop entire build
+- Errors collected and written to _errors.log
+
+# 0.19.0
+
+2025-11-21
+
+- Fixed YAML parsing issues with horizontal rules being mistaken for front matter
+- Improved regex to require closing --- on its own line
+
+# 0.18.0
+
+2025-11-21
+
+- Fixed errors with wikitext rendering
+- Better handling of undefined args.db
+
+# 0.17.0
+
+2025-10-23
+
+- Added Table of Contents (TOC) generation
+- Smooth scrolling to headings with offset adjustment
+- Active heading tracking in TOC
+
+# 0.16.0
+
+2025-10-22
+
+- AI-implemented search feature with typeahead
+- Search index built from all articles during generation
+
+# 0.15.0
+
+2025-10-22
+
+- Improved mobile responsiveness
+- Better media query breakpoint (800px)
+- Enhanced h1 styling and article width for mobile
+
+# 0.14.0
+
+2025-10-22
+
+- Fixed sticky header generation
+- Enhanced sticky header functionality
+- Added responsive navigation styles
+
+# 0.13.0
+
+2025-10-07
+
+- Added whitelist feature for selective file generation
+- Added sectionify script for content organization
+- Fixed bugs in node-watch for file monitoring
+- Working sticky headers implementation
+
+# 0.12.0
+
+2025-10-06
+
+- Added debug CLI mode
+- Fixed embedded style issues
+- Added site navigation
+- Total rewrite of base CSS (article and topnav)
+- Added custom CSS support (disabled by default)
+
+# 0.11.0
+
+2025-07-28
+
+- added CLI commands (e.g. "ursa src" and "ursa serve src")
+
+# 0.10.0
+
+2024-03-13
+
+- Will no longer write an autoindex when index document already exists
+
 # 0.9.0
 
 2024-02-10

package/README.md

@@ -1,32 +1,195 @@
-static site generator from MD/wikitext/YML
+# Ursa Static Site Generator
 
-there are many like it, but this one's mine
+A flexible static site generator that converts Markdown, Wikitext, and YAML files into beautiful HTML sites.
 
-# Developing
+There are many like it, but this one's mine.
 
-```npm run serve```
+## Installation
 
-Watches source and meta folder; on change, writes HTML to build folder.
+### As a CLI tool (global installation)
+```bash
+npm install -g @kenjura/ursa
+```
+
+### As a library dependency
+```bash
+npm install @kenjura/ursa
+```
+
+## CLI Usage
+
+After global installation, you can use the `ursa` command:
+
+```bash
+# Generate site once
+ursa <source-directory>
+ursa generate <source-directory>
+
+# Development server with live reloading
+ursa serve <source-directory>
+
+# With custom meta and output directories
+ursa content --meta=templates --output=dist
+ursa serve content --meta=templates --output=dist --port=3000
+
+# Using a whitelist file to filter which files are processed
+ursa content --whitelist=my-whitelist.txt
+ursa serve content --whitelist=my-whitelist.txt
+
+# Using default meta and output directories (meta/ and output/)
+ursa content
+ursa serve content
+```
+
+If not installed, you can run:
+```bash
+node bin/ursa (same args)
+```
+
+### CLI Commands
+
+#### `ursa [generate] <source>`
+Generate a static site once and exit.
+
+#### `ursa serve <source>`
+Start a development server that:
+- Generates the site initially
+- Starts an HTTP server to serve the output directory
+- Watches source and meta directories for changes
+- Automatically regenerates the site when files change
+
+### CLI Options
+
+- `<source>` - Source directory containing markdown/wikitext files (required)
+- `--meta, -m` - Meta directory containing templates and styles (default: "meta")
+- `--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
+
+### Whitelist File Format
+
+The whitelist file is a plain text file where each line specifies a pattern for files to include. Patterns can be:
+
+```text
+# Comments start with # and are ignored
+# Empty lines are also ignored
+
+# Full absolute paths
+/full/path/to/file.md
+
+# Relative paths from source root
+character/classes/psion.md
+character/classes/
+
+# Directory paths (include trailing slash to match directories)
+spells/
+documentation/
 
-Optional environment variables:
-- SOURCE: path to the source folder, default `${cwd}/source`
-- META: path to the meta folder, default `${cwd}/meta`
-- BUILD: path to the build folder, default `${cwd}/build`
+# Just filenames (matches anywhere in the source tree)
+index.md
+README.md
 
-# Running
+# Partial path matches
+important-document
+classes/wizard
+```
+
+## Library Usage
+
+### ES Modules (recommended)
+
+```javascript
+import generateSite, { generate, serve } from '@kenjura/ursa';
+
+// One-time generation using the default export
+await generateSite({
+  source: './content',
+  meta: './meta',
+  output: './dist',
+  whitelist: './my-whitelist.txt' // optional
+});
+
+// One-time generation using the named export (matches internal API)
+await generate({
+  _source: './content',
+  _meta: './meta', 
+  _output: './dist',
+  _whitelist: './my-whitelist.txt' // optional
+});
+
+// Development server with live reloading
+await serve({
+  _source: './content',
+  _meta: './meta',
+  _output: './dist',
+  port: 3000  // optional, defaults to 8080
+});
+```
+
+### CommonJS
+
+```javascript
+const generateSite = require('@kenjura/ursa').default;
+const { generate, serve } = require('@kenjura/ursa');
+
+// Usage is the same as above
+```
+
+### Library Functions
+
+#### `generateSite({ source, meta, output })`
+Default export. Generates the site once with user-friendly parameter names.
+
+#### `generate({ _source, _meta, _output })`
+Named export that matches the internal API. Generates the site once.
+
+#### `serve({ _source, _meta, _output, port? })`
+Starts a development server with live reloading:
+- Generates the site initially
+- Starts HTTP server on specified port (default: 8080)
+- Watches for file changes in source and meta directories
+- Automatically regenerates when changes are detected
+
+## Project Structure
+
+Your project should have the following structure:
+
+```
+your-project/
+├── source/           # Source files (markdown, wikitext, yaml)
+│   ├── index.md     # Required: main page
+│   └── ...
+├── meta/            # Templates, styles, and configuration
+│   ├── templates/
+│   ├── styles/
+│   └── ...
+└── output/          # Generated site (created automatically)
+```
+
+## Developing
+
+For development on ursa itself:
+
+```bash
+npm run serve
+```
+
+Watches source and meta folder; on change, writes HTML to build folder.
 
-## Run once, converting source folder into static html
+### Environment Variables
 
-```npm start```
+- `SOURCE`: path to the source folder, default `${cwd}/source`
+- `META`: path to the meta folder, default `${cwd}/meta`
+- `BUILD`: path to the build folder, default `${cwd}/build`
 
-Defaults:
-- source: the "source" directory in cwd
-- meta: the "meta" directory in cwd
-- output: the "build" directory in cwd
+## Running Locally
 
-This is not very useful. Will make these configurable.
+```bash
+npm start
+```
 
+Generates the site once using default directories.
 
-# Inputs and Outputs
+## Requirements
 
-SOURCE folder should have at least an index.md in it
+SOURCE folder should have at least an index.md in it.

package/bin/ursa.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { generate } from '../src/jobs/generate.js';
+import { resolve, dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+// Get the directory where ursa is installed
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PACKAGE_META = join(__dirname, '..', 'meta');
+
+yargs(hideBin(process.argv))
+  .command(
+    'generate <source>',
+    'Generate a static site from source files',
+    (yargs) => {
+      return yargs
+        .positional('source', {
+          describe: 'Source directory containing markdown/wikitext files',
+          type: 'string',
+          demandOption: true
+        })
+        .option('meta', {
+          alias: 'm',
+          describe: 'Meta directory containing templates and styles (defaults to ursa package meta)',
+          type: 'string'
+        })
+        .option('output', {
+          alias: 'o', 
+          default: 'output',
+          describe: 'Output directory for generated site',
+          type: 'string'
+        })
+        .option('whitelist', {
+          alias: 'w',
+          describe: 'Path to whitelist file containing patterns for files to include',
+          type: 'string'
+        })
+        .option('clean', {
+          alias: 'c',
+          describe: 'Ignore cached hashes and regenerate all files',
+          type: 'boolean',
+          default: false
+        });
+    },
+    async (argv) => {
+      const source = resolve(argv.source);
+      const meta = argv.meta ? resolve(argv.meta) : PACKAGE_META;
+      const output = resolve(argv.output);
+      const whitelist = argv.whitelist ? resolve(argv.whitelist) : null;
+      const clean = argv.clean;
+      
+      console.log(`Generating site from ${source} to ${output} using meta from ${meta}`);
+      if (whitelist) {
+        console.log(`Using whitelist: ${whitelist}`);
+      }
+      if (clean) {
+        console.log(`Clean build: ignoring cached hashes`);
+      }
+      
+      try {
+        await generate({
+          _source: source,
+          _meta: meta,
+          _output: output,
+          _whitelist: whitelist,
+          _clean: clean
+        });
+        console.log('Site generation completed successfully!');
+      } catch (error) {
+        console.error('Error generating site:', error.message);
+        process.exit(1);
+      }
+    }
+  )
+  .command(
+    'serve <source>',
+    'Generate site and serve with live reloading',
+    (yargs) => {
+      return yargs
+        .positional('source', {
+          describe: 'Source directory containing markdown/wikitext files',
+          type: 'string',
+          demandOption: true
+        })
+        .option('meta', {
+          alias: 'm',
+          describe: 'Meta directory containing templates and styles (defaults to ursa package meta)',
+          type: 'string'
+        })
+        .option('output', {
+          alias: 'o', 
+          default: 'output',
+          describe: 'Output directory for generated site',
+          type: 'string'
+        })
+        .option('port', {
+          alias: 'p',
+          default: 8080,
+          describe: 'Port to serve on',
+          type: 'number'
+        })
+        .option('whitelist', {
+          alias: 'w',
+          describe: 'Path to whitelist file containing patterns for files to include',
+          type: 'string'
+        })
+        .option('clean', {
+          alias: 'c',
+          describe: 'Ignore cached hashes and regenerate all files',
+          type: 'boolean',
+          default: false
+        });
+    },
+    async (argv) => {
+      const source = resolve(argv.source);
+      const meta = argv.meta ? resolve(argv.meta) : PACKAGE_META;
+      const output = resolve(argv.output);
+      const port = argv.port;
+      const whitelist = argv.whitelist ? resolve(argv.whitelist) : null;
+      const clean = argv.clean;
+      
+      console.log(`Starting development server...`);
+      console.log(`Source: ${source}`);
+      console.log(`Meta: ${meta}`);
+      console.log(`Output: ${output}`);
+      console.log(`Port: ${port}`);
+      if (whitelist) {
+        console.log(`Using whitelist: ${whitelist}`);
+      }
+      
+      try {
+        const { serve } = await import('../src/serve.js');
+        await serve({
+          _source: source,
+          _meta: meta,
+          _output: output,
+          port: port,
+          _whitelist: whitelist,
+          _clean: clean
+        });
+      } catch (error) {
+        console.error('Error starting development server:', error.message);
+        console.error(error);
+        process.exit(1);
+      }
+    }
+  )
+  .command(
+    '$0 <source>',
+    'Generate a static site from source files (default command)',
+    (yargs) => {
+      return yargs
+        .positional('source', {
+          describe: 'Source directory containing markdown/wikitext files',
+          type: 'string',
+          demandOption: true
+        })
+        .option('meta', {
+          alias: 'm',
+          default: 'meta',
+          describe: 'Meta directory containing templates and styles',
+          type: 'string'
+        })
+        .option('output', {
+          alias: 'o', 
+          default: 'output',
+          describe: 'Output directory for generated site',
+          type: 'string'
+        })
+        .option('whitelist', {
+          alias: 'w',
+          describe: 'Path to whitelist file containing patterns for files to include',
+          type: 'string'
+        });
+    },
+    async (argv) => {
+      const source = resolve(argv.source);
+      const meta = resolve(argv.meta);
+      const output = resolve(argv.output);
+      const whitelist = argv.whitelist ? resolve(argv.whitelist) : null;
+      
+      console.log(`Generating site from ${source} to ${output} using meta from ${meta}`);
+      if (whitelist) {
+        console.log(`Using whitelist: ${whitelist}`);
+      }
+      
+      try {
+        await generate({
+          _source: source,
+          _meta: meta,
+          _output: output,
+          _whitelist: whitelist
+        });
+        console.log('Site generation completed successfully!');
+      } catch (error) {
+        console.error('Error generating site:', error.message);
+        process.exit(1);
+      }
+    }
+  )
+  .help()
+  .alias('help', 'h')
+  .version()
+  .alias('version', 'v')
+  .parse();

package/lib/index.js

@@ -1,9 +1,14 @@
 import { generate } from "../src/jobs/generate.js";
+import { serve } from "../src/serve.js";
 
-export default function generateSite({ source, meta, output }) {
+export default function generateSite({ source, meta, output, whitelist }) {
   if (!source) throw new Error("source is required");
   if (!meta) throw new Error("meta is required");
   if (!output) throw new Error("output is required");
 
-  generate({ source, meta, output });
+  return generate({ _source: source, _meta: meta, _output: output, _whitelist: whitelist });
 }
+
+// Also export the generate and serve functions directly for more flexibility
+export { generate } from "../src/jobs/generate.js";
+export { serve } from "../src/serve.js";

package/meta/character-sheet-template.html

@@ -1,6 +1,8 @@
 <html>
 
 <head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <link rel="stylesheet" href="/public/default.css" />
   <link rel="stylesheet" href="/public/cssui.bundle.min.css" />
   <link rel="stylesheet" href="/public/character-sheet.css" />

package/meta/default-template.html

@@ -1,22 +1,46 @@
 <html>
 
 <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>${title}</title>
     <link rel="stylesheet" href="/public/default.css" />
+     <style>
+        ${embeddedStyle}
+     </style>
+     <script>
+        // Embed search index data
+        window.SEARCH_INDEX = ${searchIndex};
+     </script>
+     <script src="/public/search.js"></script>
+     
 </head>
 
 <body data-template-id="default">
+    <nav id="nav-global">
+        <button class="menu-button" aria-label="Menu">☰</button>
+
+        <input id="global-search" type="text" placeholder="Search..." />
+
+        <span class="avatar" aria-hidden="true">👤</span>
+    </nav>
     <nav id="nav-main">
-        <span id="menu-icon" class="material-symbols-outlined">
-            menu
-        </span>
         ${menu}
     </nav>
-    <article>
+    <nav id="nav-toc">
+        <!-- TOC will be generated by JavaScript -->
+    </nav>
+    <article id="main-content">
         ${body}
     </article>
     <div id="global-nav">
-        global nav here
     </div>
+
+    <script src="/public/toc.js"></script>
+    <script src="/public/toc-generator.js"></script>
+    <script src="/public/menu.js"></script>
+    <script src="/public/sectionify.js"></script>
+    <script src="/public/sticky.js"></script>
 </body>
 
 </html>