@docpensieve/core 0.3.0-beta.2 → 0.4.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docpensieve/core",
-  "version": "0.3.0-beta.2",
+  "version": "0.4.0-beta.1",
   "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.2",
+    "@docpensieve/shared": "0.4.0-beta.1",
     "@mdx-js/mdx": "^3.1.1",
     "@shikijs/rehype": "^4.4.3",
     "gray-matter": "^4.0.3",

package/src/config.js

@@ -39,6 +39,8 @@ import {
  * @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
@@ -75,6 +77,9 @@ export const DEFAULT_CONFIG = Object.freeze({
   // 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 },
@@ -263,6 +268,43 @@ export function normalizeConfig(userConfig) {
     }
   }
 
+  // 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

@@ -52,6 +52,19 @@ const CLIENT_SEARCH = fileURLToPath(new URL('../client/search.js', import.meta.u
  */
 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>}
@@ -227,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();
@@ -259,6 +273,17 @@ export class SiteGenerator {
     // 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
@@ -282,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,
@@ -407,6 +435,7 @@ export class SiteGenerator {
         // still lets its links be followed.
         noindex: version.prerelease === true,
         byline,
+        tags: wide ? [] : pageTags(doc.frontmatter.tags),
         sidebar: wide ? [] : sidebar,
         toc: wide ? [] : toc,
         preloads,
@@ -494,7 +523,7 @@ export class SiteGenerator {
    * @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.
+   * @throws {ConfigError} Unreadable file, invalid JSON, wrong author, missing avatar.
    */
   async #readAuthors(sourceDir, folder, versionBase) {
     const name = this.config.authors;
@@ -506,9 +535,12 @@ export class SiteGenerator {
     try {
       text = await readFile(path.join(sourceDir, ...name.split('/')), 'utf8');
     } catch (cause) {
-      throw new ConfigError(`No author description at ${source}.`, {
+      // 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: `Each version describes its own authors: create ${source}, or drop the authors field.`,
+        hint: 'Check that it is a file, and that nothing holds it open.',
       });
     }
 
@@ -546,9 +578,13 @@ export class SiteGenerator {
         );
       }
 
+      // 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, segments.slice(0, -1).join('/')) + segments[segments.length - 1];
+        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.
@@ -569,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;
@@ -581,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.',
       });
     }
 
@@ -823,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'),
       ),
     );
@@ -833,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;

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">
@@ -128,6 +126,14 @@
         </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/config.d.ts

@@ -75,6 +75,14 @@ export type DocPensieveConfig = {
      * 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.
@@ -142,6 +150,8 @@ export type DocPensieveConfig = {
  * @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