@abreen/tada 1.11.3 → 1.13.4

package/README.md

@@ -25,6 +25,7 @@ A static site generator. The successor to Presto.
 - Interactive execution traces via `renderTrace()`
   * Supports Java and Python source files
   * Renders step-by-step source highlighting, output, and memory diagrams
+- Slides mode: separate content by `---` and present sections as full-screen slides
 - PDF files are copied into `dist/`
   - Text of each PDF page is extracted using `mutool` (if present) and indexed
 - External link handling (special visual treatment for external links)
@@ -118,7 +119,7 @@ Available flags: `--title`, `--symbol`, `--theme-color`, `--tint-hue`,
 
 ### `tada dev`
 
-Build the site for local development (using `site.dev.json`)
+Build the site for local development (using `site.dev.yaml` by default)
 into the `dist/` directory.
 
 ### `tada serve`
@@ -137,7 +138,7 @@ builds (keeps the latest two versions).
 
 ### `tada prod`
 
-Build the site for production (uses `site.prod.json`). Each prod build is
+Build the site for production (uses `site.prod.yaml` by default). 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.
@@ -160,7 +161,7 @@ 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
+`site.dev.*` (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.
 
@@ -196,31 +197,39 @@ manually.
 
 Build-time site config lives in:
 
-- `site.dev.json` (used by `tada dev` / `tada watch`)
-- `site.prod.json` (used by `tada prod`)
-- `nav.json` (navigation structure)
-- `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, "favicon": true },
-  "base": "https://example.edu",
-  "basePath": "/cs0",
-  "internalDomains": ["example.edu"],
-  "defaultTimeZone": "America/New_York",
-  "extensionToShikiLanguage": { "java": "java", "py": "python" },
-  "shikiLanguages": ["java", "python"],
-  "vars": {
-    "staffEmail": "staff@example.edu"
-  }
-}
+- `site.dev.yaml` (used by `tada dev` / `tada watch`)
+- `site.prod.yaml` (used by `tada prod`)
+- `nav.yaml` (navigation structure)
+- `authors.yaml` (author data)
+
+Tada also accepts `.yml` and `.json` for each of these files. Keep only one
+variant for each logical config name; for example, `nav.yaml` and `nav.json`
+in the same site root is an error.
+
+Example site configuration YAML file:
+
+```yaml
+title: Intro to Computer Science
+titlePostfix: " - CS 0"
+symbol: CS 0
+themeColor: hsl(351 70% 40%)
+tintAmount: 0
+features:
+  search: true
+  favicon: true
+base: https://example.edu
+basePath: /cs0
+internalDomains:
+  - example.edu
+defaultTimeZone: America/New_York
+extensionToShikiLanguage:
+  java: java
+  py: python
+shikiLanguages:
+  - java
+  - python
+vars:
+  staffEmail: staff@example.edu
 ```
 
 | Field | Description |
@@ -244,54 +253,45 @@ Example site configuration JSON file:
 | `faviconFontWeight` | *Optional*, font weight used for favicon text (default `700`) |
 | `vars` | Arbitrary key/value variables exposed to templates/content as `vars.*` (e.g., `<%= vars.staffEmail %>`) |
 
-#### `nav.json`
+#### `nav.yaml`
 
 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" }
-    ]
-  }
-]
+```yaml
+- 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`
+#### `authors.yaml`
 
 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"
-  }
-}
+```yaml
+jsmith:
+  name: Jane Smith
+  avatar: /avatars/jsmith.jpg
+ajones:
+  name: Alex Jones
+  avatar: /avatars/ajones.jpg
+  url: /staff/ajones.html
 ```
 
 ## Content
@@ -313,9 +313,10 @@ list of variables parsed using the [`front-matter`][front-matter] library).
 |-------|-------------|
 | `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 `authors.json` |
+| `author` | Author handle (e.g. `jsmith`) resolved to a full object via the authors config |
 | `description` | Meta description for the page |
 | `toc` | Set to `true` to show a table of contents |
+| `slides` | Set to `true` on Markdown pages to treat top-level `---` as slide separators and add presentation controls |
 | `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`) |
 

package/bin/tada.ts

@@ -19,6 +19,12 @@ import {
   getVersions,
   pruneOldVersions,
 } from '../build/build-manifest';
+import {
+  getDefaultProjectConfigFilePath,
+  getDefaultSiteConfigPath,
+  resolveSiteConfigFile,
+  type SiteEnv,
+} from '../build/config-files';
 
 const { version } = packageJson;
 
@@ -26,10 +32,11 @@ const SYSTEM_TIME_ZONE = Intl.DateTimeFormat().resolvedOptions().timeZone;
 
 const packageDir = path.resolve(import.meta.dir, '..');
 
-function requireSiteConfig(env: string): void {
-  const configPath = path.resolve(process.cwd(), `site.${env}.json`);
-  if (!fs.existsSync(configPath)) {
-    console.error(`Error: Missing config file: site.${env}.json`);
+function requireSiteConfig(env: SiteEnv): void {
+  try {
+    resolveSiteConfigFile(process.cwd(), env);
+  } catch (error) {
+    console.error(`Error: ${(error as Error).message}`);
     process.exit(1);
   }
 }
@@ -132,9 +139,6 @@ function printUsage() {
       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}`);
@@ -175,6 +179,10 @@ function copyDirRecursive(src: string, dest: string): void {
   }
 }
 
+function stringifyYaml(value: unknown): string {
+  return Bun.YAML.stringify(value, null, 2) + '\n';
+}
+
 const FLAG_TO_KEY: Record<string, string> = {
   title: 'title',
   symbol: 'symbol',
@@ -353,13 +361,13 @@ async function initCommand(args: string[]): Promise<void> {
   });
 
   fs.writeFileSync(
-    path.join(projectDir, 'site.dev.json'),
-    JSON.stringify(devConfig, null, 2) + '\n',
+    getDefaultSiteConfigPath(projectDir, 'dev'),
+    stringifyYaml(devConfig),
   );
 
   fs.writeFileSync(
-    path.join(projectDir, 'site.prod.json'),
-    JSON.stringify(prodConfig, null, 2) + '\n',
+    getDefaultSiteConfigPath(projectDir, 'prod'),
+    stringifyYaml(prodConfig),
   );
 
   if (bare) {
@@ -370,63 +378,53 @@ async function initCommand(args: string[]): Promise<void> {
     );
     fs.mkdirSync(path.join(projectDir, 'public'), { recursive: true });
     fs.writeFileSync(
-      path.join(projectDir, 'nav.json'),
-      JSON.stringify(
-        [
-          {
-            title: 'Navigation',
-            links: [{ text: 'Home', internal: '/index.html' }],
-          },
-        ],
-        null,
-        2,
-      ) + '\n',
+      getDefaultProjectConfigFilePath(projectDir, 'nav'),
+      stringifyYaml([
+        {
+          title: 'Navigation',
+          links: [{ text: 'Home', internal: '/index.html' }],
+        },
+      ]),
     );
   } else {
     // 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',
+      getDefaultProjectConfigFilePath(projectDir, 'nav'),
+      stringifyYaml([
+        {
+          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,
+            },
+          ],
+        },
+      ]),
     );
     fs.writeFileSync(
-      path.join(projectDir, 'authors.json'),
-      JSON.stringify(
-        { alex: { name: 'Alex Breen', avatar: '/avatars/alex.jpg' } },
-        null,
-        2,
-      ) + '\n',
+      getDefaultProjectConfigFilePath(projectDir, 'authors'),
+      stringifyYaml({
+        alex: { name: 'Alex Breen', avatar: '/avatars/alex.jpg' },
+      }),
     );
 
     // Copy content/ and public/ from the package
@@ -627,10 +625,7 @@ try {
       const { runWatch } = await import(
         path.join(packageDir, 'build/watch/index.ts')
       );
-      await runWatch({
-        httpPort: parsePortArg('--port'),
-        wsPort: parsePortArg('--ws-port'),
-      });
+      await runWatch({ httpPort: parsePortArg('--port') });
       break;
     }
 

package/build/build-manifest.ts

@@ -1,10 +1,16 @@
 import fs from 'fs';
 import path from 'path';
+import { globals, type Globals } from './globals';
 import { toPosix } from './utils/paths';
 
 const EXCLUDED_DIRS = new Set(['pagefind']);
 const EXCLUDED_FILES = new Set(['tada.manifest.json']);
 
+type ManifestGlobals = Pick<
+  Globals,
+  'createSha256Hasher' | 'now' | 'readFileArrayBuffer' | 'toISOString'
+>;
+
 export interface BuildManifest {
   schema: 1;
   build: number;
@@ -51,8 +57,12 @@ export function diffManifests(
 }
 
 export async function hashFile(filePath: string): Promise<string> {
-  const buffer = await Bun.file(filePath).arrayBuffer();
-  const hasher = new Bun.CryptoHasher('sha256');
+  const runtimeGlobals: Pick<
+    ManifestGlobals,
+    'createSha256Hasher' | 'readFileArrayBuffer'
+  > = globals;
+  const buffer = await runtimeGlobals.readFileArrayBuffer(filePath);
+  const hasher = runtimeGlobals.createSha256Hasher();
   hasher.update(buffer);
   return hasher.digest('hex');
 }
@@ -120,11 +130,12 @@ export async function generateBuildManifest(
   manifestPath: string,
   buildVersion: number,
 ): Promise<void> {
+  const runtimeGlobals: Pick<ManifestGlobals, 'now' | 'toISOString'> = globals;
   const files = await walkAndHash(distDir);
   const manifest: BuildManifest = {
     schema: 1,
     build: buildVersion,
-    buildTime: new Date().toISOString(),
+    buildTime: runtimeGlobals.toISOString(runtimeGlobals.now()),
     files,
   };
   fs.mkdirSync(path.dirname(manifestPath), { recursive: true });

package/build/bundle.ts

@@ -69,7 +69,6 @@ function createDefine(
   isDev = false,
 ): Record<string, string> {
   return {
-    __SITE_BASE__: JSON.stringify(siteVariables.base),
     __SITE_BASE_PATH__: JSON.stringify(siteVariables.basePath),
     __SITE_TITLE_POSTFIX__: JSON.stringify(siteVariables.titlePostfix),
     __SITE_DEFAULT_TIMEZONE__: JSON.stringify(siteVariables.defaultTimeZone),

package/build/config-files.ts

@@ -0,0 +1,183 @@
+import fs from 'fs';
+import path from 'path';
+
+export type SiteEnv = 'dev' | 'prod';
+export type SiteConfigName = 'site.dev' | 'site.prod';
+export type ProjectConfigName = 'nav' | 'authors';
+export type ConfigName = SiteConfigName | ProjectConfigName;
+export type ProjectConfigExtension = '.yaml' | '.yml' | '.json';
+
+export interface ResolvedProjectConfigFile<
+  Name extends ConfigName = ConfigName,
+> {
+  name: Name;
+  baseName: string;
+  fileName: string;
+  filePath: string;
+  extension: ProjectConfigExtension;
+  required: boolean;
+}
+
+export const CONFIG_FILE_EXTENSIONS = ['.yaml', '.yml', '.json'] as const;
+export const DEFAULT_CONFIG_FILE_EXTENSION = '.yaml' as const;
+
+export const SITE_CONFIG_BASE_NAMES = {
+  dev: 'site.dev',
+  prod: 'site.prod',
+} as const satisfies Record<SiteEnv, SiteConfigName>;
+
+export const PROJECT_CONFIG_BASE_NAMES = {
+  nav: 'nav',
+  authors: 'authors',
+} as const satisfies Record<ProjectConfigName, ProjectConfigName>;
+
+export const REQUIRED_PROJECT_CONFIG_NAMES = ['nav'] as const;
+export const OPTIONAL_PROJECT_CONFIG_NAMES = ['authors'] as const;
+export const PROJECT_CONFIG_NAMES = [
+  ...REQUIRED_PROJECT_CONFIG_NAMES,
+  ...OPTIONAL_PROJECT_CONFIG_NAMES,
+] as const;
+
+function joinWithOr(items: string[]): string {
+  if (items.length <= 1) {
+    return items[0] ?? '';
+  }
+  if (items.length === 2) {
+    return `${items[0]} or ${items[1]}`;
+  }
+  return `${items.slice(0, -1).join(', ')}, or ${items[items.length - 1]}`;
+}
+
+function getResolvedConfigExtension(fileName: string): ProjectConfigExtension {
+  const ext = path.extname(fileName).toLowerCase();
+  if (ext !== '.yaml' && ext !== '.yml' && ext !== '.json') {
+    throw new Error(`Unsupported config file extension for ${fileName}`);
+  }
+  return ext;
+}
+
+export function getSiteConfigBaseName(env: SiteEnv): SiteConfigName {
+  return SITE_CONFIG_BASE_NAMES[env];
+}
+
+export function getProjectConfigBaseName(
+  name: ProjectConfigName,
+): ProjectConfigName {
+  return PROJECT_CONFIG_BASE_NAMES[name];
+}
+
+export function getSupportedConfigFileNames(baseName: string): string[] {
+  return CONFIG_FILE_EXTENSIONS.map(ext => `${baseName}${ext}`);
+}
+
+export function getSupportedConfigFilePaths(
+  projectDir: string,
+  baseName: string,
+): string[] {
+  return getSupportedConfigFileNames(baseName).map(fileName =>
+    path.join(projectDir, fileName),
+  );
+}
+
+export function getSupportedConfigFileNamesText(baseName: string): string {
+  return joinWithOr(getSupportedConfigFileNames(baseName));
+}
+
+export function getDefaultConfigFileName(baseName: string): string {
+  return `${baseName}${DEFAULT_CONFIG_FILE_EXTENSION}`;
+}
+
+export function getDefaultConfigFilePath(
+  projectDir: string,
+  baseName: string,
+): string {
+  return path.join(projectDir, getDefaultConfigFileName(baseName));
+}
+
+export function getDefaultSiteConfigFileName(env: SiteEnv): string {
+  return getDefaultConfigFileName(getSiteConfigBaseName(env));
+}
+
+export function getDefaultSiteConfigPath(
+  projectDir: string,
+  env: SiteEnv,
+): string {
+  return getDefaultConfigFilePath(projectDir, getSiteConfigBaseName(env));
+}
+
+export function getDefaultProjectConfigFileName(
+  name: ProjectConfigName,
+): string {
+  return getDefaultConfigFileName(getProjectConfigBaseName(name));
+}
+
+export function getDefaultProjectConfigFilePath(
+  projectDir: string,
+  name: ProjectConfigName,
+): string {
+  return getDefaultConfigFilePath(projectDir, getProjectConfigBaseName(name));
+}
+
+export function resolveConfigFile<Name extends ConfigName = ConfigName>(
+  projectDir: string,
+  {
+    name,
+    baseName,
+    required,
+  }: { name: Name; baseName: string; required: boolean },
+): ResolvedProjectConfigFile<Name> | undefined {
+  const matches = getSupportedConfigFilePaths(projectDir, baseName).filter(
+    filePath => fs.existsSync(filePath),
+  );
+
+  if (matches.length > 1) {
+    const fileNames = matches.map(filePath => path.basename(filePath));
+    throw new Error(
+      `Multiple config files found for ${baseName}: ${joinWithOr(fileNames)}. Keep only one.`,
+    );
+  }
+
+  if (matches.length === 0) {
+    if (required) {
+      throw new Error(
+        `Missing required config file for ${baseName} (tried ${getSupportedConfigFileNamesText(baseName)})`,
+      );
+    }
+    return undefined;
+  }
+
+  const filePath = matches[0];
+  const fileName = path.basename(filePath);
+  return {
+    name,
+    baseName,
+    fileName,
+    filePath,
+    extension: getResolvedConfigExtension(fileName),
+    required,
+  };
+}
+
+export function resolveSiteConfigFile(
+  projectDir: string,
+  env: SiteEnv,
+): ResolvedProjectConfigFile<SiteConfigName> {
+  const baseName = SITE_CONFIG_BASE_NAMES[env];
+  return resolveConfigFile(projectDir, {
+    name: baseName,
+    baseName,
+    required: true,
+  })!;
+}
+
+export function resolveProjectConfigFile(
+  projectDir: string,
+  name: ProjectConfigName,
+): ResolvedProjectConfigFile<ProjectConfigName> | undefined {
+  const baseName = PROJECT_CONFIG_BASE_NAMES[name];
+  return resolveConfigFile(projectDir, {
+    name,
+    baseName,
+    required: name === 'nav',
+  });
+}