@abreen/tada 1.18.5 → 1.19.0

package/README.md

@@ -5,37 +5,62 @@
 
 A static site generator. The successor to Presto.
 
+<figure>
+  <a href="https://abreen.io/Tada/markdown.html" target="_blank">
+    <img src=".github/screenshot.png" alt="Four screenshots of the Tada example site">
+  </a>
+  <figcaption>
+    A screenshot of the Tada example site in:
+    <ul>
+      <li>light mode</li>
+      <li>dark mode, high contrast</li>
+      <li>light mode, high contrast, & serif fonts</li>
+      <li>dark mode, standard contrast</li>
+    </ul>
+    </figcaption>
+</figure>
+
+[Visit the example site ↗](https://abreen.io/Tada/index.html)
+
+
 ## Features
 
-- Modern design (light & dark following system, floating header, styled lists)
-- Fast client-side navigation
-- Detects a new version of the current page and allows the user to reload
-- Clickable/linkable landmarks (headings, deflists, alert boxes)
-- Dynamic table of contents
-  * Floats on the side of the screen when window is large enough
-  * Renders headings, alert boxes, and `<hr>` elements
-  * Highlights the heading currently being viewed
+- Modern design
+  * Light & dark mode following system, customizable tint
+  * Standard & high contrast picker
+  * Sans-serif & serif font picker
+  * Plus, provide your own web fonts (with many tuning options)
+
+- LaTeX math support
+  * Provided by [KaTeX][katex]
+  * Rendered completely at build time (zero load time on the client)
+
+- Automatically generated favicon
+  * Text, color, font and font weight taken from config file
+  * Or, provide your own favicon file
+
+- High quality output and ergonomic authoring
+  * Exhaustive internal link validation (broken links fail the build)
+  * External link handling (special visual treatment for external links,
+    no need to type `target="_blank"`)
+  * Internal links automatically prefixed with base path, if specified (no
+    need to keep writing the same URL prefix everywhere)
+
 - Built-in search powered by [Pagefind][pagefind]
   * Only pages in `content/` reachable from `/index.html` are indexed
+  * If `mutool` is installed, text inside PDFs in `content/` is indexed
+
 - Generated HTML pages for source code
   * Automatic code highlighting, clickable line numbers
   * Dynamic table of contents for each method/function
   * Converts new Markdown comment syntax ([added in Java 23][jep467]) to HTML
   * Indexed by Pagefind (classes, interfaces, methods, and fields)
-- 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
-  * Click icon near slide titles to start presenting at that slide
-  * Right-click in presentation mode to annotate
-  * Hold Shift while annotating to erase
-- 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)
-- Internal link validation at build time (broken links fail the build)
-- Internal links automatically prefixed with base path, if specified
-- Time zone chooser (automatically adjusts `<datetime>` elements)
-- LaTeX math rendered at build time via [KaTeX][katex]
+
+- Dynamic table of contents
+  * Floats on the side of the screen when window is large enough
+  * Renders headings, alert boxes, and `<hr>` elements
+  * Highlights the heading currently being viewed
+
 - Extended Markdown syntax
   * `<<< details ... <<<` renders a collapsible box
   * `::: section ... :::` renders a special section with a fancy background
@@ -45,9 +70,26 @@ 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
-- 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
+
+- Extremely fast client-side navigation
+  * A miniature SPA without the bloat of a framework
+  * Highly efficient, thoroughly covered by cross-platform browser tests
+  * Also detects a new version of the current page and supplies a reload button
+
+### Experimental features
+
+- 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
+  * Click icon near slide titles to start presenting at that slide
+  * Right-click in presentation mode to annotate
+  * Hold Shift while annotating to erase
+
+
+
+- Time zone chooser (automatically adjusts `<datetime>` elements)
 
 ## Prerequisites
 
@@ -107,9 +149,11 @@ Visit [http://localhost:8080/index.html](http://localhost:8080/index.html).
 
 Create a new Tada site in a new directory. Prompts for:
 - **Site title**: displayed in the header and `<title>` tag
-- **Symbol**: short text (1-5 uppercase characters) shown in the logo and favicon
-- **Theme color**: HSL color, e.g. `hsl(195 70% 40%)`
-- **Background tint hue**: hue (0-360) for background/foreground tinting (defaults to `33`)
+- **Symbol**: short text (1-5 uppercase characters) shown in the logo and favicon,
+  or a single emoji shown in the logo (defaults to 🎉; emoji symbols turn off
+  generated favicons)
+- **Theme color**: CSS color, e.g. `hsl(195 70% 40%)` (defaults to `darkturquoise`)
+- **Background tint hue**: hue (0-360) for background/foreground tinting (defaults to `190`)
 - **Background tint amount**: percentage (0-100) of tint to apply (defaults to `100`)
 - **Default time zone**: for `<time>` elements (defaults to your system zone)
 - **Production base URL**: e.g. `https://example.edu`
@@ -268,16 +312,16 @@ 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 when `logo` is absent; also used for generated favicons |
+| `symbol` | Text (1-5 chars) or a single emoji 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 `33`) |
+| `tintHue` | *Optional*, hue (0-360) for background and foreground tinting (default `190`) |
 | `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 generated favicons |
+| `faviconSymbol` | *Optional*, the text to use instead of `symbol` in generated favicons; required when `symbol` is an emoji and favicons are generated |
 | `features.search` | Enable search UI and Pagefind index generation |
 | `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 |

package/bin/tada.ts

@@ -27,6 +27,7 @@ import {
   resolveSiteConfigFile,
   type SiteEnv,
 } from '../build/config-files';
+import { isEmojiSymbol } from '../build/utils/symbol';
 
 const { version } = packageJson;
 
@@ -75,22 +76,22 @@ interface InitQuestion {
 const INIT_QUESTIONS: Record<string, InitQuestion> = {
   title: {
     prompt: 'Site title',
-    defaultValue: 'Introduction to Computer Science',
+    defaultValue: 'Tada',
     validate: (v: string) => (v ? null : 'Title is required'),
   },
   symbol: {
-    prompt: 'Logo symbol (1-5 uppercase chars)',
-    defaultValue: 'CS 0',
+    prompt: 'Logo symbol (1-5 uppercase chars or one emoji)',
+    defaultValue: '🎉',
     validate: validateSymbol,
   },
   themeColor: {
     prompt: 'Theme color',
-    defaultValue: 'hsl(195 70% 40%)',
+    defaultValue: 'darkturquoise',
     validate: validateColor,
   },
   tintHue: {
     prompt: 'Background tint hue (0-360)',
-    defaultValue: '33',
+    defaultValue: '190',
     validate: validateHue,
   },
   tintAmount: {
@@ -338,6 +339,14 @@ async function initCommand(args: string[]): Promise<void> {
   // Create project directory
   fs.mkdirSync(projectDir);
 
+  // Generated favicons are text-only, so an emoji symbol starts without them
+  const features = {
+    search: true,
+    favicon: !isEmojiSymbol(symbol),
+    footer: true,
+    pickers: true,
+  };
+
   // Generate site configs
   const devConfig = createSiteConfig({
     title,
@@ -349,7 +358,7 @@ async function initCommand(args: string[]): Promise<void> {
     base: 'http://localhost:8080',
     basePath: '/',
     internalDomains: ['localhost'],
-    features: { search: true, favicon: false, footer: true, pickers: true },
+    features,
     extensionToShikiLanguage: bare ? {} : { java: 'java', py: 'python' },
     shikiLanguages: bare ? [] : ['java', 'python', 'html'],
   });
@@ -364,7 +373,7 @@ async function initCommand(args: string[]): Promise<void> {
     base: prodBase,
     basePath: prodBasePath,
     internalDomains: [prodDomain],
-    features: { search: true, favicon: true, footer: true, pickers: true },
+    features,
     extensionToShikiLanguage: bare ? {} : { java: 'java', py: 'python' },
     shikiLanguages: bare ? [] : ['java', 'python', 'html'],
   });

package/bin/validators.ts

@@ -1,5 +1,6 @@
 import timezones from '../src/timezone/timezones.json' with { type: 'json' };
 import type { SiteConfigInput, SiteVariables } from '../build/types';
+import { isValidSymbol } from '../build/utils/symbol';
 
 const SUPPORTED_TIME_ZONES: readonly string[] = timezones.map(tz => tz.value);
 const FALLBACK_TIME_ZONE = 'UTC';
@@ -8,13 +9,13 @@ export function validateSymbol(value: string): string | null {
   if (!value) {
     return 'Symbol is required';
   }
-  if (value.length > 5) {
-    return 'Symbol must be 5 characters or fewer';
+  if (isValidSymbol(value)) {
+    return null;
   }
-  if (!/^[A-Z0-9\- ]{1,5}$/.test(value)) {
-    return 'Symbol must contain only uppercase letters, digits, hyphens, and spaces';
+  if (value.length > 5) {
+    return 'Symbol must be 5 characters or fewer, or a single emoji';
   }
-  return null;
+  return 'Symbol must contain only uppercase letters, digits, hyphens, and spaces, or be a single emoji';
 }
 
 export function validateColor(value: string): string | null {

package/build/bundle.ts

@@ -51,7 +51,7 @@ function renderThemeScss(siteVariables: SiteVariables): string {
   const templatePath = path.join(getPackageDir(), 'templates/_theme.scss');
   const template = fs.readFileSync(templatePath, 'utf-8');
   const theme = deriveTheme(siteVariables.themeColor);
-  const tintHue = siteVariables.tintHue ?? 33;
+  const tintHue = siteVariables.tintHue ?? 190;
   const tintAmount = siteVariables.tintAmount ?? 100;
 
   const linkHue = formatCssNumber(deriveLinkHue(tintHue));

package/build/config-loader.ts

@@ -29,6 +29,14 @@ export function parseConfigText(text: string, fileName: string): unknown {
   try {
     return Bun.YAML.parse(text);
   } catch (error) {
+    // YAML rejects JSON surrogate pair escapes such as emoji in `\ud83c\udf89` form
+    if (fileName.endsWith('.json')) {
+      try {
+        return JSON.parse(text);
+      } catch {
+        // Report the YAML error, as for any other config
+      }
+    }
     const message = error instanceof Error ? error.message : String(error);
     throw new Error(`${fileName}: ${message}`, { cause: error });
   }

package/build/site-variables.ts

@@ -4,6 +4,7 @@ import type { SiteEnv } from './config-files';
 import { loadSiteConfig } from './config-loader';
 import { compile as compileJsonSchema, doValidation } from './json-schema';
 import { getProjectDir } from './utils/paths';
+import { isEmojiSymbol } from './utils/symbol';
 import type { PlainTextLanguage, SiteVariables } from './types';
 import siteSchema from '../schema/site.schema.json' with { type: 'json' };
 import timezones from '../src/timezone/timezones.json' with { type: 'json' };
@@ -131,10 +132,7 @@ function getSiteVariables(env: SiteEnv): SiteVariables {
     },
   } as SiteVariables;
 
-  // Derive faviconSymbol from symbol if not explicitly set
-  if (variables.symbol && !variables.faviconSymbol) {
-    variables.faviconSymbol = variables.symbol;
-  }
+  resolveFaviconSymbol(variables, fileName);
 
   // Derive faviconColor from themeColor if not explicitly set
   if (!variables.faviconColor) {
@@ -157,6 +155,28 @@ function getSiteVariables(env: SiteEnv): SiteVariables {
   return variables;
 }
 
+/**
+ * Derive faviconSymbol from a text symbol. Generated favicons are drawn with a
+ * text font that has no emoji, so an emoji symbol needs a text faviconSymbol.
+ */
+export function resolveFaviconSymbol(
+  variables: SiteVariables,
+  fileName: string,
+): void {
+  if (!variables.symbol || variables.faviconSymbol) {
+    return;
+  }
+  if (!isEmojiSymbol(variables.symbol)) {
+    variables.faviconSymbol = variables.symbol;
+    return;
+  }
+  if (variables.features.favicon !== false && !variables.favicon) {
+    throw new Error(
+      `${fileName}: faviconSymbol is required when symbol is an emoji and favicons are generated; set faviconSymbol to 1 to 5 uppercase characters, digits, hyphens, or spaces`,
+    );
+  }
+}
+
 export function getDevSiteVariables(): SiteVariables {
   return getSiteVariables('dev');
 }

package/build/template-globals.ts

@@ -1,4 +1,5 @@
 import { encodePublicAssetPath } from './custom-fonts';
+import { isEmojiSymbol } from './utils/symbol';
 import timezones from '../src/timezone/timezones.json' with { type: 'json' };
 import type { SiteVariables } from './types';
 
@@ -26,6 +27,7 @@ interface TemplateGlobals {
   cx: (obj: Record<string, unknown>) => string;
   encodeAuthoredUrl: (value: string) => string;
   encodePublicAssetPath: (value: string) => string;
+  isEmojiSymbol: (value: string | null | undefined) => boolean;
   renderTimeZoneChooser: () => string;
 }
 
@@ -56,6 +58,7 @@ export default function createTemplateGlobals(
     cx: classNames,
     encodeAuthoredUrl,
     encodePublicAssetPath,
+    isEmojiSymbol,
     renderTimeZoneChooser,
   };
 }

package/build/utils/symbol.ts

@@ -0,0 +1,21 @@
+// One emoji: a flag, keycap, subdivision flag, or pictograph with optional
+// skin tone and ZWJ joins. Written for the `u` flag so the site schema (Ajv)
+// can share it; `\p{RGI_Emoji}` needs the `v` flag.
+const EMOJI = String.raw`\p{RI}\p{RI}|[#*0-9]\uFE0F\u20E3|\u{1F3F4}[\u{E0061}-\u{E007A}]+\u{E007F}|(?!\p{RI})(?:\p{Emoji_Presentation}|\p{Extended_Pictographic}\uFE0F)\p{Emoji_Modifier}?(?:\u200D(?:\p{Emoji_Presentation}|\p{Extended_Pictographic}\uFE0F?)\p{Emoji_Modifier}?)*`;
+
+/** Must match `faviconSymbol` in `schema/site.schema.json` */
+export const TEXT_SYMBOL_PATTERN = '^[A-Z0-9\\- ]{1,5}$';
+
+/** Must match `symbol` in `schema/site.schema.json` */
+export const SYMBOL_PATTERN = `^(?:[A-Z0-9\\- ]{1,5}|${EMOJI})$`;
+
+const SYMBOL_RE = new RegExp(SYMBOL_PATTERN, 'u');
+const EMOJI_RE = new RegExp(`^(?:${EMOJI})$`, 'u');
+
+export function isValidSymbol(value: string): boolean {
+  return SYMBOL_RE.test(value);
+}
+
+export function isEmojiSymbol(value: string | null | undefined): boolean {
+  return value != null && EMOJI_RE.test(value);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abreen/tada",
-  "version": "1.18.5",
+  "version": "1.19.0",
   "type": "module",
   "description": "A static site generator",
   "license": "MIT",

package/schema/site.schema.json

@@ -31,14 +31,17 @@
     },
     "title": { "type": "string" },
     "banner": { "type": "string" },
-    "symbol": { "type": "string", "pattern": "^[A-Z0-9\\- ]{1,5}$" },
+    "symbol": {
+      "type": "string",
+      "pattern": "^(?:[A-Z0-9\\- ]{1,5}|\\p{RI}\\p{RI}|[#*0-9]\\uFE0F\\u20E3|\\u{1F3F4}[\\u{E0061}-\\u{E007A}]+\\u{E007F}|(?!\\p{RI})(?:\\p{Emoji_Presentation}|\\p{Extended_Pictographic}\\uFE0F)\\p{Emoji_Modifier}?(?:\\u200D(?:\\p{Emoji_Presentation}|\\p{Extended_Pictographic}\\uFE0F?)\\p{Emoji_Modifier}?)*)$"
+    },
     "titlePostfix": { "type": "string" },
     "themeColor": { "type": "string" },
     "tintHue": {
       "type": "integer",
       "minimum": 0,
       "maximum": 360,
-      "default": 33
+      "default": 190
     },
     "tintAmount": {
       "type": "integer",

package/src/_content.scss

@@ -184,7 +184,7 @@ button.icon-button:focus {
 
 ol.styled-list,
 ul.styled-list {
-  font-weight: 700;
+  font-weight: 600;
   color: var(--theme-color-text);
 }
 

package/src/_icons.scss

@@ -65,7 +65,7 @@
   @include define-icon(
     'heading-present',
     24,
-    "<rect x='3.25' y='5.25' width='17.5' height='13.5' rx='2.25'/><path d='M10.25 9.25v5.5L14.75 12z' fill='black'/>"
+    "<rect x='4' y='5' width='16' height='11' rx='1'/><path d='M12 16v4M9 20h6'/>"
   );
   @include define-icon(
     'check',

package/src/_layout.scss

@@ -220,6 +220,7 @@ body.literate main table {
 footer {
   @include user-select(none);
 
+  font-size: var(--font-size-smaller);
   color: var(--fg2-color);
   text-align: center;
 

package/src/header/_index.scss

@@ -184,6 +184,17 @@ header summary .logo {
   background: var(--theme-color);
 }
 
+// A single emoji is the logo itself: no badge, sized like an image logo
+header summary .logo-emoji {
+  padding: 0;
+  font-family:
+    'Apple Color Emoji', 'Segoe UI Emoji', 'Noto Color Emoji', sans-serif;
+  font-size: 22px;
+  font-weight: normal;
+  line-height: 24px;
+  background: none;
+}
+
 header summary .logo-image {
   flex: 0 0 auto;
   width: auto;

package/src/question/_index.scss

@@ -21,7 +21,7 @@
 .question-a-label {
   flex: 0 0 var(--question-label-width);
   margin: 0;
-  font-weight: 700;
+  font-weight: 600;
   color: var(--theme-color-text);
 
   @include user-select(none);

package/templates/_top.html

@@ -23,7 +23,7 @@
     <link rel="apple-touch-icon" sizes="512x512" href="/favicon-512.png" />
     <link rel="apple-touch-icon" sizes="256x256" href="/favicon-256.png" />
     <link rel="manifest" href="/manifest.json" />
-    <meta name="apple-mobile-web-app-title" content="<%- site.symbol %>">
+    <meta name="apple-mobile-web-app-title" content="<%- site.title %>">
     <meta name="mobile-web-app-capable" content="yes">
     <% } %>
     <% } %>
@@ -219,7 +219,7 @@
             <path class="menu-icon-line menu-icon-line-middle" d="M3 12h18" />
             <path class="menu-icon-line menu-icon-line-bottom" d="M3 18h18" />
           </svg>
-          <% if (site.logo) { %><img class="logo-image" src="/<%- encodePublicAssetPath(site.logo) %>" alt="" aria-hidden="true" /><% } else if (site.symbol) { %><span class="logo" aria-hidden="true"><%- site.symbol %></span><% } %>
+          <% if (site.logo) { %><img class="logo-image" src="/<%- encodePublicAssetPath(site.logo) %>" alt="" aria-hidden="true" /><% } else if (site.symbol) { %><span class="<%- isEmojiSymbol(site.symbol) ? 'logo logo-emoji' : 'logo' %>" aria-hidden="true"><%- site.symbol %></span><% } %>
           <span class="header-title" aria-hidden="true">
             <span class="header-title-reel">
               <span class="site-title"><%- site.title %></span>