@docpensieve/core 0.2.0 → 0.3.0-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docpensieve/core",
-  "version": "0.2.0",
+  "version": "0.3.0-beta.2",
   "description": "DocPensieve engine: loading, MDX compilation, structured data, site generation",
   "type": "module",
   "license": "MIT",
@@ -21,7 +21,7 @@
     "types"
   ],
   "dependencies": {
-    "@docpensieve/shared": "0.2.0",
+    "@docpensieve/shared": "0.3.0-beta.2",
     "@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,7 @@ 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 {boolean} globalComponents
  * @property {boolean} scrollToTop Back-to-top button on every page.
  * @property {{ enabled: boolean }} jsonld
@@ -70,6 +71,10 @@ 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: '',
   globalComponents: true,
   scrollToTop: true,
   jsonld: { enabled: true },
@@ -240,6 +245,24 @@ 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.",
+        },
+      );
+    }
+  }
+
   // 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,12 @@ 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;
+
 /**
  * Where each project image is written in a version, before its extension.
  * @type {Record<'logo' | 'favicon' | 'socialImage', string>}
@@ -153,7 +161,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:
@@ -245,6 +255,10 @@ 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);
+
     const shell = {
       lang: this.config.lang ?? 'en',
       // A fixed scheme is a class on <html>, which the skins and the dark
@@ -279,6 +293,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 +340,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 +358,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 +384,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 +406,7 @@ 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,
         sidebar: wide ? [] : sidebar,
         toc: wide ? [] : toc,
         preloads,
@@ -407,6 +482,86 @@ 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} Missing 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) {
+      throw new ConfigError(`No author description at ${source}.`, {
+        cause,
+        hint: `Each version describes its own authors: create ${source}, or drop the authors field.`,
+      });
+    }
+
+    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.',
+          },
+        );
+      }
+
+      const entry = /** @type {Record<string, any>} */ (author);
+      entry.avatarUrl =
+        joinUrl(versionBase, segments.slice(0, -1).join('/')) + segments[segments.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.
    *
@@ -762,6 +917,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/layout.hbs

@@ -104,6 +104,29 @@
           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>
       </main>
 

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,10 @@ 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;
     globalComponents: boolean;
     /**
      * Back-to-top button on every page.
@@ -137,6 +141,7 @@ 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 {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.