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

package/client/search.js

@@ -131,6 +131,24 @@ async function init() {
   const status = /** @type {HTMLElement | null} */ (document.querySelector('[data-search-status]'));
   if (!form || !input || !list || !status) return;
 
+  // The wording of the page, put there by the build: this file is copied as
+  // it is into every site, whatever its language.
+  const words = {
+    lang: 'en',
+    failed: 'The search index could not be loaded: every page is listed below.',
+    pages: { one: 'page', other: 'pages' },
+    noResultFor: 'No page matches “{query}”.',
+    resultsFor: '{count} for “{query}”.',
+    ...JSON.parse(form.dataset.strings || '{}'),
+  };
+
+  // The plural comes from the language, not from a comparison with one: that
+  // rule is English, and gets French wrong on zero — "0 page".
+  const plural = new Intl.PluralRules(words.lang);
+
+  /** @param {number} n */
+  const count = (n) => `${n} ${words.pages[plural.select(n)] ?? words.pages.other}`;
+
   /** @type {Map<string, HTMLElement>} */
   const items = new Map();
   const listed = /** @type {NodeListOf<HTMLElement>} */ (list.querySelectorAll('li[data-url]'));
@@ -142,7 +160,7 @@ async function init() {
     const response = await fetch(form.dataset.index ?? '');
     entries = await response.json();
   } catch {
-    status.textContent = 'The search index could not be loaded: every page is listed below.';
+    status.textContent = words.failed;
     return;
   }
 
@@ -161,7 +179,7 @@ async function init() {
         reset(item);
         list.append(item);
       }
-      status.textContent = `${items.size} pages.`;
+      status.textContent = `${count(items.size)}.`;
       return;
     }
 
@@ -186,8 +204,8 @@ async function init() {
 
     status.textContent =
       found.length === 0
-        ? `No page matches “${query}”.`
-        : `${found.length} ${found.length === 1 ? 'page' : 'pages'} for “${query}”.`;
+        ? words.noResultFor.replace('{query}', query)
+        : words.resultsFor.replace('{count}', count(found.length)).replace('{query}', query);
   };
 
   input.value = new URLSearchParams(location.search).get('q') ?? '';

package/package.json

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

package/src/authors.js

@@ -12,7 +12,10 @@
  * @module @docpensieve/core/authors
  */
 
-import { ConfigError } from '@docpensieve/shared';
+import { ConfigError, UI_STRINGS } from '@docpensieve/shared';
+
+/** Locale of a date when the caller names none: the wording of the default language. */
+const DEFAULT_DATE_LOCALE = UI_STRINGS.en.dateLocale;
 
 /**
  * @typedef {object} Author
@@ -44,10 +47,11 @@ const AUTHOR_FIELDS = new Set(['name', 'bio', 'avatar', 'url']);
  * @param {unknown} value
  * @param {string} field Name of the field, for the error message.
  * @param {string} where Page the date comes from.
+ * @param {string} [locale] Locale the label is written in. Default: `en-GB`.
  * @returns {{ iso: string, label: string } | null} `null` when absent.
  * @throws {ConfigError} When the value is not a date.
  */
-export function readDate(value, field, where) {
+export function readDate(value, field, where, locale = DEFAULT_DATE_LOCALE) {
   if (value === undefined || value === null || value === '') return null;
 
   const date = value instanceof Date ? value : new Date(String(value));
@@ -59,11 +63,11 @@ export function readDate(value, field, where) {
 
   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', {
+    // The locale comes from the page, never from the machine that built it:
+    // a site is produced once and read everywhere. 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(locale, {
       day: 'numeric',
       month: 'long',
       year: 'numeric',
@@ -159,14 +163,15 @@ export function resolvePageAuthors(value, table = new Map()) {
  * @param {Record<string, any>} frontmatter
  * @param {Map<string, Author>} [table]
  * @param {string} [where] Page named in a date error.
+ * @param {string} [locale] Locale the dates are written in.
  * @returns {Byline | null}
  * @throws {ConfigError} When a date cannot be read.
  */
-export function buildByline(frontmatter, table = new Map(), where = 'this page') {
+export function buildByline(frontmatter, table = new Map(), where = 'this page', locale) {
   const authors = resolvePageAuthors(frontmatter?.authors, table);
-  const created = readDate(frontmatter?.date, 'date', where);
+  const created = readDate(frontmatter?.date, 'date', where, locale);
   // The same field the sitemap reads for lastmod: one date, one meaning.
-  const updated = readDate(frontmatter?.modified, 'modified', where);
+  const updated = readDate(frontmatter?.modified, 'modified', where, locale);
 
   if (authors.length === 0 && !created && !updated) return null;
 

package/src/config.js

@@ -9,11 +9,13 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 
 import {
+  ADMONITION_TONES,
   CONFIG_FILENAME,
   CONFIG_FILENAMES,
   ConfigError,
   DEFAULT_OUT_DIR,
   THEME_FRAMEWORKS,
+  UI_STRINGS,
 } from '@docpensieve/shared';
 
 /**
@@ -27,6 +29,9 @@ import {
  *   reference one. Its pages carry a notice and are not indexed.
  * @property {string} [logo]    Logo of this version, instead of the project's.
  * @property {string} [favicon] Favicon of this version, instead of the project's.
+ * @property {Record<string, string>} [translations] Folder of each translation,
+ *   by language code. The pages of the site language stay at the root of the
+ *   version; a translation is served under its code.
  */
 
 /**
@@ -44,8 +49,14 @@ import {
  *   `columns` opens a panel of links instead of leading anywhere itself.
  * @property {boolean} [foldedSidebar] Categories of the menu fold, opened on
  *   the branch of the page being read.
+ * @property {Record<string, Record<string, string>>} [ui]
+ * @property {Record<string, { label: string, tone: string, icon?: string }>} [admonitions]
+ *   Kinds of admonition the project adds to the ones shipped. `icon` names an
+ *   SVG of the version folder, inlined in place of the tone's drawing.
  * @property {boolean} globalComponents
  * @property {boolean} scrollToTop Back-to-top button on every page.
+ * @property {boolean} [stickyHeader] Header held at the top of the screen.
+ *   `false` lets it scroll away with the page.
  * @property {{ enabled: boolean }} jsonld
  * @property {string} [logo]        Image beside the project name, in the header.
  * @property {string} [favicon]     Icon of the browser tab: `.ico`, `.png` or `.svg`.
@@ -86,8 +97,15 @@ export const DEFAULT_CONFIG = Object.freeze({
   // The menu shows whole by default: a documentation of a few dozen pages
   // reads better open than behind folds. Long ones turn this on.
   foldedSidebar: false,
+  // Six kinds of admonition ship with the tool; a project names its own here
+  // rather than waiting for that list to grow.
+  ui: {},
+  admonitions: {},
   globalComponents: true,
   scrollToTop: true,
+  // The header stays in reach: search, versions and menu are in it. A site
+  // that would rather give the height back to the text turns this off.
+  stickyHeader: true,
   jsonld: { enabled: true },
   logo: '',
   favicon: '',
@@ -179,9 +197,43 @@ export function normalizeConfig(userConfig) {
   // be both. "../../elsewhere" wrote outside the output folder, "a/b" nested
   // the version, "Été" produced an encoded URL.
   const VERSION_SLUG = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+  // A language code becomes a URL segment and the `lang` of the document. The
+  // standard is BCP 47, and Intl carries it: a regex of our own refused
+  // "zh-Hans-CN", which is valid, and accepted shapes that are not.
+  const isLanguageCode = (/** @type {string} */ value) => {
+    try {
+      Intl.getCanonicalLocales(value);
+      // Well formed is not the same as real: BCP 47 allows a language subtag
+      // of five to eight letters, so "francais" passes that check and would
+      // land in the markup as `lang="francais"` — a value no browser maps to
+      // a language, under a French address serving English wording. CLDR
+      // knows which tags name a language; the subtag alone is asked, so that
+      // a region, a script or a private extension does not get in the way.
+      const names = new Intl.DisplayNames(['en'], { type: 'language', fallback: 'none' });
+      return names.of(new Intl.Locale(value).language) !== undefined;
+    } catch {
+      return false;
+    }
+  };
+
+  // A translation belongs to a version, since a version is what has pages.
+  // Written at the root, it was read by nobody: the build succeeded, no
+  // language appeared, and nothing said why.
+  if (userConfig.translations !== undefined) {
+    throw new ConfigError('"translations" belongs to a version, not to the configuration root.', {
+      hint: "Move it into the version it translates: { slug: 'v1.0', folder: 'docs/v1.0', translations: { fr: 'docs/v1.0-fr' } }.",
+    });
+  }
 
   const seen = new Set();
   for (const version of config.versions) {
+    // The language of the site is declared once, at the root: a version
+    // carries translations, not a language of its own.
+    if (/** @type {Record<string, unknown>} */ (version)?.lang !== undefined) {
+      throw new ConfigError(`The version "${version.slug}" declares a language of its own.`, {
+        hint: 'The site has one language, set by "lang" at the root; a version names its translations in "translations".',
+      });
+    }
     for (const field of /** @type {const} */ (['slug', 'name', 'folder'])) {
       if (typeof version?.[field] !== 'string' || version[field].length === 0) {
         throw new ConfigError(
@@ -207,6 +259,47 @@ export function normalizeConfig(userConfig) {
         );
       }
     }
+    // A translation names a language and the folder holding it. The pages of
+    // the site language keep their address: only a translation takes a prefix,
+    // so nothing already published moves.
+    if (version.translations !== undefined) {
+      if (
+        version.translations === null ||
+        typeof version.translations !== 'object' ||
+        Array.isArray(version.translations)
+      ) {
+        throw new ConfigError(`The translations of version "${version.slug}" must be an object.`, {
+          hint: "Write translations: { fr: 'docs/v1.0-fr' } — one folder per language.",
+        });
+      }
+      for (const [lang, folder] of Object.entries(version.translations)) {
+        if (!isLanguageCode(lang)) {
+          throw new ConfigError(
+            `"${lang}" does not name a language, in version "${version.slug}".`,
+            {
+              hint: 'Write the code, not the name: "fr" for French, "pt-BR", "zh-Hans". It becomes the lang of the document and a segment of the address.',
+            },
+          );
+        }
+        if (typeof folder !== 'string' || folder === '') {
+          throw new ConfigError(
+            `The translation "${lang}" of version "${version.slug}" has no folder.`,
+            {
+              hint: "Give the folder holding those pages: { ${lang}: 'docs/v1.0-${lang}' }.",
+            },
+          );
+        }
+        if (folder === version.folder) {
+          throw new ConfigError(
+            `The translation "${lang}" of version "${version.slug}" reads the same folder as the version.`,
+            {
+              hint: 'A translation is a folder of its own: the same pages would be published twice.',
+            },
+          );
+        }
+      }
+    }
+
     if (seen.has(version.slug)) {
       throw new ConfigError(`The version slug "${version.slug}" is declared twice.`);
     }
@@ -274,6 +367,91 @@ export function normalizeConfig(userConfig) {
     }
   }
 
+  // Kinds of admonition the project adds. A kind is a label and a tone: the
+  // tone carries the colour, taken from the theme, so a new kind needs no
+  // stylesheet and follows whichever theme is active.
+  if (config.ui !== undefined) {
+    if (config.ui === null || typeof config.ui !== 'object' || Array.isArray(config.ui)) {
+      throw new ConfigError('ui must be an object of languages.', {
+        hint: "Write ui: { fr: { search: 'Chercher' } } — one entry per language.",
+      });
+    }
+    const known = Object.keys(UI_STRINGS.en);
+    for (const [lang, words] of Object.entries(config.ui)) {
+      if (!words || typeof words !== 'object' || Array.isArray(words)) {
+        throw new ConfigError(`The wording of "${lang}" must be an object.`, {
+          hint: "Write ui: { fr: { search: 'Chercher' } }.",
+        });
+      }
+      for (const [key, value] of Object.entries(words)) {
+        // A key nobody reads would leave the shipped wording in place without
+        // a word, and a typo is exactly what this field invites.
+        if (!known.includes(key)) {
+          throw new ConfigError(`Unknown wording key in "${lang}": "${key}".`, {
+            hint: `Keys: ${known.join(', ')}.`,
+          });
+        }
+        // `pages` counts, so it is written by plural category rather than as
+        // one word: a language with four of them cannot be served by a pair.
+        if (key === 'pages') {
+          const forms = Object.values(value ?? {});
+          if (typeof value !== 'object' || Array.isArray(value) || forms.length === 0) {
+            throw new ConfigError(`The wording "pages" of "${lang}" must be a set of plurals.`, {
+              hint: "Write pages: { one: 'page', other: 'pages' } — the categories of the language, 'other' at least.",
+            });
+          }
+          if (forms.some((form) => typeof form !== 'string' || form === '')) {
+            throw new ConfigError(`A plural of "pages" in "${lang}" is not a text.`, {
+              hint: 'Every category gives the word that follows the number.',
+            });
+          }
+          continue;
+        }
+        if (typeof value !== 'string' || value === '') {
+          throw new ConfigError(`The wording "${key}" of "${lang}" must be a text.`, {
+            hint: 'An empty label would leave the element unnamed on screen.',
+          });
+        }
+      }
+    }
+  }
+
+  if (config.admonitions !== undefined) {
+    if (
+      config.admonitions === null ||
+      typeof config.admonitions !== 'object' ||
+      Array.isArray(config.admonitions)
+    ) {
+      throw new ConfigError('admonitions must be an object of kinds.', {
+        hint: "Write admonitions: { review: { label: 'Review', tone: 'info' } }.",
+      });
+    }
+    for (const [name, kind] of Object.entries(config.admonitions)) {
+      if (!kind || typeof kind.label !== 'string' || kind.label.trim() === '') {
+        throw new ConfigError(`The admonition "${name}" has no label.`, {
+          hint: `Write "${name}": { label: '…', tone: '${ADMONITION_TONES[0]}' } — the label is what the reader sees.`,
+        });
+      }
+      if (kind.icon !== undefined && (typeof kind.icon !== 'string' || kind.icon.trim() === '')) {
+        throw new ConfigError(`The icon of the admonition "${name}" must be a path.`, {
+          hint: "Give an SVG of the version folder — icon: '/icons/review.svg' — or leave the field out.",
+        });
+      }
+      if (!ADMONITION_TONES.includes(kind.tone)) {
+        throw new ConfigError(
+          `The admonition "${name}" has an unknown tone: "${String(kind.tone)}".`,
+          { hint: `Tones: ${ADMONITION_TONES.join(', ')}. The tone is what colours the block.` },
+        );
+      }
+    }
+  }
+
+  if (config.stickyHeader !== undefined && typeof config.stickyHeader !== 'boolean') {
+    throw new ConfigError('stickyHeader must be true or false.', {
+      hint: 'true holds the header at the top of the screen; false lets it scroll away.',
+    });
+  }
+
   // 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,