npm - @docpensieve/core - Versions diffs - 0.1.5 → 0.2.0-beta.1 - Mend

@docpensieve/core 0.1.5 → 0.2.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/README.md +4 -0
package/client/search.js +205 -0
package/package.json +4 -3
package/src/compiler.js +76 -2
package/src/config.js +72 -7
package/src/discovery.js +128 -0
package/src/generator.js +227 -35
package/src/image-size.js +128 -0
package/src/index.js +2 -1
package/src/minify-css.js +70 -0
package/src/search-index.js +76 -0
package/src/sidebar.js +182 -1
package/src/structured-data.js +1 -1
package/templates/layout.hbs +13 -0
package/types/compiler.d.ts +2 -1
package/types/config.d.ts +25 -0
package/types/discovery.d.ts +59 -0
package/types/generator.d.ts +3 -1
package/types/image-size.d.ts +22 -0
package/types/index.d.ts +2 -1
package/types/minify-css.d.ts +17 -0
package/types/search-index.d.ts +33 -0
package/types/sidebar.d.ts +37 -0
package/types/structured-data.d.ts +10 -0

package/src/generator.js CHANGED Viewed

@@ -9,6 +9,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
+  ConfigError,
   DOC_EXTENSIONS,
   assetPathToSlug,
   dirPathToSlug,
@@ -22,7 +23,10 @@ import Handlebars from 'handlebars';
 import { Compiler } from './compiler.js';
 import { resolveVersion } from './config.js';
 import { DocLoader } from './loader.js';
-import { buildSidebar, collectSectionTitles } from './sidebar.js';
+import { buildFeed, buildRobots, buildSitemap } from './discovery.js';
+import { minifyCss } from './minify-css.js';
+import { SEARCH_SLUG, htmlToText, searchPageContent } from './search-index.js';
+import { buildSidebar, buildSidebarFromDescription, collectSectionTitles } from './sidebar.js';
 import { StructuredDataBuilder } from './structured-data.js';
 /** Template folder, resolved from this module rather than from the cwd. */
@@ -31,6 +35,15 @@ const TEMPLATE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..
 /** Path of the stylesheet written into every version. */
 const STYLESHEET = 'assets/docpensieve.css';
+/** Index of a version, which the search page reads. */
+const SEARCH_INDEX = 'assets/search-index.json';
+/** Script of the search page, the only one a site loads. */
+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));
 /**
  * Where each project image is written in a version, before its extension.
  * @type {Record<'logo' | 'favicon' | 'socialImage', string>}
@@ -162,7 +175,8 @@ export 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.
    */
   async buildVersion(versionSlug, outDir) {
@@ -188,7 +202,12 @@ export class SiteGenerator {
     const current = this.config.versions.find((candidate) => candidate.current);
     const notice = versionNotice(version, current, this.config.baseUrl);
-    const sidebar = buildSidebar(docs, pageUrl, { brand: this.config.projectName });
+    // '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 =
+      this.config.sidebar && this.config.sidebar !== 'auto'
+        ? await this.#describedSidebar(sourceDir, docs, pageUrl, version.folder)
+        : buildSidebar(docs, pageUrl, { brand: this.config.projectName });
     const breadcrumbTitles = collectSectionTitles(docs);
     const layout = await this.#loadLayout();
     const classes = this.#classes();
@@ -209,7 +228,44 @@ export class SiteGenerator {
     // The project's images go into every version: each one stands on its
     // own, down to the orphan branch it is published on.
-    const images = await this.#copyImages(target, versionBase, written);
+    const images = await this.#copyImages(target, versionBase, written, version);
+    // What every page of the version shares, the search page included.
+    const searchUrl = this.config.search !== false ? joinUrl(versionBase, SEARCH_SLUG) : '';
+    const shell = {
+      lang: this.config.lang ?? 'en',
+      // A fixed scheme is a class on <html>, which the skins and the dark
+      // variant of the utilities both obey.
+      darkModeClass: ['dark', 'light'].includes(this.config.theme?.darkMode ?? '')
+        ? this.config.theme.darkMode
+        : null,
+      projectName: this.config.projectName,
+      versionName: version.name,
+      homeUrl: versionBase,
+      cssHref: joinUrl(versionBase, path.dirname(STYLESHEET)) + path.basename(STYLESHEET),
+      feedUrl: this.#feedUrl(),
+      logoUrl: images.logo ?? '',
+      favicon: images.favicon
+        ? { href: images.favicon, type: FAVICON_TYPES[path.extname(images.favicon).toLowerCase()] }
+        : null,
+      // Social networks only read an absolute address: normalisation
+      // refuses a preview image without siteUrl.
+      socialImage:
+        images.socialImage && this.config.siteUrl
+          ? new URL(images.socialImage, this.config.siteUrl).href
+          : '',
+      searchUrl,
+      cls: classes,
+      versions: this.#versionLinks(version.slug),
+      // A switcher offering a single choice is not a switcher.
+      showVersions: this.config.versions.length > 1,
+      // The back-to-top button is page furniture, not content: writing it in
+      // every file would repeat it everywhere, and forget it somewhere.
+      scrollToTop: this.config.scrollToTop !== false,
+      notice,
+    };
+    /** @type {{ title: string, url: string, description: string, text: string }[]} */
+    const entries = [];
     for (const doc of docs) {
       const url = pageUrl(doc);
@@ -229,6 +285,7 @@ export class SiteGenerator {
         url,
         dirUrl,
         basePath: versionBase,
+        sourceDir,
       });
       const jsonld = new StructuredDataBuilder(doc.frontmatter, url, this.config, {
@@ -242,39 +299,20 @@ export class SiteGenerator {
       // landmarks within a document, not in an entrance hall.
       const wide = pageLayout(doc) === 'home';
+      entries.push({
+        title: String(doc.frontmatter.title ?? this.config.projectName),
+        url,
+        description: String(doc.frontmatter.description ?? ''),
+        text: htmlToText(html),
+      });
       const page = layout({
-        lang: this.config.lang ?? 'en',
-        darkModeClass: null,
+        ...shell,
         title: documentTitle(doc.frontmatter.title, this.config.projectName),
         description: doc.frontmatter.description ?? '',
         canonical: this.config.siteUrl ? new URL(url, this.config.siteUrl).href : '',
-        projectName: this.config.projectName,
-        versionName: version.name,
-        homeUrl: versionBase,
         currentUrl: url,
-        cssHref: joinUrl(versionBase, path.dirname(STYLESHEET)) + path.basename(STYLESHEET),
-        logoUrl: images.logo ?? '',
-        favicon: images.favicon
-          ? {
-              href: images.favicon,
-              type: FAVICON_TYPES[path.extname(images.favicon).toLowerCase()],
-            }
-          : null,
-        // Social networks only read an absolute address: normalisation
-        // refuses a preview image without siteUrl.
-        socialImage:
-          images.socialImage && this.config.siteUrl
-            ? new URL(images.socialImage, this.config.siteUrl).href
-            : '',
-        cls: classes,
-        versions: this.#versionLinks(version.slug),
-        // A switcher offering a single choice is not a switcher.
-        showVersions: this.config.versions.length > 1,
         wide,
-        // The back-to-top button is page furniture, not content: writing it in
-        // every file would repeat it everywhere, and forget it somewhere.
-        scrollToTop: this.config.scrollToTop !== false,
-        notice,
         // A version in preparation must not compete with the current one:
         // same content, two addresses, and the wrong one comes up. "follow"
         // still lets its links be followed.
@@ -295,13 +333,159 @@ export class SiteGenerator {
       await this.#write(destination, page);
     }
+    // The search page and the index it reads, built with the site: content
+    // pages load no script, and this page is useful before its own runs.
+    if (searchUrl) {
+      const destination = path.join(target, SEARCH_SLUG, 'index.html');
+      const taken = written.get(destination);
+      if (taken !== undefined) {
+        throw new GeneratorError(`"${taken}" takes the place of the search page, ${searchUrl}.`, {
+          hint: 'Rename that page, or set search: false in the configuration.',
+        });
+      }
+      /** @param {string} file */
+      const assetUrl = (file) =>
+        joinUrl(versionBase, path.posix.dirname(file)) + path.posix.basename(file);
+      const indexFile = path.join(target, ...SEARCH_INDEX.split('/'));
+      const scriptFile = path.join(target, ...SEARCH_SCRIPT.split('/'));
+      await this.#write(indexFile, JSON.stringify(entries));
+      await mkdir(path.dirname(scriptFile), { recursive: true });
+      await copyFile(CLIENT_SEARCH, scriptFile);
+      const page = layout({
+        ...shell,
+        title: documentTitle('Search', this.config.projectName),
+        description: `Search the pages of ${this.config.projectName} ${version.name}.`,
+        canonical: '',
+        currentUrl: searchUrl,
+        wide: false,
+        // A list of every page, and a script: nothing a search engine should
+        // offer as a result.
+        noindex: true,
+        sidebar,
+        toc: [],
+        preloads: [],
+        scripts: [assetUrl(SEARCH_SCRIPT)],
+        content: searchPageContent(entries, assetUrl(SEARCH_INDEX)),
+        jsonld: '',
+      });
+      for (const [, value] of page.matchAll(CLASS_ATTRIBUTE)) {
+        for (const token of value.split(/\s+/)) if (token) candidates.add(token);
+      }
+      await this.#write(destination, page);
+      for (const file of [destination, indexFile, scriptFile]) written.set(file, 'the search page');
+    }
     await this.#copyAssets(sourceDir, target, '', written);
     // The stylesheet is compiled last: it needs the classes above.
     const { css } = await this.deps.theme.compile({ candidates: [...candidates] });
-    await this.#write(path.join(target, ...STYLESHEET.split('/')), css);
+    // Comments and indentation make the stylesheet readable, and heavier on
+    // every page: the reader receives it minified.
+    await this.#write(path.join(target, ...STYLESHEET.split('/')), minifyCss(css));
+    return {
+      pages: docs.length,
+      outDir: target,
+      published: docs.map((doc) => ({ url: pageUrl(doc), frontmatter: doc.frontmatter })),
+    };
+  }
-    return { pages: docs.length, outDir: target };
+  /**
+   * Reads the sidebar description of a version.
+   *
+   * @param {string} sourceDir Source folder of the version.
+   * @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.
+   */
+  async #describedSidebar(sourceDir, docs, pageUrl, folder) {
+    const name = this.config.sidebar;
+    const source = `${folder}/${name}`;
+    let text;
+    try {
+      text = await readFile(path.join(sourceDir, ...name.split('/')), 'utf8');
+    } catch (cause) {
+      throw new ConfigError(`No sidebar description at ${source}.`, {
+        cause,
+        hint: `Each version describes its own menu, since each has its own pages: create ${source}, or set sidebar: 'auto'.`,
+      });
+    }
+    let description;
+    try {
+      description = JSON.parse(text);
+    } catch (cause) {
+      throw new ConfigError(
+        `${source} is not valid JSON: ${/** @type {Error} */ (cause).message}`,
+        {
+          cause,
+          hint: 'JSON accepts neither comments nor a comma after the last entry.',
+        },
+      );
+    }
+    return buildSidebarFromDescription(description, docs, pageUrl, { source });
+  }
+  /**
+   * Absolute address of the RSS feed, or `''` when none is written.
+   *
+   * Known before any page is rendered: every page announces the feed in its
+   * head, whereas the feed itself is written once every version is built.
+   *
+   * @returns {string}
+   */
+  #feedUrl() {
+    if (!this.config.feed || !this.config.siteUrl) return '';
+    return new URL(`${this.config.baseUrl}feed.xml`, this.config.siteUrl).href;
+  }
+  /**
+   * Writes what search engines and feed readers read, at the root of the
+   * site: `sitemap.xml`, `robots.txt` and the RSS feed.
+   *
+   * @param {string} target Output folder.
+   * @param {Map<string, import('./discovery.js').PublishedPage[]>} published
+   *   Pages of each version, by slug.
+   */
+  async #writeDiscovery(target, published) {
+    const { siteUrl, baseUrl } = this.config;
+    if (!siteUrl) return;
+    if (this.config.sitemap !== false) {
+      // A version in preparation is kept out of search engines: its pages
+      // carry noindex, and listing them would contradict it.
+      const pages = this.config.versions
+        .filter((version) => !version.prerelease)
+        .flatMap((version) => published.get(version.slug) ?? []);
+      await this.#write(path.join(target, 'sitemap.xml'), buildSitemap(pages, siteUrl));
+      // Crawlers only read robots.txt at the root of a domain: under a
+      // sub-path, the file would be written for nobody.
+      if (baseUrl === '/') {
+        const sitemapUrl = new URL('/sitemap.xml', siteUrl).href;
+        await this.#write(path.join(target, 'robots.txt'), buildRobots(sitemapUrl));
+      }
+    }
+    const feedUrl = this.#feedUrl();
+    if (feedUrl) {
+      const current = resolveVersion(this.config);
+      const feed = buildFeed(published.get(current.slug) ?? [], {
+        projectName: this.config.projectName,
+        siteUrl,
+        homeUrl: new URL(joinUrl(baseUrl, 'versions', current.slug), siteUrl).href,
+        feedUrl,
+        lang: this.config.lang,
+      });
+      await this.#write(path.join(target, 'feed.xml'), feed);
+    }
   }
   /**
@@ -310,17 +494,19 @@ export class SiteGenerator {
    * @param {string} target Output folder of the version.
    * @param {string} versionBase URL of the version.
    * @param {Map<string, string>} written Files already written, for collisions.
+   * @param {import('./config.js').Version} version The version being built.
    * @returns {Promise<Partial<Record<keyof typeof IMAGE_FILES, string>>>} URL
    *   of each declared image.
    * @throws {GeneratorError} When a declared image does not exist.
    */
-  async #copyImages(target, versionBase, written) {
+  async #copyImages(target, versionBase, written, version) {
     const rootDir = this.config.rootDir ?? process.cwd();
     /** @type {Partial<Record<keyof typeof IMAGE_FILES, string>>} */
     const urls = {};
     for (const field of /** @type {(keyof typeof IMAGE_FILES)[]} */ (Object.keys(IMAGE_FILES))) {
-      const declared = this.config[field];
+      // A version's own logo or favicon replaces the project's.
+      const declared = (field !== 'socialImage' && version[field]) || this.config[field];
       if (!declared) continue;
       const file = `${IMAGE_FILES[field]}${path.extname(declared).toLowerCase()}`;
@@ -361,16 +547,20 @@ export class SiteGenerator {
     const target = path.resolve(rootDir, this.config.outDir);
     let pages = 0;
+    /** @type {Map<string, import('./discovery.js').PublishedPage[]>} */
+    const published = new Map();
     for (const version of this.config.versions) {
       const result = await this.buildVersion(
         version.slug,
         path.join(target, 'versions', version.slug),
       );
       pages += result.pages;
+      published.set(version.slug, result.published);
     }
     await this.#writeManifest(target);
     await this.#writeRootRedirect(target);
+    await this.#writeDiscovery(target, published);
     return { versions: this.config.versions.length, pages, outDir: target };
   }
@@ -498,6 +688,8 @@ export class SiteGenerator {
         });
       }
+      // The sidebar description is read by the build, not published.
+      if (this.config.sidebar !== 'auto' && readable === this.config.sidebar) continue;
       if (DOC_EXTENSIONS.includes(path.extname(entry.name).toLowerCase())) continue;
       const destination = path.join(target, ...assetPathToSlug(next).split('/'));

package/src/image-size.js ADDED Viewed

@@ -0,0 +1,128 @@
+/**
+ * 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
+ */
+/**
+ * @typedef {{ width: number, height: number }} ImageSize
+ */
+/**
+ * @param {Buffer} bytes
+ * @returns {ImageSize | null}
+ */
+function png(bytes) {
+  // Signature, then the IHDR chunk: width and height, big-endian.
+  if (bytes.length < 24 || bytes.readUInt32BE(0) !== 0x89504e47) return null;
+  return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+}
+/**
+ * @param {Buffer} bytes
+ * @returns {ImageSize | null}
+ */
+function gif(bytes) {
+  if (bytes.length < 10 || bytes.toString('ascii', 0, 3) !== 'GIF') return null;
+  return { width: bytes.readUInt16LE(6), height: bytes.readUInt16LE(8) };
+}
+/**
+ * @param {Buffer} bytes
+ * @returns {ImageSize | null}
+ */
+function jpeg(bytes) {
+  if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8) return null;
+  // Walk the segments up to the frame header (SOF), which holds the size.
+  let offset = 2;
+  while (offset + 9 < bytes.length) {
+    if (bytes[offset] !== 0xff) return null;
+    const marker = bytes[offset + 1];
+    const isFrame = marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker);
+    if (isFrame) {
+      return { height: bytes.readUInt16BE(offset + 5), width: bytes.readUInt16BE(offset + 7) };
+    }
+    offset += 2 + bytes.readUInt16BE(offset + 2);
+  }
+  return null;
+}
+/**
+ * @param {Buffer} bytes
+ * @returns {ImageSize | null}
+ */
+function webp(bytes) {
+  if (bytes.length < 30 || bytes.toString('ascii', 0, 4) !== 'RIFF') return null;
+  if (bytes.toString('ascii', 8, 12) !== 'WEBP') return null;
+  const chunk = bytes.toString('ascii', 12, 16);
+  if (chunk === 'VP8 ') {
+    return { width: bytes.readUInt16LE(26) & 0x3fff, height: bytes.readUInt16LE(28) & 0x3fff };
+  }
+  if (chunk === 'VP8L') {
+    const bits = bytes.readUInt32LE(21);
+    return { width: (bits & 0x3fff) + 1, height: ((bits >> 14) & 0x3fff) + 1 };
+  }
+  if (chunk === 'VP8X') {
+    return { width: bytes.readUIntLE(24, 3) + 1, height: bytes.readUIntLE(27, 3) + 1 };
+  }
+  return null;
+}
+/**
+ * @param {Buffer} bytes
+ * @returns {ImageSize | null}
+ */
+function svg(bytes) {
+  const text = bytes.toString('utf8', 0, Math.min(bytes.length, 4096));
+  const tag = /<svg\b[^>]*>/i.exec(text)?.[0];
+  if (!tag) return null;
+  /** @param {string} name */
+  const attribute = (name) => new RegExp(`\\b${name}\\s*=\\s*["']([^"']+)["']`, 'i').exec(tag)?.[1];
+  // Width and height in pixels, or failing that the proportions of the viewBox.
+  const width = Number.parseFloat(attribute('width') ?? '');
+  const height = Number.parseFloat(attribute('height') ?? '');
+  const inPixels = (/** @type {string | undefined} */ value) =>
+    !value || /^[\d.]+(px)?$/.test(value.trim());
+  if (width > 0 && height > 0 && inPixels(attribute('width')) && inPixels(attribute('height'))) {
+    return { width: Math.round(width), height: Math.round(height) };
+  }
+  const box = (attribute('viewBox') ?? '')
+    .trim()
+    .split(/[\s,]+/)
+    .map(Number);
+  if (box.length === 4 && box[2] > 0 && box[3] > 0) {
+    return { width: Math.round(box[2]), height: Math.round(box[3]) };
+  }
+  return null;
+}
+/**
+ * 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 function imageSize(bytes, extension) {
+  switch (extension.toLowerCase()) {
+    case '.png':
+      return png(bytes);
+    case '.jpg':
+    case '.jpeg':
+      return jpeg(bytes);
+    case '.gif':
+      return gif(bytes);
+    case '.webp':
+      return webp(bytes);
+    case '.svg':
+      return svg(bytes);
+    default:
+      return null;
+  }
+}

package/src/index.js CHANGED Viewed

@@ -32,4 +32,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/src/minify-css.js ADDED Viewed

@@ -0,0 +1,70 @@
+/**
+ * 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
+ */
+/** Characters around which no space is ever needed. */
+const TIGHT = new Set(['{', '}', ';']);
+/**
+ * @param {string} css
+ * @returns {string} The same rules, lighter.
+ */
+export function minifyCss(css) {
+  let out = '';
+  let space = false;
+  let i = 0;
+  while (i < css.length) {
+    const char = css[i];
+    // A string is copied as is, escapes included.
+    if (char === '"' || char === "'") {
+      let end = i + 1;
+      while (end < css.length && css[end] !== char) end += css[end] === '\\' ? 2 : 1;
+      if (space && out && !TIGHT.has(out[out.length - 1])) out += ' ';
+      space = false;
+      out += css.slice(i, end + 1);
+      i = end + 1;
+      continue;
+    }
+    // A comment weighs its length and says nothing to the browser.
+    if (char === '/' && css[i + 1] === '*') {
+      const end = css.indexOf('*/', i + 2);
+      i = end < 0 ? css.length : end + 2;
+      space = true;
+      continue;
+    }
+    if (char === ' ' || char === '\n' || char === '\r' || char === '\t' || char === '\f') {
+      space = true;
+      i += 1;
+      continue;
+    }
+    if (TIGHT.has(char)) {
+      // The last declaration of a block needs no semicolon.
+      if (char === '}' && out.endsWith(';')) out = out.slice(0, -1);
+      out += char;
+      space = false;
+      i += 1;
+      continue;
+    }
+    if (space && out && !TIGHT.has(out[out.length - 1])) out += ' ';
+    space = false;
+    out += char;
+    i += 1;
+  }
+  return out;
+}

package/src/search-index.js ADDED Viewed

@@ -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('');
+}