soames-astro-theme 0.1.2 → 0.1.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "soames-astro-theme",
   "type": "module",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Shared Astro theme for the Soames ecosystem (WordPress headless + React islands). Successor to soames-gatsby-theme.",
   "keywords": [
     "astro",

package/src/components/Breadcrumbs.tsx

@@ -0,0 +1,40 @@
+// Breadcrumb trail for single Knowledge Base articles (docs CPT). Presentational
+// and static (no hydration): the crumb list is assembled in the docs template
+// from docAncestors() + the /docs/ landing title. Crumbs with an `href` render
+// as links; the last crumb (the current page) has no href and renders as plain
+// text with aria-current="page". Separators are drawn in CSS (::before), so they
+// aren't part of the accessible name or selectable text.
+import React from "react";
+import parse from "html-react-parser";
+
+export interface Crumb {
+  label: string;
+  href?: string;
+}
+
+interface BreadcrumbsProps {
+  crumbs: Crumb[];
+}
+
+const Breadcrumbs: React.FC<BreadcrumbsProps> = ({ crumbs }) => (
+  <nav className="soames-breadcrumbs-nav" aria-label="Breadcrumb">
+    <ol className="soames-breadcrumbs">
+      {crumbs.map((crumb, i) => {
+        const isCurrent = i === crumbs.length - 1;
+        return (
+          <li key={i} className="soames-breadcrumb-item">
+            {crumb.href && !isCurrent ? (
+              <a href={crumb.href}>{parse(crumb.label)}</a>
+            ) : (
+              <span aria-current={isCurrent ? "page" : undefined}>
+                {parse(crumb.label)}
+              </span>
+            )}
+          </li>
+        );
+      })}
+    </ol>
+  </nav>
+);
+
+export default Breadcrumbs;

package/src/lib/wp.ts

@@ -263,6 +263,25 @@ export function buildDocTree(docs: WpDoc[]): DocTreeNode[] {
   return roots;
 }
 
+// Walk the parentDatabaseId chain up from a doc, returning its ancestors in
+// root→parent order (excluding the doc itself). Used for breadcrumbs. Derives
+// from the data, not the URI, because slugs don't always match titles and we
+// need each ancestor's title as well as its uri. The depth cap guards against a
+// malformed cycle in parentDatabaseId.
+export function docAncestors(docs: WpDoc[], databaseId: number): WpDoc[] {
+  const byId = new Map<number, WpDoc>(docs.map((d) => [d.databaseId, d]));
+  const chain: WpDoc[] = [];
+  let current = byId.get(databaseId);
+  let guard = 0;
+  while (current && current.parentDatabaseId && guard++ < 50) {
+    const parent = byId.get(current.parentDatabaseId);
+    if (!parent) break;
+    chain.unshift(parent);
+    current = parent;
+  }
+  return chain;
+}
+
 export async function getGeneralSettings(): Promise<{ title: string; description: string }> {
   const data = await wpQuery<{ generalSettings: { title: string; description: string } }>(
     `{ generalSettings { title description } }`

package/src/routes/docs/[...slug].astro

@@ -7,7 +7,8 @@ import Base from "@theme/layouts/Base.astro";
 import HeroHeader from "@theme/components/HeroHeader";
 import Shortcodes from "@theme/components/shortcodes/Shortcodes";
 import DocsSidebar from "@theme/components/DocsSidebar";
-import { getDocs, buildDocTree, getDocsPage } from "../../lib/wp";
+import Breadcrumbs from "@theme/components/Breadcrumbs";
+import { getDocs, buildDocTree, getDocsPage, docAncestors } from "../../lib/wp";
 
 export async function getStaticPaths() {
   // Derive the [...slug] param from the doc's WP uri (e.g. /docs/getting-started/
@@ -31,18 +32,18 @@ export async function getStaticPaths() {
     .filter(({ slug }) => slug.length > 0)
     .map(({ doc, slug }) => ({
       params: { slug },
-      props: { doc, tree, heroTitle, heroBg, heroOverlay },
+      props: { doc, docs, tree, heroTitle, heroBg, heroOverlay },
     }));
 }
 
-let { doc, tree, heroTitle, heroBg, heroOverlay } = Astro.props;
+let { doc, docs, tree, heroTitle, heroBg, heroOverlay } = Astro.props;
 
 // Dev only: re-fetch on each request so WP doc edits show on refresh without
 // restarting `astro dev` (getStaticPaths props are cached otherwise). Stripped
 // from production builds (import.meta.env.DEV).
 if (import.meta.env.DEV) {
   const toSlug = (uri: string) => uri.replace(/^\/+|\/+$/g, "").replace(/^docs\/?/, "");
-  const docs = await getDocs();
+  docs = await getDocs();
   const fresh = docs.find((d) => toSlug(d.uri) === Astro.params.slug);
   if (fresh) {
     doc = fresh;
@@ -53,6 +54,15 @@ if (import.meta.env.DEV) {
   heroBg = dp?.featuredImage?.sourceUrl ?? null;
   heroOverlay = dp?.overlayOpacity ?? null;
 }
+
+// Breadcrumb trail: Home › <docs landing> › <ancestors…> › current (plain text).
+// Ancestors come from the parentDatabaseId chain (data, not the URI).
+const crumbs = [
+  { label: "Home", href: "/" },
+  { label: heroTitle, href: "/docs/" },
+  ...docAncestors(docs, doc.databaseId).map((a) => ({ label: a.title, href: a.uri })),
+  { label: doc.title },
+];
 ---
 <Base pageTitle={doc.title} description={doc.excerpt}>
   <HeroHeader title={heroTitle} subhead="" backgroundImage={heroBg} overlayOpacity={heroOverlay} />
@@ -62,6 +72,7 @@ if (import.meta.env.DEV) {
         <section id="soames-gatsby-content-container" class="soames-gatsby-blog-content">
           <article class="blog-post soames-prose" itemscope itemtype="http://schema.org/TechArticle">
             <header>
+              <Breadcrumbs crumbs={crumbs} />
               <h1 itemprop="headline">{doc.title}</h1>
             </header>
             {doc.content && (

package/src/styles/soames/overrides.css

@@ -1108,9 +1108,23 @@ section.lazy-placeholder:after {
   padding: 0;
 }
 
-/* Nested levels indent under their parent. */
+/* Own the vertical rhythm locally instead of inheriting the global `ul li`
+   margin from wordpress-blocks.css. That global margin is cancelled on a
+   submenu's first item by `.soames-docs-menu { margin: 0 }`, which left the
+   first link under a parent with no gap above it. Reset it, then apply one
+   uniform step between every item. */
+.soames-docs-menu-item {
+  margin: 0;
+}
+.soames-docs-menu-item + .soames-docs-menu-item {
+  margin-top: 1rem;
+}
+
+/* Nested levels indent under their parent, and sit a full step below the parent
+   link so the first child matches the spacing between all other items. */
 .soames-docs-submenu {
   margin-left: 0.85rem;
+  margin-top: 1rem;
 }
 
 .soames-docs-menu-item > a {
@@ -1139,6 +1153,53 @@ section.lazy-placeholder:after {
   font-weight: 500;
 }
 
+/* ── Article breadcrumbs (Breadcrumbs) ─────────────────────────────────────── */
+.soames-breadcrumbs-nav {
+  font-family: 'Rubik', sans-serif;
+}
+
+.soames-breadcrumbs {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  list-style: none;
+  margin: 0 0 0.75rem;
+  padding: 0;
+  font-size: 0.9rem;
+  line-height: 1.4;
+  color: #6c6c6c;
+}
+
+.soames-breadcrumb-item {
+  display: inline-flex;
+  align-items: center;
+  margin: 0;
+}
+
+/* Separator between crumbs, drawn in CSS so it isn't selectable or announced. */
+.soames-breadcrumb-item + .soames-breadcrumb-item::before {
+  content: "›";
+  margin: 0 0.5rem;
+  color: #b3b0aa;
+}
+
+.soames-breadcrumb-item a {
+  color: #6c6c6c;
+  text-decoration: none;
+  transition: color 0.15s ease-in-out;
+}
+
+.soames-breadcrumb-item a:hover,
+.soames-breadcrumb-item a:focus {
+  color: #bc361b;
+  text-decoration: underline;
+}
+
+/* Current page: no link, reads a touch stronger than the ancestors. */
+.soames-breadcrumb-item [aria-current="page"] {
+  color: #232323;
+}
+
 .soames-menu .navbar {
   padding: .5rem 0;
   background: #bc361b;