@abreen/tada 1.1.0 → 1.3.1

package/README.md

@@ -23,11 +23,12 @@ A static site generator. The successor to Presto.
 - 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)
+- LaTeX math rendered at build time via [KaTeX][katex]
 - 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
+  * `??? question ... ???` 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
@@ -78,8 +79,13 @@ Create a new Tada site in a new directory. Prompts for:
 - **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.
+Pass `--no-interactive` to skip prompts and use default values for all options.
+You can also override specific defaults with flags:
+
+    tada init mysite --no-interactive --prod-base https://example.edu --prod-base-path /cs101
+
+Available flags: `--title`, `--symbol`, `--theme-color`, `--tint-hue`,
+`--tint-amount`, `--default-time-zone`, `--prod-base`, `--prod-base-path`.
 
 
 ### `tada dev`
@@ -101,12 +107,69 @@ Start a development web server, watch for changes and rebuild automatically.
 
 ### `tada clean`
 
-Remove the `dist/` directory.
+Remove the `dist/` directory. Pass `--prod` to also prune old production
+builds (keeps the latest two versions).
 
 
 ### `tada prod`
 
-Build the site for production (uses `site.prod.json`).
+Build the site for production (uses `site.prod.json`). Each prod build is
+saved to a versioned directory under `dist-prod/` (e.g., `dist-prod/v1/`,
+`dist-prod/v2/`) with a manifest file that records the SHA-256 hash of every
+output file.
+
+
+### `tada diff`
+
+Compare two production builds and list added, changed, and removed files.
+With no arguments, compares the last two builds. You can also specify version
+numbers explicitly:
+
+    tada diff          # compare latest two builds
+    tada diff 1 3      # compare v1 and v3
+
+Use `--copy <dir>` to copy only the changed and added files to a directory:
+
+    tada diff --copy upload/
+
+The output directory will also include a `manifest.json` for the newer build.
+
+
+## Development vs. production builds
+
+`tada dev` and `tada watch` build to the `dist/` directory using
+`site.dev.json` (typically `localhost` URLs). `tada watch` includes a
+development server with live reload; `tada serve` is a standalone server
+for previewing a `tada dev` build. Dev builds overwrite `dist/` each time.
+
+`tada prod` builds to a new versioned directory under `dist-prod/` each time
+it runs. Previous production builds are preserved, so you can compare any
+two versions with `tada diff`.
+
+
+## Deploying to S3
+
+If you host your site in an S3 bucket, `tada diff --copy` lets you upload
+only the files that changed between prod builds instead of re-uploading
+everything.
+
+First time:
+
+```
+tada prod
+# Upload the entire dist-prod/v1/ directory to your S3 bucket
+```
+
+After making changes:
+
+```
+tada prod
+tada diff --copy upload/
+# Upload just the upload/ directory to S3 (only changed files)
+```
+
+If `tada diff` reports removed files, delete those from your S3 bucket
+manually.
 
 
 ## Prerequisites
@@ -224,18 +287,6 @@ with `name`, `avatar`, and optionally `url`.
 ```
 
 
-### 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.
@@ -284,3 +335,4 @@ templates][lodash].
 [pagefind]: https://pagefind.app/
 [mutool]: https://mupdf.readthedocs.io/en/latest/tools/mutool.html
 [jep467]: https://openjdk.org/jeps/467
+[katex]: https://katex.org/

package/bin/tada.ts

@@ -2,6 +2,7 @@
 import fs from 'fs';
 import path from 'path';
 import { execSync } from 'child_process';
+import { parseArgs } from 'util';
 import packageJson from '../package.json' with { type: 'json' };
 import {
   validateSymbol,
@@ -10,7 +11,14 @@ import {
   validateUrl,
   validateBasePath,
   createSiteConfig,
-} from './validators.js';
+} from './validators';
+import {
+  loadManifest,
+  diffManifests,
+  copyChangedFiles,
+  getVersions,
+  pruneOldVersions,
+} from '../build/build-manifest';
 
 const { version } = packageJson;
 
@@ -33,6 +41,7 @@ const COMMANDS = {
   watch: 'Watch for changes and rebuild',
   serve: 'Start a local development server',
   clean: null,
+  diff: null,
 };
 
 interface InitQuestion {
@@ -97,13 +106,45 @@ function printUsage() {
   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)',
+        '       [--no-interactive]  (Skip prompts; use defaults or flags)',
+      );
+      console.log(
+        '       [--bare]            (Create a minimal site with one page)',
+      );
+      console.log('       [--title, --symbol, --theme-color, --tint-hue,');
+      console.log('        --tint-amount, --default-time-zone, --prod-base,');
+      console.log('        --prod-base-path]');
+      continue;
+    } else if (cmd === 'watch') {
+      console.log(`  ${cmd.padEnd(18)} ${desc}`);
+      console.log(
+        '       [--port <n>]        HTTP server port (default: 8080)',
+      );
+      console.log(
+        '       [--ws-port <n>]     WebSocket port for live reload (default: 35729)',
+      );
+      continue;
+    } else if (cmd === 'serve') {
+      console.log(`  ${cmd.padEnd(18)} ${desc}`);
+      console.log(
+        '       [--port <n>]        HTTP server port (default: 8080)',
       );
       continue;
     } else if (cmd === 'clean') {
       console.log('  clean              Remove the dist/ directory');
+      console.log(
+        '       [--prod]            Prune old prod builds, keeping the two latest',
+      );
+      continue;
+    } else if (cmd === 'diff') {
+      console.log(
+        '  diff               Show changed files since last prod build',
+      );
+      console.log('       [N M]               Compare version N vs version M');
+      console.log(
+        '       [--copy <dir>]      Copy changed files to a directory',
+      );
       continue;
     }
     console.log(`  ${cmd.padEnd(18)} ${desc}`);
@@ -111,7 +152,18 @@ function printUsage() {
 }
 
 function run(cmd: string): void {
-  execSync(cmd, { cwd: process.cwd(), stdio: 'inherit' });
+  try {
+    execSync(cmd, { cwd: process.cwd(), stdio: 'inherit' });
+  } catch (err: unknown) {
+    const code = (err as { status?: number }).status;
+    if (code != null) {
+      console.error(`tada ${command} failed with exit code ${code}`);
+      process.exit(code);
+    } else {
+      console.error(`tada ${command} failed`);
+      process.exit(1);
+    }
+  }
 }
 
 function copyDirRecursive(src: string, dest: string): void {
@@ -127,14 +179,69 @@ function copyDirRecursive(src: string, dest: string): void {
   }
 }
 
+const FLAG_TO_KEY: Record<string, string> = {
+  title: 'title',
+  symbol: 'symbol',
+  'theme-color': 'themeColor',
+  'tint-hue': 'tintHue',
+  'tint-amount': 'tintAmount',
+  'default-time-zone': 'defaultTimeZone',
+  'prod-base': 'prodBase',
+  'prod-base-path': 'prodBasePath',
+};
+
 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];
+  let values: Record<string, string | boolean | undefined>;
+  let positionals: string[];
+
+  try {
+    ({ values, positionals } = parseArgs({
+      args,
+      options: {
+        'no-interactive': { type: 'boolean', default: false },
+        bare: { type: 'boolean', default: false },
+        title: { type: 'string', default: INIT_QUESTIONS.title.defaultValue },
+        symbol: { type: 'string', default: INIT_QUESTIONS.symbol.defaultValue },
+        'theme-color': {
+          type: 'string',
+          default: INIT_QUESTIONS.themeColor.defaultValue,
+        },
+        'tint-hue': {
+          type: 'string',
+          default: INIT_QUESTIONS.tintHue.defaultValue,
+        },
+        'tint-amount': {
+          type: 'string',
+          default: INIT_QUESTIONS.tintAmount.defaultValue,
+        },
+        'default-time-zone': {
+          type: 'string',
+          default: INIT_QUESTIONS.defaultTimeZone.defaultValue,
+        },
+        'prod-base': {
+          type: 'string',
+          default: INIT_QUESTIONS.prodBase.defaultValue,
+        },
+        'prod-base-path': {
+          type: 'string',
+          default: INIT_QUESTIONS.prodBasePath.defaultValue,
+        },
+      },
+      strict: true,
+      allowPositionals: true,
+    }));
+  } catch (e: unknown) {
+    console.error(`Error: ${(e as Error).message}`);
+    process.exit(1);
+  }
+
+  const noInteractive = values['no-interactive'] as boolean;
+  const bare = values.bare as boolean;
+  const dirname = positionals[0];
 
   if (!dirname) {
     console.error('Error: Provide a name for the new directory');
-    console.log('Usage: tada init <dirname> [--default] [--bare]');
+    console.log('Usage: tada init <dirname> [--no-interactive] [--bare]');
     process.exit(1);
   }
 
@@ -145,9 +252,9 @@ async function initCommand(args: string[]): Promise<void> {
   }
 
   const message = `Creating a new Tada site in ${projectDir}`;
-  if (useDefaults && bare) {
+  if (noInteractive && bare) {
     console.log(message + ' using default config (bare)');
-  } else if (useDefaults) {
+  } else if (noInteractive) {
     console.log(message + ' using default config');
   } else if (bare) {
     console.log(message + ' (bare)');
@@ -157,9 +264,15 @@ async function initCommand(args: string[]): Promise<void> {
 
   const config: Record<string, string> = {};
 
-  if (useDefaults) {
-    for (const [key, { defaultValue }] of Object.entries(INIT_QUESTIONS)) {
-      config[key] = defaultValue;
+  if (noInteractive) {
+    for (const [flag, key] of Object.entries(FLAG_TO_KEY)) {
+      const value = values[flag] as string;
+      const error = INIT_QUESTIONS[key].validate(value);
+      if (error) {
+        console.error(`Error: --${flag}: ${error}`);
+        process.exit(1);
+      }
+      config[key] = value;
     }
   } else {
     const questions = Object.entries(INIT_QUESTIONS);
@@ -223,6 +336,7 @@ async function initCommand(args: string[]): Promise<void> {
     base: 'http://localhost:8080',
     basePath: '/',
     internalDomains: ['localhost'],
+    features: { search: true, code: true, favicon: false },
   });
 
   const prodConfig = createSiteConfig({
@@ -235,6 +349,7 @@ async function initCommand(args: string[]): Promise<void> {
     base: prodBase,
     basePath: prodBasePath,
     internalDomains: [prodDomain],
+    features: { search: true, code: true, favicon: true },
   });
 
   fs.writeFileSync(
@@ -268,23 +383,59 @@ async function initCommand(args: string[]): Promise<void> {
       ) + '\n',
     );
   } else {
-    // Copy nav and authors data files to the project root
-    fs.copyFileSync(
-      path.join(packageDir, 'config/nav.json'),
+    // Create nav and authors data files in the project root
+    fs.writeFileSync(
       path.join(projectDir, 'nav.json'),
+      JSON.stringify(
+        [
+          {
+            title: 'Navigation',
+            links: [{ text: 'Home', internal: '/index.html' }],
+          },
+          {
+            title: 'Topics',
+            links: [
+              { text: 'Lectures', internal: '/lectures/index.html' },
+              { text: 'Labs', internal: '/labs/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,
+              },
+            ],
+          },
+        ],
+        null,
+        2,
+      ) + '\n',
     );
-    fs.copyFileSync(
-      path.join(packageDir, 'config/authors.json'),
+    fs.writeFileSync(
       path.join(projectDir, 'authors.json'),
+      JSON.stringify(
+        { alex: { name: 'Alex Breen', avatar: '/avatars/alex.jpg' } },
+        null,
+        2,
+      ) + '\n',
     );
 
     // Copy content/ and public/ from the package
     copyDirRecursive(
-      path.join(packageDir, 'content'),
+      path.join(packageDir, 'init/content'),
       path.join(projectDir, 'content'),
     );
     copyDirRecursive(
-      path.join(packageDir, 'public'),
+      path.join(packageDir, 'init/public'),
       path.join(projectDir, 'public'),
     );
   }
@@ -296,6 +447,147 @@ async function initCommand(args: string[]): Promise<void> {
   console.log(`  tada serve`);
 }
 
+function cleanCommand(args: string[]): void {
+  if (args.includes('--prod')) {
+    const prodBase = path.resolve(process.cwd(), 'dist-prod');
+    const removed = pruneOldVersions(prodBase);
+    if (removed.length === 0) {
+      console.log('Nothing to clean.');
+      return;
+    }
+    for (const v of removed) {
+      console.log(`Removed v${v}`);
+    }
+    return;
+  }
+
+  const distDir = path.resolve(process.cwd(), 'dist');
+  if (!fs.existsSync(distDir)) {
+    console.log('Nothing to clean.');
+    return;
+  }
+  fs.rmSync(distDir, { recursive: true });
+  console.log('Cleaned dist/');
+}
+
+function diffCommand(args: string[]): void {
+  const projectDir = process.cwd();
+  const prodBase = path.resolve(projectDir, 'dist-prod');
+  const versions = getVersions(prodBase);
+
+  if (versions.length === 0) {
+    console.error('Error: No prod builds found. Run "tada prod" first.');
+    process.exit(1);
+  }
+
+  const copyIdx = args.indexOf('--copy');
+  const versionArgs = copyIdx === -1 ? args : args.slice(0, copyIdx);
+  const numericArgs = versionArgs
+    .map(a => parseInt(a, 10))
+    .filter(n => !isNaN(n));
+
+  let oldVer: number;
+  let newVer: number;
+
+  if (numericArgs.length === 2) {
+    [oldVer, newVer] = numericArgs.sort((a, b) => a - b);
+  } else if (numericArgs.length === 0) {
+    if (versions.length < 2) {
+      console.error(
+        'Error: Need at least two prod builds to diff. Run "tada prod" again.',
+      );
+      process.exit(1);
+    }
+    oldVer = versions[versions.length - 2];
+    newVer = versions[versions.length - 1];
+  } else {
+    console.error('Error: Provide zero or two version numbers.');
+    console.log('Usage: tada diff [N M] [--copy <dir>]');
+    process.exit(1);
+  }
+
+  const oldManifestPath = path.join(prodBase, `v${oldVer}.manifest.json`);
+  const newManifestPath = path.join(prodBase, `v${newVer}.manifest.json`);
+
+  const oldManifest = loadManifest(oldManifestPath);
+  if (!oldManifest) {
+    console.error(`Error: No manifest for v${oldVer}.`);
+    process.exit(1);
+  }
+  const newManifest = loadManifest(newManifestPath);
+  if (!newManifest) {
+    console.error(`Error: No manifest for v${newVer}.`);
+    process.exit(1);
+  }
+
+  const diff = diffManifests(oldManifest, newManifest);
+  const totalChanges =
+    diff.added.length + diff.changed.length + diff.removed.length;
+
+  const fmtDate = (iso: string) => new Date(iso).toLocaleString();
+  console.log(`v${oldVer}  ${fmtDate(oldManifest.buildTime)}`);
+  console.log(`v${newVer}  ${fmtDate(newManifest.buildTime)}`);
+
+  if (totalChanges === 0) {
+    console.log('\nNo changes between builds.');
+    return;
+  }
+
+  if (diff.added.length > 0) {
+    console.log(`\nAdded (${diff.added.length}):`);
+    for (const f of diff.added) {
+      console.log(`  + ${f}`);
+    }
+  }
+  if (diff.changed.length > 0) {
+    console.log(`\nChanged (${diff.changed.length}):`);
+    for (const f of diff.changed) {
+      console.log(`  ~ ${f}`);
+    }
+  }
+  if (diff.removed.length > 0) {
+    console.log(`\nRemoved (${diff.removed.length}):`);
+    for (const f of diff.removed) {
+      console.log(`  - ${f}`);
+    }
+  }
+
+  const noun = (n: number) => (n === 1 ? 'file' : 'files');
+  console.log(`\nTotal: ${totalChanges} ${noun(totalChanges)} differ`);
+
+  if (copyIdx !== -1) {
+    const outDirArg = args[copyIdx + 1];
+    if (!outDirArg) {
+      console.error('Error: --copy requires a directory argument');
+      process.exit(1);
+    }
+
+    const newDistDir = path.join(prodBase, `v${newVer}`);
+    const resolvedOutDir = path.resolve(projectDir, outDirArg);
+    copyChangedFiles(diff, newDistDir, resolvedOutDir);
+
+    // Always include pagefind/ (excluded from manifest but needed for search)
+    const pagefindSrc = path.join(newDistDir, 'pagefind');
+    if (fs.existsSync(pagefindSrc)) {
+      copyDirRecursive(pagefindSrc, path.join(resolvedOutDir, 'pagefind'));
+    }
+
+    const manifestSrc = path.join(prodBase, `v${newVer}.manifest.json`);
+    fs.copyFileSync(manifestSrc, path.join(resolvedOutDir, 'manifest.json'));
+
+    const copiedCount = diff.added.length + diff.changed.length;
+    console.log(
+      `\nCopied ${copiedCount} ${noun(copiedCount)} + manifest.json to ${outDirArg}`,
+    );
+
+    if (diff.removed.length > 0) {
+      console.log(
+        `\nNote: ${diff.removed.length} ${noun(diff.removed.length)} were removed from the build.`,
+      );
+    }
+  }
+}
+
 /*
  * Start of script
  */
@@ -335,11 +627,11 @@ switch (command) {
   }
 
   case 'clean':
-    fs.rmSync(path.resolve(process.cwd(), 'dist'), {
-      recursive: true,
-      force: true,
-    });
-    console.log('Cleaned dist/');
+    cleanCommand(process.argv.slice(3));
+    break;
+
+  case 'diff':
+    diffCommand(process.argv.slice(3));
     break;
 
   case '--version':

package/bin/validators.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import type { SiteConfigInput } from '../build/types.js';
+import type { SiteConfigInput } from '../build/types';
 import {
   validateSymbol,
   validateColor,
@@ -7,7 +7,7 @@ import {
   validateUrl,
   validateBasePath,
   createSiteConfig,
-} from './validators.js';
+} from './validators';
 
 describe('validateSymbol', () => {
   test('accepts a single uppercase letter', () => {
@@ -172,6 +172,7 @@ describe('createSiteConfig', () => {
     base: 'https://example.edu',
     basePath: '/',
     internalDomains: ['example.edu'],
+    features: { search: true, code: true, favicon: false },
   };
 
   test('returns an object with all expected keys', () => {
@@ -184,7 +185,7 @@ describe('createSiteConfig', () => {
       basePath: '/',
       internalDomains: ['example.edu'],
       defaultTimeZone: 'America/New_York',
-      features: { search: true, code: true, favicon: true },
+      features: { search: true, code: true, favicon: false },
       codeLanguages: { java: 'java', py: 'python' },
       vars: {},
     });

package/bin/validators.ts

@@ -1,4 +1,4 @@
-import type { SiteConfigInput, SiteVariables } from '../build/types.js';
+import type { SiteConfigInput, SiteVariables } from '../build/types';
 
 export function validateSymbol(value: string): string | null {
   if (!value) {
@@ -65,11 +65,13 @@ export function createSiteConfig({
   base,
   basePath,
   internalDomains,
+  features,
 }: SiteConfigInput): SiteVariables {
   return {
     title,
+    titlePostfix: ` - ${title}`,
     symbol,
-    features: { search: true, code: true, favicon: true },
+    features,
     base,
     basePath,
     internalDomains,

package/build/apply-base-path-plugin.ts

@@ -1,8 +1,9 @@
 import type MarkdownIt from 'markdown-it';
 import type Token from 'markdown-it/lib/token.mjs';
-import { createApplyBasePath } from './utils/paths.js';
-import { makeLogger } from './log.js';
-import type { SiteVariables } from './types.js';
+import { createApplyBasePath } from './utils/paths';
+import { isFeatureEnabled } from './features';
+import { makeLogger } from './log';
+import type { SiteVariables } from './types';
 
 const log = makeLogger(__filename);
 
@@ -11,7 +12,7 @@ export default function applyBasePathPlugin(
   siteVariables: SiteVariables,
 ): void {
   const applyBasePath = createApplyBasePath(siteVariables);
-  const rewriteCodeLinks = siteVariables.features?.code !== false;
+  const rewriteCodeLinks = isFeatureEnabled(siteVariables, 'code');
 
   function rewriteInternalHref(href: string): string {
     const match = href.match(/^([^?#]*)(.*)$/);
@@ -67,15 +68,25 @@ export default function applyBasePathPlugin(
         token.attrSet('src', afterApply);
       }
     } else if (token.type === 'html_block' || token.type === 'html_inline') {
-      token.content = token.content.replace(
-        /(<img\b[^>]*\bsrc=")(\/)([^"]*")/g,
-        (match, prefix, slash, rest) => {
-          const src = slash + rest.slice(0, -1);
-          const afterApply = applyBasePath(src);
-          log.debug`Applying base path to img tag src: ${src} -> ${afterApply}`;
-          return prefix + afterApply + '"';
-        },
-      );
+      token.content = token.content
+        .replace(
+          /(<a\b[^>]*\bhref=")(\/)([^"]*")/g,
+          (match, prefix, slash, rest) => {
+            const href = slash + rest.slice(0, -1);
+            const afterApply = applyBasePath(href);
+            log.debug`Applying base path to a tag href: ${href} -> ${afterApply}`;
+            return prefix + afterApply + '"';
+          },
+        )
+        .replace(
+          /(<img\b[^>]*\bsrc=")(\/)([^"]*")/g,
+          (match, prefix, slash, rest) => {
+            const src = slash + rest.slice(0, -1);
+            const afterApply = applyBasePath(src);
+            log.debug`Applying base path to img tag src: ${src} -> ${afterApply}`;
+            return prefix + afterApply + '"';
+          },
+        );
     }
 
     token.children?.map(checkAndApplyBasePath);