@abreen/tada 1.4.1 → 1.5.1

package/README.md

@@ -5,6 +5,7 @@ A static site generator. The successor to Presto.
 ## Features
 
 - Modern design (light & dark following system, floating header, styled lists)
+- Fast client-side navigation
 - Clickable/linkable landmarks (headings, deflists, alert boxes)
 - Dynamic table of contents
   * Floats on the side of the screen when window is large enough
@@ -29,6 +30,7 @@ A static site generator. The successor to Presto.
   * `::: section ... :::` renders a special section with a fancy background
   * `!!! note ... !!!` and `!!! warning ... !!!` render alert boxes
   * `??? question ... ???` renders a Q & A section; answers hidden until click
+  * `+++ ... +++ ... +++` renders a two-column layout
   * Special heading subtitles with `## Heading # A subtitle here`
 - Automatically generated favicon
   * Text, color, font and font weight taken from config file
@@ -233,7 +235,7 @@ Example site configuration JSON file:
 | `codeLanguages` | Map file extension to Shiki language (e.g., `"java": "java"`) |
 | `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 %>`) |
+| `vars` | Arbitrary key/value variables exposed to templates/content as `vars.*` (e.g., `<%= vars.staffEmail %>`) |
 
 
 #### `nav.json`
@@ -326,7 +328,7 @@ templates][lodash].
 - 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 %>`)
+  under `vars` (e.g., `<%= vars.staffEmail %>`)
 
 
 

package/bin/tada.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import fs from 'fs';
 import path from 'path';
-import { execFileSync } from 'child_process';
+
 import { parseArgs } from 'util';
 import packageJson from '../package.json' with { type: 'json' };
 import {
@@ -24,7 +24,7 @@ const { version } = packageJson;
 
 const SYSTEM_TIME_ZONE = Intl.DateTimeFormat().resolvedOptions().timeZone;
 
-const packageDir = path.resolve(__dirname, '..');
+const packageDir = path.resolve(import.meta.dir, '..');
 
 function requireSiteConfig(env: string): void {
   const configPath = path.resolve(process.cwd(), `site.${env}.json`);
@@ -34,6 +34,17 @@ function requireSiteConfig(env: string): void {
   }
 }
 
+function parsePortArg(name: string): number | undefined {
+  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 undefined;
+}
+
 const COMMANDS = {
   init: null,
   dev: 'Build the site for development',
@@ -151,21 +162,6 @@ function printUsage() {
   }
 }
 
-function run(args: string[]): void {
-  try {
-    execFileSync('bun', args, { 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 {
   fs.mkdirSync(dest, { recursive: true });
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
@@ -605,49 +601,77 @@ function diffCommand(args: string[]): void {
 
 const command = process.argv[2];
 
-switch (command) {
-  case 'init':
-    initCommand(process.argv.slice(3));
-    break;
-
-  case 'dev':
-    requireSiteConfig('dev');
-    run([path.join(packageDir, 'build/pipeline.ts'), 'dev']);
-    break;
-
-  case 'prod':
-    requireSiteConfig('prod');
-    run([path.join(packageDir, 'build/pipeline.ts'), 'prod']);
-    break;
-
-  case 'watch': {
-    requireSiteConfig('dev');
-    run([path.join(packageDir, 'build/watch.ts'), ...process.argv.slice(3)]);
-    break;
-  }
-
-  case 'serve': {
-    run([path.join(packageDir, 'build/serve.ts'), ...process.argv.slice(3)]);
-    break;
-  }
+try {
+  switch (command) {
+    case 'init':
+      await initCommand(process.argv.slice(3));
+      break;
 
-  case 'clean':
-    cleanCommand(process.argv.slice(3));
-    break;
+    case 'dev': {
+      requireSiteConfig('dev');
+      const { runPipeline } = await import(
+        path.join(packageDir, 'build/pipeline.ts')
+      );
+      await runPipeline('development');
+      break;
+    }
 
-  case 'diff':
-    diffCommand(process.argv.slice(3));
-    break;
+    case 'prod': {
+      requireSiteConfig('prod');
+      const { runPipeline } = await import(
+        path.join(packageDir, 'build/pipeline.ts')
+      );
+      await runPipeline('production');
+      break;
+    }
 
-  case '--version':
-  case '-v':
-    console.log(`tada v${version}`);
-    break;
+    case 'watch': {
+      requireSiteConfig('dev');
+      const { runWatch } = await import(
+        path.join(packageDir, 'build/watch.ts')
+      );
+      await runWatch({
+        httpPort: parsePortArg('--port'),
+        wsPort: parsePortArg('--ws-port'),
+      });
+      break;
+    }
 
-  default:
-    printUsage();
-    if (command && command !== '--help' && command !== '-h') {
-      process.exit(1);
+    case 'serve': {
+      const { startServer } = await import(
+        path.join(packageDir, 'build/serve.ts')
+      );
+      const { getDistDir } = await import(
+        path.join(packageDir, 'build/util.ts')
+      );
+      startServer({
+        port: parsePortArg('--port') ?? 8080,
+        distDir: getDistDir(),
+      });
+      break;
     }
-    break;
+
+    case 'clean':
+      cleanCommand(process.argv.slice(3));
+      break;
+
+    case 'diff':
+      diffCommand(process.argv.slice(3));
+      break;
+
+    case '--version':
+    case '-v':
+      console.log(`tada v${version}`);
+      break;
+
+    default:
+      printUsage();
+      if (command && command !== '--help' && command !== '-h') {
+        process.exit(1);
+      }
+      break;
+  }
+} catch (err) {
+  console.error(`tada ${command} failed: ${(err as Error).message}`);
+  process.exit(1);
 }

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

@@ -1,3 +1,4 @@
+import path from 'path';
 import type MarkdownIt from 'markdown-it';
 import type Token from 'markdown-it/lib/token.mjs';
 import { createApplyBasePath } from './utils/paths';
@@ -5,14 +6,22 @@ import { isFeatureEnabled } from './features';
 import { makeLogger } from './log';
 import type { SiteVariables } from './types';
 
-const log = makeLogger(__filename);
+const log = makeLogger(import.meta.url);
+
+interface ApplyBasePathOptions {
+  literateJavaOutputPaths?: Set<string>;
+  sourceUrlPath?: string;
+}
 
 export default function applyBasePathPlugin(
   md: MarkdownIt,
   siteVariables: SiteVariables,
+  pluginOptions: ApplyBasePathOptions = {},
 ): void {
   const applyBasePath = createApplyBasePath(siteVariables);
   const rewriteCodeLinks = isFeatureEnabled(siteVariables, 'code');
+  const literateJavaOutputPaths = pluginOptions.literateJavaOutputPaths;
+  const sourceUrlPath = pluginOptions.sourceUrlPath;
 
   function rewriteInternalHref(href: string): string {
     const match = href.match(/^([^?#]*)(.*)$/);
@@ -21,13 +30,20 @@ export default function applyBasePathPlugin(
     let modifiedPath = pathname;
 
     if (rewriteCodeLinks) {
-      // Rewrite code file links to .html links
       for (const ext of Object.keys(siteVariables.codeLanguages ?? {})) {
         if (modifiedPath.endsWith(`.${ext}`)) {
-          modifiedPath = modifiedPath.replace(
-            new RegExp(`\\.${ext}$`),
-            '.html',
-          );
+          if (literateJavaOutputPaths && sourceUrlPath) {
+            const resolved = modifiedPath.startsWith('/')
+              ? modifiedPath
+              : path.posix.join(
+                  path.posix.dirname(sourceUrlPath),
+                  modifiedPath,
+                );
+            if (literateJavaOutputPaths.has(resolved)) {
+              break;
+            }
+          }
+          modifiedPath += '.html';
           break;
         }
       }

package/build/code.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, test, beforeAll } from 'bun:test';
 import { initHighlighter } from './utils/shiki-highlighter';
-import { renderCodeWithComments, extractJavaMethodToc } from './utils/code';
+import {
+  renderCodeWithComments,
+  extractJavaMethodToc,
+  rewriteProseLinks,
+} from './utils/code';
 import type { SiteVariables } from './types';
 
 beforeAll(async () => {
@@ -162,4 +166,107 @@ describe('renderCodeWithComments', () => {
     expect(html).not.toContain('id="L4" href="#L4"');
     expect(html).toContain('<code class="shiki language-java">');
   });
+
+  test('data-prose-source contains rewritten links when pageDirPath is provided', () => {
+    const source = '/// See [rect](./rect.py)\npublic class Foo {}\n';
+    const html = renderCodeWithComments(
+      source,
+      'java',
+      {
+        base: 'https://example.edu',
+        basePath: '/course',
+        codeLanguages: { java: 'java', py: 'python' },
+        internalDomains: [],
+        title: 'Test',
+        titlePostfix: ' - Test',
+        themeColor: 'steelblue',
+        defaultTimeZone: 'America/New_York',
+      } as SiteVariables,
+      'lectures/01',
+    );
+
+    expect(html).toContain(
+      'https://example.edu/course/lectures/01/rect.py.html',
+    );
+  });
+});
+
+describe('rewriteProseLinks', () => {
+  const siteVariables = {
+    base: 'https://example.edu',
+    basePath: '/course',
+    codeLanguages: { java: 'java', py: 'python' },
+    internalDomains: [],
+    title: 'Test',
+    titlePostfix: ' - Test',
+    themeColor: 'steelblue',
+    defaultTimeZone: 'America/New_York',
+  } as SiteVariables;
+
+  test('rewrites relative link with base + basePath', () => {
+    const lines = ['/// See [rectangle.py](./rectangle.py)'];
+    const result = rewriteProseLinks(lines, siteVariables, 'lectures/01');
+    expect(result[0]).toBe(
+      '/// See [rectangle.py](https://example.edu/course/lectures/01/rectangle.py.html)',
+    );
+  });
+
+  test('rewrites absolute link with base + basePath', () => {
+    const lines = ['/// See [about](/about.html)'];
+    const result = rewriteProseLinks(lines, siteVariables, 'lectures/01');
+    expect(result[0]).toBe(
+      '/// See [about](https://example.edu/course/about.html)',
+    );
+  });
+
+  test('leaves external links unchanged', () => {
+    const lines = ['/// See [Google](https://google.com)'];
+    const result = rewriteProseLinks(lines, siteVariables, 'lectures/01');
+    expect(result[0]).toBe('/// See [Google](https://google.com)');
+  });
+
+  test('leaves anchor links unchanged', () => {
+    const lines = ['/// See [section](#overview)'];
+    const result = rewriteProseLinks(lines, siteVariables, 'lectures/01');
+    expect(result[0]).toBe('/// See [section](#overview)');
+  });
+
+  test('applies code extension rewriting', () => {
+    const lines = ['/// See [App](./App.java)'];
+    const result = rewriteProseLinks(lines, siteVariables, 'lectures/01');
+    expect(result[0]).toBe(
+      '/// See [App](https://example.edu/course/lectures/01/App.java.html)',
+    );
+  });
+
+  test('handles multiple links on one line', () => {
+    const lines = ['/// See [a](./a.py) and [b](./b.java)'];
+    const result = rewriteProseLinks(lines, siteVariables, 'lectures/01');
+    expect(result[0]).toBe(
+      '/// See [a](https://example.edu/course/lectures/01/a.py.html) and [b](https://example.edu/course/lectures/01/b.java.html)',
+    );
+  });
+
+  test('does not rewrite non-comment lines', () => {
+    const lines = ['String s = "[link](./file.py)";'];
+    const result = rewriteProseLinks(lines, siteVariables, 'lectures/01');
+    expect(result[0]).toBe('String s = "[link](./file.py)";');
+  });
+
+  test('preserves query string and fragment', () => {
+    const lines = ['/// See [code](./App.java?view=1#L5)'];
+    const result = rewriteProseLinks(lines, siteVariables, 'lectures/01');
+    expect(result[0]).toBe(
+      '/// See [code](https://example.edu/course/lectures/01/App.java.html?view=1#L5)',
+    );
+  });
+
+  test('works with root basePath', () => {
+    const vars = { ...siteVariables, basePath: '/' } as SiteVariables;
+    const lines = ['/// See [rect](./rect.py)'];
+    const result = rewriteProseLinks(lines, vars, 'lectures/01');
+    expect(result[0]).toBe(
+      '/// See [rect](https://example.edu/lectures/01/rect.py.html)',
+    );
+  });
 });

package/build/colors.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from 'bun:test';
+import { R, G, B, Y, L, P, I, Ri, Gi, Yi, Li } from './colors';
+
+describe('color tag functions', () => {
+  test('R wraps text in red', () => {
+    const result = R`hello`;
+    expect(result).toContain('hello');
+    expect(typeof result).toBe('string');
+  });
+
+  test('G wraps text in green', () => {
+    const result = G`hello`;
+    expect(result).toContain('hello');
+  });
+
+  test('B wraps text in blue', () => {
+    const result = B`hello`;
+    expect(result).toContain('hello');
+  });
+
+  test('Y wraps text in yellow', () => {
+    const result = Y`hello`;
+    expect(result).toContain('hello');
+  });
+
+  test('L wraps text in dim', () => {
+    const result = L`hello`;
+    expect(result).toContain('hello');
+  });
+
+  test('P wraps text in magenta', () => {
+    const result = P`hello`;
+    expect(result).toContain('hello');
+  });
+
+  test('I wraps text in italic bold', () => {
+    const result = I`hello`;
+    expect(result).toContain('hello');
+  });
+
+  test('Ri wraps text in inverse red', () => {
+    const result = Ri`hello`;
+    expect(result).toContain('hello');
+  });
+
+  test('Gi wraps text in inverse green', () => {
+    const result = Gi`hello`;
+    expect(result).toContain('hello');
+  });
+
+  test('Yi wraps text in inverse yellow', () => {
+    const result = Yi`hello`;
+    expect(result).toContain('hello');
+  });
+
+  test('Li wraps text in inverse dim', () => {
+    const result = Li`hello`;
+    expect(result).toContain('hello');
+  });
+
+  test('handles template interpolation', () => {
+    const name = 'world';
+    const result = R`hello ${name}`;
+    expect(result).toContain('hello world');
+  });
+});

package/build/columns-plugin.ts

@@ -0,0 +1,116 @@
+import type MarkdownIt from 'markdown-it';
+import type StateBlock from 'markdown-it/lib/rules_block/state_block.mjs';
+
+const MARKER_CHAR = 0x2b; // '+'
+const MIN_MARKERS = 3;
+
+function isColumnsFence(state: StateBlock, line: number): boolean {
+  const start = state.bMarks[line] + state.tShift[line];
+  const max = state.eMarks[line];
+
+  if (state.sCount[line] - state.blkIndent >= 4) {
+    return false;
+  }
+  if (state.src.charCodeAt(start) !== MARKER_CHAR) {
+    return false;
+  }
+
+  let pos = start + 1;
+  while (pos < max && state.src.charCodeAt(pos) === MARKER_CHAR) {
+    pos++;
+  }
+
+  if (pos - start < MIN_MARKERS) {
+    return false;
+  }
+
+  // Rest of line must be whitespace only
+  if (state.skipSpaces(pos) < max) {
+    return false;
+  }
+
+  return true;
+}
+
+function columnsRule(
+  state: StateBlock,
+  startLine: number,
+  endLine: number,
+  silent: boolean,
+): boolean {
+  if (!isColumnsFence(state, startLine)) {
+    return false;
+  }
+
+  // Find the separator (second +++) and closing (third +++) fences
+  let separatorLine = -1;
+  let closeLine = -1;
+
+  for (let line = startLine + 1; line < endLine; line++) {
+    if (!isColumnsFence(state, line)) {
+      continue;
+    }
+    if (separatorLine === -1) {
+      separatorLine = line;
+    } else {
+      closeLine = line;
+      break;
+    }
+  }
+
+  if (separatorLine === -1 || closeLine === -1) {
+    return false;
+  }
+  if (silent) {
+    return true;
+  }
+
+  const oldParent = state.parentType;
+  const oldLineMax = state.lineMax;
+
+  // Outer wrapper: <div class="columns">
+  const tokOpen = state.push('columns_open', 'div', 1);
+  tokOpen.block = true;
+  tokOpen.map = [startLine, closeLine + 1];
+  tokOpen.markup = '+++';
+  tokOpen.attrJoin('class', 'columns');
+
+  // Column 1
+  const col1Open = state.push('column_open', 'div', 1);
+  col1Open.block = true;
+  col1Open.map = [startLine + 1, separatorLine];
+
+  state.lineMax = separatorLine;
+  state.md.block.tokenize(state, startLine + 1, separatorLine);
+
+  const col1Close = state.push('column_close', 'div', -1);
+  col1Close.block = true;
+
+  // Column 2
+  const col2Open = state.push('column_open', 'div', 1);
+  col2Open.block = true;
+  col2Open.map = [separatorLine + 1, closeLine];
+
+  state.lineMax = closeLine;
+  state.md.block.tokenize(state, separatorLine + 1, closeLine);
+
+  const col2Close = state.push('column_close', 'div', -1);
+  col2Close.block = true;
+
+  // Close wrapper
+  const tokClose = state.push('columns_close', 'div', -1);
+  tokClose.block = true;
+  tokClose.markup = '+++';
+
+  state.parentType = oldParent;
+  state.lineMax = oldLineMax;
+  state.line = closeLine + 1;
+
+  return true;
+}
+
+export default function columnsPlugin(md: MarkdownIt): void {
+  md.block.ruler.before('fence', 'columns', columnsRule, {
+    alt: ['paragraph', 'reference', 'blockquote', 'list'],
+  });
+}

package/build/content-watch.ts

@@ -1,23 +1,19 @@
 import path from 'path';
 import type { SiteVariables } from './types';
-import { getContentDir, getBuildContentFiles } from './util';
-import {
-  compileTemplates,
-  getHtmlTemplatesDir,
-  getJsonDataDir,
-  JSON_DATA_FILES,
-} from './templates';
+import { getContentDir, getBuildContentFiles, isPartial } from './util';
+import { compileTemplates, getJsonDataDir, JSON_DATA_FILES } from './templates';
 import { getProjectDir } from './utils/paths';
 import { B } from './colors';
 import { makeLogger } from './log';
 
-const log = makeLogger(__filename);
+const log = makeLogger(import.meta.url);
 
 interface ChangeDetectionResult {
   templateError: Error | null;
   needsRestart: boolean;
   changedContentFiles?: Set<string>;
-  templatesChanged?: boolean;
+  jsonDataChanged?: boolean;
+  partialsChanged?: boolean;
 }
 
 export class ContentChangeDetector {
@@ -36,10 +32,9 @@ export class ContentChangeDetector {
       [...(modifiedFiles || [])].map(filePath => path.resolve(filePath)),
     );
 
-    const htmlTemplatesDir = getHtmlTemplatesDir();
     const jsonDataDir = getJsonDataDir();
 
-    // Try to recompile templates
+    // Try to recompile templates (also re-reads JSON data files)
     let templateError: Error | null = null;
     try {
       compileTemplates(this.siteVariables);
@@ -53,7 +48,6 @@ export class ContentChangeDetector {
 
     const contentDir = getContentDir();
     const normalizedContentDir = path.resolve(contentDir) + path.sep;
-    const normalizedHtmlDir = path.resolve(htmlTemplatesDir) + path.sep;
     const buildContentFiles = getBuildContentFiles(
       contentDir,
       Object.keys(this.siteVariables.codeLanguages || {}),
@@ -73,22 +67,36 @@ export class ContentChangeDetector {
       ),
     );
 
-    // Check if any HTML template or JSON data file changed
+    // Check if any JSON data file changed (nav.json, authors.json)
     const jsonDataPaths = JSON_DATA_FILES.map(f =>
       path.resolve(jsonDataDir, f),
     );
-    const changedTemplatePaths = [...resolvedFiles].filter(
-      filePath =>
-        filePath === path.resolve(htmlTemplatesDir) ||
-        filePath.startsWith(normalizedHtmlDir) ||
-        jsonDataPaths.includes(filePath),
+    const changedJsonDataPaths = [...resolvedFiles].filter(filePath =>
+      jsonDataPaths.includes(filePath),
     );
-    const templatesChanged = changedTemplatePaths.length > 0;
+    const jsonDataChanged = changedJsonDataPaths.length > 0;
+    const partialsChanged = [...changedContentFiles].some(f => isPartial(f));
 
-    for (const filePath of changedTemplatePaths) {
+    for (const filePath of changedJsonDataPaths) {
       log.event`${B`${path.basename(filePath)}`} changed, rebuilding`;
     }
 
+    if (partialsChanged) {
+      const changedPartials = [...changedContentFiles].filter(f =>
+        isPartial(f),
+      );
+      for (const filePath of changedPartials) {
+        log.event`Partial ${B`${path.basename(filePath)}`} changed, rebuilding`;
+      }
+    }
+
+    const changedJavaFiles = [...changedContentFiles].filter(f =>
+      f.endsWith('.java'),
+    );
+    for (const filePath of changedJavaFiles) {
+      log.event`${B`${path.basename(filePath)}`} changed, re-running traces`;
+    }
+
     // Check if site config changed
     const siteConfigChanged = resolvedFiles.has(
       path.resolve(this.siteConfigPath),
@@ -101,7 +109,8 @@ export class ContentChangeDetector {
       templateError: null,
       needsRestart,
       changedContentFiles,
-      templatesChanged,
+      jsonDataChanged,
+      partialsChanged,
     };
   }
 }

package/build/copy.ts

@@ -3,7 +3,7 @@ import path from 'path';
 import { makeLogger } from './log';
 import { B } from './colors';
 
-const log = makeLogger(__filename);
+const log = makeLogger(import.meta.url);
 
 interface CollectedFile {
   abs: string;

package/build/external-links-plugin.ts

@@ -3,7 +3,7 @@ import type Token from 'markdown-it/lib/token.mjs';
 import { makeLogger } from './log';
 import type { SiteVariables } from './types';
 
-const log = makeLogger(__filename);
+const log = makeLogger(import.meta.url);
 
 export default function externalLinks(
   md: MarkdownIt,