@abreen/tada 1.11.3 → 1.13.4

package/build/template-globals.ts

@@ -0,0 +1,91 @@
+import timezones from '../src/timezone/timezones.json' with { type: 'json' };
+import type { SiteVariables } from './types';
+
+const MONTHS = [
+  '',
+  'January',
+  'February',
+  'March',
+  'April',
+  'May',
+  'June',
+  'July',
+  'August',
+  'September',
+  'October',
+  'November',
+  'December',
+];
+
+interface TemplateGlobals {
+  isHomePage: boolean;
+  isoDate: (str: string | null | undefined) => string | null;
+  readableDate: (date: string | Date | null | undefined) => string;
+  classNames: (obj: Record<string, unknown>) => string;
+  cx: (obj: Record<string, unknown>) => string;
+  renderTimeZoneChooser: () => string;
+}
+
+export default function createTemplateGlobals(
+  pageVariables: Record<string, unknown>,
+  siteVariables: SiteVariables,
+  subPath: string,
+): TemplateGlobals {
+  const defaultTz = timezones.find(
+    t => t.value === siteVariables.defaultTimeZone,
+  )!;
+  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 aria-label="Time zone">${options}</select><noscript>Times shown in ${defaultTz.abbreviation}.</noscript>`;
+
+  return {
+    isHomePage: subPath === 'index',
+    isoDate,
+    readableDate,
+    classNames,
+    cx: classNames,
+    renderTimeZoneChooser,
+  };
+}
+
+function isoDate(str: string | null | undefined): string | null {
+  if (str == null || str == '') {
+    return null;
+  }
+  const date = new Date(str);
+  return date.toISOString().slice(0, 10);
+}
+
+function readableDate(date: string | Date | null | undefined): string {
+  if (date == null || date == '') {
+    return '';
+  }
+
+  if (!(date instanceof Date)) {
+    date = new Date(date);
+  }
+
+  const str = date.toISOString();
+  const year = str.slice(0, 4);
+  const month = Number(str.slice(5, 7));
+  const day = Number(str.slice(8, 10));
+
+  return `${MONTHS[month]} ${day}, ${year}`;
+}
+
+export function classNames(obj: Record<string, unknown>): string {
+  const names: string[] = [];
+  for (const key in obj) {
+    if (obj[key]) {
+      names.push(key);
+    }
+  }
+  return names.join(' ');
+}

package/build/templates.ts

@@ -1,6 +1,15 @@
 import fs from 'fs';
 import path from 'path';
 import _ from 'lodash';
+import {
+  PROJECT_CONFIG_NAMES,
+  getProjectConfigBaseName,
+  type ProjectConfigName,
+} from './config-files';
+import {
+  loadProjectConfig,
+  type LoadedProjectConfigFile,
+} from './config-loader';
 import { compile as compileJsonSchema, doValidation } from './json-schema';
 import { makeLogger } from './log';
 import { getPackageDir, getProjectDir } from './utils/paths';
@@ -12,34 +21,33 @@ const log: Logger = makeLogger(import.meta.url);
 // Store all templates in memory (don't read template files during build)
 const templates: Record<string, string> = {};
 
-// All parsed data (from .json files)
-const jsonData: Record<string, unknown> = {};
+// All parsed project config files
+const projectConfig: Partial<Record<ProjectConfigName, unknown>> = {};
+const loadedProjectConfig: Partial<
+  Record<ProjectConfigName, LoadedProjectConfigFile>
+> = {};
 
-// Compiled JSON Schema for the .json files
-const validators: Record<string, ValidateFunction> = {};
+// Compiled JSON Schema for the project config files
+const validators: Partial<Record<ProjectConfigName, ValidateFunction>> = {};
 
 // Keeps track of template call tree
 const renderStack: string[] = [];
 let errorStack: string[] | null = null;
 
-// JSON data files that live in the user's config directory
-const REQUIRED_JSON_DATA_FILES: string[] = ['nav.json'];
-const OPTIONAL_JSON_DATA_FILES: string[] = ['authors.json'];
-const JSON_DATA_FILES: string[] = [
-  ...REQUIRED_JSON_DATA_FILES,
-  ...OPTIONAL_JSON_DATA_FILES,
-];
-
 function getHtmlTemplatesDir(): string {
   return path.resolve(getPackageDir(), 'templates');
 }
 
-function getJsonDataDir(): string {
+function getProjectConfigDir(): string {
   return getProjectDir();
 }
 
-export function json(fileName: string): unknown {
-  return jsonData[fileName];
+export function config(name: ProjectConfigName): unknown {
+  return projectConfig[name];
+}
+
+export function getConfigFileName(name: ProjectConfigName): string | undefined {
+  return loadedProjectConfig[name]?.fileName;
 }
 
 export function render(
@@ -50,8 +58,8 @@ export function render(
     // Allow the template to call render(), it will use our params
     params.render = (otherFileName: string) => render(otherFileName, params);
 
-    // Allow the template to read the JSON files we previously read into memory
-    params.json = json;
+    // Allow templates to read the project config files we previously read into memory
+    params.config = config;
   }
 
   renderStack.push(fileName);
@@ -82,7 +90,11 @@ export function compileTemplates(
   }
 
   Object.keys(templates).forEach(k => delete templates[k]);
-  Object.keys(jsonData).forEach(k => delete jsonData[k]);
+  for (const name of PROJECT_CONFIG_NAMES) {
+    delete projectConfig[name];
+    delete loadedProjectConfig[name];
+    delete validators[name];
+  }
 
   // Load HTML templates from the package
   const htmlDir = getHtmlTemplatesDir();
@@ -97,41 +109,39 @@ export function compileTemplates(
     }
   });
 
-  // Load JSON data files from the project's config directory
-  const jsonDir = getJsonDataDir();
-  for (const fileName of JSON_DATA_FILES) {
-    const filePath = path.join(jsonDir, fileName);
-    if (!fs.existsSync(filePath)) {
-      if (REQUIRED_JSON_DATA_FILES.includes(fileName)) {
-        throw new Error(`Missing required config file: ${filePath}`);
-      }
+  // Load project config files from the project's config directory
+  const projectConfigDir = getProjectConfigDir();
+  for (const name of PROJECT_CONFIG_NAMES) {
+    const loaded = loadProjectConfig(projectConfigDir, name, siteVariables);
+    if (!loaded) {
       continue;
     }
 
     // Schema validation
     const schemaDir = path.resolve(getPackageDir(), 'schema');
-    const schemaFile = `${path.parse(fileName).name}.schema.json`;
+    const schemaFile = `${getProjectConfigBaseName(name)}.schema.json`;
     const schemaPath = path.join(schemaDir, schemaFile);
     if (!fs.existsSync(schemaPath)) {
-      throw new Error(`Missing JSON Schema for ${fileName}: ${schemaPath}`);
+      throw new Error(
+        `Missing JSON Schema for ${loaded.fileName}: ${schemaPath}`,
+      );
     }
-    compileAndSetValidator(schemaPath, fileName);
+    compileAndSetValidator(schemaPath, name);
 
-    log.debug`Reading ${fileName}`;
-    jsonData[fileName] = JSON.parse(
-      _.template(fs.readFileSync(filePath, 'utf-8'))({
-        vars: siteVariables.vars || {},
-        site: siteVariables,
-      }),
-    );
+    log.debug`Reading ${loaded.fileName}`;
+    projectConfig[name] = loaded.value;
+    loadedProjectConfig[name] = loaded;
 
-    doValidation(validators[fileName], jsonData[fileName], fileName);
+    doValidation(validators[name]!, projectConfig[name], loaded.fileName);
   }
 }
 
-function compileAndSetValidator(schemaPath: string, fileName: string): void {
+function compileAndSetValidator(
+  schemaPath: string,
+  name: ProjectConfigName,
+): void {
   const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf-8'));
-  validators[fileName] = compileJsonSchema(schema);
+  validators[name] = compileJsonSchema(schema);
 }
 
-export { getHtmlTemplatesDir, getJsonDataDir, JSON_DATA_FILES };
+export { getHtmlTemplatesDir, getProjectConfigDir };

package/build/test-helpers.ts

@@ -0,0 +1,15 @@
+type FsModule = typeof import('fs');
+type FsModuleOverrides = object & { promises?: FsModule['promises'] };
+
+type FsModuleMock<T extends FsModuleOverrides> = T & {
+  default: Omit<T, 'promises'> & Pick<FsModule, 'promises'>;
+  promises: FsModule['promises'];
+};
+
+export function createFsModuleMock<T extends FsModuleOverrides>(
+  overrides: T,
+): FsModuleMock<T> {
+  const promises = overrides.promises ?? ({} as FsModule['promises']);
+
+  return { ...overrides, default: { ...overrides, promises }, promises };
+}

package/build/toc-plugin.ts

@@ -55,7 +55,11 @@ export function tocPlugin(md: MarkdownIt): void {
       }
 
       // Thematic breaks / dinkuses (only at top level)
-      if (token.type === 'hr' && containerStack.length === 0) {
+      if (
+        token.type === 'hr' &&
+        containerStack.length === 0 &&
+        !state.env?.slides
+      ) {
         items.push({ kind: 'dinkus' });
         continue;
       }

package/build/types.d.ts

@@ -1,8 +1,9 @@
 import type { BundledLanguage } from 'shiki';
+import type { TadaProjectScan } from './source-model';
 
 export type PlainTextLanguage = 'text' | 'txt' | 'plain';
 
-/** Site configuration loaded from site.dev.json or site.prod.json */
+/** Site configuration loaded from site.dev.yaml/yml/json or site.prod.yaml/yml/json */
 export interface SiteVariables {
   base: string;
   basePath: string;
@@ -33,15 +34,21 @@ export type FeatureConfig = {
 };
 
 /** A rendered content asset ready to write to dist/ */
+export interface HtmlOutputAnalysis {
+  outgoingTargets: Set<string>;
+}
+
 export interface Asset {
   assetPath: string;
   content: string | Buffer;
+  htmlAnalysis?: HtmlOutputAnalysis;
 }
 
 /** Options for the content rendering pipeline */
 export interface ContentRenderOptions {
   distDir: string;
   assetFiles: string[];
+  scan: TadaProjectScan;
   watchState?: WatchState;
 }
 
@@ -59,6 +66,7 @@ export interface ContentRenderResult {
   removedHtmlAssetPaths: Set<string>;
   removedOutputRelPaths: Set<string>;
   htmlAssetsByPath: Map<string, string>;
+  htmlAnalysisByPath: Map<string, HtmlOutputAnalysis>;
   buildContentFiles: string[];
 }
 

package/build/util.ts

@@ -1,3 +1,10 @@
+export {
+  addGeneratedRouteAliases,
+  getProcessedExts,
+  getSourceOutputPaths,
+  getSourceTargetPaths,
+  isBuildContentSource,
+} from './source-model';
 export {
   getBuildContentFiles,
   getContentFiles,
@@ -21,6 +28,7 @@ export {
 } from './utils/paths';
 export {
   injectAssetTags,
+  preparePageTemplateHtml,
   renderCodePageAsset,
   renderCopiedContentAsset,
   renderLiterateJavaPageAsset,

package/build/utils/code.ts

@@ -6,7 +6,6 @@ import { makeLogger } from '../log';
 import { getExtensionToShikiLanguage } from '../site-variables';
 import { highlightCode } from './shiki-highlighter';
 import externalLinksPlugin from '../external-links-plugin';
-import applyBasePathPlugin from '../apply-base-path-plugin';
 import { createApplyBasePath } from './paths';
 import { splitLines } from './literate-java';
 import type { JavaTocEntry, SiteVariables } from '../types';
@@ -40,13 +39,11 @@ const log = makeLogger(import.meta.url);
 
 const PROSE_LINE = /^\s*\/\/\/(\s|$)/;
 
-function createCodeMarkdown(
-  siteVariables: SiteVariables,
-  options: Record<string, unknown> = {},
-): MarkdownIt {
-  return new MarkdownIt({ html: true, typographer: true })
-    .use(externalLinksPlugin, siteVariables)
-    .use(applyBasePathPlugin, siteVariables, options);
+function createCodeMarkdown(siteVariables: SiteVariables): MarkdownIt {
+  return new MarkdownIt({ html: true, typographer: true }).use(
+    externalLinksPlugin,
+    siteVariables,
+  );
 }
 
 // Matches Markdown links: [text](url)
@@ -504,15 +501,8 @@ export function renderCodeWithComments(
   lang: string,
   siteVariables: SiteVariables,
   pageDirPath?: string,
-  sourceUrlPath?: string,
-  validTargets?: Set<string>,
-  literateJavaOutputPaths?: Set<string>,
 ): string {
-  const md = createCodeMarkdown(siteVariables, {
-    sourceUrlPath,
-    validTargets,
-    literateJavaOutputPaths,
-  });
+  const md = createCodeMarkdown(siteVariables);
   const lines = splitLines(sourceCode);
 
   // Group lines into segments

package/build/utils/content-files.ts

@@ -1,13 +1,13 @@
 import fs from 'fs';
 import path from 'path';
-import { parseFrontMatterAndContent } from './front-matter';
 import {
-  getProcessedExtensions,
-  extensionIsMarkdown,
-  isLiterateJava,
-  isPartial,
-} from './file-types';
-import { getPublicDir, normalizeOutputPath, toPosix } from './paths';
+  getProcessedExts,
+  getSourceOutputPaths,
+  getSourceTargetPaths,
+  isBuildContentSource,
+  shouldSkipContentFile,
+} from '../source-model';
+import { getPublicDir, toPosix } from './paths';
 
 function walkFiles(dir: string): string[] {
   return fs.readdirSync(dir).flatMap(file => {
@@ -31,23 +31,14 @@ export function getContentFiles(
   });
 }
 
-export function shouldSkipContentFile(filePath: string): boolean {
-  const ext = path.extname(filePath).toLowerCase();
-  if (!(extensionIsMarkdown(ext) || ext === '.html')) {
-    return false;
-  }
-
-  const raw = fs.readFileSync(filePath, 'utf-8');
-  const { pageVariables } = parseFrontMatterAndContent(raw, ext);
-  return pageVariables?.skip === true;
-}
-
 export function getBuildContentFiles(
   contentDir: string,
   codeExtensions: string[],
 ): string[] {
-  return getContentFiles(contentDir, codeExtensions).filter(
-    filePath => !isPartial(filePath) && !shouldSkipContentFile(filePath),
+  const processedExts = getProcessedExts(codeExtensions);
+
+  return getContentFiles(contentDir, codeExtensions).filter(filePath =>
+    isBuildContentSource(filePath, processedExts),
   );
 }
 
@@ -56,47 +47,17 @@ export function getContentSourceOutputRelPaths(
   filePath: string,
   codeExtensions: string[],
 ): Set<string> {
-  const processedExtSet = new Set(getProcessedExtensions(codeExtensions));
-  const relPath = toPosix(path.relative(contentDir, filePath));
-  const ext = path.extname(filePath).slice(1).toLowerCase();
-  const parsed = path.parse(relPath);
-  const outputs = new Set<string>();
-
-  if (!processedExtSet.has(ext)) {
-    outputs.add(relPath);
-    return outputs;
-  }
-
+  const processedExts = getProcessedExts(codeExtensions);
   const buildContentFiles = new Set(
     getBuildContentFiles(contentDir, codeExtensions),
   );
-  if (!buildContentFiles.has(filePath)) {
-    return outputs;
-  }
-
-  if (isLiterateJava(filePath)) {
-    outputs.add(toPosix(path.join(parsed.dir, `${parsed.name}.html`)));
-    outputs.add(toPosix(path.join(parsed.dir, parsed.name)));
-    return outputs;
-  }
-
-  if (
-    extensionIsMarkdown(parsed.ext.toLowerCase()) ||
-    parsed.ext.toLowerCase() === '.html'
-  ) {
-    outputs.add(toPosix(path.join(parsed.dir, `${parsed.name}.html`)));
-    return outputs;
-  }
-
-  const codeExtensionSet = new Set(
-    codeExtensions.map(value => value.toLowerCase()),
-  );
-  if (codeExtensionSet.has(ext)) {
-    outputs.add(relPath);
-    outputs.add(`${relPath}.html`);
-  }
 
-  return outputs;
+  return getSourceOutputPaths({
+    contentDir,
+    filePath,
+    processedExts,
+    buildContent: buildContentFiles.has(filePath),
+  });
 }
 
 export function getContentOutputRelPaths(
@@ -104,37 +65,23 @@ export function getContentOutputRelPaths(
   codeExtensions: string[],
 ): Set<string> {
   const buildContentFiles = getBuildContentFiles(contentDir, codeExtensions);
-  const codeExtensionSet = new Set(
-    codeExtensions.map(ext => ext.toLowerCase()),
-  );
+  const processedExts = getProcessedExts(codeExtensions);
   const outputs = new Set<string>();
 
   for (const filePath of buildContentFiles) {
-    const relPath = toPosix(path.relative(contentDir, filePath));
-    const parsed = path.parse(relPath);
-    const ext = parsed.ext.toLowerCase();
-
-    if (isLiterateJava(filePath)) {
-      outputs.add(toPosix(path.join(parsed.dir, `${parsed.name}.html`)));
-      outputs.add(toPosix(path.join(parsed.dir, parsed.name)));
-      continue;
-    }
-
-    if (extensionIsMarkdown(ext) || ext === '.html') {
-      outputs.add(toPosix(path.join(parsed.dir, `${parsed.name}.html`)));
-      continue;
-    }
-
-    if (codeExtensionSet.has(ext.slice(1))) {
-      outputs.add(relPath);
-      outputs.add(`${relPath}.html`);
+    for (const outputPath of getSourceOutputPaths({
+      contentDir,
+      filePath,
+      processedExts,
+      buildContent: true,
+    })) {
+      outputs.add(outputPath);
     }
   }
 
-  const processedExtSet = new Set(getProcessedExtensions(codeExtensions));
   for (const filePath of walkFiles(contentDir)) {
     const ext = path.extname(filePath).slice(1).toLowerCase();
-    if (processedExtSet.has(ext)) {
+    if (processedExts.has(ext)) {
       continue;
     }
     outputs.add(toPosix(path.relative(contentDir, filePath)));
@@ -143,24 +90,6 @@ export function getContentOutputRelPaths(
   return outputs;
 }
 
-function addGeneratedRouteAliases(
-  pathSet: Set<string>,
-  outputPath: string,
-): void {
-  const normalizedPath = normalizeOutputPath(outputPath);
-  pathSet.add(normalizedPath);
-
-  if (!normalizedPath.endsWith('/index.html')) {
-    return;
-  }
-
-  const base = normalizedPath.slice(0, -'index.html'.length);
-  pathSet.add(base);
-  if (base.endsWith('/') && base.length > 1) {
-    pathSet.add(base.slice(0, -1));
-  }
-}
-
 function getPublicFiles(publicDir: string): string[] {
   if (!fs.existsSync(publicDir)) {
     return [];
@@ -191,49 +120,51 @@ export function getValidInternalTargets(
   codeExtensions: string[],
 ): Set<string> {
   const targets = new Set<string>();
-  const codeExtensionSet = new Set(
-    codeExtensions.map(ext => ext.toLowerCase()),
-  );
+  const processedExts = getProcessedExts(codeExtensions);
 
   for (const filePath of contentFiles) {
-    if (isPartial(filePath)) {
-      continue;
-    }
-    const relPath = path.relative(contentDir, filePath);
-    const parsed = path.parse(relPath);
-    const ext = parsed.ext.toLowerCase();
-    const subPath = toPosix(path.join(parsed.dir, parsed.name));
-
-    if (isLiterateJava(filePath)) {
-      // parsed.name is e.g. "VowelCounter.java"; the output page is
-      // VowelCounter.java.html and the source file is VowelCounter.java
-      const javaSubPath = toPosix(path.join(parsed.dir, parsed.name));
-      addGeneratedRouteAliases(targets, `/${javaSubPath}.html`);
-      targets.add(normalizeOutputPath(`/${javaSubPath}`));
-    } else if (extensionIsMarkdown(ext) || ext === '.html') {
-      addGeneratedRouteAliases(targets, `/${subPath}.html`);
-    } else if (codeExtensionSet.has(ext.slice(1))) {
-      addGeneratedRouteAliases(targets, `/${relPath}.html`);
-      targets.add(normalizeOutputPath(`/${relPath}`));
+    for (const targetPath of getSourceTargetPaths({
+      kind: 'content',
+      rootDir: contentDir,
+      filePath,
+      processedExts,
+      buildContent: true,
+    })) {
+      targets.add(targetPath);
     }
   }
 
   // Include non-processed assets in content/ that are copied directly to dist/.
-  const processedExtSet = new Set(getProcessedExtensions(codeExtensions));
   for (const filePath of walkFiles(contentDir)) {
     const ext = path.extname(filePath).slice(1).toLowerCase();
-    if (processedExtSet.has(ext)) {
+    if (processedExts.has(ext)) {
       continue;
     }
-    const relPath = path.relative(contentDir, filePath);
-    targets.add(normalizeOutputPath(`/${relPath}`));
+    for (const targetPath of getSourceTargetPaths({
+      kind: 'content',
+      rootDir: contentDir,
+      filePath,
+      processedExts,
+      buildContent: false,
+    })) {
+      targets.add(targetPath);
+    }
   }
 
   const publicDir = getPublicDir();
   for (const filePath of getPublicFiles(publicDir)) {
-    const relPath = path.relative(publicDir, filePath);
-    targets.add(normalizeOutputPath(`/${relPath}`));
+    for (const targetPath of getSourceTargetPaths({
+      kind: 'public',
+      rootDir: publicDir,
+      filePath,
+      processedExts,
+      buildContent: true,
+    })) {
+      targets.add(targetPath);
+    }
   }
 
   return targets;
 }
+
+export { shouldSkipContentFile };