@docpensieve/core 0.1.5 → 0.2.0

package/src/search-index.js

@@ -0,0 +1,76 @@
+/**
+ * What the build prepares for search: the index of a version, and its search
+ * page.
+ *
+ * Search is built here, not in the reader's browser: the index holds the
+ * plain text of every page, and the search page already lists every page,
+ * so that it is useful before any script runs — and without one.
+ *
+ * @module @docpensieve/core/search-index
+ */
+
+/** Path of the search page within a version. */
+export const SEARCH_SLUG = 'search';
+
+/** @type {Record<string, string>} */
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
+
+/**
+ * Turns rendered HTML into the plain text a reader sees.
+ *
+ * @param {string} html
+ * @returns {string}
+ */
+export function htmlToText(html) {
+  return html
+    .replace(/<(script|style|svg)\b[\s\S]*?<\/\1>/gi, ' ')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (entity, name) => {
+      if (name[0] !== '#') return ENTITIES[name.toLowerCase()] ?? entity;
+      const code =
+        name[1] === 'x' || name[1] === 'X' ? parseInt(name.slice(2), 16) : Number(name.slice(1));
+      return Number.isFinite(code) ? String.fromCodePoint(code) : entity;
+    })
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * Escapes a value for HTML.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+function escapeHtml(value) {
+  return String(value)
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;');
+}
+
+/**
+ * Renders the content of the search page: a field, and the list of every
+ * page of the version, which the script filters.
+ *
+ * @param {{ title: string, url: string, description: string }[]} entries
+ *   Pages of the version, in reading order.
+ * @param {string} indexUrl URL of the version's index.
+ * @returns {string}
+ */
+export function searchPageContent(entries, indexUrl) {
+  const items = entries.map((entry) => {
+    const description = entry.description ? `<p>${escapeHtml(entry.description)}</p>` : '';
+    return `<li data-url="${escapeHtml(entry.url)}"><a href="${escapeHtml(entry.url)}">${escapeHtml(entry.title)}</a>${description}</li>`;
+  });
+
+  return [
+    '<h1 id="search">Search</h1>',
+    `<form class="dp-search-page" role="search" data-search-page data-index="${escapeHtml(indexUrl)}">`,
+    '<label for="dp-search-query">Search the documentation</label>',
+    '<input id="dp-search-query" type="search" name="q" autocomplete="off" />',
+    '</form>',
+    `<p class="dp-search-status" data-search-status aria-live="polite">${entries.length} pages.</p>`,
+    `<ol class="dp-search-results" data-search-results>${items.join('')}</ol>`,
+  ].join('');
+}

package/src/sidebar.js

@@ -4,7 +4,7 @@
  * @module @docpensieve/core/sidebar
  */
 
-import { humanizeSlug } from '@docpensieve/shared';
+import { ConfigError, humanizeSlug } from '@docpensieve/shared';
 
 /**
  * @typedef {object} SidebarNode
@@ -103,3 +103,184 @@ export function collectSectionTitles(docs) {
 
   return titles;
 }
+
+/**
+ * An entry of a sidebar description: a page path, or an object — see
+ * `buildSidebarFromDescription`.
+ *
+ * @typedef {string | {
+ *   page?: string, label?: string, items?: SidebarEntry[], href?: string, auto?: string,
+ * }} SidebarEntry
+ */
+
+/** The kinds of entry, for the hints. */
+const ENTRY_KINDS =
+  'Entries: "guide/installation", { "page", "label" }, { "label", "items", "page" }, ' +
+  '{ "label", "href" } or { "auto": "folder" }.';
+
+/**
+ * @param {string} value
+ * @returns {string} The value without its leading and trailing slashes.
+ */
+function trimSlashes(value) {
+  let start = 0;
+  let end = value.length;
+  while (start < end && value[start] === '/') start += 1;
+  while (end > start && value[end - 1] === '/') end -= 1;
+  return value.slice(start, end);
+}
+
+/**
+ * Builds the navigation tree of a version from a description.
+ *
+ * The description is an array of entries, kept in the order written:
+ *
+ * - `"guide/installation"` — a page, by its path within the version, as in
+ *   its URL; `"/"` is the home page. Its title becomes the label.
+ * - `{ "page": "guide/installation", "label": "Install" }` — the same, with a
+ *   label of its own.
+ * - `{ "label": "Guide", "items": [ … ], "page": "guide" }` — a category,
+ *   clickable when it names a page.
+ * - `{ "label": "Repository", "href": "https://…" }` — a link outside the site.
+ * - `{ "auto": "docpensieve" }` — the automatic tree of a folder: a section
+ *   keeps its own menu without listing its pages one by one.
+ *
+ * A page left out stays published: it is only absent from the menu, which is
+ * how a page is kept off it.
+ *
+ * @param {unknown} description Parsed content of the description file.
+ * @param {import('./loader.js').Doc[]} docs Documents of the version.
+ * @param {(doc: import('./loader.js').Doc) => string} [toUrl] As for
+ *   `buildSidebar`.
+ * @param {{ source?: string }} [options] `source` names the file in messages.
+ * @returns {SidebarNode[]}
+ * @throws {ConfigError} For a path that names no page, a page listed twice,
+ *   or an entry of no known kind.
+ */
+export function buildSidebarFromDescription(
+  description,
+  docs,
+  toUrl = (doc) => doc.url,
+  options = {},
+) {
+  const source = options.source ?? 'The sidebar description';
+  const bySlug = new Map(docs.map((doc) => [doc.slug, doc]));
+  /** @type {Set<string>} */
+  const listed = new Set();
+
+  /** @param {string} message @param {string} hint */
+  const fail = (message, hint) => new ConfigError(`${source}: ${message}`, { hint });
+
+  /** @param {string} slug @returns {string} Up to five known paths near it. */
+  const nearby = (slug) => {
+    const known = [...bySlug.keys()];
+    const first = slug.split('/')[0];
+    const close = known.filter((candidate) => candidate.split('/')[0] === first);
+    return (close.length > 0 ? close : known)
+      .slice(0, 5)
+      .map((candidate) => `"${candidate || '/'}"`)
+      .join(', ');
+  };
+
+  /** @param {string} slug */
+  const claim = (slug) => {
+    // The menu marks a single entry as the current page: listed twice, a page
+    // would light up in two places, or in the wrong one.
+    if (listed.has(slug)) {
+      throw fail(`the page "${slug || '/'}" is listed twice.`, 'List each page once.');
+    }
+    listed.add(slug);
+  };
+
+  /** @param {unknown} raw @returns {import('./loader.js').Doc} */
+  const pageOf = (raw) => {
+    const slug = trimSlashes(String(raw));
+    const doc = bySlug.get(slug);
+    if (!doc) {
+      throw fail(
+        `no page "${String(raw)}".`,
+        `A page is named by its path within the version, as in its URL. Close to it: ${nearby(slug)}.`,
+      );
+    }
+    claim(slug);
+    return doc;
+  };
+
+  /** @param {import('./loader.js').Doc} doc @returns {string} */
+  const titleOf = (doc) =>
+    String(
+      doc.frontmatter?.title ?? (doc.slug ? humanizeSlug(doc.slug.split('/').pop() ?? '') : 'Home'),
+    );
+
+  /** @param {unknown} entry @returns {SidebarNode[]} */
+  const expand = (entry) => {
+    if (typeof entry === 'string') {
+      const doc = pageOf(entry);
+      return [{ label: titleOf(doc), url: toUrl(doc), items: [] }];
+    }
+    if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+      throw fail(
+        `an entry must be a page path or an object: ${JSON.stringify(entry)}.`,
+        ENTRY_KINDS,
+      );
+    }
+
+    const item = /** @type {Record<string, unknown>} */ (entry);
+    const label = typeof item.label === 'string' && item.label ? item.label : undefined;
+
+    if (item.href !== undefined) {
+      if (!label || typeof item.href !== 'string') {
+        throw fail(`a link needs a label and an href: ${JSON.stringify(entry)}.`, ENTRY_KINDS);
+      }
+      return [{ label, url: item.href, items: [] }];
+    }
+
+    if (item.auto !== undefined) {
+      const folder = trimSlashes(String(item.auto));
+      const inside = docs.filter(
+        (doc) => !folder || doc.slug === folder || doc.slug.startsWith(`${folder}/`),
+      );
+      if (inside.length === 0) {
+        throw fail(
+          `the folder "${String(item.auto)}" holds no page.`,
+          `Name a folder of the version, as in its URLs. Close to it: ${nearby(folder)}.`,
+        );
+      }
+      for (const doc of inside) claim(doc.slug);
+
+      const tree = buildSidebar(inside, toUrl);
+      if (!folder) return tree;
+      // The tree starts at the version's root, one node per level down to the
+      // folder, since every page shares its path.
+      let [node] = tree;
+      for (let depth = 1; depth < folder.split('/').length; depth += 1) [node] = node.items;
+      return [{ ...node, label: label ?? node.label }];
+    }
+
+    if (item.items !== undefined) {
+      if (!label || !Array.isArray(item.items)) {
+        throw fail(
+          `a category needs a label and a list of items: ${JSON.stringify(entry)}.`,
+          ENTRY_KINDS,
+        );
+      }
+      const url = item.page !== undefined ? toUrl(pageOf(item.page)) : null;
+      return [{ label, url, items: item.items.flatMap(expand) }];
+    }
+
+    if (item.page !== undefined) {
+      const doc = pageOf(item.page);
+      return [{ label: label ?? titleOf(doc), url: toUrl(doc), items: [] }];
+    }
+
+    throw fail(
+      `${JSON.stringify(entry)} is neither a page, a category, a link nor an automatic folder.`,
+      ENTRY_KINDS,
+    );
+  };
+
+  if (!Array.isArray(description)) {
+    throw fail('it must hold an array of entries.', ENTRY_KINDS);
+  }
+  return description.flatMap(expand);
+}

package/src/structured-data.js

@@ -24,7 +24,7 @@ const ABSOLUTE_URL = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
  * @param {unknown} value
  * @returns {string | undefined} `'2026-01-15'`, or `undefined` when unusable.
  */
-function toISODate(value) {
+export function toISODate(value) {
   if (value === undefined || value === null || value === '') return undefined;
 
   /*

package/templates/layout.hbs

@@ -13,6 +13,9 @@
     {{#if canonical}}
     <link rel="canonical" href="{{canonical}}" />
     {{/if}}
+    {{#if feedUrl}}
+    <link rel="alternate" type="application/rss+xml" title="{{projectName}}" href="{{feedUrl}}" />
+    {{/if}}
     {{#if favicon}}
     <link rel="icon" href="{{favicon.href}}" type="{{favicon.type}}" />
     {{/if}}
@@ -33,13 +36,27 @@
     <link rel="preload" as="{{as}}" href="{{href}}" />
     {{/each}}
     <link rel="stylesheet" href="{{cssHref}}" />
+    {{#if schemeToggle}}
+    {{!-- Before the first paint: the scheme the reader chose, not a flash of the
+    other one. --}}
+    <script>try{var s=localStorage.getItem('dp-scheme'),c=document.documentElement.classList;if(s==='dark'||s==='light'){c.remove('dark','light');c.add(s)}}catch(e){}</script>
+    {{/if}}
+    {{!-- Only the search page carries a script: content pages load none. --}}
+    {{#each scripts}}
+    <script type="module" src="{{this}}"></script>
+    {{/each}}
     {{{jsonld}}}
   </head>
   <body>
     <a class="{{{cls.skip}}}" href="#content">Skip to content</a>
 
-    {{!-- Target of the back-to-top link: bring the focus back, not only the view. --}}
-    <header class="{{{cls.header}}}" id="top" tabindex="-1">
+    {{!-- Target of the back-to-top link: it brings the focus back, not only the
+    view. It stays out of the header on purpose — the header is sticky, so it
+    is already in view at any scroll position, and a browser asked to bring it
+    into view scrolled nowhere. --}}
+    <div id="top" tabindex="-1"></div>
+
+    <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}}
@@ -54,6 +71,19 @@
         </ul>
       </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">
+        <svg class="dp-scheme-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8z" /></svg>
+        <svg class="dp-scheme-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><circle cx="12" cy="12" r="4" /><path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4" /></svg>
+      </button>
+      {{/if}}
     </header>
 
     <div class="{{#if wide}}{{{cls.shellWide}}}{{else}}{{{cls.shell}}}{{/if}}">
@@ -107,5 +137,8 @@
       </svg>
     </a>
     {{/if}}
+    {{#if schemeToggle}}
+    <script>(function(){var b=document.querySelector('[data-scheme-toggle]');if(!b)return;var r=document.documentElement.classList;function dark(){return r.contains('dark')||(!r.contains('light')&&matchMedia('(prefers-color-scheme: dark)').matches)}function label(){b.setAttribute('aria-label',dark()?'Switch to light mode':'Switch to dark mode')}b.hidden=false;label();b.addEventListener('click',function(){var next=dark()?'light':'dark';r.remove('dark','light');r.add(next);try{localStorage.setItem('dp-scheme',next)}catch(e){}label()})})();</script>
+    {{/if}}
   </body>
 </html>

package/types/compiler.d.ts

@@ -93,7 +93,7 @@ export declare class Compiler {
      * Compiles a source into an HTML fragment and a table of contents.
      *
      * @param {string} source Markdown/MDX content, frontmatter already removed.
-     * @param {{ filepath?: string, url?: string, dirUrl?: string, basePath?: string }} [context]
+     * @param {{ filepath?: string, url?: string, dirUrl?: string, basePath?: string, sourceDir?: string }} [context]
      *   `filepath` locates errors, `dirUrl` is the base of relative targets and
      *   `basePath` prefixes absolute targets (the version root).
      * @returns {Promise<CompileResult>}
@@ -104,5 +104,6 @@ export declare class Compiler {
         url?: string;
         dirUrl?: string;
         basePath?: string;
+        sourceDir?: string;
     }): Promise<CompileResult>;
 }

package/types/config.d.ts

@@ -29,6 +29,14 @@ export type Version = {
      * reference one. Its pages carry a notice and are not indexed.
      */
     prerelease?: boolean;
+    /**
+     * Logo of this version, instead of the project's.
+     */
+    logo?: string;
+    /**
+     * Favicon of this version, instead of the project's.
+     */
+    favicon?: string;
 };
 export type DocPensieveConfig = {
     /**
@@ -54,6 +62,7 @@ export type DocPensieveConfig = {
     theme: {
         framework: string;
         darkMode?: string;
+        toggle?: boolean;
         tokens?: Record<string, string>;
         css?: string;
         source?: string;
@@ -82,6 +91,18 @@ export type DocPensieveConfig = {
      * Preview of a shared page. Needs `siteUrl`.
      */
     socialImage?: string;
+    /**
+     * `sitemap.xml` of the published versions.
+     */
+    sitemap?: boolean;
+    /**
+     * RSS feed of the dated pages of the current version.
+     */
+    feed?: boolean;
+    /**
+     * Search field, index and search page of each version.
+     */
+    search?: boolean;
     /**
      * Project root, set by `loadConfig`.
      */
@@ -104,6 +125,8 @@ export type DocPensieveConfig = {
  * @property {boolean} [archived] Version kept but no longer maintained.
  * @property {boolean} [prerelease] Version in preparation, not yet the
  *   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.
  */
 /**
  * @typedef {object} DocPensieveConfig
@@ -112,7 +135,7 @@ export type DocPensieveConfig = {
  * @property {string} baseUrl     Deployment prefix, slashes included.
  * @property {string} outDir      Output folder, relative to the root.
  * @property {Version[]} versions At least one.
- * @property {{ framework: string, darkMode?: string, tokens?: Record<string, string>, css?: string, source?: string }} theme
+ * @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 {boolean} globalComponents
  * @property {boolean} scrollToTop Back-to-top button on every page.
@@ -120,6 +143,9 @@ export type DocPensieveConfig = {
  * @property {string} [logo]        Image beside the project name, in the header.
  * @property {string} [favicon]     Icon of the browser tab: `.ico`, `.png` or `.svg`.
  * @property {string} [socialImage] Preview of a shared page. Needs `siteUrl`.
+ * @property {boolean} [sitemap] `sitemap.xml` of the published versions.
+ * @property {boolean} [feed] RSS feed of the dated pages of the current version.
+ * @property {boolean} [search] Search field, index and search page of each version.
  * @property {string} [rootDir]   Project root, set by `loadConfig`.
  * @property {string} [configFile] Path of the configuration file, set by `loadConfig`.
  * @property {string} [lang]      Document language, `'en'` by default.

package/types/discovery.d.ts

@@ -0,0 +1,59 @@
+/**
+ * What a site offers the programs that read it: the sitemap for search
+ * engines, `robots.txt` that points to it, and the RSS feed of dated pages.
+ *
+ * Pure functions: the generator gathers the published pages and writes the
+ * files.
+ *
+ * @module @docpensieve/core/discovery
+ */
+export type PublishedPage = {
+    /**
+     * Page URL, deployment prefix included
+     * (`/docs/versions/v1.0/guide/`).
+     */
+    url: string;
+    /**
+     * Frontmatter of its source.
+     */
+    frontmatter: Record<string, any>;
+};
+/**
+ * Builds `sitemap.xml`.
+ *
+ * `lastmod` is the page's `modified` date, or failing that its `date`; a page
+ * that carries neither is listed without one rather than with a made-up date.
+ *
+ * @param {PublishedPage[]} pages Pages of the versions to list.
+ * @param {string} siteUrl Public address of the site: the sitemap only holds
+ *   absolute addresses.
+ * @returns {string}
+ */
+export declare function buildSitemap(pages: PublishedPage[], siteUrl: string): string;
+/**
+ * Builds `robots.txt`, which lets every crawler in and names the sitemap.
+ *
+ * @param {string} sitemapUrl Absolute address of the sitemap.
+ * @returns {string}
+ */
+export declare function buildRobots(sitemapUrl: string): string;
+/**
+ * Builds the RSS feed of the dated pages, newest first.
+ *
+ * Only a page with a `date` enters it: a documentation page without one is
+ * reference material, not news, and dating it at build time would announce
+ * every page again at every build.
+ *
+ * @param {PublishedPage[]} pages Pages of the current version.
+ * @param {{
+ *   projectName: string, siteUrl: string, homeUrl: string, feedUrl: string, lang?: string,
+ * }} site `homeUrl` and `feedUrl` are absolute.
+ * @returns {string}
+ */
+export declare function buildFeed(pages: PublishedPage[], site: {
+    projectName: string;
+    siteUrl: string;
+    homeUrl: string;
+    feedUrl: string;
+    lang?: string;
+}): string;

package/types/generator.d.ts

@@ -61,12 +61,14 @@ export declare class SiteGenerator {
      *
      * @param {string} versionSlug Slug of the version to generate.
      * @param {string} outDir Output folder of that version.
-     * @returns {Promise<{ pages: number, outDir: string }>}
+     * @returns {Promise<{ pages: number, outDir: string, published: import('./discovery.js').PublishedPage[] }>}
+     *   `published` lists the pages as the site serves them, for the sitemap and the feed.
      * @throws {GeneratorError} Write failure.
      */
     buildVersion(versionSlug: string, outDir: string): Promise<{
         pages: number;
         outDir: string;
+        published: import('./discovery.js').PublishedPage[];
     }>;
     /**
      * Generates every declared version, plus `versions.json` and a root that

package/types/image-size.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Dimensions of an image, read from the first bytes of its file.
+ *
+ * The build writes them on every image of a page: the browser then keeps the
+ * room before the image arrives, instead of shifting the text when it does.
+ * Only the header of each format is read — no decoding, no dependency.
+ *
+ * @module @docpensieve/core/image-size
+ */
+export type ImageSize = {
+    width: number;
+    height: number;
+};
+/**
+ * Reads the dimensions of an image from its content.
+ *
+ * @param {Buffer} bytes Content of the file — its first kilobytes are enough.
+ * @param {string} extension Extension of the file, dot included.
+ * @returns {ImageSize | null} `null` for an unknown or damaged format: the
+ *   image is then written without dimensions, as before.
+ */
+export declare function imageSize(bytes: Buffer, extension: string): ImageSize | null;

package/types/index.d.ts

@@ -31,4 +31,5 @@ export { DocLoader } from './loader.js';
 export { Compiler } from './compiler.js';
 export { StructuredDataBuilder } from './structured-data.js';
 export { SiteGenerator } from './generator.js';
-export { buildSidebar, collectSectionTitles } from './sidebar.js';
+export { buildSidebar, buildSidebarFromDescription, collectSectionTitles } from './sidebar.js';
+export { buildFeed, buildRobots, buildSitemap } from './discovery.js';

package/types/minify-css.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Minification of the produced stylesheet.
+ *
+ * Deliberately cautious: comments go, and so does the whitespace that nothing
+ * reads — indentation, line breaks, the space around `{`, `}` and `;`. Every
+ * other space stays one space, since some carry meaning (`.a :hover` is not
+ * `.a:hover`), and the content of a string is never touched. That keeps most
+ * of the gain of a real minifier without its risk of changing what a rule
+ * means.
+ *
+ * @module @docpensieve/core/minify-css
+ */
+/**
+ * @param {string} css
+ * @returns {string} The same rules, lighter.
+ */
+export declare function minifyCss(css: string): string;

package/types/search-index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What the build prepares for search: the index of a version, and its search
+ * page.
+ *
+ * Search is built here, not in the reader's browser: the index holds the
+ * plain text of every page, and the search page already lists every page,
+ * so that it is useful before any script runs — and without one.
+ *
+ * @module @docpensieve/core/search-index
+ */
+/** Path of the search page within a version. */
+export declare const SEARCH_SLUG = "search";
+/**
+ * Turns rendered HTML into the plain text a reader sees.
+ *
+ * @param {string} html
+ * @returns {string}
+ */
+export declare function htmlToText(html: string): string;
+/**
+ * Renders the content of the search page: a field, and the list of every
+ * page of the version, which the script filters.
+ *
+ * @param {{ title: string, url: string, description: string }[]} entries
+ *   Pages of the version, in reading order.
+ * @param {string} indexUrl URL of the version's index.
+ * @returns {string}
+ */
+export declare function searchPageContent(entries: {
+    title: string;
+    url: string;
+    description: string;
+}[], indexUrl: string): string;

package/types/sidebar.d.ts

@@ -58,3 +58,40 @@ export declare function buildSidebar(docs: import('./loader.js').Doc[], toUrl?:
  * @returns {Record<string, string>} Full folder slug to title.
  */
 export declare function collectSectionTitles(docs: import('./loader.js').Doc[]): Record<string, string>;
+export type SidebarEntry = string | {
+    page?: string;
+    label?: string;
+    items?: SidebarEntry[];
+    href?: string;
+    auto?: string;
+};
+/**
+ * Builds the navigation tree of a version from a description.
+ *
+ * The description is an array of entries, kept in the order written:
+ *
+ * - `"guide/installation"` — a page, by its path within the version, as in
+ *   its URL; `"/"` is the home page. Its title becomes the label.
+ * - `{ "page": "guide/installation", "label": "Install" }` — the same, with a
+ *   label of its own.
+ * - `{ "label": "Guide", "items": [ … ], "page": "guide" }` — a category,
+ *   clickable when it names a page.
+ * - `{ "label": "Repository", "href": "https://…" }` — a link outside the site.
+ * - `{ "auto": "docpensieve" }` — the automatic tree of a folder: a section
+ *   keeps its own menu without listing its pages one by one.
+ *
+ * A page left out stays published: it is only absent from the menu, which is
+ * how a page is kept off it.
+ *
+ * @param {unknown} description Parsed content of the description file.
+ * @param {import('./loader.js').Doc[]} docs Documents of the version.
+ * @param {(doc: import('./loader.js').Doc) => string} [toUrl] As for
+ *   `buildSidebar`.
+ * @param {{ source?: string }} [options] `source` names the file in messages.
+ * @returns {SidebarNode[]}
+ * @throws {ConfigError} For a path that names no page, a page listed twice,
+ *   or an entry of no known kind.
+ */
+export declare function buildSidebarFromDescription(description: unknown, docs: import('./loader.js').Doc[], toUrl?: (doc: import('./loader.js').Doc) => string, options?: {
+    source?: string;
+}): SidebarNode[];

package/types/structured-data.d.ts

@@ -3,6 +3,16 @@
  *
  * @module @docpensieve/core/structured-data
  */
+/**
+ * Normalises a frontmatter date into a short ISO date.
+ *
+ * YAML turns `date: 2026-01-15` into a `Date` object, but a quoted date stays
+ * a string: both forms must come out the same.
+ *
+ * @param {unknown} value
+ * @returns {string | undefined} `'2026-01-15'`, or `undefined` when unusable.
+ */
+export declare function toISODate(value: unknown): string | undefined;
 /** Assembles a schema.org graph for a page. */
 export declare class StructuredDataBuilder {
     #private;