@opentf/web-docs 0.1.0 → 0.2.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 RSS
+ * 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,78 @@
+// RSS 2.0 feed generation for the blog. A pure, build-time counterpart to the
+// sitemap: given the post list (from `loadPosts`) plus the site origin and channel
+// metadata, it renders an `rss.xml` string. The web-cli build writes it to
+// `dist/<blogDir>/rss.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();
+}
+
+/**
+ * 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`
+  );
+}

package/build/index.js

@@ -5,3 +5,7 @@
 // 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 { renderBlogFeed } from "./feed.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/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 };
+}

package/build/reading-time.js

@@ -0,0 +1,16 @@
+// Estimate a post's reading time (minutes) from its Markdown source. Strips
+// frontmatter, code, HTML/JSX tags, and Markdown punctuation before counting words,
+// then divides by `wpm` (200 words/min ≈ average adult prose reading). Build-time
+// only — the result ships as data on each post (see blog-posts-plugin.js).
+export function readingTime(source, wpm = 200) {
+  const body = String(source || "")
+    .replace(/^?---\r?\n[\s\S]*?\r?\n---/, "") // frontmatter
+    .replace(/```[\s\S]*?```/g, " ") // fenced code
+    .replace(/`[^`]*`/g, " ") // inline code
+    .replace(/<[^>]+>/g, " ") // html / jsx tags
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, " ") // images
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1") // links → their text
+    .replace(/[#>*_~`\-]+/g, " "); // residual md punctuation
+  const words = body.split(/\s+/).filter(Boolean).length;
+  return Math.max(1, Math.round(words / wpm));
+}

package/components/BlogLayout.jsx

@@ -0,0 +1,77 @@
+// Blog section layout. Wraps both the index (`/blog`) and individual posts
+// (`/blog/<slug>`). It identifies the current page by matching `router.pathname`
+// against the post list (from `@opentf/web-docs/posts`):
+//
+//   import BlogLayout from "@opentf/web-docs"; // BlogLayout
+//   import { posts } from "@opentf/web-docs/posts";
+//   import config from "../../otfw.config.js";
+//   export default function (props) {
+//     return <BlogLayout config={config.docs} posts={posts} frame={false}>{props.children}</BlogLayout>;
+//   }
+//
+// On a post it renders the PostBanner (from the post's frontmatter) above the prose
+// body, plus a reusable "On this page" TOC; on the index it just renders the children
+// (typically a <PostList/>). `frame` (default true) adds the navbar/footer chrome;
+// pass `frame={false}` when nesting inside a site layout that already provides them.
+//
+// The layout factory re-runs on every navigation (the router rebuilds the route +
+// layout chain), so reading `router.pathname` resolves to the page being shown.
+import { Link, router } from "@opentf/web";
+import updated from "@opentf/web-docs/updated";
+
+import Navbar from "./Navbar.jsx";
+import Footer from "./Footer.jsx";
+import Toc from "./Toc.jsx";
+import PostBanner from "./PostBanner.jsx";
+import LastUpdated from "./LastUpdated.jsx";
+
+// True when the post was edited after it was published (different calendar day), so a
+// "Last updated" line adds information rather than echoing the publish date.
+function editedAfterPublish(iso, published) {
+  if (!iso) return false;
+  if (!published) return true;
+  return new Date(iso).toDateString() !== new Date(published).toDateString();
+}
+
+export default function BlogLayout(props) {
+  const config = props.config || {};
+  const posts = props.posts || [];
+  const frame = props.frame !== false;
+  const indexPath = props.indexPath || "/blog";
+
+  const post = posts.find((p) => p.path === router.pathname);
+  const editedIso = post && editedAfterPublish(updated[post.path], post.date) ? updated[post.path] : null;
+
+  const body = post ? (
+    <div class="otfw-blog otfw-blog-post">
+      {/* `otfw-content` so the shared Toc can read this article's headings. */}
+      <main id="otfw-content" class="otfw-blog-main" data-pagefind-body>
+        {/* Give blog posts a search breadcrumb too (docs get theirs from <Breadcrumbs>),
+            so a result looks the same whether it's a doc or a post. Inline `key:value`
+            syntax sets the meta literally, independent of visible text. */}
+        <span data-pagefind-meta="breadcrumb:Blog" hidden></span>
+        <Link href={indexPath} class="otfw-blog-back" data-pagefind-ignore>
+          ← {config.title ? `${config.title} Blog` : "Blog"}
+        </Link>
+        <PostBanner post={post} />
+        <article class="otfw-prose">{props.children}</article>
+        {editedIso ? <LastUpdated date={editedIso} /> : null}
+      </main>
+      <Toc />
+    </div>
+  ) : (
+    <div class="otfw-blog otfw-blog-index">
+      <main class="otfw-blog-main">{props.children}</main>
+    </div>
+  );
+
+  return frame ? (
+    <div class="otfw-shell">
+      <Navbar config={config} />
+      <div class="otfw-shell-body">{body}</div>
+      <Footer config={config} />
+    </div>
+  ) : (
+    body
+  );
+}

package/components/Breadcrumbs.jsx

@@ -5,34 +5,37 @@ import { Link, router } from "@opentf/web";
 export default function Breadcrumbs(props) {
   const nav = props.nav || [];
 
+  const findTrail = (items, path, trail) => {
+    for (const it of items) {
+      const next = trail.concat(it);
+      if (it.path === path) return next;
+      if (it.items) {
+        const found = findTrail(it.items, path, next);
+        if (found) return found;
+      }
+    }
+    return null;
+  };
+
+  // Direct-child `.map` (not wrapped in a `{() => …}` thunk) so the compiler
+  // lowers it to a reactive list whose item renderer receives `it`/`i`. The
+  // source re-runs on `router.pathname`, so the trail tracks navigation.
+  // `data-pagefind-meta="breadcrumb"` exposes this trail to the search index, so each
+  // result can show which page (and section) it belongs to.
   return (
-    <nav class="otfw-breadcrumbs" aria-label="Breadcrumb">
-      {() => {
-        const findTrail = (items, path, trail) => {
-          for (const it of items) {
-            const next = trail.concat(it);
-            if (it.path === path) return next;
-            if (it.items) {
-              const found = findTrail(it.items, path, next);
-              if (found) return found;
-            }
-          }
-          return null;
-        };
-        const trail = findTrail(nav, router.pathname, []) || [];
-        return trail.map((it, i) => (
-          <span class="otfw-crumb">
-            {i > 0 ? <span class="otfw-crumb-sep">/</span> : null}
-            {it.path ? (
-              <Link href={it.path} class="otfw-crumb-link">
-                {it.title}
-              </Link>
-            ) : (
-              <span class="otfw-crumb-text">{it.title}</span>
-            )}
-          </span>
-        ));
-      }}
+    <nav class="otfw-breadcrumbs" aria-label="Breadcrumb" data-pagefind-meta="breadcrumb">
+      {(findTrail(nav, router.pathname, []) || []).map((it, i) => (
+        <span class="otfw-crumb">
+          {i > 0 ? <span class="otfw-crumb-sep">/</span> : null}
+          {it.path ? (
+            <Link href={it.path} class="otfw-crumb-link">
+              {it.title}
+            </Link>
+          ) : (
+            <span class="otfw-crumb-text">{it.title}</span>
+          )}
+        </span>
+      ))}
     </nav>
   );
 }

package/components/Callout.jsx

@@ -5,7 +5,7 @@
 const ICONS = {
   note: "✎",
   tip: "💡",
-  info: "ℹ",
+  info: "🛈",
   warning: "⚠",
   danger: "⛔",
 };
@@ -17,13 +17,13 @@ export default function Callout(props) {
 
   return (
     <div class={"otfw-callout otfw-callout-" + type}>
-      <div class="otfw-callout-title">
-        <span class="otfw-callout-icon" aria-hidden="true">
-          {icon}
-        </span>
-        {title}
+      <span class="otfw-callout-icon" aria-hidden="true">
+        {icon}
+      </span>
+      <div class="otfw-callout-content">
+        <div class="otfw-callout-title">{title}</div>
+        <div class="otfw-callout-body">{props.children}</div>
       </div>
-      <div class="otfw-callout-body">{props.children}</div>
     </div>
   );
 }