@docpensieve/core 0.3.0-beta.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docpensieve/core",
-  "version": "0.3.0-beta.1",
+  "version": "0.3.0",
   "description": "DocPensieve engine: loading, MDX compilation, structured data, site generation",
   "type": "module",
   "license": "MIT",
@@ -21,7 +21,7 @@
     "types"
   ],
   "dependencies": {
-    "@docpensieve/shared": "0.3.0-beta.1",
+    "@docpensieve/shared": "0.3.0",
     "@mdx-js/mdx": "^3.1.1",
     "@shikijs/rehype": "^4.4.3",
     "gray-matter": "^4.0.3",

package/src/authors.js

@@ -0,0 +1,175 @@
+/**
+ * The byline of a page: who wrote it, and when it was written or last changed.
+ *
+ * The frontmatter names the authors; a JSON file of the version describes
+ * them. The split matters: a name repeated on forty pages would carry its
+ * biography forty times, and correcting it would mean forty edits.
+ *
+ * This module reads no file. The generator hands it the parsed description,
+ * as it does for the menu: without that, the engine could not be tested
+ * without a disk.
+ *
+ * @module @docpensieve/core/authors
+ */
+
+import { ConfigError } from '@docpensieve/shared';
+
+/**
+ * @typedef {object} Author
+ * @property {string} key    Key used by the frontmatter.
+ * @property {string} name   Name shown to the reader.
+ * @property {string} [bio]  One or two sentences, shown under the name.
+ * @property {string} [avatar] Image path, relative to the version's folder.
+ * @property {string} [url]  Personal site or profile.
+ */
+
+/**
+ * @typedef {object} Byline
+ * @property {Author[]} authors
+ * @property {{ iso: string, label: string } | null} created
+ * @property {{ iso: string, label: string } | null} updated
+ */
+
+/** Fields an author may declare, so that a typo is caught rather than ignored. */
+const AUTHOR_FIELDS = new Set(['name', 'bio', 'avatar', 'url']);
+
+/**
+ * Reads a date of the frontmatter, and gives it in both forms: the machine one
+ * for `<time datetime>`, the readable one for the reader.
+ *
+ * A date is often written unquoted in YAML, which parses it as a Date; quoted,
+ * it arrives as text. Both are accepted, anything unreadable is refused rather
+ * than shown as `Invalid Date`.
+ *
+ * @param {unknown} value
+ * @param {string} field Name of the field, for the error message.
+ * @param {string} where Page the date comes from.
+ * @returns {{ iso: string, label: string } | null} `null` when absent.
+ * @throws {ConfigError} When the value is not a date.
+ */
+export function readDate(value, field, where) {
+  if (value === undefined || value === null || value === '') return null;
+
+  const date = value instanceof Date ? value : new Date(String(value));
+  if (Number.isNaN(date.getTime())) {
+    throw new ConfigError(`Invalid ${field} in ${where}: "${String(value)}".`, {
+      hint: `Write a date as ${field}: 2026-09-16, which is read the same way everywhere.`,
+    });
+  }
+
+  return {
+    iso: date.toISOString().slice(0, 10),
+    // Fixed locale: the page is built once and read everywhere, so the label
+    // must not depend on the machine that produced it. Day first, month
+    // spelled out — "16 September 2026" is read the same way everywhere,
+    // where 09/16 and 16/09 are the same page read two ways.
+    label: new Intl.DateTimeFormat('en-GB', {
+      day: 'numeric',
+      month: 'long',
+      year: 'numeric',
+      timeZone: 'UTC',
+    }).format(date),
+  };
+}
+
+/**
+ * Turns the JSON description of a version into a table of authors.
+ *
+ * @param {unknown} description Parsed content of the file.
+ * @param {{ source: string }} options `source` names the file in errors.
+ * @returns {Map<string, Author>}
+ * @throws {ConfigError} When the shape is wrong, naming the offending entry.
+ */
+export function buildAuthorTable(description, { source }) {
+  if (description === null || typeof description !== 'object' || Array.isArray(description)) {
+    throw new ConfigError(`${source} must describe authors as an object.`, {
+      hint: 'Write { "ada": { "name": "Ada Lovelace", "bio": "…" } }, one entry per author.',
+    });
+  }
+
+  /** @type {Map<string, Author>} */
+  const table = new Map();
+
+  for (const [key, value] of Object.entries(/** @type {Record<string, unknown>} */ (description))) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+      throw new ConfigError(`Author "${key}" of ${source} must be an object.`, {
+        hint: `Write "${key}": { "name": "…" } — the name is the only required field.`,
+      });
+    }
+
+    const entry = /** @type {Record<string, unknown>} */ (value);
+
+    for (const field of Object.keys(entry)) {
+      if (!AUTHOR_FIELDS.has(field)) {
+        throw new ConfigError(`Author "${key}" of ${source} has an unknown field "${field}".`, {
+          hint: `Known fields: ${[...AUTHOR_FIELDS].join(', ')}. A typo here would be silently ignored.`,
+        });
+      }
+    }
+
+    if (typeof entry.name !== 'string' || entry.name.trim() === '') {
+      throw new ConfigError(`Author "${key}" of ${source} has no name.`, {
+        hint: `Add "name": "…" — it is what the reader sees, the key is only how a page refers to it.`,
+      });
+    }
+
+    for (const field of ['bio', 'avatar', 'url']) {
+      const given = entry[field];
+      if (given !== undefined && (typeof given !== 'string' || given.trim() === '')) {
+        throw new ConfigError(`The ${field} of author "${key}" of ${source} must be text.`, {
+          hint: `Either write "${field}": "…", or leave the field out.`,
+        });
+      }
+    }
+
+    /** @type {Author} */
+    const author = { key, name: entry.name.trim() };
+    if (typeof entry.bio === 'string') author.bio = entry.bio.trim();
+    if (typeof entry.avatar === 'string') author.avatar = entry.avatar.trim();
+    if (typeof entry.url === 'string') author.url = entry.url.trim();
+    table.set(key, author);
+  }
+
+  return table;
+}
+
+/**
+ * The authors of a page, in the order the frontmatter names them.
+ *
+ * A key the table does not describe is not an error: the name is shown as
+ * written. It is what lets a project name its authors before describing them,
+ * and what keeps pages written before the file working.
+ *
+ * @param {unknown} value `authors` from the frontmatter: one name or a list.
+ * @param {Map<string, Author>} [table]
+ * @returns {Author[]}
+ */
+export function resolvePageAuthors(value, table = new Map()) {
+  const list = Array.isArray(value) ? value : value === undefined || value === null ? [] : [value];
+
+  return list
+    .map((entry) => String(entry).trim())
+    .filter(Boolean)
+    .map((key) => table.get(key) ?? { key, name: key });
+}
+
+/**
+ * Assembles what the head of a page shows, or nothing when it has none of it.
+ *
+ * @param {Record<string, any>} frontmatter
+ * @param {Map<string, Author>} [table]
+ * @param {string} [where] Page named in a date error.
+ * @returns {Byline | null}
+ * @throws {ConfigError} When a date cannot be read.
+ */
+export function buildByline(frontmatter, table = new Map(), where = 'this page') {
+  const authors = resolvePageAuthors(frontmatter?.authors, table);
+  const created = readDate(frontmatter?.date, 'date', where);
+  // The same field the sitemap reads for lastmod: one date, one meaning.
+  const updated = readDate(frontmatter?.modified, 'modified', where);
+
+  if (authors.length === 0 && !created && !updated) return null;
+
+  // An update on the day of writing says nothing: it is the same event.
+  return { authors, created, updated: updated && updated.iso !== created?.iso ? updated : null };
+}

package/src/config.js

@@ -38,6 +38,9 @@ import {
  * @property {Version[]} versions At least one.
  * @property {{ framework: string, darkMode?: string, toggle?: boolean, tokens?: Record<string, string>, css?: string, source?: string }} theme
  * @property {string} sidebar     `'auto'`, or the path of a description.
+ * @property {string} [authors]   Path of a JSON describing the authors, read in each version folder.
+ * @property {{ label: string, href: string, version?: string }[]} [headerLinks]
+ *   Links of the header, beside the version switcher.
  * @property {boolean} globalComponents
  * @property {boolean} scrollToTop Back-to-top button on every page.
  * @property {{ enabled: boolean }} jsonld
@@ -70,6 +73,13 @@ export const DEFAULT_CONFIG = Object.freeze({
   // The light / dark switch is on unless the project turns it off (ADR-014).
   theme: { framework: 'tailwind', darkMode: 'class', toggle: true },
   sidebar: 'auto',
+  // No author file by default: a page still shows the names its frontmatter
+  // gives. The file only adds what a name cannot carry — a biography, an
+  // avatar, a link.
+  authors: '',
+  // No link in the header by default: the version switcher and the search
+  // field are there already.
+  headerLinks: [],
   globalComponents: true,
   scrollToTop: true,
   jsonld: { enabled: true },
@@ -240,6 +250,61 @@ export function normalizeConfig(userConfig) {
     }
   }
 
+  // Like the menu, the authors are described in each version's folder: a
+  // biography corrected in the beta must not rewrite a published version.
+  if (config.authors) {
+    const file = typeof config.authors === 'string' ? config.authors : '';
+    if (
+      !file.toLowerCase().endsWith('.json') ||
+      path.isAbsolute(file) ||
+      file.split('/').includes('..')
+    ) {
+      throw new ConfigError(
+        `authors must be a .json file within each version folder: "${String(config.authors)}".`,
+        {
+          hint: "For instance authors: 'authors.json', read as docs/v1.0/authors.json for that version.",
+        },
+      );
+    }
+  }
+
+  // Links of the header: site navigation, not page content. A target starts
+  // from the root of a version, or names another site; a relative one would
+  // change meaning from page to page. A link may name the version it lives in,
+  // so that a section written in one version is reachable from all of them.
+  if (config.headerLinks !== undefined) {
+    if (!Array.isArray(config.headerLinks)) {
+      throw new ConfigError('headerLinks must be a list of links.', {
+        hint: "For instance headerLinks: [{ label: 'Examples', href: '/examples/' }].",
+      });
+    }
+    const slugs = new Set(config.versions.map((version) => version.slug));
+    for (const link of config.headerLinks) {
+      if (!link || typeof link.label !== 'string' || link.label.trim() === '') {
+        throw new ConfigError(`A header link has no label: ${JSON.stringify(link)}.`, {
+          hint: "Write { label: 'Examples', href: '/examples/' }.",
+        });
+      }
+      if (
+        typeof link.href !== 'string' ||
+        !(link.href.startsWith('/') || /^[a-z][a-z0-9+.-]*:/i.test(link.href))
+      ) {
+        throw new ConfigError(
+          `The header link "${link.label}" needs an absolute target: "${String(link.href)}".`,
+          {
+            hint: "Start from the root of the version — '/examples/' — or give a full address.",
+          },
+        );
+      }
+      if (link.version !== undefined && !slugs.has(link.version)) {
+        throw new ConfigError(
+          `The header link "${link.label}" names an unknown version: "${String(link.version)}".`,
+          { hint: `Declared versions: ${[...slugs].join(', ')}.` },
+        );
+      }
+    }
+  }
+
   // siteUrl feeds everything that must be absolute: canonical, JSON-LD.
   // Invalid, it went through here and blew up further on as a raw TypeError,
   // stack included; with an exotic scheme, it built a nonsensical prefix.

package/src/generator.js

@@ -20,10 +20,12 @@ import {
 } from '@docpensieve/shared';
 import Handlebars from 'handlebars';
 
+import { buildAuthorTable, buildByline, readDate } from './authors.js';
 import { Compiler } from './compiler.js';
 import { resolveVersion } from './config.js';
 import { DocLoader } from './loader.js';
 import { buildFeed, buildRobots, buildSitemap } from './discovery.js';
+import { imageSize } from './image-size.js';
 import { minifyCss } from './minify-css.js';
 import { SEARCH_SLUG, htmlToText, searchPageContent } from './search-index.js';
 import { buildSidebar, buildSidebarFromDescription, collectSectionTitles } from './sidebar.js';
@@ -44,6 +46,25 @@ const SEARCH_SCRIPT = 'assets/search.js';
 /** Source of that script, shipped with this package. */
 const CLIENT_SEARCH = fileURLToPath(new URL('../client/search.js', import.meta.url));
 
+/**
+ * Targets a preview keeps as they are: another site, an anchor, a data URI.
+ * Same rule as the compiler and the components apply to a link.
+ */
+const EXTERNAL_PREVIEW = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i;
+
+/**
+ * Tags of a page, as the reader sees them: in the order written, blanks and
+ * repeats dropped. A single tag may be written without brackets, as a single
+ * author may — accepting only a list lost the value without a word.
+ *
+ * @param {unknown} value `tags` from the frontmatter.
+ * @returns {string[]}
+ */
+function pageTags(value) {
+  const list = Array.isArray(value) ? value : value === undefined || value === null ? [] : [value];
+  return [...new Set(list.map((tag) => String(tag).trim()).filter(Boolean))];
+}
+
 /**
  * Where each project image is written in a version, before its extension.
  * @type {Record<'logo' | 'favicon' | 'socialImage', string>}
@@ -153,7 +174,9 @@ export class SiteGenerator {
    *   compiler?: Compiler,
    *   onPage?: (page: {
    *     url: string, dirUrl?: string, basePath: string,
-   *     filepath?: string, sourceDir?: string,
+   *     filepath?: string, sourceDir?: string, slug?: string,
+   *     pages?: { url: string, slug: string, title: string, description?: string,
+   *       preview?: string, modified?: { iso: string, label: string } }[],
    *   }) => void,
    * }} [deps]
    *   Global components and the theme are injected rather than imported:
@@ -217,10 +240,11 @@ export class SiteGenerator {
 
     // 'auto' follows the file tree; otherwise each version describes its menu
     // in a file of its own, since each has its own pages.
-    const sidebar =
+    const described =
       this.config.sidebar && this.config.sidebar !== 'auto'
         ? await this.#describedSidebar(sourceDir, docs, pageUrl, version.folder)
-        : buildSidebar(docs, pageUrl, { brand: this.config.projectName });
+        : null;
+    const sidebar = described ?? buildSidebar(docs, pageUrl, { brand: this.config.projectName });
     const breadcrumbTitles = collectSectionTitles(docs);
     const layout = await this.#loadLayout();
     const classes = this.#classes();
@@ -245,6 +269,21 @@ export class SiteGenerator {
 
     // What every page of the version shares, the search page included.
     const searchUrl = this.config.search !== false ? joinUrl(versionBase, SEARCH_SLUG) : '';
+    // Described once per version, like the menu: the same authors serve every
+    // page, and a biography corrected in one version leaves the others alone.
+    const authors = await this.#readAuthors(sourceDir, version.folder, versionBase);
+
+    // Links of the header, resolved once per version. A link naming a version
+    // leads there from every version: a section written in one version only
+    // stays reachable from the others.
+    const headerLinks = (this.config.headerLinks ?? []).map((link) => ({
+      label: link.label,
+      href: EXTERNAL_PREVIEW.test(link.href)
+        ? link.href
+        : joinUrl(this.config.baseUrl, 'versions', link.version ?? version.slug) +
+          link.href.replace(/^\/+/, ''),
+    }));
+
     const shell = {
       lang: this.config.lang ?? 'en',
       // A fixed scheme is a class on <html>, which the skins and the dark
@@ -268,6 +307,9 @@ export class SiteGenerator {
           ? new URL(images.socialImage, this.config.siteUrl).href
           : '',
       searchUrl,
+      headerLinks,
+      // A menu with nothing in it would be a button that opens onto nothing.
+      headerMenu: this.config.versions.length > 1 || headerLinks.length > 0 || searchUrl !== '',
       // The light / dark switch: a button, and the few lines of script it needs.
       schemeToggle: this.config.theme?.toggle !== false,
       cls: classes,
@@ -279,6 +321,39 @@ export class SiteGenerator {
       scrollToTop: this.config.scrollToTop !== false,
       notice,
     };
+    // Every page of the version, for the components that list pages: one of
+    // them renders a single page at a time and could never gather this by
+    // itself. Targets are resolved here, each against the folder of the page
+    // that declares it — a preview written in one page is not relative to the
+    // page that shows it in a card.
+    const pages = docs.map((doc) => {
+      const folder = dirPathToSlug(path.relative(sourceDir, path.dirname(doc.path)));
+      const dirUrl = joinUrl(versionBase, folder);
+      const target = String(doc.frontmatter.preview ?? '');
+      const absolute = target.startsWith('/');
+
+      return {
+        url: pageUrl(doc),
+        slug: doc.slug,
+        title: String(doc.frontmatter.title ?? this.config.projectName),
+        description: doc.frontmatter.description ? String(doc.frontmatter.description) : undefined,
+        preview:
+          target === '' || EXTERNAL_PREVIEW.test(target)
+            ? target || undefined
+            : new URL(
+                absolute ? target.slice(1) : target,
+                `https://docpensieve.invalid${absolute ? versionBase : dirUrl}`,
+              ).pathname,
+        // The same date the byline and the sitemap read, formatted once.
+        modified:
+          readDate(
+            doc.frontmatter.modified ?? doc.frontmatter.date,
+            'modified',
+            doc.slug || 'the home page',
+          ) ?? undefined,
+      };
+    });
+
     /** @type {{ title: string, url: string, description: string, text: string }[]} */
     const entries = [];
 
@@ -293,7 +368,15 @@ export class SiteGenerator {
       const dirUrl = joinUrl(versionBase, folder);
       // Components need to know which page they render: a link they produce
       // escapes the compiler plugins (ADR-006).
-      this.deps.onPage?.({ url, dirUrl, basePath: versionBase, filepath: doc.path, sourceDir });
+      this.deps.onPage?.({
+        url,
+        dirUrl,
+        basePath: versionBase,
+        filepath: doc.path,
+        sourceDir,
+        slug: doc.slug,
+        pages,
+      });
 
       const { html, toc, preloads } = await this.compiler.compile(doc.content, {
         filepath: doc.path,
@@ -303,11 +386,19 @@ export class SiteGenerator {
         sourceDir,
       });
 
+      // Who wrote the page, and when. Read before the structured data, which
+      // describes the same people: the page and its metadata must not
+      // disagree about an author.
+      const credits = buildByline(doc.frontmatter, authors, doc.slug || 'the home page');
+
       const jsonld = new StructuredDataBuilder(doc.frontmatter, url, this.config, {
         breadcrumbTitles,
         basePath: versionBase,
         dirUrl,
         logo: images.logo,
+        // A described author carries a biography and a link, which a bare
+        // name in the frontmatter cannot.
+        authors: credits?.authors ?? [],
       }).toScriptTag();
 
       // A home page has neither menu nor table of contents: those are reading
@@ -321,6 +412,17 @@ export class SiteGenerator {
         text: htmlToText(html),
       });
 
+      const byline =
+        wide || !credits
+          ? null
+          : {
+              authors: credits.authors,
+              dates: [
+                credits.created && { prefix: 'Written', ...credits.created },
+                credits.updated && { prefix: 'Updated', ...credits.updated },
+              ].filter(Boolean),
+            };
+
       const page = layout({
         ...shell,
         title: documentTitle(doc.frontmatter.title, this.config.projectName),
@@ -332,6 +434,8 @@ export class SiteGenerator {
         // same content, two addresses, and the wrong one comes up. "follow"
         // still lets its links be followed.
         noindex: version.prerelease === true,
+        byline,
+        tags: wide ? [] : pageTags(doc.frontmatter.tags),
         sidebar: wide ? [] : sidebar,
         toc: wide ? [] : toc,
         preloads,
@@ -407,6 +511,93 @@ export class SiteGenerator {
     };
   }
 
+  /**
+   * Reads the authors a version describes, their avatars resolved.
+   *
+   * The file is optional: without it, a page still shows the names its
+   * frontmatter gives. Named in the configuration but missing, it is an
+   * error — leaving every biography out without a word would be worse.
+   *
+   * @param {string} sourceDir Source folder of the version.
+   * @param {string} folder The version's folder, as the configuration names it.
+   * @param {string} versionBase URL of the version.
+   * @returns {Promise<Map<string, import('./authors.js').Author>>} Authors by
+   *   key, their avatars resolved to a URL and measured.
+   * @throws {ConfigError} Unreadable file, invalid JSON, wrong author, missing avatar.
+   */
+  async #readAuthors(sourceDir, folder, versionBase) {
+    const name = this.config.authors;
+    if (!name) return new Map();
+
+    const source = `${folder}/${name}`;
+
+    let text;
+    try {
+      text = await readFile(path.join(sourceDir, ...name.split('/')), 'utf8');
+    } catch (cause) {
+      // Absent, the file has nothing to add: this version shows the names its
+      // pages give (ADR-017). Present but unreadable, it is a fault.
+      if (/** @type {{ code?: string }} */ (cause).code === 'ENOENT') return new Map();
+      throw new ConfigError(`Could not read the author description at ${source}.`, {
+        cause,
+        hint: 'Check that it is a file, and that nothing holds it open.',
+      });
+    }
+
+    let description;
+    try {
+      description = JSON.parse(text);
+    } catch (cause) {
+      throw new ConfigError(
+        `${source} is not valid JSON: ${/** @type {Error} */ (cause).message}`,
+        {
+          cause,
+          hint: 'A trailing comma or a missing quote is enough: open it in an editor that checks JSON.',
+        },
+      );
+    }
+
+    const table = buildAuthorTable(description, { source });
+
+    // Resolved once per version, not once per page: the same handful of
+    // images would otherwise be read and measured on every page.
+    for (const author of table.values()) {
+      if (!author.avatar) continue;
+      const segments = author.avatar.split('/').filter(Boolean);
+
+      let bytes;
+      try {
+        bytes = await readFile(path.join(sourceDir, ...segments));
+      } catch (cause) {
+        throw new ConfigError(
+          `No avatar at ${folder}/${author.avatar}, declared by author "${author.key}".`,
+          {
+            cause,
+            hint: 'The path starts at the version folder, so that the image travels with the version.',
+          },
+        );
+      }
+
+      // Published where the asset copy puts it: folders lose their ordering
+      // prefix, as pages do. The raw source path pointed at a file that is
+      // never written — `06-examples/` is served as `examples/`.
+      const published = assetPathToSlug(author.avatar).split('/');
+      const entry = /** @type {Record<string, any>} */ (author);
+      entry.avatarUrl =
+        joinUrl(versionBase, published.slice(0, -1).join('/')) + published[published.length - 1];
+
+      // Dimensions spare the reader a jump when the image arrives, as for
+      // every other image of a page.
+      const size = imageSize(bytes, path.extname(author.avatar));
+      if (size) {
+        entry.avatarWidth = size.width;
+        entry.avatarHeight = size.height;
+      }
+    }
+
+    return table;
+  }
+
   /**
    * Reads the sidebar description of a version.
    *
@@ -414,9 +605,10 @@ export class SiteGenerator {
    * @param {import('./loader.js').Doc[]} docs Documents of the version.
    * @param {(doc: import('./loader.js').Doc) => string} pageUrl
    * @param {string} folder The version's folder, as the configuration names it.
-   * @returns {Promise<import('./sidebar.js').SidebarNode[]>}
-   * @throws {ConfigError} When the file is missing, is not JSON, or describes
-   *   the menu wrongly.
+   * @returns {Promise<import('./sidebar.js').SidebarNode[] | null>} `null`
+   *   when this version has no description, which then keeps the automatic menu.
+   * @throws {ConfigError} When the file cannot be read, is not JSON, or
+   *   describes the menu wrongly.
    */
   async #describedSidebar(sourceDir, docs, pageUrl, folder) {
     const name = this.config.sidebar;
@@ -426,9 +618,12 @@ export class SiteGenerator {
     try {
       text = await readFile(path.join(sourceDir, ...name.split('/')), 'utf8');
     } catch (cause) {
-      throw new ConfigError(`No sidebar description at ${source}.`, {
+      // Absent, the version keeps the menu of its folders (ADR-017): a project
+      // can describe the menu of its new version without touching the others.
+      if (/** @type {{ code?: string }} */ (cause).code === 'ENOENT') return null;
+      throw new ConfigError(`Could not read the sidebar description at ${source}.`, {
         cause,
-        hint: `Each version describes its own menu, since each has its own pages: create ${source}, or set sidebar: 'auto'.`,
+        hint: 'Check that it is a file, and that nothing holds it open.',
       });
     }
 
@@ -668,8 +863,8 @@ export class SiteGenerator {
   async #loadLayout() {
     if (this.#layout) return this.#layout;
 
-    const [layout, navItems, tocItems] = await Promise.all(
-      ['layout.hbs', 'nav-items.hbs', 'toc-items.hbs'].map((file) =>
+    const [layout, navItems, tocItems, headerMenu] = await Promise.all(
+      ['layout.hbs', 'nav-items.hbs', 'toc-items.hbs', 'header-menu.hbs'].map((file) =>
         readFile(path.join(TEMPLATE_DIR, file), 'utf8'),
       ),
     );
@@ -678,6 +873,7 @@ export class SiteGenerator {
     handlebars.registerHelper('eq', (a, b) => a === b);
     handlebars.registerPartial('navItems', navItems);
     handlebars.registerPartial('tocItems', tocItems);
+    handlebars.registerPartial('headerMenu', headerMenu);
 
     this.#layout = handlebars.compile(layout);
     return this.#layout;
@@ -762,6 +958,8 @@ export class SiteGenerator {
 
       // The sidebar description is read by the build, not published.
       if (this.config.sidebar !== 'auto' && readable === this.config.sidebar) continue;
+      // The author descriptions too: they feed the pages, they are not pages.
+      if (this.config.authors && readable === this.config.authors) continue;
       if (DOC_EXTENSIONS.includes(path.extname(entry.name).toLowerCase())) continue;
 
       const destination = path.join(target, ...assetPathToSlug(next).split('/'));

package/src/index.js

@@ -19,6 +19,8 @@
  * @typedef {import('./compiler.js').TocEntry} TocEntry
  * @typedef {import('./compiler.js').Preload} Preload
  * @typedef {import('./sidebar.js').SidebarNode} SidebarNode
+ * @typedef {import('./authors.js').Author} Author
+ * @typedef {import('./authors.js').Byline} Byline
  */
 
 export {
@@ -34,3 +36,4 @@ export { StructuredDataBuilder } from './structured-data.js';
 export { SiteGenerator } from './generator.js';
 export { buildSidebar, buildSidebarFromDescription, collectSectionTitles } from './sidebar.js';
 export { buildFeed, buildRobots, buildSitemap } from './discovery.js';
+export { buildAuthorTable, buildByline, readDate, resolvePageAuthors } from './authors.js';

package/src/structured-data.js

@@ -70,15 +70,29 @@ function toList(value) {
 /**
  * Lists the authors as `Person` nodes.
  *
- * @param {unknown} authors Single string or array of names.
- * @returns {{ '@type': string, name: string }[]}
+ * @param {unknown} authors Single string or array of names, or of keys.
+ * @param {{ key: string, name: string, bio?: string, url?: string }[]} [described]
+ *   Authors the version describes, which carry what a bare name cannot.
+ * @returns {Record<string, any>[]}
  */
-function toPersons(authors) {
+function toPersons(authors, described = []) {
+  const byKey = new Map(described.map((author) => [author.key, author]));
   const list = Array.isArray(authors) ? authors : authors ? [authors] : [];
   return list
     .map((name) => String(name).trim())
     .filter(Boolean)
-    .map((name) => ({ '@type': 'Person', name }));
+    .map((name) => {
+      const found = byKey.get(name);
+      // Undescribed, the frontmatter entry is the name itself: that is what
+      // keeps a page written before the description file working.
+      if (!found) return { '@type': 'Person', name };
+
+      /** @type {Record<string, any>} */
+      const person = { '@type': 'Person', name: found.name };
+      if (found.bio) person.description = found.bio;
+      if (found.url) person.url = found.url;
+      return person;
+    });
 }
 
 /** Assembles a schema.org graph for a page. */
@@ -87,7 +101,7 @@ export class StructuredDataBuilder {
    * @param {Record<string, any>} frontmatter Page frontmatter.
    * @param {string} url Page URL on the site (`'/guide/install/'`).
    * @param {Record<string, any>} config Normalised project config.
-   * @param {{ breadcrumbTitles?: Record<string, string>, basePath?: string, dirUrl?: string, logo?: string }} [options]
+   * @param {{ breadcrumbTitles?: Record<string, string>, basePath?: string, dirUrl?: string, logo?: string, authors?: { key: string, name: string, bio?: string, url?: string }[] }} [options]
    *   `breadcrumbTitles` maps a folder slug to its real title, so that the
    *   breadcrumb shows “Café Guide” rather than “Cafe guide”. `basePath` is
    *   the site root from which crumbs are counted: the generator sets
@@ -242,7 +256,7 @@ export class StructuredDataBuilder {
     }
     if (modified) node.dateModified = modified;
 
-    const authors = toPersons(this.frontmatter.authors);
+    const authors = toPersons(this.frontmatter.authors, this.options?.authors ?? []);
     if (authors.length > 0) node.author = authors;
 
     // A single tag is written without brackets, like a single author.

package/templates/header-menu.hbs

@@ -0,0 +1,26 @@
+{{!-- What the header offers beyond the brand: the version switcher, the links of
+the site and the search field. Written once here, shown twice by the layout — in
+a row on a wide screen, behind a menu button on a narrow one. --}}
+{{#if showVersions}}
+<details class="{{{cls.versions}}}">
+  {{!-- The accessible name contains the visible label: when dictated by voice,
+  what is read on screen must find this button. --}}
+  <summary aria-label="Version {{versionName}}, switch version">{{versionName}}</summary>
+  <ul class="{{{cls.versionsList}}}">
+    {{#each versions}}
+    <li><a href="{{url}}"{{#if current}} aria-current="true"{{/if}}>{{name}}</a></li>
+    {{/each}}
+  </ul>
+</details>
+{{/if}}
+{{#if headerLinks.length}}
+<ul class="{{{cls.headerLinks}}}">
+  {{#each headerLinks}}<li><a href="{{href}}">{{label}}</a></li>{{/each}}
+</ul>
+{{/if}}
+{{!-- A plain form: it leads to the search page, and needs no script. --}}
+{{#if searchUrl}}
+<form class="{{{cls.search}}}" role="search" action="{{searchUrl}}">
+  <input type="search" name="q" placeholder="Search" aria-label="Search the documentation" />
+</form>
+{{/if}}

package/templates/layout.hbs

@@ -59,24 +59,22 @@
     <header class="{{{cls.header}}}">
       {{!-- The logo's alt stays empty: the name that follows already says it. --}}
       <a class="{{{cls.brand}}}" href="{{homeUrl}}">{{#if logoUrl}}<img class="{{{cls.brandLogo}}}" src="{{logoUrl}}" alt="" />{{/if}}{{projectName}}</a>
-      {{#if showVersions}}
-      <details class="{{{cls.versions}}}">
-        {{!-- The accessible name contains the visible label: when dictated by
-        voice, what is read on screen must find this button. --}}
-        <summary aria-label="Version {{versionName}}, switch version">{{versionName}}</summary>
-        <ul class="{{{cls.versionsList}}}">
-          {{#each versions}}
-          <li><a href="{{url}}"{{#if current}} aria-current="true"{{/if}}>{{name}}</a></li>
-          {{/each}}
-        </ul>
+      {{!-- Shown twice, one at a time: in a row on a wide screen, behind a button
+      on a narrow one. The button is a details element, so that the menu opens
+      without a script — as the version switcher does. --}}
+      {{#if headerMenu}}
+      <nav class="{{{cls.headerNav}}}" aria-label="Site">
+        {{> headerMenu}}
+      </nav>
+      <details class="{{{cls.menu}}}">
+        <summary aria-label="Menu">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true" focusable="false"><path d="M4 7h16M4 12h16M4 17h16" /></svg>
+        </summary>
+        <nav class="{{{cls.menuPanel}}}" aria-label="Site">
+          {{> headerMenu}}
+        </nav>
       </details>
       {{/if}}
-      {{!-- A plain form: it leads to the search page, and needs no script. --}}
-      {{#if searchUrl}}
-      <form class="{{{cls.search}}}" role="search" action="{{searchUrl}}">
-        <input type="search" name="q" placeholder="Search" aria-label="Search the documentation" />
-      </form>
-      {{/if}}
       {{!-- Hidden until its script runs: without JavaScript, it would do nothing. --}}
       {{#if schemeToggle}}
       <button class="{{{cls.schemeToggle}}}" type="button" data-scheme-toggle hidden aria-label="Switch the colour scheme">
@@ -104,7 +102,38 @@
           The current version is <a href="{{notice.url}}">{{notice.name}}</a>.
         </aside>
         {{/if}}
+        {{!-- Who wrote the page, and when. Absent when the page says neither,
+        and on a home page, where a byline under an entrance hall means
+        nothing. --}}
+        {{#if byline}}
+        <div class="{{{cls.byline}}}">
+          {{#if byline.authors.length}}
+          <ul class="{{{cls.bylineAuthors}}}">
+            {{#each byline.authors}}
+            <li class="{{{@root.cls.bylineAuthor}}}">
+              {{#if avatarUrl}}<img class="{{{@root.cls.bylineAvatar}}}" src="{{avatarUrl}}" alt="" {{#if avatarWidth}}width="{{avatarWidth}}" height="{{avatarHeight}}" {{/if}}loading="lazy" decoding="async" />{{/if}}
+              <span class="{{{@root.cls.bylineName}}}">{{#if url}}<a href="{{url}}">{{name}}</a>{{else}}{{name}}{{/if}}</span>
+              {{#if bio}}<span class="{{{@root.cls.bylineBio}}}">{{bio}}</span>{{/if}}
+            </li>
+            {{/each}}
+          </ul>
+          {{/if}}
+          {{#if byline.dates.length}}
+          <p class="{{{cls.bylineDates}}}">
+            {{#each byline.dates}}<span>{{prefix}} <time datetime="{{iso}}">{{label}}</time></span>{{/each}}
+          </p>
+          {{/if}}
+        </div>
+        {{/if}}
         <article class="{{{cls.article}}}">{{{content}}}</article>
+        {{!-- The tags of the page, below what they describe: read after the
+        text, they say what it was about. Labels, not links — there is no page
+        per tag. None on a home page. --}}
+        {{#if tags.length}}
+        <ul class="{{{cls.tags}}}" aria-label="Tags">
+          {{#each tags}}<li class="{{{@root.cls.tag}}}">{{this}}</li>{{/each}}
+        </ul>
+        {{/if}}
       </main>
 
       {{#if toc.length}}

package/types/authors.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The byline of a page: who wrote it, and when it was written or last changed.
+ *
+ * The frontmatter names the authors; a JSON file of the version describes
+ * them. The split matters: a name repeated on forty pages would carry its
+ * biography forty times, and correcting it would mean forty edits.
+ *
+ * This module reads no file. The generator hands it the parsed description,
+ * as it does for the menu: without that, the engine could not be tested
+ * without a disk.
+ *
+ * @module @docpensieve/core/authors
+ */
+export type Author = {
+    /**
+     * Key used by the frontmatter.
+     */
+    key: string;
+    /**
+     * Name shown to the reader.
+     */
+    name: string;
+    /**
+     * One or two sentences, shown under the name.
+     */
+    bio?: string;
+    /**
+     * Image path, relative to the version's folder.
+     */
+    avatar?: string;
+    /**
+     * Personal site or profile.
+     */
+    url?: string;
+};
+export type Byline = {
+    authors: Author[];
+    created: {
+        iso: string;
+        label: string;
+    } | null;
+    updated: {
+        iso: string;
+        label: string;
+    } | null;
+};
+/**
+ * Reads a date of the frontmatter, and gives it in both forms: the machine one
+ * for `<time datetime>`, the readable one for the reader.
+ *
+ * A date is often written unquoted in YAML, which parses it as a Date; quoted,
+ * it arrives as text. Both are accepted, anything unreadable is refused rather
+ * than shown as `Invalid Date`.
+ *
+ * @param {unknown} value
+ * @param {string} field Name of the field, for the error message.
+ * @param {string} where Page the date comes from.
+ * @returns {{ iso: string, label: string } | null} `null` when absent.
+ * @throws {ConfigError} When the value is not a date.
+ */
+export declare function readDate(value: unknown, field: string, where: string): {
+    iso: string;
+    label: string;
+} | null;
+/**
+ * Turns the JSON description of a version into a table of authors.
+ *
+ * @param {unknown} description Parsed content of the file.
+ * @param {{ source: string }} options `source` names the file in errors.
+ * @returns {Map<string, Author>}
+ * @throws {ConfigError} When the shape is wrong, naming the offending entry.
+ */
+export declare function buildAuthorTable(description: unknown, { source }: {
+    source: string;
+}): Map<string, Author>;
+/**
+ * The authors of a page, in the order the frontmatter names them.
+ *
+ * A key the table does not describe is not an error: the name is shown as
+ * written. It is what lets a project name its authors before describing them,
+ * and what keeps pages written before the file working.
+ *
+ * @param {unknown} value `authors` from the frontmatter: one name or a list.
+ * @param {Map<string, Author>} [table]
+ * @returns {Author[]}
+ */
+export declare function resolvePageAuthors(value: unknown, table?: Map<string, Author>): Author[];
+/**
+ * Assembles what the head of a page shows, or nothing when it has none of it.
+ *
+ * @param {Record<string, any>} frontmatter
+ * @param {Map<string, Author>} [table]
+ * @param {string} [where] Page named in a date error.
+ * @returns {Byline | null}
+ * @throws {ConfigError} When a date cannot be read.
+ */
+export declare function buildByline(frontmatter: Record<string, any>, table?: Map<string, Author>, where?: string): Byline | null;

package/types/config.d.ts

@@ -71,6 +71,18 @@ export type DocPensieveConfig = {
      * `'auto'`, or the path of a description.
      */
     sidebar: string;
+    /**
+     * Path of a JSON describing the authors, read in each version folder.
+     */
+    authors?: string;
+    /**
+     * Links of the header, beside the version switcher.
+     */
+    headerLinks?: {
+        label: string;
+        href: string;
+        version?: string;
+    }[];
     globalComponents: boolean;
     /**
      * Back-to-top button on every page.
@@ -137,6 +149,9 @@ export type DocPensieveConfig = {
  * @property {Version[]} versions At least one.
  * @property {{ framework: string, darkMode?: string, toggle?: boolean, tokens?: Record<string, string>, css?: string, source?: string }} theme
  * @property {string} sidebar     `'auto'`, or the path of a description.
+ * @property {string} [authors]   Path of a JSON describing the authors, read in each version folder.
+ * @property {{ label: string, href: string, version?: string }[]} [headerLinks]
+ *   Links of the header, beside the version switcher.
  * @property {boolean} globalComponents
  * @property {boolean} scrollToTop Back-to-top button on every page.
  * @property {{ enabled: boolean }} jsonld

package/types/generator.d.ts

@@ -20,6 +20,18 @@ export declare class SiteGenerator {
             basePath: string;
             filepath?: string;
             sourceDir?: string;
+            slug?: string;
+            pages?: {
+                url: string;
+                slug: string;
+                title: string;
+                description?: string;
+                preview?: string;
+                modified?: {
+                    iso: string;
+                    label: string;
+                };
+            }[];
         }) => void;
     };
     loader: DocLoader;
@@ -33,7 +45,9 @@ export declare class SiteGenerator {
      *   compiler?: Compiler,
      *   onPage?: (page: {
      *     url: string, dirUrl?: string, basePath: string,
-     *     filepath?: string, sourceDir?: string,
+     *     filepath?: string, sourceDir?: string, slug?: string,
+     *     pages?: { url: string, slug: string, title: string, description?: string,
+     *       preview?: string, modified?: { iso: string, label: string } }[],
      *   }) => void,
      * }} [deps]
      *   Global components and the theme are injected rather than imported:
@@ -54,6 +68,18 @@ export declare class SiteGenerator {
             basePath: string;
             filepath?: string;
             sourceDir?: string;
+            slug?: string;
+            pages?: {
+                url: string;
+                slug: string;
+                title: string;
+                description?: string;
+                preview?: string;
+                modified?: {
+                    iso: string;
+                    label: string;
+                };
+            }[];
         }) => void;
     });
     /**

package/types/index.d.ts

@@ -14,6 +14,8 @@ export type CompileResult = import('./compiler.js').CompileResult;
 export type TocEntry = import('./compiler.js').TocEntry;
 export type Preload = import('./compiler.js').Preload;
 export type SidebarNode = import('./sidebar.js').SidebarNode;
+export type Author = import('./authors.js').Author;
+export type Byline = import('./authors.js').Byline;
 /**
  * Engine types, re-exported for consumers of the published package: without
  * this they would only be reachable through an internal path.
@@ -25,6 +27,8 @@ export type SidebarNode = import('./sidebar.js').SidebarNode;
  * @typedef {import('./compiler.js').TocEntry} TocEntry
  * @typedef {import('./compiler.js').Preload} Preload
  * @typedef {import('./sidebar.js').SidebarNode} SidebarNode
+ * @typedef {import('./authors.js').Author} Author
+ * @typedef {import('./authors.js').Byline} Byline
  */
 export { DEFAULT_CONFIG, defineConfig, loadConfig, normalizeConfig, resolveVersion, } from './config.js';
 export { DocLoader } from './loader.js';
@@ -33,3 +37,4 @@ export { StructuredDataBuilder } from './structured-data.js';
 export { SiteGenerator } from './generator.js';
 export { buildSidebar, buildSidebarFromDescription, collectSectionTitles } from './sidebar.js';
 export { buildFeed, buildRobots, buildSitemap } from './discovery.js';
+export { buildAuthorTable, buildByline, readDate, resolvePageAuthors } from './authors.js';

package/types/structured-data.d.ts

@@ -24,6 +24,12 @@ export declare class StructuredDataBuilder {
         basePath?: string;
         dirUrl?: string;
         logo?: string;
+        authors?: {
+            key: string;
+            name: string;
+            bio?: string;
+            url?: string;
+        }[];
     };
     breadcrumbTitles: Record<string, string>;
     basePath: string;
@@ -33,7 +39,7 @@ export declare class StructuredDataBuilder {
      * @param {Record<string, any>} frontmatter Page frontmatter.
      * @param {string} url Page URL on the site (`'/guide/install/'`).
      * @param {Record<string, any>} config Normalised project config.
-     * @param {{ breadcrumbTitles?: Record<string, string>, basePath?: string, dirUrl?: string, logo?: string }} [options]
+     * @param {{ breadcrumbTitles?: Record<string, string>, basePath?: string, dirUrl?: string, logo?: string, authors?: { key: string, name: string, bio?: string, url?: string }[] }} [options]
      *   `breadcrumbTitles` maps a folder slug to its real title, so that the
      *   breadcrumb shows “Café Guide” rather than “Cafe guide”. `basePath` is
      *   the site root from which crumbs are counted: the generator sets
@@ -46,6 +52,12 @@ export declare class StructuredDataBuilder {
         basePath?: string;
         dirUrl?: string;
         logo?: string;
+        authors?: {
+            key: string;
+            name: string;
+            bio?: string;
+            url?: string;
+        }[];
     });
     /**
      * Builds the page's schema.org graph.