@abreen/tada 1.17.0 → 1.18.0

package/README.md

@@ -45,7 +45,8 @@ A static site generator. The successor to Presto.
   * `+++ ... +++ ... +++` renders a two-column layout
   * Special heading subtitles with `## Heading # A subtitle here`
   * `{{{ _partial.md }}}` syntax for including partials
-- Automatically generated favicon
+- Custom header logo from an image in `public/`
+- Automatically generated favicon or custom ICO from `public/`
   * Text, color, font and font weight taken from config file
 
 ## Prerequisites
@@ -135,6 +136,9 @@ files in the `dist/` directory.
 ### `tada watch`
 
 Start a development web server, watch for changes and rebuild automatically.
+Exactly one `site.dev.yaml`, `site.dev.yml`, or `site.dev.json` must exist
+before starting; otherwise, correct the configuration files and restart the
+command. Once watching, build errors can be fixed without restarting.
 
 ### `tada clean`
 
@@ -264,16 +268,18 @@ vars:
 | `title` | Title for the whole site (also used to derive `titlePostfix`) |
 | `titlePostfix` | *Optional*, the string to append to each page's `title` |
 | `banner` | *Optional*, Markdown rendered in a bordered box above every page |
-| `symbol` | Text (1-5 chars) displayed in header (also used as the favicon symbol) |
+| `symbol` | Text (1-5 chars) displayed in header when `logo` is absent; also used for generated favicons |
+| `logo` | *Optional*, image path relative to `public/`, replacing the header symbol |
+| `favicon` | *Optional*, `.ico` path relative to `public/`, replacing generated favicons and the web app manifest |
 | `themeColor` | Theme color for the site (e.g., `"tomato"`, `"#c04040"`, `"hsl(195 70% 40%)"`) |
 | `tintHue` | *Optional*, hue (0-360) for background and foreground tinting (default `20`) |
-| `tintAmount` | *Optional*, percentage (0-100) of tint to apply (default `100`) |
+| `tintAmount` | *Optional*, percentage (0-100) of tint to apply to the neutral palette (default `100`); link saturation stays fixed |
 | `defaultFont` | *Optional*, initial font pairing: `sans` or `serif` (default `sans`) |
 | `defaultContrast` | *Optional*, initial neutral-palette contrast: `standard` or `high` (default `standard`) |
 | `fontOverrides` | *Optional*, custom serif and serif-monospace WOFF2 faces from `public/`; each configured family requires `regular` and may include styled faces, OpenType `features`, and font-specific `tuning` |
-| `faviconSymbol` | *Optional*, the text to use instead of `symbol` in the favicon |
+| `faviconSymbol` | *Optional*, the text to use instead of `symbol` in generated favicons |
 | `features.search` | Enable search UI and Pagefind index generation |
-| `features.favicon` | Enable automatically generated favicons |
+| `features.favicon` | Enable favicon links and generation (default `true`); `false` also omits custom favicon links |
 | `features.footer` | Show the Tada footer at the bottom of every page |
 | `features.pickers` | Show the font and contrast pickers at the bottom of every page (default `true`) |
 | `base` | Full base URL of the deployed site, used for metadata and URL generation |
@@ -281,10 +287,38 @@ vars:
 | `internalDomains` | Domain names treated as internal by link processing (not marked external) |
 | `extensionToShikiLanguage` | *Optional*, map from source-file extension to the Shiki language used for generated code pages and copied-source processing |
 | `shikiLanguages` | *Optional*, list of Shiki languages permitted in code blocks |
-| `faviconColor` | *Optional*, background color for favicon (defaults to `themeColor`) |
-| `faviconFontWeight` | *Optional*, font weight used for favicon text (default `700`) |
+| `faviconColor` | *Optional*, background color for generated favicons (defaults to `themeColor`) |
+| `faviconFontWeight` | *Optional*, font weight used for generated favicon text (default `700`) |
 | `vars` | Arbitrary key/value variables exposed to templates/content as `vars.*` (e.g., `<%= vars.staffEmail %>`) |
 
+### Custom logo and favicon
+
+Place your assets in `public/` and configure their relative paths:
+
+```yaml
+logo: branding/logo.svg
+favicon: branding/favicon.ico
+symbol: TADA
+```
+
+Here the files are `public/branding/logo.svg` and
+`public/branding/favicon.ico`. Both fields are optional and independent. The
+logo replaces the header symbol and works without JavaScript. Without a custom
+favicon, Tada generates favicons from `faviconSymbol` or `symbol`, never from
+the logo image. A custom favicon replaces all generated icon assets, the web
+app manifest, and related web app metadata; `symbol` can be omitted when both
+logo and favicon are supplied.
+
+Paths must use forward slashes and cannot contain absolute paths, empty
+segments, `.` or `..` segments, query strings, or fragments. Assets must exist
+and be readable. The favicon must end in `.ico`; logo extensions are unrestricted,
+so choose a browser-supported image format. Asset URLs encode filenames and
+respect `basePath`, and files are copied unchanged.
+
+`features.favicon: false` omits all favicon links and generation. Configured
+assets are still validated and public files still copy normally. See
+[Header logo](spec/logo.md) and [Favicons](spec/favicons.md) for details.
+
 #### `nav.yaml`
 
 Defines the site navigation structure. The file contains an array of section

package/bin/tada.ts

@@ -10,6 +10,8 @@ import {
   validateHue,
   validateUrl,
   validateBasePath,
+  validateTimeZone,
+  resolveDefaultTimeZone,
   createSiteConfig,
 } from './validators';
 import {
@@ -28,7 +30,9 @@ import {
 
 const { version } = packageJson;
 
-const SYSTEM_TIME_ZONE = Intl.DateTimeFormat().resolvedOptions().timeZone;
+const DEFAULT_TIME_ZONE = resolveDefaultTimeZone(
+  Intl.DateTimeFormat().resolvedOptions().timeZone,
+);
 
 const packageDir = path.resolve(import.meta.dir, '..');
 
@@ -102,8 +106,8 @@ const INIT_QUESTIONS: Record<string, InitQuestion> = {
   },
   defaultTimeZone: {
     prompt: 'Default time zone',
-    defaultValue: SYSTEM_TIME_ZONE,
-    validate: (v: string) => (v ? null : 'Time zone is required'),
+    defaultValue: DEFAULT_TIME_ZONE.timeZone,
+    validate: validateTimeZone,
   },
   prodBase: {
     prompt: 'Production base URL',
@@ -218,10 +222,8 @@ async function initCommand(args: string[]): Promise<void> {
           type: 'string',
           default: INIT_QUESTIONS.tintAmount.defaultValue,
         },
-        'default-time-zone': {
-          type: 'string',
-          default: INIT_QUESTIONS.defaultTimeZone.defaultValue,
-        },
+        // No parseArgs default, so an omitted flag can be told apart
+        'default-time-zone': { type: 'string' },
         'prod-base': {
           type: 'string',
           default: INIT_QUESTIONS.prodBase.defaultValue,
@@ -268,6 +270,13 @@ async function initCommand(args: string[]): Promise<void> {
 
   const config: Record<string, string> = {};
 
+  const usesDefaultTimeZone =
+    !noInteractive || values['default-time-zone'] === undefined;
+  if (usesDefaultTimeZone && DEFAULT_TIME_ZONE.note) {
+    console.log(DEFAULT_TIME_ZONE.note);
+  }
+  values['default-time-zone'] ??= DEFAULT_TIME_ZONE.timeZone;
+
   if (noInteractive) {
     for (const [flag, key] of Object.entries(FLAG_TO_KEY)) {
       const value = values[flag] as string;
@@ -536,7 +545,9 @@ function diffCommand(args: string[]): void {
 
   if (totalChanges === 0) {
     console.log('\nNo changes between builds.');
-    return;
+    if (copyIdx === -1) {
+      return;
+    }
   }
 
   if (diff.added.length > 0) {
@@ -559,7 +570,9 @@ function diffCommand(args: string[]): void {
   }
 
   const noun = (n: number) => (n === 1 ? 'file' : 'files');
-  console.log(`\nTotal: ${totalChanges} ${noun(totalChanges)} differ`);
+  if (totalChanges > 0) {
+    console.log(`\nTotal: ${totalChanges} ${noun(totalChanges)} differ`);
+  }
 
   if (copyIdx !== -1) {
     const outDirArg = args[copyIdx + 1];
@@ -570,6 +583,7 @@ function diffCommand(args: string[]): void {
 
     const newDistDir = path.join(prodBase, `v${newVer}`);
     const resolvedOutDir = path.resolve(projectDir, outDirArg);
+    fs.mkdirSync(resolvedOutDir, { recursive: true });
     copyChangedFiles(diff, newDistDir, resolvedOutDir);
 
     // Always include pagefind/ (excluded from manifest but needed for search)

package/bin/validators.ts

@@ -1,5 +1,9 @@
+import timezones from '../src/timezone/timezones.json' with { type: 'json' };
 import type { SiteConfigInput, SiteVariables } from '../build/types';
 
+const SUPPORTED_TIME_ZONES: readonly string[] = timezones.map(tz => tz.value);
+const FALLBACK_TIME_ZONE = 'UTC';
+
 export function validateSymbol(value: string): string | null {
   if (!value) {
     return 'Symbol is required';
@@ -55,6 +59,35 @@ export function validateBasePath(value: string): string | null {
   return null;
 }
 
+export function validateTimeZone(value: string): string | null {
+  if (!value) {
+    return 'Time zone is required';
+  }
+  if (!SUPPORTED_TIME_ZONES.includes(value)) {
+    return `Must be one of the supported time zones: ${SUPPORTED_TIME_ZONES.join(', ')}`;
+  }
+  return null;
+}
+
+/**
+ * Picks the default time zone for `tada init`: the system zone when builds
+ * support it, otherwise UTC with a note explaining the fallback.
+ */
+export function resolveDefaultTimeZone(systemTimeZone: string | undefined): {
+  timeZone: string;
+  note: string | null;
+} {
+  if (systemTimeZone && validateTimeZone(systemTimeZone) === null) {
+    return { timeZone: systemTimeZone, note: null };
+  }
+  return {
+    timeZone: FALLBACK_TIME_ZONE,
+    note: systemTimeZone
+      ? `System time zone ${systemTimeZone} is not supported; using ${FALLBACK_TIME_ZONE}`
+      : `System time zone is unknown; using ${FALLBACK_TIME_ZONE}`,
+  };
+}
+
 export function createSiteConfig({
   title,
   symbol,
@@ -83,7 +116,7 @@ export function createSiteConfig({
     extensionToShikiLanguage,
     shikiLanguages,
     themeColor,
-    tintHue: Number(tintHue),
+    tintHue: Number(String(tintHue).replace(/deg$/, '')),
     tintAmount: Number(tintAmount),
     vars: { foobar: 123 },
   };

package/build/branding.ts

@@ -0,0 +1,41 @@
+import fs from 'fs';
+import path from 'path';
+import { isValidPublicAssetPath } from './custom-fonts';
+import type { SiteVariables } from './types';
+
+export function validateBranding(
+  site: Pick<SiteVariables, 'logo' | 'favicon'>,
+  options: {
+    publicDir: string;
+    publicFiles: ReadonlySet<string>;
+    readFile?: (filePath: string) => Buffer;
+  },
+): string[] {
+  const diagnostics: string[] = [];
+  for (const field of ['logo', 'favicon'] as const) {
+    const value = site[field];
+    if (value === undefined) {
+      continue;
+    }
+    if (
+      !isValidPublicAssetPath(value) ||
+      (field === 'favicon' && !value.endsWith('.ico'))
+    ) {
+      diagnostics.push(
+        `${field} "${value}" must be a public-relative POSIX path${field === 'favicon' ? ' ending in .ico' : ''}`,
+      );
+      continue;
+    }
+    const absolutePath = path.resolve(options.publicDir, ...value.split('/'));
+    if (!options.publicFiles.has(absolutePath)) {
+      diagnostics.push(`${field} "${value}" does not exist in public/`);
+      continue;
+    }
+    try {
+      (options.readFile ?? fs.readFileSync)(absolutePath);
+    } catch {
+      diagnostics.push(`${field} "${value}" could not be read`);
+    }
+  }
+  return diagnostics;
+}

package/build/build-manifest.ts

@@ -1,10 +1,11 @@
 import fs from 'fs';
 import path from 'path';
 import { globals, type Globals } from './globals';
-import { toPosix } from './utils/paths';
+import { SEARCH_INDEX_DIR, toPosix } from './utils/paths';
 
-const EXCLUDED_DIRS = new Set(['pagefind']);
-const EXCLUDED_FILES = new Set(['tada.manifest.json']);
+const EXCLUDED_DIRS = new Set([SEARCH_INDEX_DIR]);
+export const MANIFEST_FILE_NAME = 'tada.manifest.json';
+const EXCLUDED_FILES = new Set([MANIFEST_FILE_NAME]);
 
 type ManifestGlobals = Pick<
   Globals,
@@ -85,7 +86,7 @@ export async function walkAndHash(
     if (EXCLUDED_DIRS.has(topLevel)) {
       continue;
     }
-    if (EXCLUDED_FILES.has(entry.name)) {
+    if (EXCLUDED_FILES.has(rel)) {
       continue;
     }
 
@@ -109,7 +110,11 @@ export function getVersions(prodBaseDir: string): number[] {
       continue;
     }
     const match = entry.name.match(/^v(\d+)$/);
-    if (match) {
+    // A version exists only once its manifest, written last, is in place.
+    if (
+      match &&
+      fs.existsSync(path.join(prodBaseDir, entry.name, MANIFEST_FILE_NAME))
+    ) {
       versions.push(parseInt(match[1], 10));
     }
   }

package/build/{watch/compiler-types.d.ts → build-types.d.ts}

@@ -1,12 +1,14 @@
 import type {
   HtmlOutputAnalysis,
   SiteVariables,
-  TraceToolAvailability,
-} from '../types';
+  TraceArtifactFile,
+} from './types';
 
+/** A finished trace, keyed in the cache by its traced source files */
 export interface TraceCacheEntry {
-  manifestUrl: string;
   artifactId: string;
+  /** Manifest and chunk files, re-emitted on a cache hit */
+  files: TraceArtifactFile[];
   highlightedSources: { file: string; highlightedSource: string }[];
   totalSteps: number;
   sourceMtims: Record<string, number>;
@@ -17,9 +19,10 @@ export type TraceCache = Map<string, TraceCacheEntry>;
 export interface TadaBuildMeta {
   htmlAssetsByPath: Map<string, string>;
   htmlAnalysisByPath: Map<string, HtmlOutputAnalysis>;
+  pdfSourceByOutputPath: Map<string, string>;
   siteVariables: SiteVariables;
 }
 
-export interface WatchTraceOptions {
-  toolAvailability: TraceToolAvailability;
+export interface BuildDiagnostic {
+  message: string;
 }

package/build/build-validation.ts

@@ -0,0 +1,176 @@
+import path from 'path';
+import { validateBranding } from './branding';
+import { makeLogger } from './log';
+import { config, getConfigFileName } from './templates';
+import { validateConfigLinks } from './validate-config-links';
+import { validateCustomFontOverrides } from './custom-fonts';
+import { getProjectDir, SEARCH_INDEX_DIR, toPosix } from './utils/paths';
+import { sameOutputContent } from './output-publication';
+import { isFeatureEnabled } from './features';
+import type { OutputContent, SiteVariables } from './types';
+import type { BuildDiagnostic } from './build-types';
+import type { TadaSourceRecord } from './source-records';
+import {
+  assertNoOutputPathConflicts,
+  sourcePaths,
+  type TadaProjectScan,
+} from './source-model';
+
+const log = makeLogger(import.meta.url);
+
+/** Thrown after a build's errors have been printed */
+export class BuildFailedError extends Error {}
+
+function diagnosticsFromMessages(messages: string[]): BuildDiagnostic[] {
+  return messages.map(message => ({ message }));
+}
+
+export function diagnosticFromError(error: unknown): BuildDiagnostic {
+  return { message: error instanceof Error ? error.message : String(error) };
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Shows absolute paths inside the project as project-relative POSIX paths. */
+function formatDiagnostic(
+  message: string,
+  projectDir: string = getProjectDir(),
+): string {
+  const pattern = new RegExp(
+    `${escapeRegExp(projectDir + path.sep)}([^\\s:,"()]*)`,
+    'g',
+  );
+  return message.replace(pattern, (_, relPath: string) => toPosix(relPath));
+}
+
+/** Prints each diagnostic once, as one line. */
+export function printDiagnostics(
+  diagnostics: readonly BuildDiagnostic[],
+): void {
+  for (const diagnostic of diagnostics) {
+    log.error`${formatDiagnostic(diagnostic.message)}`;
+  }
+}
+
+function projectRelative(scan: TadaProjectScan, sourcePath: string): string {
+  return toPosix(path.relative(path.dirname(scan.contentDir), sourcePath));
+}
+
+export function validateConfig(
+  scan: TadaProjectScan,
+  siteVariables: SiteVariables,
+): BuildDiagnostic[] {
+  const publicFiles = new Set(sourcePaths(scan, 'public'));
+  const diagnostics = diagnosticsFromMessages([
+    ...validateCustomFontOverrides({
+      fontOverrides: siteVariables.fontOverrides,
+      publicDir: scan.publicDir,
+      publicFiles,
+    }),
+    ...validateBranding(siteVariables, {
+      publicDir: scan.publicDir,
+      publicFiles,
+    }),
+  ]);
+  for (const outputPath of assertNoOutputPathConflicts(scan)) {
+    const sources = [...scan.outputProducers.get(outputPath)!]
+      .map(sourcePath => projectRelative(scan, sourcePath))
+      .sort();
+    const verb = sources.length === 2 ? 'both write' : 'all write';
+    diagnostics.push({
+      message: `${sources.join(', ')}: ${verb} ${outputPath}`,
+    });
+  }
+  return diagnostics;
+}
+
+/**
+ * Output conflicts that can only be found after rendering: a source writing a
+ * file Tada generates, a file in the search index directory, or a path that
+ * would have to be both a file and a directory. Two sources writing the same
+ * path are found earlier by validateConfig.
+ */
+export function findOutputConflicts(
+  scan: TadaProjectScan,
+  siteVariables: SiteVariables,
+  generatedOutputs: ReadonlyMap<string, OutputContent>,
+  records: ReadonlyMap<string, TadaSourceRecord>,
+): BuildDiagnostic[] {
+  const searchEnabled = isFeatureEnabled(siteVariables, 'search');
+  const messages = new Set<string>();
+  // Output path to the project-relative source that writes it (null for Tada)
+  // and the content it writes.
+  const owners = new Map<
+    string,
+    { source: string | null; content: OutputContent }
+  >(
+    [...generatedOutputs].map(([outputPath, content]) => [
+      outputPath,
+      { source: null, content },
+    ]),
+  );
+  for (const record of records.values()) {
+    const source = projectRelative(scan, record.sourcePath);
+    for (const [outputPath, content] of record.outputs) {
+      const existing = owners.get(outputPath);
+      if (existing?.source === null) {
+        messages.add(
+          `${source}: conflicts with ${outputPath} generated by Tada`,
+        );
+      } else if (
+        searchEnabled &&
+        (outputPath === SEARCH_INDEX_DIR ||
+          outputPath.startsWith(`${SEARCH_INDEX_DIR}/`))
+      ) {
+        messages.add(
+          `${source}: conflicts with the search index in ${SEARCH_INDEX_DIR}/`,
+        );
+      } else if (!existing) {
+        owners.set(outputPath, { source, content });
+      } else if (
+        existing.source !== source &&
+        !sameOutputContent(existing.content, content)
+      ) {
+        // Pages that trace the same files share identical trace outputs.
+        messages.add(
+          `${[existing.source, source].sort().join(', ')}: both write ${outputPath}`,
+        );
+      }
+    }
+  }
+  for (const [outputPath, { source: owner }] of owners) {
+    const segments = outputPath.split('/');
+    for (let i = 1; i < segments.length; i++) {
+      const ancestor = segments.slice(0, i).join('/');
+      if (!owners.has(ancestor)) {
+        continue;
+      }
+      const ancestorOwner = owners.get(ancestor)!.source;
+      if (ancestorOwner === null) {
+        messages.add(`${owner}: conflicts with ${ancestor} generated by Tada`);
+      } else if (owner === null) {
+        messages.add(
+          `${ancestorOwner}: conflicts with ${ancestor}/ generated by Tada`,
+        );
+      } else {
+        messages.add(
+          `${[ancestorOwner, owner].sort().join(', ')}: ${ancestor} is both a file and a directory`,
+        );
+      }
+    }
+  }
+  return diagnosticsFromMessages([...messages]);
+}
+
+export function validateProjectConfigLinks(
+  validTargets: ReadonlySet<string>,
+): BuildDiagnostic[] {
+  return diagnosticsFromMessages(
+    validateConfigLinks(validTargets, config('nav'), config('authors'), {
+      navFileName: getConfigFileName('nav'),
+      authorsFileName: getConfigFileName('authors'),
+    }),
+  );
+}