@the-smithy/create-hearth-site 0.24.1 → 0.26.0

package/template/package.json

@@ -13,13 +13,14 @@
     "hearth:update": "node scripts/hearth.mjs update"
   },
   "dependencies": {
-    "@the-smithy/ember": "^0.3.1",
+    "@the-smithy/ember": "^0.5.0",
     "@the-smithy/hearth": "workspace:^",
     "maplibre-gl": "^6.16.0",
     "next": "16.3.8",
     "react": "19.2.8",
     "react-dom": "19.2.8",
-    "react-markdown": "^10.1.0"
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4",

package/template/scripts/hearth.mjs

@@ -1,7 +1,8 @@
 // Setup helpers for this site, for you or your coding agent. Both read .env.local and never print the API key.
-//   pnpm hearth:check   checks .env.local and the connection to Hearth, then lists what's published
+//   pnpm hearth:check   says whether The Smithy has released anything newer than this site uses, checks .env.local and
+//                       the connection to Hearth, then lists what's published
 //   pnpm hearth:docs    saves Hearth's full API guide to hearth-api.md (not committed) for an AI assistant to read,
-//                       and installs any coding-assistant skills Hearth offers this site in .claude/skills/
+//                       and installs any coding-assistant skills Hearth offers this site
 //   pnpm hearth:update  updates Hearth's code in this site (src/hearth and the other files its manifest lists) to the
 //                       latest release, and the packages it needs; src/theme and your own files stay as they are
 import { spawnSync } from "node:child_process";
@@ -16,6 +17,12 @@ const fail = (message) => {
   throw new Stop(message);
 };
 
+const PACKAGE = "@the-smithy/create-hearth-site";
+const SKILL_DIRS = [".agents/skills", ".claude/skills"];
+const MANIFEST = "src/hearth/manifest.json";
+/** The packages hearth:update raises; it leaves the site's other Smithy packages to it. */
+const UPDATED_TOGETHER = [PACKAGE, "@the-smithy/hearth", "@the-smithy/hearth-schema"];
+
 /** The SDK, loaded only by the commands that talk to Hearth (so hearth:update works before pnpm install). */
 const sdk = () => import("@the-smithy/hearth");
 
@@ -45,7 +52,49 @@ function designedBlocks() {
   return found.length ? new Set(found) : null;
 }
 
+/** The latest release of a package on npm, or null if npm can't be reached. */
+async function latestRelease(name) {
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${name.replace("/", "%2f")}`, { headers: { Accept: "application/vnd.npm.install-v1+json" } });
+    return res.ok ? (await res.json())["dist-tags"]?.latest ?? null : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Says which of The Smithy's packages have a newer release. Needs no API key, so it runs before anything else in hearth:check. */
+async function checkReleases() {
+  const pkg = JSON.parse(readFileSync("package.json", "utf8"));
+  const installed = (name, range) => {
+    const file = path.join("node_modules", ...name.split("/"), "package.json");
+    return existsSync(file) ? JSON.parse(readFileSync(file, "utf8")).version : range;
+  };
+  const used = Object.entries({ ...pkg.dependencies, ...pkg.devDependencies })
+    .filter(([name, range]) => name.startsWith("@the-smithy/") && !String(range).startsWith("workspace:"))
+    .map(([name, range]) => ({ name, have: installed(name, range) }));
+  if (existsSync(MANIFEST)) used.unshift({ name: PACKAGE, have: JSON.parse(readFileSync(MANIFEST, "utf8")).version });
+
+  const behind = [];
+  let unknown = 0;
+  await Promise.all(
+    used.map(async ({ name, have }) => {
+      const latest = await latestRelease(name);
+      if (!latest) unknown++;
+      else if (lower(have, latest)) behind.push({ name, have, latest });
+    }),
+  );
+  if (unknown) console.log(`! Couldn't check ${unknown} of The Smithy's packages on npm, so there may be newer releases than this lists.`);
+  if (!behind.length) return console.log(`✓ On the latest releases of The Smithy's packages (${used.map((u) => `${u.name.replace("@the-smithy/", "")} ${u.have}`).join(", ")})`);
+  console.log(`! The Smithy has released updates for this site:`);
+  for (const { name, have, latest } of behind) console.log(`  ${name} ${have} → ${latest}`);
+  const others = behind.filter((b) => !UPDATED_TOGETHER.includes(b.name)).map((b) => `${b.name}@latest`);
+  if (others.length < behind.length) console.log(`  Run pnpm hearth:update for Hearth's code and SDK.`);
+  if (others.length) console.log(`  Run pnpm add ${others.join(" ")} for the rest, and read their changelogs.`);
+}
+
 async function check() {
+  await checkReleases();
+  console.log();
   const env = await readEnv();
   const { createHearthClient, isHearthError } = await sdk();
   const hearth = createHearthClient(env);
@@ -103,40 +152,40 @@ async function docs() {
 }
 
 /**
- * Installs the coding-assistant skills Hearth offers this site into .claude/skills/, replacing the ones it
- * installed before. Their names are listed in .claude/skills/.gitignore, so they're never committed and the
- * site's own skills there are left alone.
+ * Installs the coding-assistant skills Hearth offers this site, replacing the ones it installed before, in
+ * .agents/skills/ (the shared place Codex, Gemini CLI, Cursor and Copilot look) and .claude/skills/ (the only one
+ * Claude Code reads). Their names are listed in each folder's .gitignore, so they're never committed and the site's
+ * own skills there are left alone.
  */
 async function skills(env) {
   const res = await fetch(`${env.baseUrl}/admin/docs/skills.json`, { headers: { Authorization: `Bearer ${env.apiKey}` } });
   if (!res.ok) return console.log(`  Hearth didn't return the coding-assistant skills (${res.status}); skipped them.`);
   const { skills: offered = [] } = await res.json();
-  const dir = path.join(".claude", "skills");
-  const listFile = path.join(dir, ".gitignore");
-  const before = existsSync(listFile)
-    ? readFileSync(listFile, "utf8").split(/\r?\n/).map((l) => l.replace(/^\/|\/$/g, "")).filter((l) => l && !l.startsWith("#") && l !== ".gitignore")
-    : [];
   const safe = (p) => /^[a-z0-9][a-z0-9-]*$/.test(p);
   const names = offered.map((s) => s.name).filter(safe);
-  for (const name of before) if (safe(name) && !names.includes(name)) rmSync(path.join(dir, name), { recursive: true, force: true });
-  for (const skill of offered.filter((s) => safe(s.name))) {
-    rmSync(path.join(dir, skill.name), { recursive: true, force: true });
-    for (const file of skill.files) {
-      if (!file.path.split("/").every((part) => /^[A-Za-z0-9._-]+$/.test(part) && part !== "..")) continue;
-      const target = path.join(dir, skill.name, ...file.path.split("/"));
-      mkdirSync(path.dirname(target), { recursive: true });
-      writeFileSync(target, file.content);
+  for (const dir of SKILL_DIRS) {
+    const listFile = path.join(dir, ".gitignore");
+    const before = existsSync(listFile)
+      ? readFileSync(listFile, "utf8").split(/\r?\n/).map((l) => l.replace(/^\/|\/$/g, "")).filter((l) => l && !l.startsWith("#") && l !== ".gitignore")
+      : [];
+    for (const name of before) if (safe(name) && !names.includes(name)) rmSync(path.join(dir, name), { recursive: true, force: true });
+    for (const skill of offered.filter((s) => safe(s.name))) {
+      rmSync(path.join(dir, skill.name), { recursive: true, force: true });
+      for (const file of skill.files) {
+        if (!file.path.split("/").every((part) => /^[A-Za-z0-9._-]+$/.test(part) && part !== "..")) continue;
+        const target = path.join(dir, skill.name, ...file.path.split("/"));
+        mkdirSync(path.dirname(target), { recursive: true });
+        writeFileSync(target, file.content);
+      }
+    }
+    if (names.length || before.length) {
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(listFile, ["# Installed by pnpm hearth:docs from Hearth; refreshed each run.", ".gitignore", ...names.map((n) => `/${n}/`)].join("\n") + "\n");
     }
   }
-  if (names.length || before.length) {
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(listFile, ["# Installed by pnpm hearth:docs from Hearth; refreshed each run.", ".gitignore", ...names.map((n) => `/${n}/`)].join("\n") + "\n");
-  }
-  if (names.length) console.log(`✓ Installed ${names.length === 1 ? "a skill" : `${names.length} skills`} for your coding assistant in .claude/skills/: ${names.join(", ")}.`);
+  if (names.length) console.log(`✓ Installed ${names.length === 1 ? "a skill" : `${names.length} skills`} for your coding assistant in ${SKILL_DIRS.map((d) => `${d}/`).join(" and ")}: ${names.join(", ")}.`);
 }
 
-const PACKAGE = "@the-smithy/create-hearth-site";
-const MANIFEST = "src/hearth/manifest.json";
 
 /** The files in an npm package tarball (.tgz), by their path inside it ("package/…"). */
 function untar(tgz) {
@@ -183,18 +232,20 @@ const lower = (a, b) => {
  * Updates the code Hearth manages in this site to the latest release (or --version x.y.z): replaces the managed files
  * listed in src/hearth/manifest.json, removes managed files the release dropped, adds seeded files that are new to
  * it (never overwriting the site's), and raises the packages the code needs. src/theme and the site's own files
- * aren't touched.
+ * aren't touched, nor are managed files the site's manifest lists under `own` (a site inside an app keeps its own root
+ * layout and route files, for example).
  */
 async function update() {
   const args = process.argv.slice(3);
   const force = args.includes("--force");
   const wanted = args.includes("--version") ? args[args.indexOf("--version") + 1] : "latest";
   if (!wanted) fail("Give a version after --version, e.g. --version 0.21.0.");
-  if (!existsSync(MANIFEST)) fail(`There's no ${MANIFEST}, so this site predates hearth:update. Move it onto the template's structure first (see CLAUDE.md).`);
+  if (!existsSync(MANIFEST)) fail(`There's no ${MANIFEST}, so this site predates hearth:update. Move it onto the template's structure first (see AGENTS.md).`);
   const old = JSON.parse(readFileSync(MANIFEST, "utf8"));
+  const own = old.own ?? [];
 
   // Managed files edited here would be lost: styling belongs in src/theme.
-  const git = spawnSync("git", ["status", "--porcelain", "--", ...old.managed], { encoding: "utf8" });
+  const git = spawnSync("git", ["status", "--porcelain", "--", ...old.managed.filter((entry) => !own.includes(entry))], { encoding: "utf8" });
   if (git.status === 0 && git.stdout.trim() && !force) {
     fail(`These managed files have uncommitted changes, which the update would replace:\n${git.stdout.trimEnd()}\nCommit them first (and move any styling into src/theme), or run with --force to replace them.`);
   }
@@ -225,12 +276,12 @@ async function update() {
   const changed = [];
   // Managed files the release no longer has.
   for (const file of old.managed.flatMap(localFiles)) {
-    if (files.has(file) || file === MANIFEST) continue;
+    if (files.has(file) || file === MANIFEST || listed(own, file)) continue;
     rmSync(file);
     changed.push(`- ${file}`);
   }
   for (const [file, body] of files) {
-    if (file === MANIFEST) continue;
+    if (file === MANIFEST || listed(own, file)) continue;
     const managed = listed(next.managed, file);
     // Seeded files are the site's own: add only ones that are new to this release's list, and never over a file.
     const newSeed = !managed && listed(next.seeded, file) && !listed(old.seeded ?? [], file) && !existsSync(file);
@@ -241,7 +292,7 @@ async function update() {
     writeFileSync(file, body);
     changed.push(`${existed ? "~" : "+"} ${file}`);
   }
-  writeFileSync(MANIFEST, JSON.stringify({ ...next, version }, null, 2) + "\n");
+  writeFileSync(MANIFEST, JSON.stringify({ ...next, version, ...(own.length ? { own } : {}) }, null, 2) + "\n");
 
   // The packages the code needs, at least at the release's versions, and its hearth:* scripts. The site's own stay.
   const pkg = JSON.parse(readFileSync("package.json", "utf8"));

package/template/src/app/donate/thank-you/page.tsx

@@ -1,2 +1,2 @@
 // Managed by Hearth (pnpm hearth:update replaces it). Style it in src/theme; the page is src/hearth/pages/thank-you.tsx.
-export { default, metadata } from "@/hearth/pages/thank-you";
+export { default, generateMetadata } from "@/hearth/pages/thank-you";

package/template/src/app/globals.css

@@ -1,4 +1,5 @@
 /* Managed by Hearth (pnpm hearth:update replaces it). The site's tokens and CSS go in src/theme/theme.css. */
 @import "tailwindcss";
 @import "../hearth/hearth.css";
+@import "../hearth/base.css";
 @import "../theme/theme.css";

package/template/src/app/layout.tsx

@@ -1,4 +1,4 @@
 // Managed by Hearth (pnpm hearth:update replaces it): the layout is src/hearth/layout/RootLayout.tsx, styled in src/theme.
 import "./globals.css";
 
-export { default, generateMetadata } from "@/hearth/layout/RootLayout";
+export { default, generateMetadata, viewport } from "@/hearth/layout/RootLayout";

package/template/src/app/not-found.tsx

@@ -1,2 +1,2 @@
 // Managed by Hearth (pnpm hearth:update replaces it). Style it in src/theme; the page is src/hearth/pages/not-found.tsx.
-export { default } from "@/hearth/pages/not-found";
+export { default, generateMetadata } from "@/hearth/pages/not-found";

package/template/src/app/registered/page.tsx

@@ -1,2 +1,2 @@
 // Managed by Hearth (pnpm hearth:update replaces it). Style it in src/theme; the page is src/hearth/pages/registered.tsx.
-export { default, metadata } from "@/hearth/pages/registered";
+export { default, generateMetadata } from "@/hearth/pages/registered";

package/template/src/hearth/base.css

@@ -0,0 +1,66 @@
+/*
+ * Hearth's rich text and focus rings, shared by every site: src/app/globals.css loads it. Don't edit it in a site: the
+ * site's own CSS goes in src/theme/theme.css, which is loaded after this file and can override anything here.
+ */
+
+/* Markdown from Hearth (rich text, FAQ answers, media + text). Unlayered, so its line height beats text-* sizes. */
+.prose {
+  line-height: 1.7;
+}
+.prose > * + * {
+  margin-top: 1em;
+}
+.prose h2 {
+  font-size: 1.75rem;
+  font-weight: 700;
+  line-height: 1.25;
+  margin-top: 1.6em;
+}
+.prose h3 {
+  font-size: 1.35rem;
+  font-weight: 700;
+  margin-top: 1.4em;
+}
+.prose a {
+  text-decoration: underline;
+  text-underline-offset: 3px;
+}
+.prose ul {
+  list-style: disc;
+  padding-left: 1.4em;
+}
+.prose ol {
+  list-style: decimal;
+  padding-left: 1.4em;
+}
+.prose blockquote {
+  border-left: 3px solid var(--color-line);
+  padding-left: 1em;
+  font-style: italic;
+}
+.prose img {
+  border-radius: 0.75rem;
+}
+/* A wide table scrolls inside the text rather than widening the page. */
+.prose table {
+  display: block;
+  max-width: 100%;
+  overflow-x: auto;
+  border-collapse: collapse;
+}
+.prose th,
+.prose td {
+  border-bottom: 1px solid var(--color-line);
+  padding: 0.5em 1em 0.5em 0;
+  text-align: left;
+  vertical-align: top;
+}
+.prose th {
+  font-weight: 700;
+}
+
+/* Unlayered, so it beats utilities like focus:outline-none: keyboard focus always shows. */
+:focus-visible {
+  outline: 2px solid var(--color-accent);
+  outline-offset: 2px;
+}

package/template/src/hearth/blocks/collections.tsx

@@ -6,17 +6,18 @@ import { fill, Img, Section, SectionHeading } from "../ui";
 
 const t = theme.collectionList;
 
-function Card({ entry }: { entry: CollectionEntry }) {
+function Card({ entry, heading }: { entry: CollectionEntry; heading?: string }) {
+  const Title = heading ? "h3" : "h2";
   return (
     <li className={t.card}>
       {entry.image ? <Img image={entry.image} crop={16 / 10} className={t.image} /> : null}
       <div className={t.body}>
         {entry.date ? <p className={t.date}>{formatEntryDate(entry.date)}</p> : null}
-        <h3 className={t.title}>
+        <Title className={t.title}>
           <Link href={entry.path} className={t.link}>
             {entry.title}
           </Link>
-        </h3>
+        </Title>
         {entry.summary ? <p className={t.summary}>{entry.summary}</p> : null}
         {entry.tags.length ? (
           <ul className={t.tags}>
@@ -36,7 +37,7 @@ function Card({ entry }: { entry: CollectionEntry }) {
 export function CollectionList({ block }: { block: BlockOf<"collectionList"> }) {
   const { entries, collection, layout } = block.data;
   return (
-    <Section block="collectionList">
+    <Section block="collectionList" id={block.anchor}>
       <SectionHeading eyebrow={block.data.eyebrow} heading={block.data.heading} intro={block.data.intro} />
       {!entries.length ? (
         <p className={t.empty}>{theme.text.noEntries}</p>
@@ -60,7 +61,7 @@ export function CollectionList({ block }: { block: BlockOf<"collectionList"> })
       ) : (
         <ul className={t.cards}>
           {entries.map((e) => (
-            <Card key={e.path} entry={e} />
+            <Card key={e.path} entry={e} heading={block.data.heading} />
           ))}
         </ul>
       )}

package/template/src/hearth/blocks/content.tsx

@@ -1,12 +1,15 @@
 import type { BlockOf } from "@the-smithy/hearth";
 import { theme } from "@/theme";
-import { Button, Emphasis, fill, ground, Img, Markdown, Section, SectionHeading, SmartLink, toTone } from "../ui";
+import { cx } from "../theme";
+import { Button, Emphasis, fill, ground, Img, Markdown, plain, Section, SectionHeading, SmartLink, toTone } from "../ui";
 
 export function Hero({ block }: { block: BlockOf<"hero"> }) {
   const d = block.data;
   const t = theme.hero;
+  const paragraphs = d.body?.split(/\n\s*\n/).filter((p) => p.trim()) ?? [];
+  // Without a tone it's the design's own ground, dark, in `hero.root`. A tone sets the ground, which turns on-dark: on or off.
   return (
-    <section data-block="hero" {...ground("inverse")} className={t.root}>
+    <section id={block.anchor} data-block="hero" data-size={d.size} {...ground(d.tone ?? "inverse")} className={cx(d.tone ? `${theme.tones[d.tone]} ${t.toned}` : t.root, block.anchor && theme.section.anchored)}>
       {d.image ? <Img image={d.image} crop priority className={t.image} /> : null}
       <div className={t.inner} data-size={d.size}>
         {d.logo ? <Img image={d.logo} priority className={t.logo} /> : null}
@@ -14,7 +17,15 @@ export function Hero({ block }: { block: BlockOf<"hero"> }) {
         <h1 className={t.title}>
           <Emphasis text={d.heading} className={t.emphasis} />
         </h1>
-        {d.body ? <p className={t.body}>{d.body}</p> : null}
+        {paragraphs.length > 1 ? (
+          paragraphs.map((p, i) => (
+            <p key={i} className={t.body}>
+              {p}
+            </p>
+          ))
+        ) : d.body ? (
+          <p className={t.body}>{d.body}</p>
+        ) : null}
         {d.primaryCta || d.secondaryCta ? (
           <div className={t.actions}>
             <Button link={d.primaryCta} />
@@ -28,7 +39,7 @@ export function Hero({ block }: { block: BlockOf<"hero"> }) {
 
 export function RichText({ block }: { block: BlockOf<"richText"> }) {
   return (
-    <Section block="richText">
+    <Section block="richText" id={block.anchor}>
       <Markdown className={theme.richText.body} data-width={block.data.width}>
         {block.data.markdown}
       </Markdown>
@@ -40,7 +51,7 @@ export function MediaText({ block }: { block: BlockOf<"mediaText"> }) {
   const d = block.data;
   const t = theme.mediaText;
   return (
-    <Section block="mediaText">
+    <Section block="mediaText" id={block.anchor}>
       <div className={t.grid} data-image={d.imagePosition}>
         <div className={t.text}>
           <SectionHeading eyebrow={d.eyebrow} heading={d.heading} />
@@ -60,7 +71,7 @@ export function MediaText({ block }: { block: BlockOf<"mediaText"> }) {
 export function Stats({ block }: { block: BlockOf<"stats"> }) {
   const t = theme.stats;
   return (
-    <Section block="stats" tone={toTone(t.tone)}>
+    <Section block="stats" id={block.anchor} tone={toTone(t.tone)}>
       <SectionHeading heading={block.data.heading} />
       <dl className={t.list}>
         {block.data.items.map((s, i) => (
@@ -74,17 +85,27 @@ export function Stats({ block }: { block: BlockOf<"stats"> }) {
   );
 }
 
+/** A card's title as a key ("Our *history*" is "our-history"), for CSS that targets one card: [data-card="our-history"]. */
+const cardKey = (title: string) =>
+  plain(title)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "") || undefined;
+
 export function CardGrid({ block }: { block: BlockOf<"cardGrid"> }) {
   const d = block.data;
   const t = theme.cardGrid;
+  const Title = d.heading ? "h3" : "h2";
   return (
-    <Section block="cardGrid" tone={d.tone}>
+    <Section block="cardGrid" id={block.anchor} tone={d.tone}>
       <SectionHeading eyebrow={d.eyebrow} heading={d.heading} intro={d.intro} />
       <ul className={t.list}>
         {d.items.map((c, i) => (
-          <li key={i} className={t.card}>
+          <li key={i} className={t.card} data-card={cardKey(c.title)} data-icon={c.icon}>
             {c.image ? <Img image={c.image} crop={16 / 10} className={t.image} /> : null}
-            <h3 className={t.title}>{c.title}</h3>
+            <Title className={t.title}>
+              <Emphasis text={c.title} />
+            </Title>
             {c.body ? <p className={t.body}>{c.body}</p> : null}
             {c.link ? (
               <SmartLink href={c.link.href} className={t.link}>
@@ -102,8 +123,9 @@ export function Projects({ block }: { block: BlockOf<"projects"> }) {
   const d = block.data;
   const t = theme.projects;
   const grid = d.layout === "grid";
+  const Title = d.heading ? "h3" : "h2";
   return (
-    <Section block="projects" tone={d.tone}>
+    <Section block="projects" id={block.anchor} tone={d.tone}>
       <SectionHeading eyebrow={d.eyebrow} heading={d.heading} intro={d.intro} />
       <ul className={grid ? t.gridList : t.showcaseList} data-layout={d.layout}>
         {d.items.map((p, i) => (
@@ -111,7 +133,7 @@ export function Projects({ block }: { block: BlockOf<"projects"> }) {
             {p.image ? <Img image={p.image} crop={16 / 10} className={t.image} /> : null}
             <div className={t.text}>
               <div className={t.top}>
-                <h3 className={t.name}>{p.name}</h3>
+                <Title className={t.name}>{p.name}</Title>
                 {p.status ? <span className={t.status}>{p.status}</span> : null}
               </div>
               {p.role ? <p className={t.role}>{p.role}</p> : null}
@@ -141,14 +163,15 @@ export function Projects({ block }: { block: BlockOf<"projects"> }) {
 export function Pricing({ block }: { block: BlockOf<"pricing"> }) {
   const d = block.data;
   const t = theme.pricing;
+  const Title = d.heading ? "h3" : "h2";
   return (
-    <Section block="pricing" tone={d.tone}>
+    <Section block="pricing" id={block.anchor} tone={d.tone}>
       <SectionHeading eyebrow={d.eyebrow} heading={d.heading} intro={d.intro} />
       <ul className={t.list} data-count={d.plans.length >= 4 ? "many" : "few"}>
         {d.plans.map((p, i) => (
           <li key={i} className={t.plan} data-highlight={p.highlight ? "" : undefined}>
             {p.highlight ? <p className={t.highlight}>{p.highlight}</p> : null}
-            <h3 className={t.name}>{p.name}</h3>
+            <Title className={t.name}>{p.name}</Title>
             <p className={t.price}>
               <span className={t.amount}>{p.price}</span>
               {p.period ? <span className={t.period}>{p.period}</span> : null}
@@ -196,12 +219,12 @@ export function CallToAction({ block }: { block: BlockOf<"cta"> }) {
   );
   if (!d.image)
     return (
-      <Section block="cta" tone={d.tone}>
+      <Section block="cta" id={block.anchor} tone={d.tone}>
         {content}
       </Section>
     );
   return (
-    <section data-block="cta" {...ground("inverse")} className={t.imageRoot}>
+    <section id={block.anchor} data-block="cta" {...ground("inverse")} className={cx(t.imageRoot, block.anchor && theme.section.anchored)}>
       <Img image={d.image} crop className={t.image} />
       <div className={t.overlay}>
         <div className={t.overlayInner}>{content}</div>
@@ -213,19 +236,32 @@ export function CallToAction({ block }: { block: BlockOf<"cta"> }) {
 export function Faq({ block }: { block: BlockOf<"faq"> }) {
   const t = theme.faq;
   return (
-    <Section block="faq">
+    <Section block="faq" id={block.anchor}>
       <SectionHeading heading={block.data.heading} />
-      <div className={t.list}>
-        {block.data.items.map((q, i) => (
-          <details key={i} className={t.item}>
-            <summary className={t.question}>
-              {q.question}
-              <span aria-hidden className={t.icon} />
-            </summary>
-            <Markdown className={t.answer}>{q.answer}</Markdown>
-          </details>
-        ))}
-      </div>
+      {block.data.display === "list" ? (
+        <dl className={t.terms}>
+          {block.data.items.map((q, i) => (
+            <div key={i} className={t.term}>
+              <dt className={t.termQuestion}>{q.question}</dt>
+              <dd>
+                <Markdown className={t.termAnswer}>{q.answer}</Markdown>
+              </dd>
+            </div>
+          ))}
+        </dl>
+      ) : (
+        <div className={t.list}>
+          {block.data.items.map((q, i) => (
+            <details key={i} className={t.item}>
+              <summary className={t.question}>
+                {q.question}
+                <span aria-hidden className={t.icon} />
+              </summary>
+              <Markdown className={t.answer}>{q.answer}</Markdown>
+            </details>
+          ))}
+        </div>
+      )}
     </Section>
   );
 }
@@ -234,7 +270,7 @@ export function Quote({ block }: { block: BlockOf<"quote"> }) {
   const d = block.data;
   const t = theme.quote;
   return (
-    <Section block="quote" tone={d.tone}>
+    <Section block="quote" id={block.anchor} tone={d.tone}>
       <figure className={t.figure}>
         <blockquote className={t.text}>{d.quote}</blockquote>
         {d.name ? (

package/template/src/hearth/blocks/custom.tsx

@@ -1,4 +1,5 @@
 import type { BlockOf } from "@the-smithy/hearth";
+import { theme } from "@/theme";
 import { customBlocks } from "@/theme/custom-blocks";
 
 /** A block type of this site's own (Settings → Custom blocks in Hearth), drawn by its component in src/theme/custom-blocks.tsx. */
@@ -8,5 +9,12 @@ export function CustomBlock({ block }: { block: BlockOf<"custom"> }) {
     if (process.env.NODE_ENV !== "production") console.warn(`[hearth] No component for custom block "${block.data.block}"; add one in src/theme/custom-blocks.tsx.`);
     return null;
   }
-  return <Component values={block.data.values} />;
+  // Custom blocks draw their own markup, so a link's target goes around them.
+  return block.anchor ? (
+    <div id={block.anchor} className={theme.section.anchored}>
+      <Component values={block.data.values} />
+    </div>
+  ) : (
+    <Component values={block.data.values} />
+  );
 }