@dogsbay/docs-layout 0.2.0-beta.93 → 0.2.0-beta.95

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/docs-layout",
-  "version": "0.2.0-beta.93",
+  "version": "0.2.0-beta.95",
   "description": "Standard documentation layout components for Dogsbay",
   "type": "module",
   "exports": {
@@ -13,6 +13,7 @@
     "./TagList.astro": "./src/TagList.astro",
     "./StatusBadge.astro": "./src/StatusBadge.astro",
     "./TypeBadge.astro": "./src/TypeBadge.astro",
+    "./BlogIndex.astro": "./src/BlogIndex.astro",
     "./TaxonomyIndex.astro": "./src/TaxonomyIndex.astro",
     "./TaxonomyTerm.astro": "./src/TaxonomyTerm.astro",
     "./SearchDialog.astro": "./src/SearchDialog.astro",
@@ -29,12 +30,12 @@
     "./json-ld": "./src/json-ld.ts"
   },
   "dependencies": {
-    "@dogsbay/ui": "0.2.0-beta.93",
-    "@dogsbay/primitives": "0.2.0-beta.93"
+    "@dogsbay/primitives": "0.2.0-beta.95",
+    "@dogsbay/ui": "0.2.0-beta.95"
   },
   "devDependencies": {
-    "happy-dom": "^20.8.9",
-    "vitest": "^3.0.0"
+    "happy-dom": "^20.10.6",
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
     "astro": "^5.0.0 || ^6.0.0 || ^7.0.0"

package/src/BlogIndex.astro

@@ -0,0 +1,179 @@
+---
+/**
+ * BlogIndex — reverse-chronological list of posts.
+ *
+ * Reads the slice its route file hands it from `src/data/blog.json`
+ * (emitted by `format-astro/src/blog.ts` during `dogsbay site build`)
+ * and renders one card per post plus page navigation.
+ *
+ * All layout lives here rather than in the generated route files, so a
+ * design fix propagates on the next build instead of being baked into
+ * every emitted page — the same reason `TaxonomyIndex` exists.
+ *
+ * Uses the shared theme tokens only. The blog is the same site as the
+ * docs, so there is no blog palette, no blog typography scale, and no
+ * second set of card styles to keep in sync.
+ */
+import Card from "@dogsbay/ui/card/Card.astro";
+
+interface BlogPostRef {
+  slug: string;
+  title: string;
+  url: string;
+  description?: string;
+  date?: string;
+  author?: string[];
+  tags?: string[];
+  heroImage?: string;
+  readingMinutes: number;
+}
+
+interface Props {
+  /** The posts for THIS page of the index, newest first. */
+  posts: BlogPostRef[];
+  /** URL-form index path, already basePath-prefixed. */
+  indexPath: string;
+  pageNo: number;
+  totalPages: number;
+  /** Page heading. Defaults to "Blog", or "Blog — page N" beyond page 1. */
+  heading?: string;
+}
+
+const {
+  posts,
+  indexPath,
+  pageNo,
+  totalPages,
+  heading = pageNo === 1 ? "Blog" : `Blog — page ${pageNo}`,
+} = Astro.props;
+
+/** Build time, so every reader sees the same string. See DocsLayout. */
+function formatDate(iso: string): string {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso;
+  // timeZone: "UTC" is load-bearing. parseMeta normalizes `created:
+  // 2026-01-01` to "2026-01-01T00:00:00.000Z", so a build host in any
+  // negative-offset zone (the default on many CI runners) would render
+  // "31 December 2025". DocsFooter already carries this fix; these
+  // copies dropped it.
+  return d.toLocaleDateString("en-GB", {
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+    timeZone: "UTC",
+  });
+}
+
+const base = indexPath === "/" ? "" : indexPath.replace(/\/+$/, "");
+const hrefForPage = (n: number): string => (n === 1 ? `${base}/` : `${base}/page/${n}`);
+---
+
+{/*
+  The index needs its own <h1>. Post titles are <h2>, so without one the
+  page has an h2 with no h1 above it — a heading-order violation axe-core
+  flags, and a missing page heading for anyone navigating by headings.
+  The sticky header's site name is chrome, not a page heading.
+*/}
+<h1 class="text-3xl font-bold tracking-tight mb-8">{heading}</h1>
+
+{posts.length === 0 && (
+  <p class="text-muted-foreground">No posts yet.</p>
+)}
+
+{/*
+  Three across at lg, two at sm, one on mobile. The card is one link, not
+  a card containing links: nesting interactive elements inside a clickable
+  card is the classic keyboard-and-screen-reader trap, so tags and other
+  links stay off the card and live on the post page instead.
+
+  `items-stretch` + `h-full` keeps a short post's card the same height as
+  a long one's — ragged card bottoms are the thing that makes a grid look
+  broken rather than sparse.
+*/}
+<ul
+  class="not-prose grid list-none grid-cols-1 items-stretch gap-6 p-0 sm:grid-cols-2 lg:grid-cols-3"
+  data-blog-index
+>
+  {posts.map((post) => (
+    <li class="m-0 p-0">
+      <a
+        href={post.url}
+        class="group block h-full rounded-lg no-underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+      >
+        <Card class="flex h-full flex-col gap-3 p-5 transition-colors group-hover:border-ring">
+          {post.heroImage && (
+            <img
+              src={post.heroImage}
+              alt=""
+              class="aspect-[16/9] w-full rounded-md border border-border object-cover"
+              loading="lazy"
+              decoding="async"
+            />
+          )}
+
+          <h2 class="text-lg font-semibold leading-snug tracking-tight text-foreground group-hover:underline">
+            {post.title}
+          </h2>
+
+          {/*
+            data-pagefind-ignore: the same values are indexed as structured
+            filters on the post itself. Without it every card's date leads
+            its search excerpt.
+          */}
+          <div
+            class="flex flex-wrap items-center gap-x-2 gap-y-1 text-xs text-muted-foreground"
+            data-pagefind-ignore
+          >
+            {post.author && post.author.length > 0 && (
+              <span class="font-medium text-foreground">{post.author.join(", ")}</span>
+            )}
+            {post.author && post.author.length > 0 && post.date && (
+              <span aria-hidden="true">&middot;</span>
+            )}
+            {post.date && <time datetime={post.date}>{formatDate(post.date)}</time>}
+            {(post.author?.length || post.date) && <span aria-hidden="true">&middot;</span>}
+            <span>{post.readingMinutes} min read</span>
+          </div>
+
+          {post.description && (
+            <p class="m-0 text-sm leading-relaxed text-muted-foreground">
+              {post.description}
+            </p>
+          )}
+        </Card>
+      </a>
+    </li>
+  ))}
+</ul>
+
+{totalPages > 1 && (
+  <nav class="not-prose mt-12 flex items-center justify-between" aria-label="Blog pages">
+    {pageNo > 1 ? (
+      <a
+        href={hrefForPage(pageNo - 1)}
+        class="text-sm text-foreground no-underline hover:underline"
+        rel="prev"
+      >
+        &larr; Newer posts
+      </a>
+    ) : (
+      <span></span>
+    )}
+
+    <span class="text-sm text-muted-foreground">
+      Page {pageNo} of {totalPages}
+    </span>
+
+    {pageNo < totalPages ? (
+      <a
+        href={hrefForPage(pageNo + 1)}
+        class="text-sm text-foreground no-underline hover:underline"
+        rel="next"
+      >
+        Older posts &rarr;
+      </a>
+    ) : (
+      <span></span>
+    )}
+  </nav>
+)}

package/src/DocsFooter.astro

@@ -14,6 +14,14 @@ interface Props {
   lastUpdated?: string;
   prev?: PaginationLink;
   next?: PaginationLink;
+  /**
+   * Captions above the prev/next titles. Default "Previous" / "Next",
+   * which is right for docs, where adjacency is position in the sidebar.
+   * A blog's adjacency is TIME, so it passes "Newer" / "Older" — the
+   * link means something different there and the label should say so.
+   */
+  prevLabel?: string;
+  nextLabel?: string;
   copyright?: string;
   /**
    * When true, render a low-key footer link to `/llms.txt` so
@@ -32,6 +40,8 @@ const {
   lastUpdated,
   prev,
   next,
+  prevLabel = "Previous",
+  nextLabel = "Next",
   copyright,
   llmsLink = false,
   llmsLinkHref = "/llms.txt",
@@ -74,7 +84,7 @@ function formatDate(value: string): string {
         <a href={prev.href} class="inline-flex items-center gap-2 rounded-md border px-4 py-2 text-sm font-medium transition-colors hover:bg-accent" rel="prev">
           <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="15 18 9 12 15 6"/></svg>
           <div class="text-left">
-            <div class="text-xs text-muted-foreground">Previous</div>
+            <div class="text-xs text-muted-foreground">{prevLabel}</div>
             <div>{prev.label}</div>
           </div>
         </a>
@@ -82,7 +92,7 @@ function formatDate(value: string): string {
       {next ? (
         <a href={next.href} class="inline-flex items-center gap-2 rounded-md border px-4 py-2 text-sm font-medium transition-colors hover:bg-accent" rel="next">
           <div class="text-right">
-            <div class="text-xs text-muted-foreground">Next</div>
+            <div class="text-xs text-muted-foreground">{nextLabel}</div>
             <div>{next.label}</div>
           </div>
           <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="9 18 15 12 9 6"/></svg>

package/src/DocsLayout.astro

@@ -36,6 +36,7 @@ import Separator from "@dogsbay/ui/separator/Separator.astro";
 import ThemeToggle from "@dogsbay/ui/theme-toggle/ThemeToggle.astro";
 import DocsToc from "./DocsToc.astro";
 import { resolveTocPlacement, hasDisplayableToc, type TocMode } from "./toc-placement.js";
+import { linkIconAttrs } from "./link-icons.js";
 import DocsFooter from "./DocsFooter.astro";
 import SearchDialog from "./SearchDialog.astro";
 import TagList from "./TagList.astro";
@@ -405,6 +406,44 @@ interface Props {
    * in per-page.
    */
   wideLayout?: boolean;
+
+  /**
+   * Which chrome this page wears.
+   *
+   * `"docs"` (default) is the full documentation shell. `"blog"` drops
+   * the sidebar and its nav fetch, and turns on the byline row — the
+   * blog is the same SITE, not a second design system, so the header,
+   * footer, search, page actions, TOC and every theme token stay
+   * identical. See plans/blog-capability.md Phase 3.
+   */
+  chrome?: "docs" | "blog";
+
+  /** Post authors. No byline is rendered when absent — never a placeholder. */
+  author?: string[];
+  /** ISO publish date for the byline. */
+  publishedDate?: string;
+  /** ISO updated date; shown only when it differs from publishedDate. */
+  updatedDate?: string;
+  /**
+   * Reading estimate in whole minutes. Computed at EMIT time from the
+   * TreeNode word count — a browser-side count would re-walk the DOM on
+   * every load for a number that cannot change.
+   */
+  readingMinutes?: number;
+  /** Optional hero image URL, rendered above the prose. */
+  heroImage?: string;
+  /**
+   * Series position, when the post belongs to one. Derived at emit time
+   * from publication order, so "Part 3 of 7" cannot disagree with reality
+   * the way a hand-typed line does.
+   */
+  series?: {
+    name: string;
+    part: number;
+    total: number;
+    /** URL of part 1, so a reader landing mid-series can start over. */
+    startHref?: string;
+  };
   /**
    * Table-of-contents placement. Default `"top"`.
    * - `"top"` — expandable "On this page" disclosure at the top of the
@@ -416,6 +455,18 @@ interface Props {
    * See plans/ask-branch1-placement-toc.md.
    */
   toc?: TocMode;
+  /**
+   * Internal/external link-icon glyphs. When set, a small trailing icon
+   * marks links in the prose — external (absolute / protocol-relative
+   * href) vs internal (root / relative) — classified purely by href
+   * shape in CSS. Either side may be absent to mark only that link kind.
+   * Sourced from `content.linkIcons` in `dogsbay.config.yml`.
+   * See plans/link-resolution-and-icons.md.
+   */
+  linkIcons?: {
+    external?: string;
+    internal?: string;
+  };
   class?: string;
 }
 
@@ -476,9 +527,23 @@ const {
   basePath,
   navMode = "client",
   wideLayout = false,
+  chrome = "docs",
+  author,
+  publishedDate,
+  updatedDate,
+  readingMinutes,
+  heroImage,
+  series,
+  linkIcons,
   class: className,
 } = Astro.props;
 
+// Link icons — classified in CSS by href shape. `data-link-icons`
+// lists which kinds are active; the glyphs ride in CSS custom props
+// (single-quoted so they're valid `content:` string values).
+const { tokens: _linkIconTokens, style: _linkIconStyle } =
+  linkIconAttrs(linkIcons);
+
 // Resolve LLM action visibility + placement once. The component
 // guards against missing markdownBody / mdUrl internally, but we
 // also gate at the layout level so the slots stay empty when
@@ -562,9 +627,54 @@ const computedCanonical = canonicalUrl
     ? canonicalOrigin + Astro.url.pathname
     : undefined);
 
-// Markdown mirror — append `.md` to the current path for the alternate link
+/**
+ * Format an ISO date for a byline.
+ *
+ * Runs at BUILD time, so the output is baked into the HTML and every
+ * reader sees the same string — no hydration flash, and no dependence on
+ * the visitor's locale for a date the author wrote. Falls back to the
+ * raw value if it will not parse, so a typo shows up as itself rather
+ * than as "Invalid Date".
+ */
+function _formatPostDate(iso: string): string {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso;
+  // timeZone: "UTC" is load-bearing. parseMeta normalizes `created:
+  // 2026-01-01` to "2026-01-01T00:00:00.000Z", so a build host in any
+  // negative-offset zone (the default on many CI runners) would render
+  // "31 December 2025". DocsFooter already carries this fix; these
+  // copies dropped it.
+  return d.toLocaleDateString("en-GB", {
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+    timeZone: "UTC",
+  });
+}
+
+// Markdown mirror for the alternate link.
+//
+// Leaf pages append `.md` to the trimmed path (`/getting-started/` →
+// `/getting-started.md`), matching the emitted `<slug>.md.ts` endpoint.
+// The SITE INDEX is the exception: it is emitted as `index.md.ts`, so
+// its mirror is `<base>/index.md`. Appending `.md` there produced
+// `/.md` (root-served) or `/blog.md` (mounted) — neither exists, and on
+// a mounted site `/blog.md` also falls outside the `/blog/*` route.
+// Both leaf and index URLs carry a trailing slash under Astro's
+// directory build format, so only "is this the site root" distinguishes
+// them. Kept in step with `shouldRewriteToMarkdown`, which is handed the
+// same combined prefix.
+// Use the `basePath` PROP, not import.meta.env.BASE_URL. Astro's `base`
+// carries only site.url's path (urlBase); the prop carries the COMBINED
+// urlBase + site.basePath prefix — the same value the middleware gets —
+// so on a `site.basePath: /docs` deploy the two would otherwise disagree
+// about which page is the index.
+const mdMirrorBase = (basePath ?? "").replace(/\/+$/, "");
+const mdMirrorPath = Astro.url.pathname.replace(/\/$/, "");
 const mdMirrorHref = mdMirror
-  ? (Astro.url.pathname.replace(/\/$/, "") || "") + ".md"
+  ? mdMirrorPath === mdMirrorBase
+    ? `${mdMirrorBase}/index.md`
+    : `${mdMirrorPath}.md`
   : undefined;
 
 // Tag keywords for HTML meta + JSON-LD. Slug-based identifiers
@@ -614,6 +724,50 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>{title} | {siteName}</title>
 
+    <style is:global>
+      /*
+        The sticky-chrome contract. This header is exactly this tall, and
+        anything else that sticks (the release-comparison toolbar) offsets
+        by the same variable — so they cannot drift apart.
+      */
+      :root {
+        --db-header-height: 3rem;
+      }
+
+      /*
+        Internal/external link icons. Opt-in via `content.linkIcons`,
+        which sets `data-link-icons` (which kinds are active) and the
+        `--db-link-icon-*` custom props (the glyphs) on <body>. Links are
+        classified purely by href shape, so it covers both structured
+        links and raw-HTML anchors from imported content. Scoped to
+        `.docs-prose` so nav/header/footer links are untouched.
+      */
+      body[data-link-icons~="external"] .docs-prose a[href^="http://" i]::after,
+      body[data-link-icons~="external"] .docs-prose a[href^="https://" i]::after,
+      body[data-link-icons~="external"] .docs-prose a[href^="//"]::after {
+        content: var(--db-link-icon-external, "");
+        display: inline-block;
+        margin-inline-start: 0.15em;
+        font-size: 0.85em;
+        line-height: 1;
+        vertical-align: baseline;
+        opacity: 0.7;
+      }
+      body[data-link-icons~="internal"]
+        .docs-prose
+        a[href^="/"]:not([href^="//"])::after,
+      body[data-link-icons~="internal"] .docs-prose a[href^="./"]::after,
+      body[data-link-icons~="internal"] .docs-prose a[href^="../"]::after {
+        content: var(--db-link-icon-internal, "");
+        display: inline-block;
+        margin-inline-start: 0.15em;
+        font-size: 0.85em;
+        line-height: 1;
+        vertical-align: baseline;
+        opacity: 0.7;
+      }
+    </style>
+
     {metaDescription && <meta name="description" content={metaDescription} />}
     {favicon && <link rel="icon" href={favicon} />}
     {themeColor && <meta name="theme-color" content={themeColor} />}
@@ -708,8 +862,19 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
   <body
     class="bg-background text-foreground antialiased"
     data-pagefind-ignore={excludeFromSearch ? "" : undefined}
+    data-link-icons={_linkIconTokens || undefined}
+    style={_linkIconStyle || undefined}
   >
     <SidebarProvider>
+      {/*
+        chrome="blog" drops the sidebar COLUMN only. SidebarProvider and
+        SidebarInset stay, so the content column, header offset and
+        sticky contract are byte-identical to a docs page — which is what
+        makes the blog read as the same site rather than a lookalike.
+        With no <Sidebar> sibling the inset's peer-* selectors simply do
+        not match and it fills the width.
+      */}
+      {chrome === "docs" && (
       <Sidebar collapsible="icon">
         <SidebarHeader>
           <SidebarMenu>
@@ -742,6 +907,7 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                 <DocsNavClient
                   currentPath={currentPath}
                   basePath={basePath ?? ""}
+                  namespace={multiSource?.namespace}
                   version={multiSource?.version}
                   locale={multiSource?.locale}
                 />
@@ -755,6 +921,7 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                   <SidebarNavTree
                     items={filterNavByAxis(group.items, {
                       basePath: basePath ?? "/docs",
+                      namespace: multiSource?.namespace,
                       version: multiSource?.version,
                       locale: multiSource?.locale,
                     })}
@@ -769,6 +936,7 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                 <SidebarNavTree
                   items={filterNavByAxis(nav, {
                     basePath: basePath ?? "/docs",
+                    namespace: multiSource?.namespace,
                     version: multiSource?.version,
                     locale: multiSource?.locale,
                   })}
@@ -781,10 +949,17 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
 
         <SidebarRail />
       </Sidebar>
+      )}
 
       <SidebarInset>
-        <header class="sticky top-0 z-40 flex h-12 shrink-0 items-center gap-2 border-b bg-background/95 px-4 backdrop-blur-sm supports-[backdrop-filter]:bg-background/60">
-          <SidebarTrigger class="-ml-1" />
+        {/*
+          Height comes from `--db-header-height` (declared on :root in
+          <head>) — the CONTRACT any other sticky chrome offsets by, e.g.
+          the release-comparison toolbar. One variable, so a change here
+          can never leave another sticky bar overlapping or floating.
+        */}
+        <header class="sticky top-0 z-40 flex h-[var(--db-header-height)] shrink-0 items-center gap-2 border-b bg-background/95 px-4 backdrop-blur-sm supports-[backdrop-filter]:bg-background/60">
+          {chrome === "docs" && <SidebarTrigger class="-ml-1" />}
           <Separator orientation="vertical" class="mr-2 h-4" />
           <span class="text-sm text-muted-foreground" data-page-title>{title}</span>
           <div class="ml-auto flex items-center gap-2">
@@ -827,6 +1002,8 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                 pagefindUrl={pagefindUrl}
                 navUrl={basePath ? `${basePath}/_dogsbay/nav.json` : "/_dogsbay/nav.json"}
                 taxonomyDisplay={taxonomyDisplay}
+                scopeProduct={multiSource?.namespace}
+                scopeVersion={multiSource?.version}
               />
             )}
             {repoUrl && (
@@ -891,6 +1068,18 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
             ))}
             {status && <div hidden data-pagefind-filter={`status:${status}`}></div>}
             {pageType && <div hidden data-pagefind-filter={`type:${pageType}`}></div>}
+            {/*
+              Multi-source axis filters — so search on a versioned/multi-
+              product site can be scoped to (or faceted by) the current
+              product and version. `product` = namespace, `version` = the
+              version segment. Only emitted when the axis is active.
+            */}
+            {multiSource?.namespace && (
+              <div hidden data-pagefind-filter={`product:${multiSource.namespace}`}></div>
+            )}
+            {multiSource?.version && (
+              <div hidden data-pagefind-filter={`version:${multiSource.version}`}></div>
+            )}
             {/*
               Custom-taxonomy filters. Any taxonomy declared in
               `dogsbay.config.yml` that isn't one of the five built-ins
@@ -944,12 +1133,90 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                   {title}
                 </h1>
               )}
+              {/*
+                Byline — blog chrome only, and only when there is
+                something to say. An absent author means NO byline row,
+                never "Unknown": a placeholder byline is worse than none,
+                because it reads as data rather than as a gap.
+
+                Sits between the H1 and the lede so the reader gets
+                attribution before the summary, which is the order a
+                post is scanned in.
+              */}
+              {chrome === "blog" && (author?.length || publishedDate || readingMinutes) && (
+                <div
+                  class="not-prose mb-6 flex flex-wrap items-center gap-x-2 gap-y-1 text-sm text-muted-foreground"
+                  data-post-byline
+                  data-pagefind-ignore
+                >
+                  {author && author.length > 0 && (
+                    <span class="font-medium text-foreground">{author.join(", ")}</span>
+                  )}
+                  {author && author.length > 0 && publishedDate && (
+                    <span aria-hidden="true">&middot;</span>
+                  )}
+                  {publishedDate && (
+                    <time datetime={publishedDate}>{_formatPostDate(publishedDate)}</time>
+                  )}
+                  {publishedDate && readingMinutes && <span aria-hidden="true">&middot;</span>}
+                  {readingMinutes && <span>{readingMinutes} min read</span>}
+                  {updatedDate && updatedDate !== publishedDate && (
+                    <span>
+                      &middot; Updated <time datetime={updatedDate}>{_formatPostDate(updatedDate)}</time>
+                    </span>
+                  )}
+                </div>
+              )}
+
+              {/*
+                Series banner. Sits above the byline because it is the
+                first thing a reader arriving from search needs: which
+                series is this, where am I in it, and where does it start.
+                A blog index is chronological, so someone can easily meet
+                part 7 first.
+              */}
+              {chrome === "blog" && series && (
+                <div
+                  class="not-prose mb-4 flex flex-wrap items-center gap-x-2 gap-y-1 rounded-md border border-border bg-muted/40 px-3 py-2 text-sm"
+                  data-post-series
+                  data-pagefind-ignore
+                >
+                  <span class="font-medium text-foreground">
+                    Part {series.part} of {series.total}
+                  </span>
+                  <span class="text-muted-foreground">in {series.name}</span>
+                  {series.startHref && series.part !== 1 && (
+                    <a
+                      href={series.startHref}
+                      class="ml-auto text-foreground underline underline-offset-2"
+                    >
+                      Start at part 1
+                    </a>
+                  )}
+                </div>
+              )}
+
               {autoLede && description && (
                 <p class="text-lg text-muted-foreground mb-6">
                   {description}
                 </p>
               )}
 
+              {/*
+                Hero image. aspect-boxed on purpose — an unsized image
+                above the fold is the classic layout-shift source, and it
+                would shove the prose down after paint.
+              */}
+              {chrome === "blog" && heroImage && (
+                <img
+                  src={heroImage}
+                  alt=""
+                  class="not-prose mb-8 w-full rounded-lg border border-border object-cover aspect-[2/1]"
+                  loading="eager"
+                  decoding="async"
+                />
+              )}
+
               {hasMetaStrip && (
                 <div
                   class="not-prose mb-6 flex flex-wrap items-center gap-2"
@@ -996,6 +1263,12 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                 lastUpdated={lastUpdated}
                 prev={prev}
                 next={next}
+                {/*
+                  Blog adjacency is chronological, so "Previous/Next"
+                  would describe the wrong axis — prev is the NEWER post.
+                */}
+                prevLabel={chrome === "blog" ? "Newer" : undefined}
+                nextLabel={chrome === "blog" ? "Older" : undefined}
                 copyright={copyright}
                 llmsLink={llmFooterLink}
                 llmsLinkHref={llmsLinkHrefResolved}