@abreen/tada 1.18.0 → 1.18.2

package/README.md

@@ -383,7 +383,7 @@ list of variables parsed using the [`front-matter`][front-matter] library).
 | `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 |
+| `breadcrumbs` | Ordered ancestor links with `label` and `url`; the page title completes the trail |
 | `published` | Year, month, and day of publishing (e.g, `2025-09-09`) |
 
 You may also add arbitrary fields in a page's front matter, and access them

package/assets/material-symbols/chevron_right_24px.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 -960 960 960" width="24"><path d="M504-480 320-664l56-56 240 240-240 240-56-56 184-184Z"/></svg>

package/build/material-symbols.ts

@@ -48,10 +48,13 @@ export const MATERIAL_SYMBOLS = Object.freeze({
     symbol: 'warning',
     opticalSize: 20,
   }),
-  parent: Object.freeze({
-    cssVariable: '--icon-parent',
-    symbol: 'south_east',
-    opticalSize: 20,
+  breadcrumbSeparator: Object.freeze({
+    cssVariable: '--icon-breadcrumb-separator',
+    symbol: 'chevron_right',
+    opticalSize: 24,
+    // The authored selection differs from the shared weight/grade defaults.
+    weight: 400,
+    grade: 0,
   }),
   search: Object.freeze({
     cssVariable: '--icon-search',

package/build/types.d.ts

@@ -1,6 +1,12 @@
 import type { BundledLanguage } from 'shiki';
 import type { TraceCache } from './build-types';
 
+/** An explicitly authored ancestor in a page's breadcrumb trail. */
+export interface BreadcrumbEntry {
+  label: string;
+  url: string;
+}
+
 export type PlainTextLanguage = 'text' | 'txt' | 'plain';
 
 export interface SerifFontTuning {

package/build/utils/render.ts

@@ -15,8 +15,8 @@ import {
   getSupportedConfigFileNamesText,
 } from '../config-files';
 import {
-  resolveParentLinkTarget,
-  validateParentLink,
+  resolveBreadcrumbLinkTarget,
+  validateBreadcrumbs,
 } from '../validate-config-links';
 import {
   extractJavaMethodToc,
@@ -66,8 +66,8 @@ export { stripHtmlComments } from './html-comments';
 
 const REQUIRED_FRONT_MATTER_FIELDS = ['title'];
 
-// Page variables that renderers assign themselves. Front matter that sets one
-// would be overwritten or, for `template`, select a nonexistent template.
+// Internal page variables and retired front matter keys. Internal values would
+// be overwritten or, for `template`, select a nonexistent template.
 const RESERVED_FRONT_MATTER_KEYS: readonly string[] = [
   'template',
   'titleHtml',
@@ -77,6 +77,8 @@ const RESERVED_FRONT_MATTER_KEYS: readonly string[] = [
   'codeFilePath',
   'downloadName',
   'filePath',
+  'parent',
+  'parentLabel',
 ];
 
 function renderInlineField(
@@ -456,7 +458,7 @@ interface PreparePageVariablesInput {
  * Turns parsed front matter into page variables. Shared by every renderer
  * whose source has front matter, so each one applies the same rules:
  * Lodash processing of string values, inline Markdown for the title and
- * description, required fields, author lookup, and parent link validation.
+ * description, required fields, author lookup, and breadcrumb validation.
  */
 function preparePageVariables({
   rawPageVariables,
@@ -484,12 +486,29 @@ function preparePageVariables({
     subPath,
     isWatchMode,
   });
+  const templateString = (value: unknown): unknown =>
+    typeof value === 'string' ? compileTemplate(value)(siteOnlyParams) : value;
   const pageVariables: Record<string, unknown> = Object.fromEntries(
-    Object.entries(rawPageVariables).map(([k, v]) => [
-      k,
-      typeof v === 'string' ? compileTemplate(v)(siteOnlyParams) : v,
+    Object.entries(rawPageVariables).map(([key, value]) => [
+      key,
+      templateString(value),
     ]),
   );
+  if (Array.isArray(pageVariables.breadcrumbs)) {
+    pageVariables.breadcrumbs = pageVariables.breadcrumbs.map(
+      (entry: unknown) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+          return entry;
+        }
+        const breadcrumb = entry as Record<string, unknown>;
+        return {
+          ...breadcrumb,
+          label: templateString(breadcrumb.label),
+          url: templateString(breadcrumb.url),
+        };
+      },
+    );
+  }
 
   // Render title and description as inline Markdown
   const frontMatterMd = createMarkdown(siteVariables, {
@@ -502,21 +521,21 @@ function preparePageVariables({
   validateFrontMatter(pageVariables, filePath);
   resolveAuthor(pageVariables, filePath, dependencyCollector);
 
-  const parentError = validateParentLink(
-    pageVariables.parent,
+  const breadcrumbs = pageVariables.breadcrumbs;
+  validateBreadcrumbs(
+    breadcrumbs,
     filePath,
     validInternalTargets,
     sourceUrlPath,
   );
-  if (parentError) {
-    throw new Error(parentError);
-  }
-  const resolvedParentTarget = resolveParentLinkTarget(
-    pageVariables.parent,
-    sourceUrlPath,
-  );
-  if (resolvedParentTarget) {
-    dependencyCollector?.internalTargets?.add(resolvedParentTarget);
+  for (const entry of breadcrumbs ?? []) {
+    const resolvedTarget = resolveBreadcrumbLinkTarget(
+      entry.url,
+      sourceUrlPath,
+    );
+    if (resolvedTarget) {
+      dependencyCollector?.internalTargets?.add(resolvedTarget);
+    }
   }
 
   return pageVariables;

package/build/validate-config-links.ts

@@ -1,4 +1,5 @@
 import path from 'path';
+import type { BreadcrumbEntry } from './types';
 import { encodeAuthoredUrl } from './template-globals';
 import { normalizeOutputPath } from './utils/paths';
 
@@ -208,47 +209,86 @@ function splitHref(href: string): { pathname: string; suffix: string } {
   return { pathname: match ? match[1] : href, suffix: match ? match[2] : '' };
 }
 
-export function validateParentLink(
-  parent: unknown,
+export function validateBreadcrumbs(
+  breadcrumbs: unknown,
   filePath: string,
   validTargets: ReadonlySet<string>,
   sourceUrlPath: string,
-): string | null {
-  if (typeof parent === 'string' && splitHref(parent).pathname === '') {
-    return `${filePath}: broken parent link: "${parent}"`;
+): asserts breadcrumbs is BreadcrumbEntry[] | undefined {
+  if (breadcrumbs === undefined) {
+    return;
+  }
+  if (!Array.isArray(breadcrumbs)) {
+    throw new Error(`${filePath}: breadcrumbs must be a list`);
   }
+  breadcrumbs.forEach((entry: unknown, index) => {
+    const context = `${filePath}: breadcrumb entry ${index + 1}`;
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      throw new Error(`${context} must be an object with label and url fields`);
+    }
+    const { label, url } = entry as Record<string, unknown>;
+    for (const [field, value] of Object.entries({ label, url })) {
+      if (typeof value !== 'string' || !value.trim()) {
+        throw new Error(`${context}: ${field} must be a nonempty string`);
+      }
+    }
+    const error = validateBreadcrumbLink(
+      url as string,
+      filePath,
+      validTargets,
+      sourceUrlPath,
+      index + 1,
+    );
+    if (error) {
+      throw new Error(error);
+    }
+  });
+}
 
-  const resolvedTarget = resolveParentLinkTarget(parent, sourceUrlPath);
+export function validateBreadcrumbLink(
+  url: string,
+  filePath: string,
+  validTargets: ReadonlySet<string>,
+  sourceUrlPath: string,
+  entryNumber = 1,
+): string | null {
+  const context = `${filePath}: breadcrumb entry ${entryNumber}`;
+  const resolvedTarget = resolveBreadcrumbLinkTarget(url, sourceUrlPath);
   if (!resolvedTarget) {
-    return null;
+    return `${context}: broken breadcrumb link: "${url}" (must be an internal site link with a pathname)`;
   }
 
   const directoryError = validateDirectoryLink(
-    parent as string,
+    url,
     resolvedTarget,
     validTargets,
-    `${filePath}: parent link`,
+    context,
   );
   if (directoryError) {
     return directoryError;
   }
 
   if (!validTargets.has(resolvedTarget)) {
-    return `${filePath}: broken parent link: "${parent}"`;
+    return `${context}: broken breadcrumb link: "${url}"`;
   }
 
   return null;
 }
 
-export function resolveParentLinkTarget(
-  parent: unknown,
+export function resolveBreadcrumbLinkTarget(
+  url: string,
   sourceUrlPath: string,
 ): string | null {
-  if (!parent || typeof parent !== 'string') {
+  // Breadcrumbs always point into this site. Backslashes also have special
+  // URL semantics in browsers, so they cannot be used as path separators.
+  if (
+    /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(url) ||
+    url.startsWith('//') ||
+    url.includes('\\')
+  ) {
     return null;
   }
-
-  const { pathname } = splitHref(parent);
+  const { pathname } = splitHref(url);
   if (!pathname) {
     return null;
   }

package/init/content/labs/00/VowelCounter.java.md

@@ -1,6 +1,9 @@
 ---
-parent: /labs/00/index.html
-parentLabel: Lab 0
+breadcrumbs:
+  - label: Labs
+    url: /labs/index.html
+  - label: Lab 0
+    url: /labs/00/index.html
 title: Counting vowels
 author: alex
 description: An example of a literate Java program that takes predefined input.
@@ -15,7 +18,7 @@ The <dfn>standard in</dfn> (or `stdin`) is one of three streams available to a
 running program. The other two streams are the standard out and standard error.
 
 <figure>
-<svg viewBox="0 50 410 90" xmlns="http://www.w3.org/2000/svg" font-size="14" fill="none" style="margin:1rem auto;display:block;max-width:410px">
+<svg viewBox="15 50 380 90" xmlns="http://www.w3.org/2000/svg" font-size="14" fill="none" style="margin:1rem auto;display:block;max-width:380px">
   <defs>
     <marker id="arrow" markerWidth="8" markerHeight="8" refX="8" refY="4" orient="auto">
       <path d="M0,0 L8,4 L0,8 Z" stroke="currentColor" fill="currentColor"></path>

package/init/content/labs/00/index.md

@@ -1,6 +1,7 @@
 ---
-parent: /labs/index.html
-parentLabel: Labs
+breadcrumbs:
+  - label: Labs
+    url: /labs/index.html
 title: Lab 0
 author: alex
 description: An example lab page for <%= site.title %>.

package/init/content/labs/01/index.md

@@ -1,6 +1,7 @@
 ---
-parent: /labs/index.html
-parentLabel: Labs
+breadcrumbs:
+  - label: Labs
+    url: /labs/index.html
 title: Lab 1
 author: alex
 description: A lab page for <%= site.title %> demonstrating the trace feature.

package/init/content/labs/02/index.md

@@ -1,6 +1,7 @@
 ---
-parent: ../index.html
-parentLabel: Labs
+breadcrumbs:
+  - label: Labs
+    url: ../index.html
 title: Lab 2
 author: alex
 description: A page demonstrating slides mode.

package/init/content/lectures/01/index.md

@@ -1,6 +1,7 @@
 ---
-parentLabel: Lectures
-parent: /lectures/index.html
+breadcrumbs:
+  - label: Lectures
+    url: /lectures/index.html
 title: Lecture 1
 description: An example lecture page.
 author: alex

package/init/content/lectures/02/index.md

@@ -1,6 +1,7 @@
 ---
-parentLabel: Lectures
-parent: /lectures/index.html
+breadcrumbs:
+  - label: Lectures
+    url: /lectures/index.html
 title: Lecture 2
 description: An example lecture page demonstrating partials.
 author: alex

package/package.json

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

package/src/_content.scss

@@ -364,18 +364,34 @@ dfn {
   color: var(--theme-color-text);
 }
 
-a.breadcrumb {
-  @include user-select(none);
-  @include subdued-link;
+.breadcrumbs {
+  ol {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.25em;
+    padding: 0;
+    margin: 0;
+    list-style: none;
+  }
+
+  li {
+    display: flex;
+    gap: 0.25em;
+    align-items: center;
+    min-width: 0;
+    overflow-wrap: anywhere;
+  }
 
-  &::after {
-    display: inline-block;
-    width: var(--icon-parent-size);
-    height: var(--icon-parent-size);
-    vertical-align: middle;
-    content: '';
+  a {
+    @include subdued-link;
+  }
+
+  [aria-current='page'] {
+    font-style: italic;
+  }
 
-    @include contained-mask(var(--icon-parent));
+  .material-symbol-icon {
+    flex-shrink: 0;
   }
 }
 

package/src/_layout.scss

@@ -152,14 +152,16 @@ body.literate main table {
 .info {
   @include user-select(none);
 
-  display: grid;
-  grid-template-columns: 1fr auto;
+  // Flex instead of a `1fr auto` grid: WebKit keeps the auto column's width
+  // after the font changes, which wraps the author avatar onto its own line.
+  display: flex;
   align-items: baseline;
+  justify-content: space-between;
   font-size: var(--font-size-smaller);
   color: var(--fg2-color);
 
   @media (width < 450px) {
-    grid-template-columns: 1fr;
+    flex-direction: column;
   }
 
   aside.author {

package/src/_material-symbols.scss

@@ -22,3 +22,10 @@
   --material-symbol-icon: var(--icon-contrast-high);
   --material-symbol-icon-size: var(--icon-contrast-high-size);
 }
+
+.material-symbol-icon-breadcrumb-separator {
+  --material-symbol-icon: var(--icon-breadcrumb-separator);
+  --material-symbol-icon-size: var(--icon-breadcrumb-separator-size);
+
+  color: var(--fg2-color);
+}

package/src/navigate/_index.scss

@@ -2,6 +2,11 @@ $shift: 8px;
 $duration: 150ms;
 $movement-easing: cubic-bezier(0.2, 0, 0, 1);
 
+:root {
+  --page-transition-duration: #{$duration};
+  --page-transition-movement-easing: #{$movement-easing};
+}
+
 @keyframes page-fade-out {
   to {
     opacity: 0;
@@ -38,19 +43,38 @@ $movement-easing: cubic-bezier(0.2, 0, 0, 1);
   }
 }
 
-// Page heading and info: crossfade in place instead of sliding with the page
+// Page heading parts: crossfade in place instead of sliding with the page
 // view-transition-name is set via inline style by the navigator
-// only when .title-and-info is visible in the viewport
-
+// only when .title-and-info is visible in the viewport. All parts share one
+// duration and easing so they move in step when the layout changes; the
+// crossfades inherit the group timing.
+::view-transition-group(page-breadcrumbs),
+::view-transition-old(page-breadcrumbs),
+::view-transition-new(page-breadcrumbs),
+::view-transition-group(page-title),
 ::view-transition-old(page-title),
 ::view-transition-new(page-title),
+::view-transition-group(page-info),
 ::view-transition-old(page-info),
-::view-transition-new(page-info),
-::view-transition-old(page-breadcrumb),
-::view-transition-new(page-breadcrumb) {
+::view-transition-new(page-info) {
   animation-duration: $duration;
 }
 
+::view-transition-group(page-breadcrumbs),
+::view-transition-group(page-title),
+::view-transition-group(page-info) {
+  animation-timing-function: $movement-easing;
+}
+
+// Breadcrumbs: the whole trail is one group, so every item moves together when
+// the layout changes. The default plus-lighter crossfade keeps unchanged items
+// opaque while added or removed items fade. Snapshots keep their natural size
+// so a change in trail width does not stretch the text.
+::view-transition-old(page-breadcrumbs),
+::view-transition-new(page-breadcrumbs) {
+  inline-size: auto;
+}
+
 // The site-wide banner does not change between pages. Keep it out of the root
 // slide and pin its named transition layer in place without a crossfade.
 .site-banner {

package/src/navigate/runtime.ts

@@ -117,25 +117,28 @@ function dispatchNavigationEvent(
   );
 }
 
-function cleanupViewTransitionNames(document: Document): void {
-  const newH1 = document.querySelector(
-    '.title-and-info h1',
-  ) as HTMLElement | null;
-  const newInfo = document.querySelector(
-    '.title-and-info .info',
-  ) as HTMLElement | null;
-  const newBreadcrumb = document.querySelector(
-    '.title-and-info a.breadcrumb',
-  ) as HTMLElement | null;
-
-  if (newH1) {
-    newH1.style.viewTransitionName = '';
-  }
-  if (newInfo) {
-    newInfo.style.viewTransitionName = '';
+// Heading parts that get their own layer instead of sliding with the page. The
+// breadcrumb trail is one group so every item, including the current one,
+// moves together when the page layout changes.
+const TITLE_TRANSITION_NAMES = [
+  ['nav.breadcrumbs', 'page-breadcrumbs'],
+  ['h1', 'page-title'],
+  ['.info', 'page-info'],
+] as const;
+
+function setTitleTransitionNames(titleEl: Element, enabled: boolean): void {
+  for (const [selector, name] of TITLE_TRANSITION_NAMES) {
+    const element = titleEl.querySelector<HTMLElement>(selector);
+    if (element) {
+      element.style.viewTransitionName = enabled ? name : '';
+    }
   }
-  if (newBreadcrumb) {
-    newBreadcrumb.style.viewTransitionName = '';
+}
+
+function cleanupViewTransitionNames(document: Document): void {
+  const titleEl = document.querySelector('.title-and-info');
+  if (titleEl) {
+    setTitleTransitionNames(titleEl, false);
   }
 }
 
@@ -343,20 +346,7 @@ export async function navigateToUrl(
       titleEl != null && titleEl.getBoundingClientRect().top >= headerHeight;
 
     if (titleVisible) {
-      const h1 = titleEl.querySelector('h1') as HTMLElement | null;
-      const info = titleEl.querySelector('.info') as HTMLElement | null;
-      const breadcrumb = titleEl.querySelector(
-        'a.breadcrumb',
-      ) as HTMLElement | null;
-      if (h1) {
-        h1.style.viewTransitionName = 'page-title';
-      }
-      if (info) {
-        info.style.viewTransitionName = 'page-info';
-      }
-      if (breadcrumb) {
-        breadcrumb.style.viewTransitionName = 'page-breadcrumb';
-      }
+      setTitleTransitionNames(titleEl, true);
     }
 
     document.documentElement.classList.add(
@@ -376,20 +366,7 @@ export async function navigateToUrl(
         newTitleEl.getBoundingClientRect().top >= newHeaderHeight;
 
       if (newTitleVisible && newTitleEl) {
-        const h1 = newTitleEl.querySelector('h1') as HTMLElement | null;
-        const info = newTitleEl.querySelector('.info') as HTMLElement | null;
-        const breadcrumb = newTitleEl.querySelector(
-          'a.breadcrumb',
-        ) as HTMLElement | null;
-        if (h1) {
-          h1.style.viewTransitionName = 'page-title';
-        }
-        if (info) {
-          info.style.viewTransitionName = 'page-info';
-        }
-        if (breadcrumb) {
-          breadcrumb.style.viewTransitionName = 'page-breadcrumb';
-        }
+        setTitleTransitionNames(newTitleEl, true);
       }
     });
 

package/templates/_heading.html

@@ -1,6 +1,19 @@
 <div class="title-and-info" data-pagefind-body>
-  <% if (page.parent) { %>
-  <a class="breadcrumb" href="<%- encodeAuthoredUrl(page.parent) %>" data-pagefind-ignore><%- page.parentLabel %></a>
+  <% if (page.breadcrumbs && page.breadcrumbs.length) { %>
+  <nav class="breadcrumbs" aria-label="Breadcrumb" data-pagefind-ignore>
+    <ol>
+      <% page.breadcrumbs.forEach((entry, index) => { %>
+      <li>
+        <% if (index > 0) { %><span class="material-symbol-icon material-symbol-icon-breadcrumb-separator" aria-hidden="true"></span><% } %>
+        <a href="<%- encodeAuthoredUrl(entry.url) %>"><%- entry.label %></a>
+      </li>
+      <% }); %>
+      <li>
+        <span class="material-symbol-icon material-symbol-icon-breadcrumb-separator" aria-hidden="true"></span>
+        <span aria-current="page"><%- page.title %></span>
+      </li>
+    </ol>
+  </nav>
   <% } %>
   <h1 data-pagefind-weight="10" data-pagefind-meta="title_html[data-title-html]" data-title-html="<%- page.titleHtml %>"><%= page.titleHtml %></h1>
 

package/templates/_theme.scss

@@ -33,8 +33,10 @@
 
   // Main background color (the color of the page background)
   --bg-color: hsl(var(--tint-hue) calc(5% * var(--tint-amount)) 97%);
+
+  // Same saturation as --bg-color, so frosting doesn't add color to the page
   --bg-color-translucent: hsl(
-    var(--tint-hue) calc(30% * var(--tint-amount)) 95% / 66%
+    var(--tint-hue) calc(5% * var(--tint-amount)) 95% / 66%
   );
 
   // Secondary background color (lighter)
@@ -117,7 +119,7 @@
     --link-color-hover: <%= linkColorHoverDark %>;
     --bg-color: hsl(var(--tint-hue) calc(3% * var(--tint-amount)) 5%);
     --bg-color-translucent: hsl(
-      var(--tint-hue) calc(15% * var(--tint-amount)) 10% / 66%
+      var(--tint-hue) calc(3% * var(--tint-amount)) 10% / 66%
     );
     --bg2-color: hsl(var(--tint-hue) calc(12% * var(--tint-amount)) 12%);
     --bg2-color-translucent: hsl(

package/assets/material-symbols/south_east_20px.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" height="20" viewBox="0 -960 960 960" width="20"><path d="M386-224v-58h250.69L200-718.69 241.31-760 678-323.31V-574h58v350H386Z"/></svg>