@docpensieve/core 0.1.0

package/src/loader.js

@@ -0,0 +1,260 @@
+/**
+ * Loads the Markdown/MDX sources of a version.
+ *
+ * @module @docpensieve/core/loader
+ */
+
+import { readFile, readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  blankSegments,
+  DOC_EXTENSIONS,
+  INDEX_SLUGS,
+  LoaderError,
+  filePathToSlug,
+  orderOf,
+  slugToUrl,
+} from '@docpensieve/shared';
+import matter from 'gray-matter';
+
+/** Folders never walked, whatever they contain. */
+const IGNORED_DIRS = new Set(['node_modules', 'dist', 'coverage']);
+
+/**
+ * @typedef {object} Doc
+ * @property {string} slug        Page slug (`'guide/install'`).
+ * @property {string} path        Absolute path of the source file.
+ * @property {string} url         Site URL (`'/guide/install/'`).
+ * @property {Record<string, any>} frontmatter Frontmatter parsed by gray-matter.
+ * @property {string} content     Raw Markdown/MDX body, frontmatter removed.
+ * @property {number} order       Ordering weight for the sidebar.
+ */
+
+/**
+ * Compares two entries of the same folder for reading order.
+ *
+ * Three rules, in this order: the folder's index page comes first, then the
+ * numeric prefix (`01-`, `02-`), then alphabetical order.
+ *
+ * @param {import('node:fs').Dirent} a
+ * @param {import('node:fs').Dirent} b
+ * @returns {number}
+ */
+function compareEntries(a, b) {
+  const indexDelta = Number(isIndexEntry(b)) - Number(isIndexEntry(a));
+  if (indexDelta !== 0) return indexDelta;
+
+  const orderA = orderOf(a.name);
+  const orderB = orderOf(b.name);
+  // `orderOf` returns Infinity without a prefix: a subtraction would give NaN
+  // for two unprefixed files, which silently breaks the sort.
+  if (orderA !== orderB) return orderA - orderB;
+
+  return a.name.localeCompare(b.name, 'en');
+}
+
+/**
+ * Is an entry the index page of its folder (`index.md`, `readme.mdx`)?
+ *
+ * @param {import('node:fs').Dirent} entry
+ * @returns {boolean}
+ */
+function isIndexEntry(entry) {
+  if (entry.isDirectory()) return false;
+  const base = path.basename(entry.name, path.extname(entry.name)).toLowerCase();
+  return INDEX_SLUGS.includes(base);
+}
+
+/** Walks a version folder and produces the list of documents. */
+export class DocLoader {
+  /**
+   * @param {{ extensions?: string[], includeDrafts?: boolean }} [options]
+   *   `extensions` replaces the default list (`.md`, `.mdx`);
+   *   `includeDrafts` keeps the pages marked `draft: true`.
+   */
+  constructor(options = {}) {
+    this.options = options;
+    this.extensions = (options.extensions ?? DOC_EXTENSIONS).map((ext) => ext.toLowerCase());
+    this.includeDrafts = options.includeDrafts ?? false;
+  }
+
+  /**
+   * Recursively loads every document of a folder.
+   *
+   * Documents come back in the site's reading order: at each level, the index
+   * page first, then numeric prefixes, then alphabetical. That is the order
+   * the sidebar needs, hence sorting during the walk rather than a flat sort
+   * of the result.
+   *
+   * The URLs produced carry no version prefix: the loader does not know which
+   * version it works on, the generator adds it.
+   *
+   * @param {string} dir Version folder (e.g. `docs/v1.0`).
+   * @returns {Promise<Doc[]>}
+   * @throws {LoaderError} Missing folder, invalid frontmatter, colliding slugs.
+   */
+  async load(dir) {
+    const root = path.resolve(dir);
+
+    let stats;
+    try {
+      stats = await stat(root);
+    } catch (cause) {
+      throw new LoaderError(`Documentation folder not found: ${root}.`, {
+        cause,
+        hint: 'Check the "folder" field of the version in docpensieve.config.js.',
+      });
+    }
+    if (!stats.isDirectory()) {
+      throw new LoaderError(`${root} is not a folder.`, {
+        hint: 'The "folder" field must point to a folder, not a file.',
+      });
+    }
+
+    const files = await this.#collect(root);
+    const docs = await Promise.all(files.map((file) => this.#read(root, file)));
+
+    // Filtering comes before collision detection: a draft left out of the
+    // build conflicts with nothing.
+    const kept = this.includeDrafts ? docs : docs.filter((doc) => doc.frontmatter.draft !== true);
+    this.#assertNoSlugCollision(kept);
+    return kept;
+  }
+
+  /**
+   * Lists the documentation files, depth first, already sorted.
+   *
+   * @param {string} dir
+   * @returns {Promise<string[]>} Absolute paths.
+   */
+  async #collect(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const files = [];
+
+    for (const entry of entries.sort(compareEntries)) {
+      // Hidden entries are not documentation: tool folders, editor metadata,
+      // file-system leftovers.
+      if (entry.name.startsWith('.')) continue;
+
+      // Safety net: a misconfigured "folder" pointing at the project root
+      // would swallow thousands of dependency files.
+      if (entry.isDirectory() && IGNORED_DIRS.has(entry.name)) continue;
+
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        files.push(...(await this.#collect(full)));
+      } else if (this.extensions.includes(path.extname(entry.name).toLowerCase())) {
+        files.push(full);
+      }
+    }
+
+    return files;
+  }
+
+  /**
+   * Reads a file and turns it into a document.
+   *
+   * @param {string} root Root of the version folder, for the relative slug.
+   * @param {string} absolutePath
+   * @returns {Promise<Doc>}
+   */
+  async #read(root, absolutePath) {
+    const relative = path.relative(root, absolutePath);
+
+    let raw;
+    try {
+      raw = await readFile(absolutePath, 'utf8');
+    } catch (cause) {
+      throw new LoaderError(`Could not read ${relative}.`, { cause });
+    }
+
+    let parsed;
+    try {
+      parsed = matter(raw);
+    } catch (cause) {
+      throw new LoaderError(`Invalid frontmatter in ${relative}.`, {
+        cause,
+        // gray-matter surfaces the raw YAML error: repeat it as is, it is the
+        // one that gives the offending line.
+        hint: cause instanceof Error ? cause.message : undefined,
+      });
+    }
+
+    // The frontmatter must be a map of fields. A string or a list went
+    // through, and every field of the page was ignored without a word.
+    const data = parsed.data;
+    if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+      throw new LoaderError(`Frontmatter of ${relative}: a map of fields is expected.`, {
+        hint: 'Write "key: value" pairs, one per line — title: Installation.',
+      });
+    }
+    /** @type {Record<string, any>} */
+    const frontmatter = { ...data };
+
+    // The title feeds <title>, the menu and the JSON-LD: it must be text. A
+    // list came out as "one,two", an object as "[object Object]". A number
+    // reads as text; an empty title counts as none.
+    const title = frontmatter.title;
+    if (
+      title === null ||
+      title === undefined ||
+      (typeof title === 'string' && title.trim() === '')
+    ) {
+      delete frontmatter.title;
+    } else if (typeof title === 'number') {
+      frontmatter.title = String(title);
+    } else if (typeof title === 'string') {
+      frontmatter.title = title.trim();
+    } else {
+      throw new LoaderError(`Invalid title in ${relative}: text is expected.`, {
+        hint: 'title: My title — without brackets or braces.',
+      });
+    }
+
+    // A name without a Latin letter or a digit yields no URL: the page
+    // silently took the home page's place, or its folder vanished from the
+    // address.
+    const blank = blankSegments(relative);
+    if (blank.length > 0) {
+      throw new LoaderError(`"${relative}" yields no URL for "${blank.join('", "')}".`, {
+        hint: 'Give the file or folder a name that contains Latin letters or digits.',
+      });
+    }
+
+    const slug = filePathToSlug(relative);
+    return {
+      slug,
+      path: absolutePath,
+      url: slugToUrl(slug),
+      frontmatter,
+      content: parsed.content,
+      order: orderOf(path.basename(absolutePath)),
+    };
+  }
+
+  /**
+   * Refuses two documents that would produce the same URL.
+   *
+   * The classic case is `guide.md` and `guide/index.md`: two legitimate files,
+   * a single slug. Better to say so at build time than to ship a page
+   * overwritten by the other.
+   *
+   * @param {Doc[]} docs
+   * @throws {LoaderError}
+   */
+  #assertNoSlugCollision(docs) {
+    /** @type {Map<string, string>} */
+    const seen = new Map();
+
+    for (const doc of docs) {
+      const previous = seen.get(doc.slug);
+      if (previous !== undefined) {
+        throw new LoaderError(`Two files produce the same slug "${doc.slug || '(root)'}".`, {
+          hint: `Conflicting: ${previous} and ${doc.path}. Rename one of them.`,
+        });
+      }
+      seen.set(doc.slug, doc.path);
+    }
+  }
+}

package/src/sidebar.js

@@ -0,0 +1,105 @@
+/**
+ * Builds the sidebar from the loaded documents.
+ *
+ * @module @docpensieve/core/sidebar
+ */
+
+import { humanizeSlug } from '@docpensieve/shared';
+
+/**
+ * @typedef {object} SidebarNode
+ * @property {string} label   Displayed title.
+ * @property {string | null} url Page URL, or `null` for a folder without an
+ *   index page — the category is then a mere grouping.
+ * @property {SidebarNode[]} items Child entries.
+ */
+
+/**
+ * Builds the navigation tree of a version.
+ *
+ * The order is the `DocLoader`'s, which has already sorted: index page first,
+ * then numeric prefixes, then alphabetical. Nothing is re-sorted here, which
+ * guarantees that the sidebar follows the reading order of the files exactly.
+ *
+ * That order has a useful consequence: since `guide/index.md` is loaded
+ * before `guide/installation.md`, the “guide” category receives its real
+ * title before a child page creates it with a default one.
+ *
+ * @param {import('./loader.js').Doc[]} docs Documents in loader order.
+ * @param {(doc: import('./loader.js').Doc) => string} [toUrl] Turns a
+ *   document into a URL. By default, the document's URL as is.
+ * @param {{ brand?: string }} [options] `brand` is the name shown in the
+ *   header: a root entry carrying exactly that title is dropped, since the
+ *   brand already leads to that page. The same word twice, an inch apart,
+ *   tells the reader nothing.
+ * @returns {SidebarNode[]}
+ */
+export function buildSidebar(docs, toUrl = (doc) => doc.url, options = {}) {
+  /** @type {SidebarNode[]} */
+  const root = [];
+  /** @type {Map<string, SidebarNode>} */
+  const byPath = new Map();
+
+  for (const doc of docs) {
+    const label = doc.frontmatter?.title;
+    const segments = doc.slug ? doc.slug.split('/') : [];
+
+    // The root page has no segment: it becomes a top-level entry rather than
+    // the category that would hold everything else.
+    if (segments.length === 0) {
+      if (options.brand && label === options.brand) continue;
+      root.push({ label: label ?? 'Home', url: toUrl(doc), items: [] });
+      continue;
+    }
+
+    let level = root;
+    let path = '';
+
+    segments.forEach((segment, index) => {
+      path = path ? `${path}/${segment}` : segment;
+
+      let node = byPath.get(path);
+      if (!node) {
+        node = { label: humanizeSlug(segment), url: null, items: [] };
+        byPath.set(path, node);
+        level.push(node);
+      }
+
+      if (index === segments.length - 1) {
+        if (label) node.label = label;
+        node.url = toUrl(doc);
+      }
+
+      level = node.items;
+    });
+  }
+
+  return root;
+}
+
+/**
+ * Collects folder titles, for the breadcrumb.
+ *
+ * Only folders with an index page have a known title; the others will be
+ * humanised from their slug by `StructuredDataBuilder`.
+ *
+ * @param {import('./loader.js').Doc[]} docs
+ * @returns {Record<string, string>} Full folder slug to title.
+ */
+export function collectSectionTitles(docs) {
+  /** @type {Record<string, string>} */
+  const titles = {};
+
+  for (const doc of docs) {
+    const title = doc.frontmatter?.title;
+    if (!doc.slug || !title) continue;
+
+    // `guide/advanced/index.md` has the slug “guide/advanced”: that whole path
+    // names the folder. Keyed by its last segment alone, two folders sharing a
+    // name — `api/advanced` and `guide/advanced` — swapped their titles in the
+    // breadcrumb, first come first served.
+    if (titles[doc.slug] === undefined) titles[doc.slug] = String(title);
+  }
+
+  return titles;
+}

package/src/structured-data.js

@@ -0,0 +1,334 @@
+/**
+ * Builds the JSON-LD from the frontmatter.
+ *
+ * @module @docpensieve/core/structured-data
+ */
+
+import { JSONLD_TYPES, StructuredDataError, humanizeSlug, slugify } from '@docpensieve/shared';
+
+/** Article type used when the frontmatter names none. */
+const DEFAULT_TYPE = 'Article';
+
+/** Name of the first crumb of the breadcrumb. */
+const HOME_LABEL = 'Home';
+
+/** Matches a URL that is already absolute (with a scheme) or protocol-relative. */
+const ABSOLUTE_URL = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
+
+/**
+ * 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.
+ */
+function toISODate(value) {
+  if (value === undefined || value === null || value === '') return undefined;
+
+  /*
+   * A number is not a date: `new Date('42')` nevertheless returns
+   * 31 December 2041, and `new Date('0')` the year 2000. YAML turns an
+   * unquoted `date: 42` into a number, and the page ended up dated in the
+   * next century without anything saying so.
+   */
+  if (typeof value === 'number' || typeof value === 'boolean') return undefined;
+  if (!(value instanceof Date) && typeof value !== 'string') return undefined;
+
+  /*
+   * A bare date is read in UTC, not in the machine's time zone. Otherwise
+   * `2026-01-15 00:30` is read as local time then truncated to UTC: the
+   * published date moves back one day east of Greenwich, and the same source
+   * gives two different outputs depending on where it is built.
+   */
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? undefined : value.toISOString().slice(0, 10);
+  }
+
+  const text = value.trim();
+  // A calendar date, with or without a time: keep only the day, read in UTC.
+  const dateOnly = /^\d{4}-\d{2}-\d{2}([ T].*)?$/.test(text);
+  const date = dateOnly ? new Date(`${text.slice(0, 10)}T00:00:00Z`) : new Date(text);
+
+  if (Number.isNaN(date.getTime())) return undefined;
+
+  return date.toISOString().slice(0, 10);
+}
+
+/**
+ * Brings a value down to a list of non-empty strings.
+ *
+ * @param {unknown} value Single string, array, or nothing.
+ * @returns {string[]}
+ */
+function toList(value) {
+  const list = Array.isArray(value) ? value : value === undefined || value === null ? [] : [value];
+  return list.map((entry) => String(entry).trim()).filter(Boolean);
+}
+
+/**
+ * Lists the authors as `Person` nodes.
+ *
+ * @param {unknown} authors Single string or array of names.
+ * @returns {{ '@type': string, name: string }[]}
+ */
+function toPersons(authors) {
+  const list = Array.isArray(authors) ? authors : authors ? [authors] : [];
+  return list
+    .map((name) => String(name).trim())
+    .filter(Boolean)
+    .map((name) => ({ '@type': 'Person', name }));
+}
+
+/** Assembles a schema.org graph for a page. */
+export class StructuredDataBuilder {
+  /**
+   * @param {Record<string, any>} frontmatter Page frontmatter.
+   * @param {string} url Page URL on the site (`'/guide/install/'`).
+   * @param {Record<string, any>} config Normalised project config.
+   * @param {{ breadcrumbTitles?: Record<string, string>, basePath?: string, dirUrl?: string }} [options]
+   *   `breadcrumbTitles` maps a folder slug to its real title, so that the
+   *   breadcrumb shows “Café Guide” rather than “Cafe guide”. `basePath` is
+   *   the site root from which crumbs are counted: the generator sets
+   *   `/versions/v1.0/`, otherwise the breadcrumb would show “Versions” and
+   *   “V1.0”, which are neither pages nor titles. `dirUrl` is the source
+   *   file's folder as a URL: the base of the frontmatter's relative targets.
+   */
+  constructor(frontmatter, url, config, options = {}) {
+    this.frontmatter = frontmatter ?? {};
+    this.url = url;
+    this.config = config ?? {};
+    this.options = options;
+    this.breadcrumbTitles = options.breadcrumbTitles ?? {};
+    this.basePath = options.basePath ?? '/';
+    this.dirUrl = options.dirUrl;
+  }
+
+  /**
+   * Builds the page's schema.org graph.
+   *
+   * @returns {Record<string, any> | null} Object ready to serialise, or
+   *   `null` when structured data is turned off in the configuration.
+   * @throws {StructuredDataError} Unknown article type, or malformed FAQ.
+   */
+  build() {
+    if (this.config.jsonld?.enabled === false) return null;
+
+    const graph = [this.#organization(), this.#article()];
+
+    const breadcrumbs = this.#breadcrumbs();
+    if (breadcrumbs) graph.push(breadcrumbs);
+
+    const faq = this.#faq();
+    if (faq) graph.push(faq);
+
+    return { '@context': 'https://schema.org', '@graph': graph };
+  }
+
+  /**
+   * Serialises the graph into a tag ready for the `<head>`.
+   *
+   * @returns {string} `<script>` tag, or an empty string when disabled.
+   */
+  toScriptTag() {
+    const graph = this.build();
+    if (!graph) return '';
+
+    // A "</script>" or a "<!--" inside a title would close the tag. Escaping
+    // "<" is enough and stays valid JSON.
+    const json = JSON.stringify(graph).replaceAll('<', '\\u003c');
+    return `<script type="application/ld+json">${json}</script>`;
+  }
+
+  /**
+   * Makes a site URL absolute.
+   *
+   * Without a configured `siteUrl`, URLs stay relative: the graph is then less
+   * useful to search engines, but generation is not blocked for all that.
+   *
+   * @param {string} target
+   * @returns {string}
+   */
+  #absolute(target) {
+    if (!this.config.siteUrl || ABSOLUTE_URL.test(target)) return target;
+    return new URL(target, this.config.siteUrl).href;
+  }
+
+  /**
+   * Resolves a target written by the author, following the link rules
+   * (ADR-006).
+   *
+   * A relative target starts from the page's folder, an absolute one from the
+   * version root. Resolved against the site root, a “preview: ./thumb.png”
+   * pointed to an image that does not exist.
+   *
+   * @param {string} target
+   * @returns {string}
+   */
+  #target(target) {
+    if (ABSOLUTE_URL.test(target)) return target;
+    const root = this.basePath.endsWith('/') ? this.basePath.slice(0, -1) : this.basePath;
+    if (target.startsWith('/')) {
+      return this.basePath === '/' || target.startsWith(this.basePath) ? target : root + target;
+    }
+    const resolved = new URL(target, `https://docpensieve.invalid${this.dirUrl ?? this.url}`);
+    return resolved.pathname + resolved.search + resolved.hash;
+  }
+
+  /** @returns {string} Stable identifier of the organisation in the graph. */
+  #organizationId() {
+    /*
+     * The deployment prefix is part of the identity. Without it, two sites
+     * hosted on the same origin — two projects of the same pages account —
+     * would claim the same identifier under different names, and an engine
+     * reconciling by identifier would merge them.
+     */
+    return `${this.#absolute(this.config.baseUrl)}#organization`;
+  }
+
+  /** @returns {Record<string, any>} `Organization` node. */
+  #organization() {
+    /** @type {Record<string, any>} */
+    const node = {
+      '@type': 'Organization',
+      '@id': this.#organizationId(),
+      name: this.config.projectName,
+    };
+    if (this.config.siteUrl) node.url = this.config.siteUrl;
+    return node;
+  }
+
+  /**
+   * @returns {Record<string, any>} `Article`, `TechArticle` or `BlogPosting` node.
+   * @throws {StructuredDataError} When `jsonld.type` is not recognised.
+   */
+  #article() {
+    const type = this.frontmatter.jsonld?.type ?? DEFAULT_TYPE;
+    if (!JSONLD_TYPES.includes(type)) {
+      throw new StructuredDataError(`Unknown JSON-LD type: "${type}".`, {
+        hint: `Accepted values for jsonld.type in the frontmatter: ${JSONLD_TYPES.join(', ')}.`,
+      });
+    }
+
+    const pageUrl = this.#absolute(this.url);
+    /** @type {Record<string, any>} */
+    const node = {
+      '@type': type,
+      '@id': `${pageUrl}#article`,
+      headline: this.frontmatter.title ?? this.config.projectName,
+      mainEntityOfPage: { '@type': 'WebPage', '@id': pageUrl },
+      publisher: { '@id': this.#organizationId() },
+    };
+
+    if (this.frontmatter.description) node.description = this.frontmatter.description;
+
+    const published = toISODate(this.frontmatter.date);
+    if (published) node.datePublished = published;
+
+    // Without an explicit modification date, the publication date stands: an
+    // article never edited was indeed “modified” on the day it came out.
+    const modified = toISODate(this.frontmatter.modified) ?? published;
+    // A modification earlier than the publication describes an impossibility:
+    // publishing it would assert it.
+    if (published && modified && modified < published) {
+      throw new StructuredDataError(
+        `Modification date earlier than publication: ${modified} before ${published}.`,
+        { hint: 'Fix "modified" or "date" in the page frontmatter.' },
+      );
+    }
+    if (modified) node.dateModified = modified;
+
+    const authors = toPersons(this.frontmatter.authors);
+    if (authors.length > 0) node.author = authors;
+
+    // A single tag is written without brackets, like a single author.
+    // Accepting only the array lost the value without a word.
+    const tags = toList(this.frontmatter.tags);
+    if (tags.length > 0) node.keywords = tags;
+
+    if (this.frontmatter.preview) {
+      node.image = this.#absolute(this.#target(String(this.frontmatter.preview)));
+    }
+
+    return node;
+  }
+
+  /**
+   * Derives the breadcrumb from the URL path.
+   *
+   * @returns {Record<string, any> | null} `null` on the home page, where a
+   *   single crumb would tell nothing, or when the frontmatter turns them off.
+   */
+  #breadcrumbs() {
+    if (this.frontmatter.jsonld?.breadcrumbs === false) return null;
+
+    const relative = this.url.startsWith(this.basePath)
+      ? this.url.slice(this.basePath.length)
+      : this.url;
+    const segments = relative.split('/').filter(Boolean);
+    if (segments.length === 0) return null;
+
+    const items = [{ name: HOME_LABEL, url: this.#absolute(this.basePath) }];
+
+    let currentPath = this.basePath.replace(/\/$/, '');
+    segments.forEach((segment, index) => {
+      currentPath += `/${segment}`;
+      const isLast = index === segments.length - 1;
+      items.push({
+        name: isLast
+          ? (this.frontmatter.title ?? humanizeSlug(segment))
+          : (this.breadcrumbTitles[segments.slice(0, index + 1).join('/')] ??
+            humanizeSlug(segment)),
+        url: this.#absolute(`${currentPath}/`),
+      });
+    });
+
+    return {
+      '@type': 'BreadcrumbList',
+      '@id': `${this.#absolute(this.url)}#breadcrumb`,
+      itemListElement: items.map((item, index) => ({
+        '@type': 'ListItem',
+        position: index + 1,
+        name: item.name,
+        item: item.url,
+      })),
+    };
+  }
+
+  /**
+   * @returns {Record<string, any> | null} `FAQPage` node, or `null` without FAQ.
+   * @throws {StructuredDataError} When an entry lacks a question or an answer.
+   */
+  #faq() {
+    const entries = this.frontmatter.jsonld?.faq;
+    if (!Array.isArray(entries) || entries.length === 0) return null;
+
+    const questions = entries.map((entry, index) => {
+      if (!entry?.question || !entry?.answer) {
+        throw new StructuredDataError(
+          `Incomplete FAQ entry at position ${index + 1} (page ${this.url}).`,
+          { hint: 'Every jsonld.faq entry must carry "question" and "answer".' },
+        );
+      }
+      return {
+        '@type': 'Question',
+        // The rank is always a suffix: two questions that only punctuation
+        // tells apart give the same slug, and two nodes with the same
+        // identifier are one to a JSON-LD processor — the second disappears.
+        '@id': `${this.#absolute(this.url)}#faq-${index + 1}-${slugify(entry.question)}`.replace(
+          /-$/,
+          '',
+        ),
+        name: String(entry.question),
+        acceptedAnswer: { '@type': 'Answer', text: String(entry.answer) },
+      };
+    });
+
+    return {
+      '@type': 'FAQPage',
+      '@id': `${this.#absolute(this.url)}#faq`,
+      mainEntity: questions,
+    };
+  }
+}