@opentf/web-docs 0.1.0 → 0.3.0

package/build/blog-posts-plugin.js

@@ -0,0 +1,127 @@
+// Build-time blog post index generator (a Rolldown plugin), the blog counterpart of
+// docs-nav-plugin.js. It scans `app/<dir>` for post folders (`<slug>/page.{mdx,md}`),
+// reads each post's frontmatter + computes its reading time, and resolves the virtual
+// module `@opentf/web-docs/posts` to the ordered post list. A pure build-time
+// consumer of the file tree — no compiler stage, no runtime cost.
+//
+// Post shape: `{ slug, path, title, description?, date?, author?, tags?, readingTime,
+// order? }`. Sorted newest-first by `date`; a numeric `order` (frontmatter) overrides.
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { readFrontmatter } from "./frontmatter.js";
+import { readingTime } from "./reading-time.js";
+
+const VIRTUAL_ID = "@opentf/web-docs/posts";
+const RESOLVED_ID = "\0otfw-blog-posts";
+const PAGE_RE = /^page\.(mdx|md)$/;
+
+/**
+ * @param {Object} opts
+ * @param {string} opts.appDir       Absolute path to the project's `app/` directory.
+ * @param {string} [opts.contentDir] Blog content folder under app/ (default "blog").
+ * @param {Set<string>} [opts.exclude] Folder names to skip.
+ */
+export function blogPostsPlugin({ appDir, contentDir = "blog", exclude = new Set() } = {}) {
+  const root = join(appDir, contentDir);
+  const base = "/" + contentDir;
+  return {
+    name: "otfw-blog-posts",
+    resolveId(source) {
+      return source === VIRTUAL_ID ? RESOLVED_ID : null;
+    },
+    load(id) {
+      if (id !== RESOLVED_ID) return null;
+      const watch = [];
+      const posts = existsSync(root) ? collectPosts(root, base, exclude, watch) : [];
+      for (const f of watch) this.addWatchFile?.(f);
+      return `export const posts = ${JSON.stringify(posts)};\nexport default posts;\n`;
+    },
+  };
+}
+
+/**
+ * Scan the blog content folder and return the ordered post list — the same array the
+ * `blogPostsPlugin` virtual module exposes, but callable directly (used by the feed
+ * generator at build time). Returns `[]` when the folder is absent.
+ *
+ * @param {Object} opts
+ * @param {string} opts.appDir
+ * @param {string} [opts.contentDir]
+ * @param {Set<string>} [opts.exclude]
+ */
+export function loadPosts({ appDir, contentDir = "blog", exclude = new Set() } = {}) {
+  const root = join(appDir, contentDir);
+  if (!existsSync(root)) return [];
+  return collectPosts(root, "/" + contentDir, exclude, []);
+}
+
+function collectPosts(root, base, exclude, watch) {
+  const posts = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (
+      !entry.isDirectory() ||
+      entry.name.startsWith(".") ||
+      entry.name.startsWith("_") ||
+      exclude.has(entry.name)
+    ) {
+      continue;
+    }
+    const dir = join(root, entry.name);
+    const page = readdirSync(dir).find((n) => PAGE_RE.test(n));
+    if (!page) continue;
+
+    const file = join(dir, page);
+    watch.push(file);
+    const source = readFileSync(file, "utf8");
+    const fm = readFrontmatter(file);
+    posts.push(
+      clean({
+        slug: entry.name,
+        path: `${base}/${entry.name}`,
+        title: fm.title ?? humanize(entry.name),
+        description: fm.description,
+        date: fm.date != null ? String(fm.date) : undefined,
+        // Cover image (frontmatter `cover`) — shown on the post banner and the card.
+        cover: fm.cover,
+        author: fm.author,
+        authorAvatar: fm.author_avatar,
+        authorRole: fm.author_role,
+        // Frontmatter is flat scalars, so `tags: a, b` arrives as a string; normalize
+        // to a trimmed array. Components can render chips from it.
+        tags: typeof fm.tags === "string" ? splitTags(fm.tags) : undefined,
+        readingTime: readingTime(source),
+        order: typeof fm.order === "number" ? fm.order : undefined,
+      }),
+    );
+  }
+  return sortPosts(posts);
+}
+
+/** Newest-first by `date`; a numeric `order` wins when present; title breaks ties. */
+function sortPosts(posts) {
+  return posts.sort((a, b) => {
+    if (a.order != null || b.order != null) {
+      return (a.order ?? Number.MAX_SAFE_INTEGER) - (b.order ?? Number.MAX_SAFE_INTEGER);
+    }
+    if (a.date && b.date && a.date !== b.date) return a.date < b.date ? 1 : -1;
+    if (a.date && !b.date) return -1;
+    if (!a.date && b.date) return 1;
+    return a.title.localeCompare(b.title);
+  });
+}
+
+function splitTags(s) {
+  const tags = s.split(",").map((t) => t.trim()).filter(Boolean);
+  return tags.length ? tags : undefined;
+}
+
+function humanize(seg) {
+  return seg.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+function clean(node) {
+  for (const k of Object.keys(node)) if (node[k] === undefined) delete node[k];
+  return node;
+}

package/build/docs-nav-plugin.js

@@ -22,17 +22,16 @@ const PAGE_RE = /^page\.(mdx|md|[jt]sx)$/;
 const MD_RE = /\.(mdx|md)$/;
 
 /**
+ * Generates `@opentf/web-docs/nav` as a **section map** — `{ "/<dir>": tree }`, one entry
+ * per top-level folder under `app/`. Each folder is a potential `DocsLayout` section; the
+ * layout selects its own subtree by the current route, so any number of sections (`/docs`,
+ * `/api`, …) "just work" with no config — drop a folder in and give it a `DocsLayout`.
+ *
  * @param {Object} opts
- * @param {string} opts.appDir      Absolute path to the project's `app/` directory.
- * @param {string} [opts.contentDir] Docs content folder under app/ (default "docs").
+ * @param {string} opts.appDir       Absolute path to the project's `app/` directory.
  * @param {Set<string>} [opts.exclude] Folder names to skip (mirrors route exclusions).
  */
-export function docsNavPlugin({ appDir, contentDir = "docs", exclude = new Set() } = {}) {
-  // `"."`/`""` means the docs live at the app root (routes at "/"); otherwise they
-  // live in app/<contentDir> (routes under "/<contentDir>").
-  const atRoot = contentDir === "." || contentDir === "";
-  const root = atRoot ? appDir : join(appDir, contentDir);
-  const base = atRoot ? "" : "/" + contentDir;
+export function docsNavPlugin({ appDir, exclude = new Set() } = {}) {
   return {
     name: "otfw-docs-nav",
     resolveId(source) {
@@ -42,10 +41,18 @@ export function docsNavPlugin({ appDir, contentDir = "docs", exclude = new Set()
     async load(id) {
       if (id !== RESOLVED_ID) return null;
       const watch = [];
-      const tree = existsSync(root) ? await buildSection(root, base, watch, true, exclude) : [];
+      const out = {};
+      for (const entry of readdirSync(appDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        if (entry.name.startsWith(".") || entry.name.startsWith("_") || exclude.has(entry.name)) {
+          continue;
+        }
+        const base = "/" + entry.name;
+        out[base] = await buildSection(join(appDir, entry.name), base, watch, true, exclude);
+      }
       // Rebuild on changes to meta/page files during `otfw dev`.
       for (const f of watch) this.addWatchFile?.(f);
-      return `export default ${JSON.stringify(tree)};\n`;
+      return `export default ${JSON.stringify(out)};\n`;
     },
   };
 }

package/build/feed.js

@@ -0,0 +1,136 @@
+// RSS/Atom feed generation for the blog. Pure, build-time counterparts to the
+// sitemap: given the post list (from `loadPosts`) plus the site origin and channel
+// metadata, render feed XML strings. The web-cli build writes them to
+// `dist/<blogDir>/rss.xml` and `dist/<blogDir>/atom.xml` when a base URL is configured.
+//
+// RSS 2.0 (https://www.rssboard.org/rss-specification) is the lowest-common-
+// denominator feed format: every reader supports it, and `<pubDate>` must be RFC-822.
+
+/** XML text-escape (the five predefined entities). */
+function esc(s) {
+  return String(s).replace(/[&<>'"]/g, (c) =>
+    c === "&" ? "&amp;" : c === "<" ? "&lt;" : c === ">" ? "&gt;" : c === "'" ? "&apos;" : "&quot;",
+  );
+}
+
+/** Absolute URL from a (trailing-slash-trimmed) origin + an absolute path. */
+function abs(baseUrl, path) {
+  return baseUrl.replace(/\/+$/, "") + (path.startsWith("/") ? path : "/" + path);
+}
+
+/** `YYYY-MM-DD` (or any Date-parseable string) → RFC-822, e.g. for `<pubDate>`. */
+function rfc822(date) {
+  if (!date) return null;
+  const d = new Date(date);
+  return Number.isNaN(d.getTime()) ? null : d.toUTCString();
+}
+
+/** `YYYY-MM-DD` (or any Date-parseable string) -> ISO-8601 for Atom timestamps. */
+function iso8601(date) {
+  if (!date) return null;
+  const d = new Date(date);
+  return Number.isNaN(d.getTime()) ? null : d.toISOString();
+}
+
+/**
+ * Render an RSS 2.0 feed.
+ *
+ * @param {Object} opts
+ * @param {Array}  opts.posts        Post list (from `loadPosts`).
+ * @param {string} opts.baseUrl      Canonical site origin (required; absolute links).
+ * @param {string} [opts.feedPath]   Path of the feed itself (for `<atom:link rel=self>`).
+ * @param {Object} [opts.channel]    `{ title, description, link, language }`.
+ * @returns {string} The `rss.xml` document.
+ */
+export function renderBlogFeed({ posts = [], baseUrl, feedPath = "/blog/rss.xml", channel = {} } = {}) {
+  const title = channel.title || "Blog";
+  const description = channel.description || title;
+  const link = channel.link ? abs(baseUrl, channel.link) : abs(baseUrl, "/blog");
+  const language = channel.language || "en";
+  const self = abs(baseUrl, feedPath);
+  const lastBuild = rfc822(posts.find((p) => p.date)?.date) || new Date().toUTCString();
+
+  const items = posts
+    .map((p) => {
+      const url = abs(baseUrl, p.path);
+      const pubDate = rfc822(p.date);
+      const parts = [
+        `      <title>${esc(p.title)}</title>`,
+        `      <link>${esc(url)}</link>`,
+        `      <guid isPermaLink="true">${esc(url)}</guid>`,
+      ];
+      if (pubDate) parts.push(`      <pubDate>${pubDate}</pubDate>`);
+      if (p.author) parts.push(`      <dc:creator>${esc(p.author)}</dc:creator>`);
+      if (p.description) parts.push(`      <description>${esc(p.description)}</description>`);
+      for (const tag of p.tags || []) parts.push(`      <category>${esc(tag)}</category>`);
+      return `    <item>\n${parts.join("\n")}\n    </item>`;
+    })
+    .join("\n");
+
+  return (
+    `<?xml version="1.0" encoding="UTF-8"?>\n` +
+    `<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">\n` +
+    `  <channel>\n` +
+    `    <title>${esc(title)}</title>\n` +
+    `    <link>${esc(link)}</link>\n` +
+    `    <atom:link href="${esc(self)}" rel="self" type="application/rss+xml"/>\n` +
+    `    <description>${esc(description)}</description>\n` +
+    `    <language>${esc(language)}</language>\n` +
+    `    <lastBuildDate>${lastBuild}</lastBuildDate>\n` +
+    `    <generator>@opentf/web-docs</generator>\n` +
+    (items ? items + "\n" : "") +
+    `  </channel>\n` +
+    `</rss>\n`
+  );
+}
+
+/**
+ * Render an Atom 1.0 feed.
+ *
+ * @param {Object} opts
+ * @param {Array}  opts.posts        Post list (from `loadPosts`).
+ * @param {string} opts.baseUrl      Canonical site origin (required; absolute links).
+ * @param {string} [opts.feedPath]   Path of the feed itself (for `<link rel=self>`).
+ * @param {Object} [opts.channel]    `{ title, description, link, author }`.
+ * @returns {string} The `atom.xml` document.
+ */
+export function renderAtomFeed({ posts = [], baseUrl, feedPath = "/blog/atom.xml", channel = {} } = {}) {
+  const title = channel.title || "Blog";
+  const description = channel.description || title;
+  const link = channel.link ? abs(baseUrl, channel.link) : abs(baseUrl, "/blog");
+  const self = abs(baseUrl, feedPath);
+  const updated = iso8601(posts.find((p) => p.date)?.date) || new Date().toISOString();
+  const fallbackAuthor = channel.author || title;
+
+  const entries = posts
+    .map((p) => {
+      const url = abs(baseUrl, p.path);
+      const published = iso8601(p.date);
+      const parts = [
+        `    <title>${esc(p.title)}</title>`,
+        `    <link href="${esc(url)}"/>`,
+        `    <id>${esc(url)}</id>`,
+        `    <updated>${published || updated}</updated>`,
+      ];
+      if (published) parts.push(`    <published>${published}</published>`);
+      parts.push(`    <author><name>${esc(p.author || fallbackAuthor)}</name></author>`);
+      if (p.description) parts.push(`    <summary>${esc(p.description)}</summary>`);
+      for (const tag of p.tags || []) parts.push(`    <category term="${esc(tag)}"/>`);
+      return `  <entry>\n${parts.join("\n")}\n  </entry>`;
+    })
+    .join("\n");
+
+  return (
+    `<?xml version="1.0" encoding="UTF-8"?>\n` +
+    `<feed xmlns="http://www.w3.org/2005/Atom">\n` +
+    `  <title>${esc(title)}</title>\n` +
+    `  <subtitle>${esc(description)}</subtitle>\n` +
+    `  <link href="${esc(link)}"/>\n` +
+    `  <link href="${esc(self)}" rel="self" type="application/atom+xml"/>\n` +
+    `  <id>${esc(link)}</id>\n` +
+    `  <updated>${updated}</updated>\n` +
+    `  <generator>@opentf/web-docs</generator>\n` +
+    (entries ? entries + "\n" : "") +
+    `</feed>\n`
+  );
+}

package/build/index.js

@@ -5,3 +5,8 @@
 // from web-cli keeps all docs-specific build logic owned by this package.
 
 export { docsNavPlugin } from "./docs-nav-plugin.js";
+export { blogPostsPlugin, loadPosts } from "./blog-posts-plugin.js";
+export { lastUpdatedPlugin, loadLastUpdated } from "./last-updated-plugin.js";
+export { renderAtomFeed, renderBlogFeed } from "./feed.js";
+export { renderLlmsFullTxt, renderLlmsTxt } from "./llms.js";
+export { indexWithPagefind } from "./pagefind.js";

package/build/last-updated-plugin.js

@@ -0,0 +1,98 @@
+// Build-time "last updated" map generator (a Rolldown plugin), sibling of the nav and
+// blog-posts plugins. It walks every page under `app/`, resolves each one's last-updated
+// time (git commit or frontmatter override — see last-updated.js), and resolves the
+// virtual module `@opentf/web-docs/updated` to a `{ [routePath]: ISO }` map. Layouts look
+// the current route up in that map to render a "Last updated" line — so every section
+// gets it from one switch, no per-section config.
+//
+// The same map is needed by the SSG step for the `article:modified_time` SEO tag, so
+// the scan is exposed as a callable (`loadLastUpdated`) too.
+
+import { execFileSync } from "node:child_process";
+import { readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+
+import { readFrontmatter } from "./frontmatter.js";
+import { resolveLastUpdated } from "./last-updated.js";
+
+const VIRTUAL_ID = "@opentf/web-docs/updated";
+const RESOLVED_ID = "\0otfw-last-updated";
+const PAGE_RE = /^page\.(mdx|md|[jt]sx)$/;
+const MD_RE = /\.(mdx|md)$/;
+
+/**
+ * @param {Object} opts
+ * @param {string} opts.appDir
+ * @param {Set<string>} [opts.exclude] Folder names to skip (mirrors route exclusions).
+ */
+export function lastUpdatedPlugin({ appDir, exclude = new Set() } = {}) {
+  return {
+    name: "otfw-last-updated",
+    resolveId(source) {
+      return source === VIRTUAL_ID ? RESOLVED_ID : null;
+    },
+    load(id) {
+      if (id !== RESOLVED_ID) return null;
+      const watch = [];
+      const { updated, editPaths } = collect(appDir, exclude, watch);
+      for (const f of watch) this.addWatchFile?.(f);
+      // Default export: the `{ route: ISO }` last-updated map. Named `editPaths`:
+      // `{ route: repo-relative-file }`, for building "Edit this page" links.
+      return (
+        `export default ${JSON.stringify(updated)};\n` +
+        `export const editPaths = ${JSON.stringify(editPaths)};\n`
+      );
+    },
+  };
+}
+
+/**
+ * The `{ [routePath]: ISO }` last-updated map, callable directly (used by the SSG SEO
+ * step). Mirrors what the virtual module exposes.
+ */
+export function loadLastUpdated({ appDir, exclude = new Set() } = {}) {
+  return collect(appDir, exclude, []).updated;
+}
+
+/** Git repo root containing `dir`, or null (so edit links degrade gracefully). */
+function gitRoot(dir) {
+  try {
+    return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd: dir,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function collect(appDir, exclude, watch) {
+  const updated = {};
+  const editPaths = {};
+  const root0 = gitRoot(appDir);
+  // One walk over every page under app/ — covers all sections (and the home page).
+  walk(appDir, "", exclude, (file, route) => {
+    watch.push(file);
+    const fm = MD_RE.test(file) ? readFrontmatter(file) : {};
+    const iso = resolveLastUpdated(file, fm.lastUpdated);
+    if (iso) updated[route] = iso;
+    // Repo-relative path (POSIX separators) for the "Edit this page" link.
+    if (root0) editPaths[route] = relative(root0, file).split(/[\\/]/).join("/");
+  });
+  return { updated, editPaths };
+}
+
+/** Recursively find every `page.*` under `root`, mapping it to its route path. */
+function walk(dir, route, exclude, onPage) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (entry.name.startsWith(".") || entry.name.startsWith("_") || exclude.has(entry.name)) {
+        continue;
+      }
+      walk(join(dir, entry.name), `${route}/${entry.name}`, exclude, onPage);
+    } else if (PAGE_RE.test(entry.name)) {
+      onPage(join(dir, entry.name), route || "/");
+    }
+  }
+}

package/build/last-updated.js

@@ -0,0 +1,45 @@
+// "Last updated" resolution for a page file. Two sources only (build time):
+//
+//   1. A frontmatter override — `lastUpdated: 2026-06-25` (any Date-parseable value)
+//      pins the date; `lastUpdated: false` hides it for that page.
+//   2. The file's last git commit (committer date, `git log -1 --format=%cI`).
+//
+// No file-mtime fallback: mtime is noise (a checkout/copy bumps it), so when the file
+// isn't in git history the value is simply null and the UI omits it. This runs in dev
+// and build alike — the displayed time is always the real last content change.
+
+import { execFileSync } from "node:child_process";
+import { dirname } from "node:path";
+
+/** Last git commit (committer ISO-8601) that touched `file`, or null. */
+export function gitLastUpdated(file) {
+  try {
+    const out = execFileSync("git", ["log", "-1", "--format=%cI", "--", file], {
+      cwd: dirname(file),
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    return out || null; // empty = untracked / no history (e.g. a shallow CI clone)
+  } catch {
+    return null; // not a git repo / git unavailable
+  }
+}
+
+/** Normalize a frontmatter override to ISO-8601, or keep the raw string if unparseable. */
+function normalize(value) {
+  const d = new Date(value);
+  return Number.isNaN(d.getTime()) ? String(value) : d.toISOString();
+}
+
+/**
+ * Resolve a page's last-updated timestamp.
+ *
+ * @param {string} file            Absolute path to the page file.
+ * @param {*}      [frontmatter]   The frontmatter `lastUpdated` value, if any.
+ * @returns {string|null} ISO-8601 (or a raw override string), or null to omit.
+ */
+export function resolveLastUpdated(file, frontmatter) {
+  if (frontmatter === false) return null; // explicit opt-out for this page
+  if (frontmatter != null && frontmatter !== true) return normalize(frontmatter);
+  return gitLastUpdated(file);
+}

package/build/llms.js

@@ -0,0 +1,156 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, relative, sep } from "node:path";
+
+import { readFrontmatter } from "./frontmatter.js";
+
+const PAGE_RE = /(^|[\\/])page\.(mdx|md|[jt]sx)$/;
+const MD_RE = /\.(mdx|md)$/;
+
+function abs(baseUrl, path) {
+  return baseUrl.replace(/\/+$/, "") + (path === "/" ? "/" : path);
+}
+
+function routePath(appDir, file) {
+  const rel = relative(appDir, file).split(sep).join("/");
+  if (!PAGE_RE.test(rel)) return null;
+  const dir = dirname(rel).split(sep).join("/");
+  if (dir === ".") return "/";
+  const segments = dir.split("/");
+  if (segments.some((seg) => seg.startsWith("_") || seg.startsWith(".") || seg.includes("["))) {
+    return null;
+  }
+  return "/" + segments.join("/");
+}
+
+function humanize(seg) {
+  return seg.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+function titleFor(file, path) {
+  const fm = MD_RE.test(file) ? readFrontmatter(file) : {};
+  if (fm.title) return String(fm.title);
+  if (path === "/") return "Home";
+  return humanize(path.split("/").filter(Boolean).at(-1) ?? "Home");
+}
+
+function descriptionFor(file) {
+  const fm = MD_RE.test(file) ? readFrontmatter(file) : {};
+  return fm.description ? String(fm.description) : "";
+}
+
+function stripFrontmatter(source) {
+  return source.replace(/^?---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
+}
+
+function stripMdxBoilerplate(source) {
+  const lines = stripFrontmatter(source).split(/\r?\n/);
+  const out = [];
+  let inFence = false;
+  for (const line of lines) {
+    if (/^```/.test(line.trim())) inFence = !inFence;
+    if (!inFence && /^\s*import\s/.test(line)) continue;
+    if (!inFence && /^\s*export\s+(const|let|var|default)\s/.test(line)) continue;
+    out.push(line);
+  }
+  return out.join("\n").trim();
+}
+
+function sectionFor(path) {
+  if (path === "/") return "Start Here";
+  if (path.startsWith("/docs")) return "Documentation";
+  if (path.startsWith("/api")) return "API Reference";
+  if (path.startsWith("/blog")) return "Blog";
+  return "Other Routes";
+}
+
+function pageRecords({ appDir, pages = [], baseUrl }) {
+  return pages
+    .filter((file) => PAGE_RE.test(file))
+    .map((file) => {
+      const path = routePath(appDir, file);
+      if (!path) return null;
+      return {
+        file,
+        path,
+        url: abs(baseUrl, path),
+        title: titleFor(file, path),
+        description: descriptionFor(file),
+        markdown: MD_RE.test(file) && existsSync(file) ? stripMdxBoilerplate(readFileSync(file, "utf8")) : "",
+      };
+    })
+    .filter(Boolean)
+    .sort((a, b) => {
+      if (a.path === "/") return -1;
+      if (b.path === "/") return 1;
+      return a.path.localeCompare(b.path);
+    });
+}
+
+function grouped(records) {
+  const out = new Map();
+  for (const record of records) {
+    const section = sectionFor(record.path);
+    if (!out.has(section)) out.set(section, []);
+    out.get(section).push(record);
+  }
+  return out;
+}
+
+const SECTION_ORDER = ["Start Here", "Documentation", "API Reference", "Blog", "Other Routes"];
+
+export function renderLlmsTxt({ appDir, pages = [], baseUrl, config = {} } = {}) {
+  const title = config?.docs?.title || "OTF Web";
+  const records = pageRecords({ appDir, pages, baseUrl });
+  const description =
+    config?.docs?.description ||
+    "Documentation, API reference, and blog content for the OTF Web framework.";
+  const lines = [
+    `# ${title}`,
+    "",
+    `> ${description}`,
+    "",
+    `This file is a curated entry point for language models. For full page content, see [llms-full.txt](${abs(baseUrl, "/llms-full.txt")}).`,
+    "",
+  ];
+
+  const groups = grouped(records);
+  for (const section of SECTION_ORDER) {
+    const items = groups.get(section);
+    if (!items?.length) continue;
+    lines.push(`## ${section}`, "");
+    for (const item of items) {
+      const note = item.description ? `: ${item.description}` : "";
+      lines.push(`- [${item.title}](${item.url})${note}`);
+    }
+    lines.push("");
+  }
+
+  if (config?.blog) {
+    lines.push("## Optional", "");
+    lines.push(`- [RSS feed](${abs(baseUrl, `/${config.blog.dir ?? "blog"}/rss.xml`)}): Blog feed in RSS 2.0 format.`);
+    lines.push(`- [Atom feed](${abs(baseUrl, `/${config.blog.dir ?? "blog"}/atom.xml`)}): Blog feed in Atom 1.0 format.`);
+  }
+  return lines.join("\n").replace(/\n{3,}/g, "\n\n").trim() + "\n";
+}
+
+export function renderLlmsFullTxt({ appDir, pages = [], baseUrl, config = {} } = {}) {
+  const title = config?.docs?.title || "OTF Web";
+  const records = pageRecords({ appDir, pages, baseUrl }).filter((record) => record.markdown);
+  const lines = [
+    `# ${title} Full Documentation`,
+    "",
+    `Generated from filesystem routes for ${baseUrl.replace(/\/+$/, "")}.`,
+    "",
+  ];
+
+  for (const record of records) {
+    lines.push(`## ${record.title}`, "");
+    lines.push(`URL: ${record.url}`);
+    if (record.description) lines.push(`Description: ${record.description}`);
+    lines.push("");
+    lines.push(record.markdown);
+    lines.push("");
+  }
+
+  return lines.join("\n").replace(/\n{3,}/g, "\n\n").trim() + "\n";
+}

package/build/pagefind.js

@@ -0,0 +1,58 @@
+// Post-build Pagefind indexing for the docs site (Phase 2 search).
+//
+// Runs after the SSG pre-render, over the built HTML in `dist/`. Pagefind reads the
+// `data-pagefind-body` region of each page (the docs `<main id="otfw-content">`) and
+// writes a static, fragmented search index to `dist/pagefind/`. The runtime `<Search>`
+// modal loads `/pagefind/pagefind.js` on demand and queries that index — no server.
+//
+// `@opentf/web-cli` calls this from `otfw build --ssg` when the project's docs config
+// has `search.provider === "pagefind"`, keeping all docs build logic owned by web-docs.
+
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+
+/** Recursively collect every `*.html` file under `dir` (absolute paths). */
+async function htmlFiles(dir) {
+  const out = [];
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...(await htmlFiles(path)));
+    else if (entry.name.endsWith(".html")) out.push(path);
+  }
+  return out;
+}
+
+/**
+ * Index a built site directory with Pagefind, file by file so callers can show
+ * progress. Only pages that opted into search (`data-pagefind-body`, the docs shell)
+ * are added — matching Pagefind's site-wide body-exclusion rule deterministically.
+ *
+ * @param {{ siteDir: string, onProgress?: (done: number, total: number) => void }} opts
+ * @returns {Promise<{ pages: number, errors: string[] }>}
+ */
+export async function indexWithPagefind({ siteDir, onProgress }) {
+  // Lazy import so the (native) Pagefind binary is only loaded when search is enabled.
+  const pagefind = await import("pagefind");
+  const { index } = await pagefind.createIndex();
+
+  // Pick the searchable pages up front so progress has a real total.
+  const pages = [];
+  for (const path of await htmlFiles(siteDir)) {
+    const content = await readFile(path, "utf8");
+    if (content.includes("data-pagefind-body")) pages.push({ path, content });
+  }
+
+  const total = pages.length;
+  const errors = [];
+  let done = 0;
+  onProgress?.(0, total);
+  for (const { path, content } of pages) {
+    const res = await index.addHTMLFile({ sourcePath: relative(siteDir, path), content });
+    if (res.errors && res.errors.length) errors.push(...res.errors);
+    onProgress?.(++done, total);
+  }
+
+  await index.writeFiles({ outputPath: join(siteDir, "pagefind") });
+  await pagefind.close();
+  return { pages: total, errors };
+}