@abreen/tada 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alex Breen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,290 @@
+# Tada :tada:
+
+A static site generator. The successor to Presto.
+
+## Features
+
+- Modern design (light & dark following system, floating header, styled lists)
+- Clickable/linkable landmarks (headings, deflists, alert boxes)
+- Dynamic table of contents
+  * Floats on the side of the screen when window is large enough
+  * 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
+- 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
+- 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)
+- Internal link validation at build time (broken links fail the build)
+- Internal links automatically prefixed with base path, if specified
+- Time zone chooser (automatically adjusts `<datetime>` elements)
+- Extended Markdown syntax
+  * `<<< details ... <<<` renders a collapsible box
+  * `::: section ... :::` renders a special section with a fancy background
+  * `!!! note ... !!!` and `!!! warning ... !!!` render alert boxes
+  * `??? review ... ???` renders a Q & A section; answers hidden until click
+  * Special heading subtitles with `## Heading # A subtitle here`
+- Automatically generated favicon
+  * Text, color, font and font weight taken from config file
+
+
+## Installation
+
+Install [Bun](https://bun.sh/), then install Tada globally:
+
+```
+bun add -g @abreen/tada
+```
+
+
+## Quick start
+
+Create a new site:
+
+```
+tada init mysite
+```
+
+This will ask you a few questions (site title, logo symbol, theme color, etc.)
+and create a new directory with everything you need.
+
+Then build and preview your site:
+
+```
+cd mysite
+tada dev
+tada serve
+```
+
+Visit [http://localhost:8080/index.html](http://localhost:8080/index.html).
+
+
+## CLI commands
+
+### `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 `/`)
+
+Pass `--default` to use the default values for all options without being
+prompted.
+
+
+### `tada dev`
+
+Build the site for local development (using `config/site.dev.json`)
+into the `dist/` directory.
+
+
+### `tada serve`
+
+Start a development web server at `http://localhost:8080` which serves the
+files in the `dist/` directory.
+
+
+### `tada watch`
+
+Start a development web server, watch for changes and rebuild automatically.
+
+
+### `tada clean`
+
+Remove the `dist/` directory.
+
+
+### `tada prod`
+
+Build the site for production (uses `config/site.prod.json`).
+
+
+## Prerequisites
+
+- [Bun](https://bun.sh/)
+- [MuPDF](https://mupdf.com/) (optional, for PDF text extraction in search)
+  - On macOS: `brew install mupdf-tools`
+  - On Fedora: `dnf install mupdf`
+
+> You may skip MuPDF if you don't need search results to include links to PDF
+> pages. You can also turn off `features.search` in the config to disable
+> search entirely.
+
+
+## Configuration
+
+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)
+
+Example site configuration JSON file:
+
+```json
+{
+  "title": "Intro to Computer Science",
+  "titlePostfix": " - CS 0",
+  "symbol": "CS 0",
+  "themeColor": "hsl(351 70% 40%)",
+  "tintAmount": 0,
+  "features": { "search": true, "code": true, "favicon": true },
+  "base": "https://example.edu",
+  "basePath": "/cs0",
+  "internalDomains": ["example.edu"],
+  "defaultTimeZone": "America/New_York",
+  "codeLanguages": { "java": "java", "py": "python" },
+  "vars": {
+    "staffEmail": "staff@example.edu"
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `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%)"` |
+| `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 |
+| `features.search` | Enable search UI and Pagefind index generation |
+| `features.code` | Enable generated source-code HTML pages for configured code extensions |
+| `features.favicon` | Enable automatically generated favicons |
+| `base` | Full base URL of the deployed site, used for metadata and URL generation |
+| `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`) |
+| `faviconFontWeight` | *Optional*, font weight used for favicon text (default `700`) |
+| `vars` | Arbitrary key/value variables exposed to templates/content (e.g., `<%= staffEmail %>`) |
+
+
+#### `nav.json`
+
+Defines the site navigation structure. The file contains an array of section
+objects. Each section contains an array of link objects (internal or external,
+and whether the link is disabled). You should specify at least two sections,
+but three or more sections are supported.
+
+```json
+[
+  {
+    "title": "Navigation",
+    "links": [{ "text": "Home", "internal": "/index.html" }]
+  },
+  {
+    "title": "Topics",
+    "links": [
+      { "text": "Lectures", "internal": "/lectures/index.html" },
+      {
+        "text": "Problem Sets",
+        "internal": "/problem_sets/index.html",
+        "disabled": true
+      }
+    ]
+  },
+  {
+    "title": "Links",
+    "links": [
+      { "text": "Zoom", "external": "https://zoom.com" }
+    ]
+  }
+]
+```
+
+
+#### `authors.json`
+
+Maps author handles (used in front matter `author` fields) to display names
+and avatars. Each key is a handle (e.g., `jsmith`) and each value is an object
+with `name`, `avatar`, and optionally `url`.
+
+```json
+{
+  "jsmith": { "name": "Jane Smith", "avatar": "/avatars/jsmith.jpg" },
+  "ajones": {
+    "name": "Alex Jones",
+    "avatar": "/avatars/ajones.jpg",
+    "url": "/staff/ajones.html"
+  }
+}
+```
+
+
+### Log level
+
+Set the `TADA_LOG_LEVEL` environment variable to control build log verbosity.
+Valid levels (from most to least verbose): `debug`, `info`, `warn`, `error`.
+The default level is `info`. To see *all* logs generated by Tada, set the env
+var to `debug`:
+
+```
+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.
+
+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.
+
+
+### Front matter fields
+
+Each file in `content/` should start with "front matter" (a YAML-formatted
+list of variables parsed using the [`front-matter`][front-matter] library).
+
+| Field | Description |
+|-------|-------------|
+| `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` |
+| `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`) |
+
+
+### 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`)
+- 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
+[front-matter]: https://www.npmjs.com/package/front-matter
+[pagefind]: https://pagefind.app/
+[mutool]: https://mupdf.readthedocs.io/en/latest/tools/mutool.html
+[jep467]: https://openjdk.org/jeps/467

package/bin/tada.js

@@ -0,0 +1,361 @@
+#!/usr/bin/env bun
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { execSync } = require('child_process');
+
+const SYSTEM_TIME_ZONE = Intl.DateTimeFormat().resolvedOptions().timeZone;
+
+const packageDir = path.resolve(__dirname, '..');
+
+const COMMANDS = {
+  init: 'Create a new Tada site',
+  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: 'Remove the dist/ directory',
+};
+
+const INIT_QUESTIONS = {
+  title: {
+    prompt: 'Site title',
+    defaultValue: 'Introduction to Computer Science',
+    validate: v => (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: validateHslColor,
+  },
+  tintHue: {
+    prompt: 'Background tint hue (0-360)',
+    defaultValue: '20',
+    validate: v => {
+      const n = Number(v);
+      if (!Number.isInteger(n) || n < 0 || n > 360) {
+        return 'Must be an integer from 0 to 360';
+      }
+      return null;
+    },
+  },
+  tintAmount: {
+    prompt: 'Background tint amount (0-100)',
+    defaultValue: '100',
+    validate: v => {
+      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 => (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('Usage: tada <command>\n');
+  console.log('Commands:');
+  console.log('  init <dirname>     Initialize a new site');
+  for (const [cmd, desc] of Object.entries(COMMANDS)) {
+    if (cmd === 'init') {
+      console.log('       [--default]     Use defaults for all config options');
+      continue;
+    }
+    console.log(`  ${cmd.padEnd(18)} ${desc}`);
+  }
+}
+
+const webpackCli = path.join(packageDir, 'node_modules/webpack-cli/bin/cli.js');
+
+function run(cmd) {
+  execSync(cmd, { cwd: process.cwd(), stdio: 'inherit' });
+}
+
+function copyDirRecursive(src, dest) {
+  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);
+    }
+  }
+}
+
+// --- init command ---
+
+function ask(rl, question, { defaultValue, validate } = {}) {
+  const suffix = defaultValue != null ? ` (default: ${defaultValue})` : '';
+  return new Promise(resolve => {
+    function prompt() {
+      rl.question(`${question}${suffix}? `, answer => {
+        const value = answer.trim() || defaultValue || '';
+        if (validate) {
+          const error = validate(value);
+          if (error) {
+            console.error(`Error: ${error}`);
+            prompt();
+            return;
+          }
+        }
+        resolve(value);
+      });
+    }
+    prompt();
+  });
+}
+
+function validateSymbol(value) {
+  if (!value) {
+    return 'Symbol is required';
+  }
+  if (value.length > 5) {
+    return 'Symbol must be 5 characters or fewer';
+  }
+  if (!/^[A-Z0-9\- ]{1,5}$/.test(value)) {
+    return 'Symbol must contain only uppercase letters, digits, hyphens, and spaces';
+  }
+  return null;
+}
+
+function validateHslColor(value) {
+  if (!value) {
+    return 'Color is required';
+  }
+  if (!/^hsl\(\d+(deg)? \d+% \d+%\)$/.test(value)) {
+    return 'Color must be in HSL format, e.g. hsl(195 70% 40%)';
+  }
+  return null;
+}
+
+function validateUrl(value) {
+  if (!value) {
+    return 'URL is required';
+  }
+  if (!/^https?:\/\/[-.:a-zA-Z0-9]+$/.test(value)) {
+    return 'Must be a valid URL like https://example.edu (no trailing slash or path)';
+  }
+  return null;
+}
+
+function validateBasePath(value) {
+  if (!/^\/[-a-zA-Z0-9]*$/.test(value)) {
+    return 'Must start with / and contain only letters, digits, and hyphens';
+  }
+  return null;
+}
+
+function createSiteConfig({
+  title,
+  symbol,
+  themeColor,
+  tintHue,
+  tintAmount,
+  defaultTimeZone,
+  base,
+  basePath,
+  internalDomains,
+}) {
+  return {
+    title,
+    symbol,
+    features: { search: true, code: true, favicon: true },
+    base,
+    basePath,
+    internalDomains,
+    defaultTimeZone,
+    codeLanguages: { java: 'java', py: 'python' },
+    themeColor,
+    tintHue: Number(tintHue),
+    tintAmount: Number(tintAmount),
+    vars: {},
+  };
+}
+
+async function initCommand(args) {
+  const dirname = args[0];
+  const useDefaults = args[1] === '--default';
+
+  if (!dirname) {
+    console.error('Error: Provide a name for the new directory');
+    console.log('Usage: tada init <dirname> [--default]');
+    process.exit(1);
+  }
+
+  const projectDir = path.resolve(process.cwd(), dirname);
+  if (fs.existsSync(projectDir)) {
+    console.error(`Error: "${dirname}" already exists`);
+    process.exit(1);
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  let message = `Creating a new Tada site in ${projectDir}`;
+  if (useDefaults) {
+    console.log(message + ' using default config');
+  } else {
+    console.log(message);
+  }
+
+  const config = {};
+
+  for (const [key, { prompt, defaultValue, validate }] of Object.entries(
+    INIT_QUESTIONS,
+  )) {
+    if (useDefaults) {
+      config[key] = defaultValue;
+    } else {
+      config[key] = await ask(rl, prompt, { defaultValue, validate });
+    }
+  }
+
+  const {
+    title,
+    symbol,
+    themeColor,
+    tintHue,
+    tintAmount,
+    defaultTimeZone,
+    prodBase,
+    prodBasePath,
+  } = config;
+
+  rl.close();
+
+  // Derive internal domain from production base URL
+  const prodDomain = new URL(prodBase).hostname;
+
+  // Create project directory
+  fs.mkdirSync(path.join(projectDir, 'config'), { recursive: true });
+
+  // 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, 'config/site.dev.json'),
+    JSON.stringify(devConfig, null, 2) + '\n',
+  );
+
+  fs.writeFileSync(
+    path.join(projectDir, 'config/site.prod.json'),
+    JSON.stringify(prodConfig, null, 2) + '\n',
+  );
+
+  // Copy nav and authors data files to the project's config directory
+  fs.copyFileSync(
+    path.join(packageDir, 'config/nav.json'),
+    path.join(projectDir, 'config/nav.json'),
+  );
+  fs.copyFileSync(
+    path.join(packageDir, 'config/authors.json'),
+    path.join(projectDir, 'config/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`);
+}
+
+// --- main ---
+
+const command = process.argv[2];
+
+switch (command) {
+  case 'init':
+    initCommand(process.argv.slice(3));
+    break;
+
+  case 'dev':
+    run(
+      `bun ${webpackCli} --config ${path.join(packageDir, 'webpack/config.dev.js')}`,
+    );
+    break;
+
+  case 'prod':
+    run(
+      `bun ${webpackCli} --config ${path.join(packageDir, 'webpack/config.prod.js')}`,
+    );
+    break;
+
+  case 'watch':
+    run(`bun ${path.join(packageDir, 'webpack/watch.js')}`);
+    break;
+
+  case 'serve':
+    run(`bun ${path.join(packageDir, 'webpack/serve.js')}`);
+    break;
+
+  case 'clean':
+    fs.rmSync(path.resolve(process.cwd(), 'dist'), {
+      recursive: true,
+      force: true,
+    });
+    console.log('Cleaned dist/');
+    break;
+
+  default:
+    printUsage();
+    if (command && command !== '--help' && command !== '-h') {
+      process.exit(1);
+    }
+    break;
+}

package/config/authors.json

@@ -0,0 +1 @@
+{ "alex": { "name": "Alex Breen", "avatar": "/avatars/alex.jpg" } }

package/config/nav.json

@@ -0,0 +1,28 @@
+[
+  {
+    "title": "Navigation",
+    "links": [{ "text": "Home", "internal": "/index.html" }]
+  },
+  {
+    "title": "Topics",
+    "links": [
+      { "text": "Lectures", "internal": "/lectures/index.html" },
+      {
+        "text": "Problem Sets",
+        "internal": "/problem_sets/index.html",
+        "disabled": true
+      }
+    ]
+  },
+  {
+    "title": "Links",
+    "links": [
+      { "text": "Zoom", "external": "https://zoom.com" },
+      {
+        "text": "Canvas",
+        "external": "https://www.instructure.com/",
+        "disabled": true
+      }
+    ]
+  }
+]