@abreen/tada 1.1.0 → 1.3.1

package/build/generate-content-assets.ts

@@ -1,8 +1,8 @@
 import fs from 'fs';
 import path from 'path';
-import { makeLogger } from './log.js';
-import { isFeatureEnabled } from './features.js';
-import { initHighlighter } from './utils/shiki-highlighter.js';
+import { makeLogger } from './log';
+import { isFeatureEnabled } from './features';
+import { initHighlighter } from './utils/shiki-highlighter';
 import {
   getBuildContentFiles,
   getContentDir,
@@ -11,16 +11,16 @@ import {
   renderCopiedContentAsset,
   renderLiterateJavaPageAsset,
   renderPlainTextPageAsset,
-} from './util.js';
-import { isLiterateJava } from './utils/file-types.js';
-import { checkJavac } from './utils/literate-java.js';
+} from './util';
+import { isLiterateJava } from './utils/file-types';
+import { checkJavac } from './utils/literate-java';
 import type {
   SiteVariables,
   Asset,
   ContentRenderOptions,
   ContentRenderResult,
   WatchState,
-} from './types.js';
+} from './types';
 
 const log = makeLogger(__filename);
 
@@ -102,6 +102,7 @@ export class ContentRenderer {
   renderSourceAssets(
     filePath: string,
     contentDir: string,
+    distDir: string,
     validInternalTargets: Set<string>,
     assetFiles: string[],
   ): Asset[] {
@@ -113,6 +114,7 @@ export class ContentRenderer {
         ...renderLiterateJavaPageAsset({
           filePath,
           contentDir,
+          distDir,
           siteVariables: this.siteVariables,
           assetFiles,
           skipExecution: !this.javacAvailable,
@@ -126,6 +128,7 @@ export class ContentRenderer {
         ...renderPlainTextPageAsset({
           filePath,
           contentDir,
+          distDir,
           siteVariables: this.siteVariables,
           validInternalTargets,
           assetFiles,
@@ -141,6 +144,7 @@ export class ContentRenderer {
           ...renderCodePageAsset({
             filePath,
             contentDir,
+            distDir,
             siteVariables: this.siteVariables,
             assetFiles,
           }),
@@ -274,6 +278,7 @@ export class ContentRenderer {
         assets = this.renderSourceAssets(
           filePath,
           contentDir,
+          distDir,
           validInternalTargets,
           assetFiles,
         );

package/build/generate-favicon.ts

@@ -3,10 +3,10 @@ import path from 'path';
 import * as fontkit from 'fontkit';
 import sharp from 'sharp';
 import pngToIco from 'png-to-ico';
-import { makeLogger } from './log.js';
-import { getPackageDir } from './utils/paths.js';
-import { deriveTheme } from './utils/derive-theme.js';
-import type { SiteVariables } from './types.js';
+import { makeLogger } from './log';
+import { getPackageDir } from './utils/paths';
+import { deriveTheme } from './utils/derive-theme';
+import type { SiteVariables } from './types';
 
 const log = makeLogger(__filename);
 
@@ -117,8 +117,15 @@ export async function generateFavicons(
   const svgSize = 512;
   const filenameBase = 'favicon';
 
-  if (!color || !symbol) {
-    throw new Error('Missing required "color" and/or "symbol" options');
+  if (!symbol) {
+    throw new Error(
+      'Favicon generation requires "symbol" in site config (or "faviconSymbol")',
+    );
+  }
+  if (!color) {
+    throw new Error(
+      'Favicon generation requires "themeColor" in site config (or "faviconColor")',
+    );
   }
 
   const { themeColorLight, textOnThemeLight } = deriveTheme(color);

package/build/generate-fonts.ts

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import path from 'path';
-import { getPackageDir } from './utils/paths.js';
-import { makeLogger } from './log.js';
+import { getPackageDir } from './utils/paths';
+import { makeLogger } from './log';
 
 const log = makeLogger(__filename);
 const FONTS_DIR = path.join(getPackageDir(), 'fonts');

package/build/generate-katex-assets.ts

@@ -0,0 +1,35 @@
+import fs from 'fs';
+import path from 'path';
+import * as sass from 'sass';
+import { makeLogger } from './log';
+
+const log = makeLogger(__filename);
+
+export function copyKatexAssets(distDir: string): void {
+  log.info`Copying KaTeX assets`;
+
+  const outDir = path.join(distDir, 'katex');
+  const outFontsDir = path.join(outDir, 'fonts');
+  fs.mkdirSync(outFontsDir, { recursive: true });
+
+  // Compile KaTeX SCSS with woff2-only font references
+  const katexScssDir = path.dirname(
+    require.resolve('katex/src/styles/katex.scss'),
+  );
+  const result = sass.compileString(
+    `@use 'katex' with ($use-woff2: true, $use-woff: false, $use-ttf: false, $font-folder: 'fonts');`,
+    { loadPaths: [katexScssDir], style: 'compressed' },
+  );
+  fs.writeFileSync(path.join(outDir, 'katex.min.css'), result.css);
+
+  // Copy woff2 fonts
+  const katexDistDir = path.dirname(
+    require.resolve('katex/dist/katex.min.css'),
+  );
+  const fontsDir = path.join(katexDistDir, 'fonts');
+  for (const file of fs.readdirSync(fontsDir)) {
+    if (file.endsWith('.woff2')) {
+      fs.copyFileSync(path.join(fontsDir, file), path.join(outFontsDir, file));
+    }
+  }
+}

package/build/generate-manifest.ts

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import path from 'path';
-import { createApplyBasePath } from './util.js';
-import type { SiteVariables } from './types.js';
+import { createApplyBasePath } from './util';
+import type { SiteVariables } from './types';
 
 interface ManifestIcon {
   src: string;

package/build/globals.test.ts

@@ -1,10 +1,14 @@
 import { describe, expect, test } from 'bun:test';
-import createGlobals from './globals.js';
-import type { SiteVariables } from './types.js';
+import createGlobals from './globals';
+import type { SiteVariables } from './types';
 
 const baseSite: SiteVariables = {
   base: 'http://localhost:8080',
   basePath: '/',
+  title: 'Test',
+  titlePostfix: ' - Test',
+  themeColor: 'hsl(195 70% 40%)',
+  defaultTimeZone: 'America/New_York',
 };
 
 function makeGlobals(subPath = 'index', site: Partial<SiteVariables> = {}) {
@@ -26,16 +30,11 @@ describe('createGlobals', () => {
     expect(g.cx).toBe(g.classNames);
   });
 
-  test('timezoneChooser includes noscript when defaultTimeZone is set', () => {
+  test('renderTimeZoneChooser includes hidden disabled select, inline script, and noscript', () => {
     const g = makeGlobals('index', { defaultTimeZone: 'America/New_York' });
-    expect(g.timezoneChooser).toContain('noscript');
-    expect(g.timezoneChooser).toContain('select');
-  });
-
-  test('timezoneChooser has no noscript when defaultTimeZone is not set', () => {
-    const g = makeGlobals('index');
-    expect(g.timezoneChooser).toContain('select');
-    expect(g.timezoneChooser).not.toContain('noscript');
+    const html = g.renderTimeZoneChooser();
+    expect(html).toContain('<select class="time-zone" hidden disabled>');
+    expect(html).toContain('<noscript>Times shown in ET.</noscript>');
   });
 });
 

package/build/globals.ts

@@ -1,5 +1,5 @@
 import timezones from '../src/timezone/timezones.json' with { type: 'json' };
-import type { SiteVariables } from './types.js';
+import type { SiteVariables } from './types';
 
 interface Globals {
   isHomePage: boolean;
@@ -7,7 +7,7 @@ interface Globals {
   readableDate: (date: string | Date | null | undefined) => string;
   classNames: (obj: Record<string, unknown>) => string;
   cx: (obj: Record<string, unknown>) => string;
-  timezoneChooser: string;
+  renderTimeZoneChooser: () => string;
 }
 
 export default function createGlobals(
@@ -17,10 +17,17 @@ export default function createGlobals(
 ): Globals {
   const defaultTz = timezones.find(
     t => t.value === siteVariables.defaultTimeZone,
-  );
-  const timezoneChooser = defaultTz
-    ? `<select class="time-zone" hidden></select><noscript>Times shown in ${defaultTz.abbreviation}.</noscript>`
-    : '<select class="time-zone" hidden></select>';
+  )!;
+  const options = timezones
+    .map(tz => {
+      const label =
+        tz.value === 'UTC' ? tz.label : `${tz.label} (${tz.abbreviation})`;
+      const selected = tz.value === defaultTz.value ? ' selected' : '';
+      return `<option value="${tz.value}"${selected}>${label}</option>`;
+    })
+    .join('');
+  const renderTimeZoneChooser = () =>
+    `<span class="time-zone-label" hidden>Times shown in </span><select class="time-zone" hidden disabled>${options}</select><noscript>Times shown in ${defaultTz.abbreviation}.</noscript>`;
 
   return {
     isHomePage: subPath === 'index',
@@ -28,7 +35,7 @@ export default function createGlobals(
     readableDate,
     classNames,
     cx: classNames,
-    timezoneChooser,
+    renderTimeZoneChooser,
   };
 }
 

package/build/json-schema.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import { compile, doValidation } from './json-schema.js';
+import { compile, doValidation } from './json-schema';
 
 const schema = {
   type: 'object',

package/build/log.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import { makeLogger, getFlair } from './log.js';
+import { makeLogger, getFlair } from './log';
 
 function captureOutput(fn: () => void): { stdout: string; stderr: string } {
   let stdout = '';

package/build/log.ts

@@ -1,7 +1,7 @@
 import { inspect } from 'node:util';
 import path from 'path';
-import { Gi, L, Ri, P, Yi, Li } from './colors.js';
-import type { Logger } from './types.js';
+import { Gi, L, Ri, P, Yi, Li } from './colors';
+import type { Logger } from './types';
 import FLAIR_STRINGS from './flair.json' with { type: 'json' };
 
 const LEVELS = ['debug', 'info', 'warn', 'error'] as const;

package/build/markdown-plugins.test.ts

@@ -1,16 +1,16 @@
 import { describe, expect, test } from 'bun:test';
 import MarkdownIt from 'markdown-it';
 import deflist from 'markdown-it-deflist';
-import applyBasePathPlugin from './apply-base-path-plugin.js';
-import deflistIdPlugin from './deflist-id-plugin.js';
-import externalLinksPlugin from './external-links-plugin.js';
-import headingSubtitlePlugin from './heading-subtitle-plugin.js';
-import { createMarkdown } from './utils/markdown.js';
-import { stripHtmlComments } from './utils/render.js';
-import type { SiteVariables } from './types.js';
+import applyBasePathPlugin from './apply-base-path-plugin';
+import deflistIdPlugin from './deflist-id-plugin';
+import externalLinksPlugin from './external-links-plugin';
+import headingSubtitlePlugin from './heading-subtitle-plugin';
+import { createMarkdown } from './utils/markdown';
+import { stripHtmlComments, injectKatexStylesheet } from './utils/render';
+import type { SiteVariables } from './types';
 
 describe('apply-base-path-plugin', () => {
-  test('rewrites internal links, images, and raw html image sources', () => {
+  test('rewrites internal links, images, and raw html sources', () => {
     const md = new MarkdownIt({ html: true });
     md.use(applyBasePathPlugin, {
       basePath: '/course/',
@@ -25,12 +25,35 @@ describe('apply-base-path-plugin', () => {
         '![Image](/images/pic.png)',
         '',
         '<img src="/images/raw.png" alt="Raw">',
+        '',
+        '<a href="/about/">About</a>',
       ].join('\n'),
     );
 
     expect(html).toContain('href="/course/src/example.html?view=1#top"');
     expect(html).toContain('src="/course/images/pic.png"');
     expect(html).toContain('src="/course/images/raw.png"');
+    expect(html).toContain('href="/course/about/"');
+  });
+
+  test('does not rewrite external or relative raw html links', () => {
+    const md = new MarkdownIt({ html: true });
+    md.use(applyBasePathPlugin, {
+      basePath: '/course/',
+      codeLanguages: {},
+      features: { code: true },
+    });
+
+    const html = md.render(
+      [
+        '<a href="https://example.com/">External</a>',
+        '',
+        '<a href="relative.html">Relative</a>',
+      ].join('\n'),
+    );
+
+    expect(html).toContain('href="https://example.com/"');
+    expect(html).toContain('href="relative.html"');
   });
 
   test('rewrites relative code file links without applying base path', () => {
@@ -122,7 +145,11 @@ describe('custom markdown containers', () => {
         basePath: '/',
         internalDomains: [],
         codeLanguages: {},
-        features: {},
+        features: { search: true, code: true, favicon: false },
+        title: 'Test',
+        titlePostfix: ' - Test',
+        themeColor: 'steelblue',
+        defaultTimeZone: 'America/New_York',
       } as SiteVariables,
       { validatorOptions: { enabled: false } },
     );
@@ -218,7 +245,11 @@ describe('hidden_fence rule', () => {
         basePath: '/',
         internalDomains: [],
         codeLanguages: {},
-        features: {},
+        features: { search: true, code: true, favicon: false },
+        title: 'Test',
+        titlePostfix: ' - Test',
+        themeColor: 'steelblue',
+        defaultTimeZone: 'America/New_York',
       } as SiteVariables,
       { validatorOptions: { enabled: false } },
     );
@@ -286,3 +317,78 @@ describe('stripHtmlComments', () => {
     expect(stripHtmlComments(input)).toBe(input);
   });
 });
+
+describe('katex plugin', () => {
+  function createProjectMarkdown() {
+    return createMarkdown(
+      {
+        base: '',
+        basePath: '/',
+        internalDomains: [],
+        codeLanguages: {},
+        features: { search: true, code: true, favicon: false },
+        title: 'Test',
+        titlePostfix: ' - Test',
+        themeColor: 'steelblue',
+        defaultTimeZone: 'America/New_York',
+      } as SiteVariables,
+      { validatorOptions: { enabled: false } },
+    );
+  }
+
+  test('renders inline math with $ delimiters', () => {
+    const md = createProjectMarkdown();
+    const html = md.render('The equation $E = mc^2$ is famous.');
+    expect(html).toContain('class="katex"');
+    expect(html).toContain('mc');
+  });
+
+  test('renders display math with $$ delimiters', () => {
+    const md = createProjectMarkdown();
+    const html = md.render('$$\\sum_{i=1}^{n} i = \\frac{n(n+1)}{2}$$');
+    expect(html).toContain('class="katex-display"');
+  });
+
+  test('includes aria-label for inline math', () => {
+    const md = createProjectMarkdown();
+    const html = md.render('$E = mc^2$');
+    expect(html).toContain('aria-label="E, equals, m, c, squared"');
+  });
+
+  test('includes aria-label for display math', () => {
+    const md = createProjectMarkdown();
+    const html = md.render('$$\\frac{1}{2}$$');
+    expect(html).toContain(
+      'aria-label="start fraction, 1, divided by, 2, end fraction"',
+    );
+  });
+
+  test('throws on invalid LaTeX syntax', () => {
+    const md = createProjectMarkdown();
+    expect(() => md.render('$\\invalidcommand{$')).toThrow();
+  });
+
+  test('does not produce katex output when no math delimiters are used', () => {
+    const md = createProjectMarkdown();
+    const html = md.render('Just a normal paragraph with a $5 price tag.');
+    expect(html).not.toContain('class="katex"');
+  });
+});
+
+describe('injectKatexStylesheet', () => {
+  test('injects deferred KaTeX stylesheet link into <head>', () => {
+    const html =
+      '<html><head><meta charset="UTF-8"></head><body></body></html>';
+    const result = injectKatexStylesheet(html, p => p);
+
+    expect(result).toContain('href="/katex/katex.min.css"');
+    expect(result).toContain('rel="stylesheet"');
+  });
+
+  test('applies basePath to the stylesheet URL', () => {
+    const html = '<html><head></head><body></body></html>';
+    const result = injectKatexStylesheet(html, p => '/course' + p);
+
+    expect(result).toContain('href="/course/katex/katex.min.css"');
+  });
+});

package/build/pagefind.test.ts

@@ -1,7 +1,7 @@
 import path from 'path';
 import { describe, expect, test } from 'bun:test';
-import { buildIndex, collectIndexTargets } from './pagefind.js';
-import type { SiteVariables } from './types.js';
+import { buildIndex, collectIndexTargets } from './pagefind';
+import type { SiteVariables } from './types';
 
 interface FakePagefindCalls {
   htmlFiles?: { sourcePath: string; content: string }[];

package/build/pagefind.ts

@@ -1,13 +1,13 @@
 import path from 'path';
-import { makeLogger } from './log.js';
-import { collectReachableSiteAssets } from './reachability.js';
+import { makeLogger } from './log';
+import { collectReachableSiteAssets } from './reachability';
 import {
   getContentDir,
   getFilesByExtensions,
   normalizeOutputPath,
-} from './util.js';
-import { assertMutoolAvailable, extractPdfPages } from './pdf-text.js';
-import type { SiteVariables } from './types.js';
+} from './util';
+import { assertMutoolAvailable, extractPdfPages } from './pdf-text';
+import type { SiteVariables } from './types';
 
 const log = makeLogger(__filename);
 const PAGEFIND_VERBOSE = process.env.TADA_LOG_LEVEL === 'debug';

package/build/pdf-text.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, test } from 'bun:test';
+import { buildPdfPageRecords } from './pdf-text';
+
+describe('buildPdfPageRecords', () => {
+  test('creates page records with 1-based page numbers', () => {
+    const result = buildPdfPageRecords(['Hello world', 'Second page']);
+    expect(result).toEqual({
+      pages: [
+        { pageNumber: 1, content: 'Hello world' },
+        { pageNumber: 2, content: 'Second page' },
+      ],
+      hasExtractedText: true,
+    });
+  });
+
+  test('normalizes whitespace in extracted text', () => {
+    const result = buildPdfPageRecords(['  lots   of\n\tspaces  ']);
+    expect(result).toEqual({
+      pages: [{ pageNumber: 1, content: 'lots of spaces' }],
+      hasExtractedText: true,
+    });
+  });
+
+  test('skips blank pages', () => {
+    const result = buildPdfPageRecords(['Page one', '', '   ', 'Page four']);
+    expect(result).toEqual({
+      pages: [
+        { pageNumber: 1, content: 'Page one' },
+        { pageNumber: 4, content: 'Page four' },
+      ],
+      hasExtractedText: true,
+    });
+  });
+
+  test('returns hasExtractedText false when all pages are blank', () => {
+    const result = buildPdfPageRecords(['', '   ', '\n\t']);
+    expect(result).toEqual({ pages: [], hasExtractedText: false });
+  });
+
+  test('returns hasExtractedText false for empty input', () => {
+    const result = buildPdfPageRecords([]);
+    expect(result).toEqual({ pages: [], hasExtractedText: false });
+  });
+
+  test('handles a single page', () => {
+    const result = buildPdfPageRecords(['Only page']);
+    expect(result).toEqual({
+      pages: [{ pageNumber: 1, content: 'Only page' }],
+      hasExtractedText: true,
+    });
+  });
+});

package/build/pipeline.ts

@@ -1,25 +1,43 @@
 #!/usr/bin/env bun
 import fs from 'fs';
-import { getDevSiteVariables, getProdSiteVariables } from './site-variables.js';
-import { compileTemplates } from './templates.js';
-import { getDistDir, getContentDir, getPublicDir } from './utils/paths.js';
-import { isFeatureEnabled } from './features.js';
-import { bundle } from './bundle.js';
-import { copyFonts } from './generate-fonts.js';
-import { generateFavicons } from './generate-favicon.js';
-import { generateManifest } from './generate-manifest.js';
-import { copyPublicFiles, copyContentAssets } from './copy.js';
-import { getProcessedExtensions } from './utils/file-types.js';
-import { ContentRenderer } from './generate-content-assets.js';
-import { runPagefind } from './pagefind.js';
-import { makeLogger, printFlair } from './log.js';
+import { getDevSiteVariables, getProdSiteVariables } from './site-variables';
+import { compileTemplates } from './templates';
+import {
+  getDistDir,
+  getProdDistDir,
+  getContentDir,
+  getPublicDir,
+} 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 } from './copy';
+import { getProcessedExtensions } from './utils/file-types';
+import { ContentRenderer } from './generate-content-assets';
+import { runPagefind } from './pagefind';
+import { makeLogger, printFlair } from './log';
+import { generateBuildManifest, getNextVersion } from './build-manifest';
+import path from 'path';
 
 const log = makeLogger(__filename);
 
 async function runPipeline(mode: 'development' | 'production'): Promise<void> {
   const isDev = mode === 'development';
   const siteVariables = isDev ? getDevSiteVariables() : getProdSiteVariables();
-  const distDir = getDistDir();
+  let distDir: string;
+  let prodVersion: number;
+
+  if (isDev) {
+    distDir = getDistDir();
+  } else {
+    const prodBase = getProdDistDir();
+    prodVersion = getNextVersion(prodBase);
+    distDir = path.join(prodBase, `v${prodVersion}`);
+  }
+
   const contentDir = getContentDir();
   const publicDir = getPublicDir();
 
@@ -33,8 +51,9 @@ async function runPipeline(mode: 'development' | 'production'): Promise<void> {
 
   // Phase 2: Bundle + assets (parallel)
   const parallelTasks: (Promise<unknown> | void)[] = [
-    bundle(siteVariables, { mode }),
+    bundle(siteVariables, { mode, distDir }),
     copyFonts(distDir),
+    copyKatexAssets(distDir),
   ];
 
   if (isFeatureEnabled(siteVariables, 'favicon')) {
@@ -72,6 +91,14 @@ async function runPipeline(mode: 'development' | 'production'): Promise<void> {
     await runPagefind({ siteVariables, distPath: distDir, htmlAssetsByPath });
   }
 
+  // Phase 5: Build manifest (production only)
+  if (!isDev) {
+    const prodBase = getProdDistDir();
+    const manifestPath = path.join(prodBase, `v${prodVersion!}.manifest.json`);
+    await generateBuildManifest(distDir, manifestPath);
+    log.info`Built dist-prod/v${prodVersion!}/`;
+  }
+
   printFlair();
 }
 

package/build/reachability.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, test } from 'bun:test';
 import {
   collectDirectSiteAssetLinks,
   collectReachableSiteAssets,
-} from './reachability.js';
+} from './reachability';
 
 describe('reachability', () => {
   test('collectDirectSiteAssetLinks resolves relative links and ignores excluded links', () => {