@docpensieve/core 0.1.5 → 0.2.0-beta.1

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,6 +36,10 @@
     <link rel="preload" as="{{as}}" href="{{href}}" />
     {{/each}}
     <link rel="stylesheet" href="{{cssHref}}" />
+    {{!-- Only the search page carries a script: content pages load none. --}}
+    {{#each scripts}}
+    <script type="module" src="{{this}}"></script>
+    {{/each}}
     {{{jsonld}}}
   </head>
   <body>
@@ -54,6 +61,12 @@
         </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}}
     </header>
 
     <div class="{{#if wide}}{{{cls.shellWide}}}{{else}}{{{cls.shell}}}{{/if}}">

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 = {
     /**
@@ -82,6 +90,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 +124,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
@@ -120,6 +142,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;