@abreen/tada 1.0.1 → 1.1.0

package/README.md

@@ -11,12 +11,12 @@ A static site generator. The successor to Presto.
   * Renders headings, alert boxes, and `<hr>` elements
   * Highlights the heading currently being viewed
 - Built-in search powered by [Pagefind][pagefind]
-  * Only pages reachable by links on the site appear in search results
+  * Only pages in `content/` reachable from `/index.html` are indexed
 - Generated HTML pages for source code
   * Automatic code highlighting, clickable line numbers
   * Dynamic table of contents for each method/function
   * Converts new Markdown comment syntax ([added in Java 23][jep467]) to HTML
-  * Indexed by Pagefind
+  * Indexed by Pagefind (classes, interfaces, methods, and fields)
 - PDF files are copied into `dist/`
   - Text of each PDF page is extracted using [mutool][mutool] and indexed
 - External link handling (special visual treatment for external links)
@@ -69,14 +69,14 @@ Visit [http://localhost:8080/index.html](http://localhost:8080/index.html).
 ### `tada init <dirname>`
 
 Create a new Tada site in a new directory. Prompts for:
-- **Site title** --- displayed in the header and `<title>` tag
-- **Symbol** --- short text (1-5 uppercase characters) shown in the logo and favicon
-- **Theme color** --- HSL color, e.g. `hsl(195 70% 40%)`
-- **Background tint hue** --- hue (0-360) for background/foreground tinting (defaults to `20`)
-- **Background tint amount** --- percentage (0-100) of tint to apply (defaults to `100`)
-- **Default time zone** --- for `<datetime>` elements (defaults to your system zone)
-- **Production base URL** --- e.g. `https://example.edu`
-- **Production base path** --- e.g. `/cs101` (defaults to `/`)
+- **Site title**: displayed in the header and `<title>` tag
+- **Symbol**: short text (1-5 uppercase characters) shown in the logo and favicon
+- **Theme color**: HSL color, e.g. `hsl(195 70% 40%)`
+- **Background tint hue**: hue (0-360) for background/foreground tinting (defaults to `20`)
+- **Background tint amount**: percentage (0-100) of tint to apply (defaults to `100`)
+- **Default time zone**: for `<time>` elements (defaults to your system zone)
+- **Production base URL**: e.g. `https://example.edu`
+- **Production base path**: e.g. `/cs101` (defaults to `/`)
 
 Pass `--default` to use the default values for all options without being
 prompted.
@@ -84,7 +84,7 @@ prompted.
 
 ### `tada dev`
 
-Build the site for local development (using `config/site.dev.json`)
+Build the site for local development (using `site.dev.json`)
 into the `dist/` directory.
 
 
@@ -106,7 +106,7 @@ Remove the `dist/` directory.
 
 ### `tada prod`
 
-Build the site for production (uses `config/site.prod.json`).
+Build the site for production (uses `site.prod.json`).
 
 
 ## Prerequisites
@@ -125,10 +125,10 @@ Build the site for production (uses `config/site.prod.json`).
 
 Build-time site config lives in:
 
-- `config/site.dev.json` (used by `tada dev` / `tada watch`)
-- `config/site.prod.json` (used by `tada prod`)
-- `config/nav.json` (navigation structure)
-- `config/authors.json` (author data)
+- `site.dev.json` (used by `tada dev` / `tada watch`)
+- `site.prod.json` (used by `tada prod`)
+- `nav.json` (navigation structure)
+- `authors.json` (author data)
 
 Example site configuration JSON file:
 
@@ -156,7 +156,7 @@ Example site configuration JSON file:
 | `title` | Title for the whole site (also used to derive `titlePostfix`) |
 | `titlePostfix` | *Optional*, the string to append to each page's `title` |
 | `symbol` | Text (1-5 chars) displayed in header (also used as the favicon symbol) |
-| `themeColor` | HSL theme color for the site, e.g. `"hsl(195 70% 40%)"` |
+| `themeColor` | Theme color for the site (e.g., `"tomato"`, `"#c04040"`, `"hsl(195 70% 40%)"`) |
 | `tintHue` | *Optional*, hue (0-360) for background and foreground tinting (default `20`) |
 | `tintAmount` | *Optional*, percentage (0-100) of tint to apply (default `100`) |
 | `faviconSymbol` | *Optional*, the text to use instead of `symbol` in the favicon |
@@ -167,7 +167,7 @@ Example site configuration JSON file:
 | `basePath` | URL prefix for deployment under a subpath (e.g., `"/cs101"`), use `"/"` at root |
 | `internalDomains` | Domain names treated as internal by link processing (not marked external) |
 | `codeLanguages` | Map file extension to Shiki language (e.g., `"java": "java"`) |
-| `faviconColor` | *Optional*, HSL color override for favicon (defaults to `themeColor`) |
+| `faviconColor` | *Optional*, background color for favicon (defaults to `themeColor`) |
 | `faviconFontWeight` | *Optional*, font weight used for favicon text (default `700`) |
 | `vars` | Arbitrary key/value variables exposed to templates/content (e.g., `<%= staffEmail %>`) |
 
@@ -239,12 +239,12 @@ TADA_LOG_LEVEL=debug tada dev
 ## Content
 
 Site content lives in the `content/` directory. Markdown is converted to HTML.
-HTML files should contain front matter and are also built, but not processed
-like Markdown files are.
+HTML files should contain front matter and are also built.
 
-PDF, `.txt`, ZIP, images, and other kinds of files are copied into `dist/`
-in the same locations. All files in `public/` are copied directly into `dist/`
-with zero processing.
+Any other kinds of files are copied into `dist/` in the same locations.
+
+All files in `public/` are copied directly into `dist/` with zero processing.
+Files in `public/` are **not** included in the search index.
 
 
 ### Front matter fields
@@ -256,31 +256,27 @@ list of variables parsed using the [`front-matter`][front-matter] library).
 |-------|-------------|
 | `title` (required) | Page title (`<title>` tag and page heading) |
 | `skip` | Set to `true` to skip building this page completely |
-| `author` | Author handle (e.g. `jsmith`) resolved to a full object via `config/authors.json` |
+| `author` | Author handle (e.g. `jsmith`) resolved to a full object via `authors.json` |
 | `description` | Meta description for the page |
 | `toc` | Set to `true` to show a table of contents |
 | `parent` & `parentLabel` | URL and label for a breadcrumb link displayed above the title |
 | `published` | Year, month, and day of publishing (e.g, `2025-09-09`) |
 
+You may also add arbitrary fields in a page's front matter, and access them
+using Lodash syntax (see below).
+
 
 ### Variable substitution
 
 Plain text content (e.g., HTML and Markdown) are processed using [Lodash
 templates][lodash].
 
-- Site config values are available under `site` (e.g., `site.title`, `site.symbol`)
-- Page variables (from front matter) are available under `page` (e.g., `page.author`)
+- Site config values are available under `site` (e.g., `site.title`)
+- Page variables (from front matter) are available under `page`
 - Custom variables from the `"vars"` property of the config are available
   without any prefix (e.g., `<%= staffEmail %>`)
 
 
-## Templates
-
-HTML page layouts are internal to the Tada package. You don't need to modify
-them; they are designed to work with the client-side components and styles
-bundled in the package.
-
-
 
 [inter]: https://fonts.google.com/specimen/Inter
 [lodash]: https://lodash.info/doc/template

package/bin/tada.ts

@@ -0,0 +1,356 @@
+#!/usr/bin/env bun
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import packageJson from '../package.json' with { type: 'json' };
+import {
+  validateSymbol,
+  validateColor,
+  validateHue,
+  validateUrl,
+  validateBasePath,
+  createSiteConfig,
+} from './validators.js';
+
+const { version } = packageJson;
+
+const SYSTEM_TIME_ZONE = Intl.DateTimeFormat().resolvedOptions().timeZone;
+
+const packageDir = path.resolve(__dirname, '..');
+
+function requireSiteConfig(env: string): void {
+  const configPath = path.resolve(process.cwd(), `site.${env}.json`);
+  if (!fs.existsSync(configPath)) {
+    console.error(`Error: Missing config file: site.${env}.json`);
+    process.exit(1);
+  }
+}
+
+const COMMANDS = {
+  init: null,
+  dev: 'Build the site for development',
+  prod: 'Build the site for production',
+  watch: 'Watch for changes and rebuild',
+  serve: 'Start a local development server',
+  clean: null,
+};
+
+interface InitQuestion {
+  prompt: string;
+  defaultValue: string;
+  validate: (value: string) => string | null;
+}
+
+const INIT_QUESTIONS: Record<string, InitQuestion> = {
+  title: {
+    prompt: 'Site title',
+    defaultValue: 'Introduction to Computer Science',
+    validate: (v: string) => (v ? null : 'Title is required'),
+  },
+  symbol: {
+    prompt: 'Logo symbol (1-5 uppercase chars)',
+    defaultValue: 'CS 0',
+    validate: validateSymbol,
+  },
+  themeColor: {
+    prompt: 'Theme color',
+    defaultValue: 'hsl(195 70% 40%)',
+    validate: validateColor,
+  },
+  tintHue: {
+    prompt: 'Background tint hue (0-360)',
+    defaultValue: '20',
+    validate: validateHue,
+  },
+  tintAmount: {
+    prompt: 'Background tint amount (0-100)',
+    defaultValue: '100',
+    validate: (v: string) => {
+      const n = Number(v);
+      if (!Number.isInteger(n) || n < 0 || n > 100) {
+        return 'Must be an integer from 0 to 100';
+      }
+      return null;
+    },
+  },
+  defaultTimeZone: {
+    prompt: 'Default time zone',
+    defaultValue: SYSTEM_TIME_ZONE,
+    validate: (v: string) => (v ? null : 'Time zone is required'),
+  },
+  prodBase: {
+    prompt: 'Production base URL',
+    defaultValue: 'https://example.edu',
+    validate: validateUrl,
+  },
+  prodBasePath: {
+    prompt: 'Production base path',
+    defaultValue: '/',
+    validate: validateBasePath,
+  },
+};
+
+function printUsage() {
+  console.log(`tada v${version}\n`);
+  console.log('Usage: tada <command>\n');
+  console.log('Commands:');
+  for (const [cmd, desc] of Object.entries(COMMANDS)) {
+    if (cmd === 'init') {
+      console.log('  init <dirname>     Initialize a new site');
+      console.log('       [--default]     (Use defaults for all options)');
+      console.log(
+        '       [--bare]        (Create a minimal site with one page)',
+      );
+      continue;
+    } else if (cmd === 'clean') {
+      console.log('  clean              Remove the dist/ directory');
+      continue;
+    }
+    console.log(`  ${cmd.padEnd(18)} ${desc}`);
+  }
+}
+
+function run(cmd: string): void {
+  execSync(cmd, { cwd: process.cwd(), stdio: 'inherit' });
+}
+
+function copyDirRecursive(src: string, dest: string): void {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+async function initCommand(args: string[]): Promise<void> {
+  const useDefaults = args.includes('--default');
+  const bare = args.includes('--bare');
+  const dirname = args.filter(a => !a.startsWith('--'))[0];
+
+  if (!dirname) {
+    console.error('Error: Provide a name for the new directory');
+    console.log('Usage: tada init <dirname> [--default] [--bare]');
+    process.exit(1);
+  }
+
+  const projectDir = path.resolve(process.cwd(), dirname);
+  if (fs.existsSync(projectDir)) {
+    console.error(`Error: "${dirname}" already exists`);
+    process.exit(1);
+  }
+
+  const message = `Creating a new Tada site in ${projectDir}`;
+  if (useDefaults && bare) {
+    console.log(message + ' using default config (bare)');
+  } else if (useDefaults) {
+    console.log(message + ' using default config');
+  } else if (bare) {
+    console.log(message + ' (bare)');
+  } else {
+    console.log(message);
+  }
+
+  const config: Record<string, string> = {};
+
+  if (useDefaults) {
+    for (const [key, { defaultValue }] of Object.entries(INIT_QUESTIONS)) {
+      config[key] = defaultValue;
+    }
+  } else {
+    const questions = Object.entries(INIT_QUESTIONS);
+    let qi = 0;
+    let { prompt, defaultValue, validate } = questions[qi][1];
+    let suffix = defaultValue != null ? ` (default: ${defaultValue})` : '';
+    process.stdout.write(`${prompt}${suffix}? `);
+
+    for await (const line of console) {
+      const value = line.trim() || defaultValue || '';
+
+      if (validate) {
+        const error = validate(value);
+        if (error) {
+          console.error(`Error: ${error}`);
+          process.stdout.write(`${prompt}${suffix}? `);
+          continue;
+        }
+      }
+
+      config[questions[qi][0]] = value;
+      qi++;
+
+      if (qi >= questions.length) {
+        break;
+      }
+
+      ({ prompt, defaultValue, validate } = questions[qi][1]);
+
+      suffix = defaultValue != null ? ` (default: ${defaultValue})` : '';
+
+      process.stdout.write(`${prompt}${suffix}? `);
+    }
+  }
+
+  const {
+    title,
+    symbol,
+    themeColor,
+    tintHue,
+    tintAmount,
+    defaultTimeZone,
+    prodBase,
+    prodBasePath,
+  } = config;
+
+  // Derive internal domain from production base URL
+  const prodDomain = new URL(prodBase).hostname;
+
+  // Create project directory
+  fs.mkdirSync(projectDir);
+
+  // Generate site configs
+  const devConfig = createSiteConfig({
+    title,
+    symbol,
+    themeColor,
+    tintHue,
+    tintAmount,
+    defaultTimeZone,
+    base: 'http://localhost:8080',
+    basePath: '/',
+    internalDomains: ['localhost'],
+  });
+
+  const prodConfig = createSiteConfig({
+    title,
+    symbol,
+    themeColor,
+    tintHue,
+    tintAmount,
+    defaultTimeZone,
+    base: prodBase,
+    basePath: prodBasePath,
+    internalDomains: [prodDomain],
+  });
+
+  fs.writeFileSync(
+    path.join(projectDir, 'site.dev.json'),
+    JSON.stringify(devConfig, null, 2) + '\n',
+  );
+
+  fs.writeFileSync(
+    path.join(projectDir, 'site.prod.json'),
+    JSON.stringify(prodConfig, null, 2) + '\n',
+  );
+
+  if (bare) {
+    fs.mkdirSync(path.join(projectDir, 'content'), { recursive: true });
+    fs.writeFileSync(
+      path.join(projectDir, 'content', 'index.md'),
+      'title: Home\n\nWelcome to your new site.\n',
+    );
+    fs.mkdirSync(path.join(projectDir, 'public'), { recursive: true });
+    fs.writeFileSync(
+      path.join(projectDir, 'nav.json'),
+      JSON.stringify(
+        [
+          {
+            title: 'Navigation',
+            links: [{ text: 'Home', internal: '/index.html' }],
+          },
+        ],
+        null,
+        2,
+      ) + '\n',
+    );
+  } else {
+    // Copy nav and authors data files to the project root
+    fs.copyFileSync(
+      path.join(packageDir, 'config/nav.json'),
+      path.join(projectDir, 'nav.json'),
+    );
+    fs.copyFileSync(
+      path.join(packageDir, 'config/authors.json'),
+      path.join(projectDir, 'authors.json'),
+    );
+
+    // Copy content/ and public/ from the package
+    copyDirRecursive(
+      path.join(packageDir, 'content'),
+      path.join(projectDir, 'content'),
+    );
+    copyDirRecursive(
+      path.join(packageDir, 'public'),
+      path.join(projectDir, 'public'),
+    );
+  }
+
+  console.log(`\nGenerated a new site in ${projectDir}`);
+  console.log(`\nNext steps:`);
+  console.log(`  cd ${dirname}`);
+  console.log(`  tada dev`);
+  console.log(`  tada serve`);
+}
+
+/*
+ * Start of script
+ */
+
+const command = process.argv[2];
+
+switch (command) {
+  case 'init':
+    initCommand(process.argv.slice(3));
+    break;
+
+  case 'dev':
+    requireSiteConfig('dev');
+    run(`bun ${path.join(packageDir, 'build/pipeline.ts')} dev`);
+    break;
+
+  case 'prod':
+    requireSiteConfig('prod');
+    run(`bun ${path.join(packageDir, 'build/pipeline.ts')} prod`);
+    break;
+
+  case 'watch': {
+    requireSiteConfig('dev');
+    const watchArgs = process.argv.slice(3).join(' ');
+    run(
+      `bun ${path.join(packageDir, 'build/watch.ts')}${watchArgs ? ' ' + watchArgs : ''}`,
+    );
+    break;
+  }
+
+  case 'serve': {
+    const serveArgs = process.argv.slice(3).join(' ');
+    run(
+      `bun ${path.join(packageDir, 'build/serve.ts')}${serveArgs ? ' ' + serveArgs : ''}`,
+    );
+    break;
+  }
+
+  case 'clean':
+    fs.rmSync(path.resolve(process.cwd(), 'dist'), {
+      recursive: true,
+      force: true,
+    });
+    console.log('Cleaned dist/');
+    break;
+
+  case '--version':
+  case '-v':
+    console.log(`tada v${version}`);
+    break;
+
+  default:
+    printUsage();
+    if (command && command !== '--help' && command !== '-h') {
+      process.exit(1);
+    }
+    break;
+}

package/bin/validators.test.ts

@@ -0,0 +1,204 @@
+import { describe, expect, test } from 'bun:test';
+import type { SiteConfigInput } from '../build/types.js';
+import {
+  validateSymbol,
+  validateColor,
+  validateHue,
+  validateUrl,
+  validateBasePath,
+  createSiteConfig,
+} from './validators.js';
+
+describe('validateSymbol', () => {
+  test('accepts a single uppercase letter', () => {
+    expect(validateSymbol('A')).toBeNull();
+  });
+
+  test('accepts digits and uppercase letters up to 5 chars', () => {
+    expect(validateSymbol('CS 0')).toBeNull();
+    expect(validateSymbol('CS101')).toBeNull();
+    expect(validateSymbol('AB-CD')).toBeNull();
+  });
+
+  test('rejects empty string', () => {
+    expect(validateSymbol('')).not.toBeNull();
+  });
+
+  test('rejects value longer than 5 chars', () => {
+    expect(validateSymbol('TOOLONG')).not.toBeNull();
+  });
+
+  test('rejects lowercase letters', () => {
+    expect(validateSymbol('abc')).not.toBeNull();
+  });
+
+  test('rejects special characters', () => {
+    expect(validateSymbol('A@B')).not.toBeNull();
+    expect(validateSymbol('A.B')).not.toBeNull();
+  });
+});
+
+describe('validateColor', () => {
+  test('accepts CSS color names', () => {
+    expect(validateColor('red')).toBeNull();
+    expect(validateColor('tomato')).toBeNull();
+    expect(validateColor('blue')).toBeNull();
+  });
+
+  test('accepts hex colors', () => {
+    expect(validateColor('#f00')).toBeNull();
+    expect(validateColor('#ff0000')).toBeNull();
+    expect(validateColor('#c04040')).toBeNull();
+  });
+
+  test('accepts HSL colors', () => {
+    expect(validateColor('hsl(195 70% 40%)')).toBeNull();
+    expect(validateColor('hsl(195, 70%, 40%)')).toBeNull();
+    expect(validateColor('hsl(195deg 70% 40%)')).toBeNull();
+  });
+
+  test('accepts RGB colors', () => {
+    expect(validateColor('rgb(0 0 0)')).toBeNull();
+    expect(validateColor('rgb(255, 99, 71)')).toBeNull();
+  });
+
+  test('rejects empty string', () => {
+    expect(validateColor('')).not.toBeNull();
+  });
+
+  test('rejects invalid color strings', () => {
+    expect(validateColor('notacolor')).not.toBeNull();
+    expect(validateColor('hsl 195 70% 40%')).not.toBeNull();
+  });
+});
+
+describe('validateHue', () => {
+  test('accepts integer', () => {
+    expect(validateHue('0')).toBeNull();
+    expect(validateHue('180')).toBeNull();
+    expect(validateHue('360')).toBeNull();
+  });
+
+  test('accepts integer with deg suffix', () => {
+    expect(validateHue('90deg')).toBeNull();
+    expect(validateHue('360deg')).toBeNull();
+  });
+
+  test('rejects empty string', () => {
+    expect(validateHue('')).not.toBeNull();
+  });
+
+  test('rejects out of range', () => {
+    expect(validateHue('-1')).not.toBeNull();
+    expect(validateHue('361')).not.toBeNull();
+  });
+
+  test('rejects non-integer', () => {
+    expect(validateHue('1.5')).not.toBeNull();
+    expect(validateHue('abc')).not.toBeNull();
+  });
+});
+
+describe('validateUrl', () => {
+  test('accepts https URL', () => {
+    expect(validateUrl('https://example.edu')).toBeNull();
+  });
+
+  test('accepts http URL', () => {
+    expect(validateUrl('http://localhost')).toBeNull();
+  });
+
+  test('accepts URL with port', () => {
+    expect(validateUrl('http://localhost:8080')).toBeNull();
+  });
+
+  test('rejects empty string', () => {
+    expect(validateUrl('')).not.toBeNull();
+  });
+
+  test('rejects trailing slash', () => {
+    expect(validateUrl('https://example.edu/')).not.toBeNull();
+  });
+
+  test('rejects URL with path', () => {
+    expect(validateUrl('https://example.edu/foo')).not.toBeNull();
+  });
+
+  test('rejects non-http scheme', () => {
+    expect(validateUrl('ftp://example.edu')).not.toBeNull();
+  });
+
+  test('rejects bare domain', () => {
+    expect(validateUrl('example.edu')).not.toBeNull();
+  });
+});
+
+describe('validateBasePath', () => {
+  test('accepts root path', () => {
+    expect(validateBasePath('/')).toBeNull();
+  });
+
+  test('accepts simple path segment', () => {
+    expect(validateBasePath('/foo')).toBeNull();
+    expect(validateBasePath('/foo-bar')).toBeNull();
+    expect(validateBasePath('/cs101')).toBeNull();
+  });
+
+  test('rejects path without leading slash', () => {
+    expect(validateBasePath('foo')).not.toBeNull();
+  });
+
+  test('rejects trailing slash', () => {
+    expect(validateBasePath('/foo/')).not.toBeNull();
+  });
+
+  test('rejects spaces', () => {
+    expect(validateBasePath('/foo bar')).not.toBeNull();
+  });
+
+  test('rejects nested paths', () => {
+    expect(validateBasePath('/foo/bar')).not.toBeNull();
+  });
+});
+
+describe('createSiteConfig', () => {
+  const base: SiteConfigInput = {
+    title: 'Test Site',
+    symbol: 'TS',
+    themeColor: 'hsl(200 50% 40%)',
+    tintHue: '20',
+    tintAmount: '100',
+    defaultTimeZone: 'America/New_York',
+    base: 'https://example.edu',
+    basePath: '/',
+    internalDomains: ['example.edu'],
+  };
+
+  test('returns an object with all expected keys', () => {
+    const config = createSiteConfig(base);
+    expect(config).toMatchObject({
+      title: 'Test Site',
+      symbol: 'TS',
+      themeColor: 'hsl(200 50% 40%)',
+      base: 'https://example.edu',
+      basePath: '/',
+      internalDomains: ['example.edu'],
+      defaultTimeZone: 'America/New_York',
+      features: { search: true, code: true, favicon: true },
+      codeLanguages: { java: 'java', py: 'python' },
+      vars: {},
+    });
+  });
+
+  test('coerces tintHue and tintAmount to numbers', () => {
+    const config = createSiteConfig(base);
+    expect(config.tintHue).toBe(20);
+    expect(config.tintAmount).toBe(100);
+  });
+
+  test('coerces numeric string tintHue correctly', () => {
+    const config = createSiteConfig({ ...base, tintHue: '0', tintAmount: '0' });
+    expect(config.tintHue).toBe(0);
+    expect(config.tintAmount).toBe(0);
+  });
+});