@abreen/tada 1.0.2 → 1.2.0

package/build/watch.ts

@@ -0,0 +1,549 @@
+#!/usr/bin/env bun
+import fs from 'fs';
+import { fork } from 'child_process';
+import path from 'path';
+import chokidar from 'chokidar';
+import WebSocket, { WebSocketServer } from 'ws';
+import type { SiteVariables, WatchState } from './types';
+import { B } from './colors';
+import { makeLogger, printFlair } from './log';
+import { getDevSiteVariables } from './site-variables';
+import { compileTemplates, getJsonDataDir, JSON_DATA_FILES } from './templates';
+import {
+  getContentDir,
+  getPublicDir,
+  getDistDir,
+  getPackageDir,
+} from './utils/paths';
+import { isFeatureEnabled } from './features';
+import { bundle } from './bundle';
+import { copyFonts } from './generate-fonts';
+import { copyKatexAssets } from './generate-katex-assets';
+import { generateFavicons } from './generate-favicon';
+import { generateManifest } from './generate-manifest';
+import {
+  copyPublicFiles,
+  copyContentAssets,
+  copyContentFile,
+  copyPublicFile,
+} from './copy';
+import { getProcessedExtensions } from './utils/file-types';
+import { ContentRenderer } from './generate-content-assets';
+import { WatchPagefindRunner } from './pagefind';
+import { ContentChangeDetector } from './content-watch';
+
+function getArg(name: string): number | null {
+  const idx = process.argv.indexOf(name);
+  if (idx !== -1 && process.argv[idx + 1]) {
+    const val = parseInt(process.argv[idx + 1], 10);
+    if (val > 0 && val < 65536) {
+      return val;
+    }
+  }
+  return null;
+}
+
+const httpPort = getArg('--port');
+const WEBSOCKET_PORT = getArg('--ws-port') ?? 35729;
+const DEBOUNCE_MS = 300;
+const RELOAD_CLIENT_PATH = path.resolve(
+  getPackageDir(),
+  'build/watch-reload-client.ts',
+);
+
+// Bundle the reload client separately to work around a Bun bundler bug where
+// side-effect-only JS entrypoints are tree-shaken when bundled alongside SCSS
+// entrypoints processed by a plugin.
+async function bundleReloadClient(): Promise<string[]> {
+  const result = await Bun.build({
+    entrypoints: [RELOAD_CLIENT_PATH],
+    outdir: getDistDir(),
+    naming: '[name].bundle.[ext]',
+    sourcemap: 'inline',
+    define: { __WEBSOCKET_PORT__: String(WEBSOCKET_PORT) },
+  });
+  return result.outputs.map(output =>
+    path
+      .relative(getDistDir(), output.path)
+      .split(path.sep)
+      .join(path.posix.sep),
+  );
+}
+
+type ChangeCategory = 'content' | 'public' | 'config';
+
+const log = makeLogger(__filename);
+const wslog = makeLogger('WebSocket');
+
+// --- WebSocket server (unchanged) ---
+
+let webSocketsReady = false;
+let watcherReady = false;
+let webServerReady = false;
+let webServerTimeout: ReturnType<typeof setTimeout> | undefined;
+let serveStarted = false;
+
+let wss: WebSocketServer | null = null;
+try {
+  wss = new WebSocketServer({ port: WEBSOCKET_PORT });
+
+  wss.on('connection', (conn: WebSocket) => {
+    wslog.debug`WebSocket client connected`;
+    if (watcherReady && conn.readyState === WebSocket.OPEN) {
+      if (initialBuildFailed) {
+        conn.send('error');
+      }
+      conn.send('ready');
+    }
+    conn.on('close', () => {
+      wslog.debug`WebSocket client disconnected`;
+    });
+  });
+
+  wss.on('error', (err: Error) => {
+    wslog.error`WebSocket server error: ${err.message}`;
+  });
+
+  wss.on('listening', () => {
+    wslog.debug`WebSocket server listening at ws://localhost:${WEBSOCKET_PORT}`;
+    webSocketsReady = true;
+  });
+} catch (err) {
+  wslog.error`Failed to start WebSocket server on port ${WEBSOCKET_PORT}: ${(err as Error).message}`;
+}
+
+function broadcast(msg: string): void {
+  if (wss == null || !webSocketsReady) {
+    return;
+  }
+  wslog.debug`Broadcasting "${msg}" to WebSocket clients`;
+  wss.clients.forEach((client: WebSocket) => {
+    if (client.readyState === WebSocket.OPEN) {
+      client.send(msg);
+    }
+  });
+}
+
+// --- Dev server ---
+
+function serve(): void {
+  const serveArgs = httpPort != null ? ['--port', String(httpPort)] : [];
+  const child = fork(path.join(__dirname, 'serve.js'), serveArgs, {
+    stdio: 'inherit',
+  });
+  child.on('close', (code: number | null) => {
+    webServerReady = false;
+    log.error`Web server exited with code ${code}`;
+    process.exit(2);
+  });
+  child.on('error', (err: Error) => {
+    webServerReady = false;
+    log.error`Web server failed: ${err.message}`;
+  });
+  child.on('message', (msg: Record<string, unknown>) => {
+    if (msg.ready) {
+      webServerReady = true;
+      clearTimeout(webServerTimeout);
+    }
+  });
+
+  webServerTimeout = setTimeout(() => {
+    if (webServerReady) {
+      return;
+    }
+    log.error`Web server failed to report within 10 seconds, exiting`;
+    process.exit(3);
+  }, 10000);
+}
+
+// --- Path helpers ---
+
+function toContentMarkdownPath(filePath: string): string | null {
+  if (!filePath) {
+    return null;
+  }
+  const ext = path.extname(filePath).toLowerCase();
+  if (!['.md', '.markdown'].includes(ext)) {
+    return null;
+  }
+
+  const normalizedContentDir = path.resolve(contentDir) + path.sep;
+  const normalizedFilePath = path.resolve(filePath);
+  if (!normalizedFilePath.startsWith(normalizedContentDir)) {
+    return null;
+  }
+
+  return path
+    .relative(contentDir, normalizedFilePath)
+    .split(path.sep)
+    .join(path.posix.sep);
+}
+
+function toPublicRelativePath(filePath: string): string | null {
+  if (!filePath) {
+    return null;
+  }
+  const normalizedPublicDir = path.resolve(publicDir) + path.sep;
+  const normalizedFilePath = path.resolve(filePath);
+  if (!normalizedFilePath.startsWith(normalizedPublicDir)) {
+    return null;
+  }
+  return path
+    .relative(publicDir, normalizedFilePath)
+    .split(path.sep)
+    .join(path.posix.sep);
+}
+
+// --- Watch mode ---
+
+const contentDir: string = getContentDir();
+const publicDir: string = getPublicDir();
+const distDir: string = getDistDir();
+
+let siteVariables: SiteVariables;
+let processedExtSet = new Set<string>();
+let publicRelPaths: Set<string> = new Set();
+let contentAssetRelPaths: Set<string> = new Set();
+let contentRenderer: ContentRenderer;
+let changeDetector: ContentChangeDetector;
+let pagefindRunner: WatchPagefindRunner | undefined;
+let assetFiles: string[] = [];
+let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+const pendingChanges = new Set<string>();
+let rebuilding = false;
+
+async function initialBuild(): Promise<void> {
+  siteVariables = getDevSiteVariables();
+  processedExtSet = new Set(
+    getProcessedExtensions(Object.keys(siteVariables.codeLanguages || {})),
+  );
+  fs.mkdirSync(distDir, { recursive: true });
+
+  compileTemplates(siteVariables);
+  contentRenderer = new ContentRenderer(siteVariables);
+  changeDetector = new ContentChangeDetector(siteVariables);
+
+  if (isFeatureEnabled(siteVariables, 'search')) {
+    pagefindRunner = new WatchPagefindRunner(siteVariables);
+  }
+
+  await contentRenderer.initHighlighter();
+
+  assetFiles = [
+    ...(await bundle(siteVariables, { mode: 'development' })),
+    ...(await bundleReloadClient()),
+  ];
+
+  copyFonts(distDir);
+  copyKatexAssets(distDir);
+
+  if (isFeatureEnabled(siteVariables, 'favicon')) {
+    await generateFavicons(siteVariables, distDir);
+    generateManifest(siteVariables, distDir);
+  }
+
+  publicRelPaths = copyPublicFiles(publicDir, distDir);
+  contentAssetRelPaths = copyContentAssets(
+    contentDir,
+    distDir,
+    [...processedExtSet],
+    publicRelPaths,
+  );
+
+  const result = contentRenderer.processContent({ distDir, assetFiles });
+
+  for (const err of result.errors) {
+    log.error`${err.message}`;
+  }
+
+  if (result.errors.length === 0) {
+    printFlair();
+
+    if (pagefindRunner) {
+      pagefindRunner.update(distDir, result.htmlAssetsByPath);
+      setImmediate(() => pagefindRunner!.run());
+    }
+
+    if (!serveStarted) {
+      serveStarted = true;
+      serve();
+    }
+  }
+}
+
+function classifyChange(filePath: string): ChangeCategory | null {
+  const resolved = path.resolve(filePath);
+  const resolvedContentDir = path.resolve(contentDir) + path.sep;
+  const resolvedPublicDir = path.resolve(publicDir) + path.sep;
+  const jsonDataDir = getJsonDataDir();
+  const siteConfigPath = path.resolve('site.dev.json');
+
+  if (resolved.startsWith(resolvedContentDir)) {
+    return 'content';
+  }
+  if (resolved.startsWith(resolvedPublicDir)) {
+    return 'public';
+  }
+  if (
+    resolved === siteConfigPath ||
+    JSON_DATA_FILES.some(f => resolved === path.resolve(jsonDataDir, f))
+  ) {
+    return 'config';
+  }
+  return null;
+}
+
+async function rebuild(): Promise<void> {
+  if (rebuilding) {
+    return;
+  }
+  rebuilding = true;
+
+  const changes = new Set(pendingChanges);
+  pendingChanges.clear();
+
+  broadcast('rebuilding');
+
+  // Classify changes
+  const categories = new Set<ChangeCategory>();
+  for (const filePath of changes) {
+    const category = classifyChange(filePath);
+    if (category) {
+      categories.add(category);
+    }
+  }
+
+  let succeeded = false;
+
+  try {
+    // Site config changed, full restart
+    if (categories.has('config')) {
+      log.event`Site config changed, restarting`;
+      siteVariables = getDevSiteVariables();
+      processedExtSet = new Set(
+        getProcessedExtensions(Object.keys(siteVariables.codeLanguages || {})),
+      );
+      contentRenderer = new ContentRenderer(siteVariables);
+      changeDetector = new ContentChangeDetector(siteVariables);
+      if (isFeatureEnabled(siteVariables, 'search')) {
+        pagefindRunner = new WatchPagefindRunner(siteVariables);
+      }
+      compileTemplates(siteVariables);
+      await contentRenderer.initHighlighter();
+
+      assetFiles = [
+        ...(await bundle(siteVariables, { mode: 'development' })),
+        ...(await bundleReloadClient()),
+      ];
+
+      copyFonts(distDir);
+      copyKatexAssets(distDir);
+
+      if (isFeatureEnabled(siteVariables, 'favicon')) {
+        await generateFavicons(siteVariables, distDir);
+        generateManifest(siteVariables, distDir);
+      }
+
+      const result = contentRenderer.processContent({ distDir, assetFiles });
+      for (const err of result.errors) {
+        log.error`${err.message}`;
+      }
+      if (result.errors.length === 0) {
+        printFlair();
+        if (!serveStarted) {
+          serveStarted = true;
+          serve();
+        }
+        broadcast('reload');
+        if (pagefindRunner) {
+          pagefindRunner.update(distDir, result.htmlAssetsByPath);
+          setImmediate(() => pagefindRunner!.run());
+        }
+        succeeded = true;
+      }
+      return;
+    }
+
+    // Public file changed, copy just that file
+    if (categories.has('public') && !categories.has('content')) {
+      for (const filePath of changes) {
+        if (classifyChange(filePath) === 'public') {
+          const absPath = path.resolve(filePath);
+          if (fs.existsSync(absPath)) {
+            copyPublicFile(publicDir, distDir, absPath, contentAssetRelPaths);
+            const rel = path
+              .relative(publicDir, absPath)
+              .split(path.sep)
+              .join(path.posix.sep);
+            publicRelPaths.add(rel);
+          }
+        }
+      }
+      printFlair();
+      broadcast('reload');
+      succeeded = true;
+      return;
+    }
+
+    // Content changed, incremental rebuild
+    const detection = changeDetector.detectChanges(changes);
+
+    if (detection.needsRestart) {
+      log.event`Content structure changed, full rebuild`;
+      contentRenderer = new ContentRenderer(siteVariables);
+      await contentRenderer.initHighlighter();
+    }
+
+    // Log changed content files
+    for (const filePath of changes) {
+      const markdownPath = toContentMarkdownPath(filePath);
+      if (markdownPath) {
+        log.event`${B`${markdownPath}`} changed, rebuilding`;
+      } else {
+        const pubPath = toPublicRelativePath(filePath);
+        if (pubPath) {
+          log.event`${B`public/${pubPath}`} changed`;
+        }
+      }
+    }
+
+    // Copy any changed public files too
+    if (categories.has('public')) {
+      for (const filePath of changes) {
+        if (classifyChange(filePath) === 'public') {
+          const absPath = path.resolve(filePath);
+          if (fs.existsSync(absPath)) {
+            copyPublicFile(publicDir, distDir, absPath, contentAssetRelPaths);
+            const rel = path
+              .relative(publicDir, absPath)
+              .split(path.sep)
+              .join(path.posix.sep);
+            publicRelPaths.add(rel);
+          }
+        }
+      }
+    }
+
+    // Copy any changed non-processed content files (images, PDFs, etc.)
+    if (categories.has('content')) {
+      for (const filePath of changes) {
+        if (classifyChange(filePath) !== 'content') {
+          continue;
+        }
+        const absPath = path.resolve(filePath);
+        const ext = path.extname(absPath).slice(1).toLowerCase();
+        if (!processedExtSet.has(ext) && fs.existsSync(absPath)) {
+          copyContentFile(contentDir, distDir, absPath, publicRelPaths);
+          const rel = path
+            .relative(contentDir, absPath)
+            .split(path.sep)
+            .join(path.posix.sep);
+          contentAssetRelPaths.add(rel);
+        }
+      }
+    }
+
+    const watchState: WatchState | undefined = detection.needsRestart
+      ? undefined
+      : {
+          changedContentFiles: detection.changedContentFiles,
+          templatesChanged: detection.templatesChanged,
+        };
+
+    const result = contentRenderer.processContent({
+      distDir,
+      assetFiles,
+      watchState,
+    });
+
+    for (const err of result.errors) {
+      log.error`${err.message}`;
+    }
+
+    if (result.errors.length === 0) {
+      printFlair();
+      if (!serveStarted) {
+        serveStarted = true;
+        serve();
+      }
+      broadcast('reload');
+
+      if (pagefindRunner) {
+        pagefindRunner.update(distDir, result.htmlAssetsByPath);
+        setImmediate(() => pagefindRunner!.run());
+      }
+      succeeded = true;
+    }
+  } catch (err) {
+    log.error`Build failed: ${(err as Error).message}`;
+  } finally {
+    if (!succeeded) {
+      broadcast('error');
+    }
+    rebuilding = false;
+
+    // If more changes accumulated during rebuild, schedule another
+    if (pendingChanges.size > 0) {
+      scheduleRebuild();
+    }
+  }
+}
+
+function scheduleRebuild(): void {
+  if (debounceTimer) {
+    clearTimeout(debounceTimer);
+  }
+  debounceTimer = setTimeout(rebuild, DEBOUNCE_MS);
+}
+
+function onFileChange(filePath: string): void {
+  pendingChanges.add(filePath);
+  scheduleRebuild();
+}
+
+// --- Start ---
+
+let initialBuildFailed = false;
+
+initialBuild()
+  .catch(err => {
+    log.error`Initial build failed: ${(err as Error).message}`;
+    initialBuildFailed = true;
+  })
+  .finally(() => {
+    // Watch content, public, data files, site config
+    const watchPaths: string[] = [contentDir, publicDir];
+
+    // Watch data files (nav.json, authors.json)
+    const jsonDataDir = getJsonDataDir();
+    for (const dataFile of JSON_DATA_FILES) {
+      const dataPath = path.join(jsonDataDir, dataFile);
+      if (fs.existsSync(dataPath)) {
+        watchPaths.push(dataPath);
+      }
+    }
+
+    // Watch site config
+    const siteConfigPath = path.resolve('site.dev.json');
+    if (fs.existsSync(siteConfigPath)) {
+      watchPaths.push(siteConfigPath);
+    }
+
+    const watcher = chokidar.watch(watchPaths, {
+      ignoreInitial: true,
+      awaitWriteFinish: { stabilityThreshold: 100 },
+    });
+
+    watcher.on('change', onFileChange);
+    watcher.on('add', onFileChange);
+    watcher.on('unlink', onFileChange);
+
+    watcher.on('ready', () => {
+      watcherReady = true;
+      if (initialBuildFailed) {
+        broadcast('error');
+      }
+      broadcast('ready');
+      log.info`Watching for changes...`;
+    });
+  });

package/{content → init/content}/index.md

@@ -1,10 +1,13 @@
 title: Home
 description: The home page for <%= site.title %>.
 author: alex
+published: 2026-03-20
+toolName: Tada
 
 ## Welcome
 
-This is an example site built with [Tada](https://github.com/abreen/tada).
+This is an example site built with <%= page.toolName %>.
+
 
 ## Getting started
 
@@ -14,6 +17,9 @@ contains the site configuration, and `templates/` contains the HTML layouts.
 See the [Markdown examples page](/markdown.html) for syntax examples.
 
 !!! note
-Consult the [readme](https://github.com/abreen/tada) for full
-documentation on configuration, templates, and content authoring.
+For more documentation, see the [GitHub page][github].
 !!!
+
+
+
+[github]: https://github.com/abreen/Tada

package/{content → init/content}/lectures/index.md

@@ -2,7 +2,7 @@ title: Lectures
 author: alex
 description: An example page for <%= site.title %>.
 
-<%= timezoneChooser %>
+<%= renderTimeZoneChooser() %>
 
 One-hour lectures are held weekly at <time datetime="17:40">5:40 PM</time>.
 Each lecture is recorded and made available by password-protected link.

package/{content → init/content}/markdown.md

@@ -1,7 +1,8 @@
 title: Markdown Examples
 description: Examples of Markdown syntax supported by Tada.
-toc: true
 author: alex
+published: 2026-03-20
+toc: true
 
 Markdown and HTML files in the `content/` directory
 must contain ["front matter"][front-matter] (YAML-formatted metadata).
@@ -127,6 +128,20 @@ See `config/site.dev.json` and `config/site.prod.json` to change `site.basePath`
 and `site.internalDomains`.
 
 
+## LaTeX
+
+$\LaTeX$ support is implemented via [KaTeX](https://katex.org/). The standard
+dollar sign-based syntax is supported. Wrap inline math in single `$`,
+or use `$$` for a math block.
+
+Here's an example: selection sort performs $O(n^2)$ comparisons. And to
+demonstrate a block, here's the exact number of comparisons:
+
+$$
+(n-1) + (n-2) + \dots + 1 = \sum_{i=1}^{n-1}i
+$$
+
+
 ## Additional syntax
 
 !!! note Headings are links
@@ -227,7 +242,7 @@ Beware of this rule.
 A time zone chooser for testing styles (see the "time zone chooser" section
 below):
 
-<%= timezoneChooser %>
+<%= renderTimeZoneChooser() %>
 
 A `<time>` element for testing styles: <time datetime="15:00">3 pm</time>
 
@@ -325,14 +340,19 @@ These features aren't Markdown-specific, but are included here for reference.
 
 Allows the user to see times in their local time zone.
 
-!!! note
-Look at the source code for this file to see how to insert it.
-!!!
+Insert the time zone chooser using Lodash templates, calling the
+`renderTimeZoneChooser()` function (made available on any page as a global):
+
+```
+<%= '\x3C%= renderTimeZoneChooser() %\x3E' %>
+```
+
+To produce:
 
-<%= timezoneChooser %>
+<%= renderTimeZoneChooser() %>
 
-Wrap your times in `<time datetime="...">` elements and they will be updated
-when the user makes a time zone selection.
+Then, wrap your times in `<time datetime="...">` elements and they will be
+updated when the user makes a time zone selection.
 
 Use
 

package/init/content/problem_sets/index.html

@@ -0,0 +1,14 @@
+title: Problem Sets
+author: alex
+description: An example page for <%= site.title %> which is not generated.
+skip: true
+
+<p>
+    For convenience or backwards compatibility, you can write standard HTML
+    files. The front matter section should still be specified for HTML files.
+</p>
+
+<p>
+    This page is not generated during the build because <code>skip</code>
+    is set to <code>true</code>.
+</p>