soames-astro-theme 0.1.0

package/src/lib/wp.ts

@@ -0,0 +1,351 @@
+// ORBI-24 spike — WordPress sourcing layer for Astro (replaces gatsby-source-wordpress).
+//
+// Finding: this WP install's Wordfence WAF 403-blocks GraphQL POST bodies whose
+// FIRST selection-set field is `posts`/`pages` (the literal `{ posts`/`{ pages`).
+// Aliasing the root field (e.g. `wpPages: pages`) dodges the rule. GET also works.
+// This is a server-config quirk that affects ANY client (incl. Gatsby) equally.
+
+const GRAPHQL_URL =
+  import.meta.env.WORDPRESS_GRAPHQL_URL || "http://soames.orbivision.net/graphql";
+const BASE_URL =
+  import.meta.env.WORDPRESS_BASE_URL || "http://soames.orbivision.net";
+
+// A browser-ish UA — Wordfence also 403s some default UAs.
+const UA =
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36";
+
+async function wpQuery<T>(query: string): Promise<T> {
+  const res = await fetch(GRAPHQL_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "User-Agent": UA },
+    body: JSON.stringify({ query }),
+  });
+  if (!res.ok) {
+    throw new Error(`WPGraphQL ${res.status} for query: ${query.slice(0, 60)}…`);
+  }
+  const json = (await res.json()) as { data: T; errors?: unknown };
+  if (json.errors) throw new Error(`WPGraphQL errors: ${JSON.stringify(json.errors)}`);
+  return json.data;
+}
+
+export interface WpImage {
+  sourceUrl: string;
+  altText: string;
+  width?: number;
+  height?: number;
+}
+export interface WpPage {
+  databaseId: number;
+  title: string;
+  // null for the assigned "Posts page" (WP serves the blog at its URL, so
+  // WPGraphQL returns no page uri) — callers must guard before using it.
+  uri: string | null;
+  slug: string;
+  isPostsPage: boolean;
+  isFrontPage: boolean;
+  content: string;
+  excerpt: string;
+  overlayOpacity: number | null;
+  featuredImage: WpImage | null;
+}
+export interface WpAuthor {
+  firstName: string | null;
+  name: string | null;
+  description: string | null;
+  avatarUrl: string | null;
+}
+export interface WpPost {
+  databaseId: number;
+  title: string;
+  slug: string;
+  uri: string;
+  date: string;
+  excerpt: string;
+  content: string;
+  featuredImage: WpImage | null;
+  author: WpAuthor | null;
+}
+
+// weDocs documentation custom post type, exposed to WPGraphQL by the Soames WP
+// plugin (Document/Documents). weDocs is OPTIONAL — see getDocs().
+export interface WpDoc {
+  databaseId: number;
+  title: string;
+  slug: string;
+  uri: string;
+  content: string;
+  excerpt: string;
+  menuOrder: number;
+  parentDatabaseId: number; // 0 when top-level
+  featuredImage: WpImage | null;
+}
+export interface DocTreeNode extends WpDoc {
+  children: DocTreeNode[];
+}
+
+const IMAGE_FRAGMENT = `featuredImage { node { sourceUrl altText mediaDetails { width height } } }`;
+
+// overlayOpacity arrives from WPGraphQL as a String ("0.4") or, defensively, a
+// number. Coerce to a finite number; null when missing/unparseable so callers
+// fall back to the HeroHeader default (0.6).
+function parseOverlayOpacity(value: unknown): number | null {
+  const n = typeof value === "number" ? value : parseFloat(String(value));
+  return Number.isFinite(n) ? n : null;
+}
+
+function normalizeImage(node: any): WpImage | null {
+  const n = node?.featuredImage?.node;
+  if (!n?.sourceUrl) return null;
+  return {
+    sourceUrl: n.sourceUrl,
+    altText: n.altText ?? "",
+    width: n.mediaDetails?.width,
+    height: n.mediaDetails?.height,
+  };
+}
+
+export async function getPages(): Promise<WpPage[]> {
+  // NOTE the alias `wpPages:` — required to pass Wordfence.
+  const data = await wpQuery<{ wpPages: { nodes: any[] } }>(
+    `{ wpPages: pages(first: 100) { nodes { databaseId title uri slug isPostsPage isFrontPage content excerpt overlayOpacity ${IMAGE_FRAGMENT} } } }`
+  );
+  return data.wpPages.nodes.map((n) => ({
+    databaseId: n.databaseId,
+    title: n.title,
+    uri: n.uri ?? null,
+    slug: n.slug ?? "",
+    isPostsPage: !!n.isPostsPage,
+    isFrontPage: !!n.isFrontPage,
+    content: n.content ?? "",
+    excerpt: n.excerpt ?? "",
+    // The plugin's WPGraphQL `overlayOpacity` field is typed String (e.g. "0.4"),
+    // so parse it to a number; null (→ HeroHeader default 0.6) if absent/invalid.
+    overlayOpacity: parseOverlayOpacity(n.overlayOpacity),
+    featuredImage: normalizeImage(n),
+  }));
+}
+
+// The page assigned as Settings > Reading > "Posts page" (where the blog lives),
+// or null if none is set. Drives the blog's base URL (its slug) and hero (its
+// title + featured image + overlay). Derived from getPages, which already fetches
+// these fields.
+export interface WpPostsPage {
+  databaseId: number;
+  slug: string;
+  title: string;
+  featuredImage: WpImage | null;
+  overlayOpacity: number | null;
+}
+export async function getPostsPage(): Promise<WpPostsPage | null> {
+  const pp = (await getPages()).find((p) => p.isPostsPage);
+  if (!pp) return null;
+  return {
+    databaseId: pp.databaseId,
+    slug: pp.slug,
+    title: pp.title,
+    featuredImage: pp.featuredImage,
+    overlayOpacity: pp.overlayOpacity,
+  };
+}
+
+// The page chosen in Soames Settings → Documentation page, or null if none is
+// set. Drives the /docs/ landing hero (title + subhead + featured image +
+// overlay) — parity with getPostsPage() for the blog roll. The chosen page's ID
+// comes from the Soames REST settings (docsPageId); the hero fields come from
+// getPages. Decoupled from the GraphQL schema on purpose: an older plugin simply
+// omits docsPageId (→ null), so /docs/ falls back to its default hero and the
+// rest of the site is unaffected. Any failure degrades to null, never throws.
+export interface WpDocsPage {
+  databaseId: number;
+  title: string;
+  excerpt: string;
+  featuredImage: WpImage | null;
+  overlayOpacity: number | null;
+}
+export async function getDocsPage(): Promise<WpDocsPage | null> {
+  try {
+    const settings = await getSoamesSettings();
+    const id = settings.docsPageId;
+    if (!id) return null;
+    const dp = (await getPages()).find((p) => p.databaseId === id);
+    if (!dp) return null;
+    return {
+      databaseId: dp.databaseId,
+      title: dp.title,
+      excerpt: dp.excerpt,
+      featuredImage: dp.featuredImage,
+      overlayOpacity: dp.overlayOpacity,
+    };
+  } catch (err) {
+    console.warn(
+      "[soames] getDocsPage: could not resolve the docs hero page — using default hero.",
+      (err as Error).message
+    );
+    return null;
+  }
+}
+
+export async function getPosts(): Promise<WpPost[]> {
+  const data = await wpQuery<{ wpPosts: { nodes: any[] } }>(
+    `{ wpPosts: posts(first: 100) { nodes { databaseId title slug uri date excerpt content ${IMAGE_FRAGMENT}
+        author { node { firstName name description avatar { url } } } } } }`
+  );
+  return data.wpPosts.nodes.map((n) => {
+    const a = n.author?.node;
+    return {
+      databaseId: n.databaseId,
+      title: n.title,
+      slug: n.slug,
+      uri: n.uri,
+      date: n.date,
+      excerpt: n.excerpt ?? "",
+      content: n.content ?? "",
+      featuredImage: normalizeImage(n),
+      author: a
+        ? {
+            firstName: a.firstName ?? null,
+            name: a.name ?? null,
+            description: a.description ?? null,
+            avatarUrl: a.avatar?.url ?? null,
+          }
+        : null,
+    };
+  });
+}
+
+// Documentation (weDocs `docs` CPT → GraphQL `documents`). OPTIONAL: weDocs may
+// not be installed, in which case the `documents` field isn't in the schema and
+// the query errors — we treat that as "no docs" and return [] so sites without
+// documentation build normally. Aliased `wpDocs:` to dodge Wordfence (see top).
+export async function getDocs(): Promise<WpDoc[]> {
+  try {
+    // Our docs CPT (registered by the Soames plugin) supports excerpts, so
+    // `excerpt` is a field on the Document type — used for the /docs/ card grid.
+    const data = await wpQuery<{ wpDocs: { nodes: any[] } }>(
+      `{ wpDocs: documents(first: 200) { nodes { databaseId title slug uri content excerpt menuOrder parentDatabaseId ${IMAGE_FRAGMENT} } } }`
+    );
+    return data.wpDocs.nodes.map((n) => ({
+      databaseId: n.databaseId,
+      title: n.title,
+      slug: n.slug,
+      uri: n.uri,
+      content: n.content ?? "",
+      excerpt: n.excerpt ?? "",
+      menuOrder: n.menuOrder ?? 0,
+      parentDatabaseId: n.parentDatabaseId ?? 0,
+      featuredImage: normalizeImage(n),
+    }));
+  } catch (err) {
+    console.warn(
+      "[soames] getDocs: `documents` unavailable (weDocs not installed?) — rendering no docs.",
+      (err as Error).message
+    );
+    return [];
+  }
+}
+
+// Turn the flat doc list into an ordered hierarchy (sort by menuOrder then title,
+// nest by parentDatabaseId) for the docs sidebar nav.
+export function buildDocTree(docs: WpDoc[]): DocTreeNode[] {
+  const byId = new Map<number, DocTreeNode>();
+  docs.forEach((d) => byId.set(d.databaseId, { ...d, children: [] }));
+  const roots: DocTreeNode[] = [];
+  byId.forEach((node) => {
+    const parent = node.parentDatabaseId ? byId.get(node.parentDatabaseId) : undefined;
+    if (parent) parent.children.push(node);
+    else roots.push(node);
+  });
+  const sort = (arr: DocTreeNode[]) => {
+    arr.sort((a, b) => a.menuOrder - b.menuOrder || a.title.localeCompare(b.title));
+    arr.forEach((n) => sort(n.children));
+  };
+  sort(roots);
+  return roots;
+}
+
+export async function getGeneralSettings(): Promise<{ title: string; description: string }> {
+  const data = await wpQuery<{ generalSettings: { title: string; description: string } }>(
+    `{ generalSettings { title description } }`
+  );
+  return data.generalSettings;
+}
+
+// WP "Reading settings" → posts-per-page, drives blog archive pagination
+// (parity with gatsby-node.js readingSettings.postsPerPage).
+export async function getPostsPerPage(): Promise<number> {
+  try {
+    const data = await wpQuery<{ readingSettings: { postsPerPage: number } }>(
+      `{ readingSettings { postsPerPage } }`
+    );
+    return data.readingSettings?.postsPerPage || 10;
+  } catch {
+    return 10;
+  }
+}
+
+export async function getPostBySlug(slug: string): Promise<WpPost | null> {
+  const posts = await getPosts();
+  return posts.find((p) => p.slug === slug) ?? null;
+}
+
+// --- Navigation menus (parity with allWpMenu + locations HEADER/FOOTER) ---
+export interface MenuChild {
+  id: string;
+  label: string;
+  uri: string;
+  order: number;
+}
+export interface MenuItem extends MenuChild {
+  path: string;
+  parentDatabaseId: number;
+  childItems: MenuChild[];
+}
+
+// Returns top-level items (with their children) for a registered menu location
+// e.g. "HEADER" / "FOOTER". `menus` is not WAF-blocked, so no aliasing needed.
+export async function getMenuByLocation(location: string): Promise<MenuItem[]> {
+  const data = await wpQuery<{ menus: { nodes: any[] } }>(
+    `{ menus(first: 20) { nodes { locations menuItems(first: 100) { nodes {
+        id label path uri parentDatabaseId order
+        childItems { nodes { id label uri order } }
+      } } } } }`
+  );
+  const menu = data.menus.nodes.find((m) => (m.locations ?? []).includes(location));
+  const nodes: any[] = menu?.menuItems?.nodes ?? [];
+  return nodes
+    .filter((n) => n.parentDatabaseId === 0)
+    .sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
+    .map((n) => ({
+      id: n.id,
+      label: n.label,
+      path: n.path,
+      uri: n.uri,
+      parentDatabaseId: n.parentDatabaseId,
+      order: n.order,
+      childItems: (n.childItems?.nodes ?? []).sort(
+        (a: MenuChild, b: MenuChild) => (a.order ?? 0) - (b.order ?? 0)
+      ),
+    }));
+}
+
+// Soames plugin settings via the REST endpoint (same source the Gatsby theme uses
+// in gatsby-node.js sourceNodes — companyName, logo, contactBlurb, etc.).
+export interface SoamesSettings {
+  logoUrl: string | null;
+  logoAlt: string | null;
+  faviconUrl: string | null;
+  contactBlurb: string | null;
+  companyName: string | null;
+  showCompanyName: boolean;
+  // Page ID chosen in Soames Settings → Documentation page (drives the /docs/
+  // hero). null when unset, or undefined against an older plugin that predates
+  // this field — getDocsPage() treats both as "no docs page".
+  docsPageId?: number | null;
+}
+export async function getSoamesSettings(): Promise<SoamesSettings> {
+  const res = await fetch(`${BASE_URL}/wp-json/soames/v1/settings`, {
+    headers: { "User-Agent": UA },
+  });
+  if (!res.ok) throw new Error(`Soames settings REST ${res.status}`);
+  return (await res.json()) as SoamesSettings;
+}

package/src/routes/[...uri].astro

@@ -0,0 +1,41 @@
+---
+// All WordPress Pages (except the front page, served by index.astro).
+// Mirrors the Gatsby page template: HeroHeader (featured image as parallax bg,
+// excerpt as subhead) + content wrapped in the .soames-gatsby-content container.
+import Base from "@theme/layouts/Base.astro";
+import HeroHeader from "@theme/components/HeroHeader";
+import Shortcodes from "@theme/components/shortcodes/Shortcodes";
+import RemoveContentAreaPadding from "@theme/components/shortcodes/RemoveContentAreaPadding";
+import { getPages } from "../lib/wp";
+
+export async function getStaticPaths() {
+  const pages = await getPages();
+  return pages
+    .filter(
+      (page) =>
+        page.uri && // skip the assigned Posts page (uri is null) — it would
+        page.uri !== "/" && // crash page.uri.replace(); front page → index.astro
+        !page.isPostsPage // the blog archive renders the Posts page, not here
+    )
+    .map((page) => {
+      const clean = page.uri!.replace(/^\/+|\/+$/g, "");
+      return { params: { uri: clean || undefined }, props: { page } };
+    });
+}
+
+const { page } = Astro.props;
+---
+<Base pageTitle={page.title} description={page.excerpt}>
+  <HeroHeader
+    title={page.title}
+    subhead={page.excerpt}
+    backgroundImage={page.featuredImage?.sourceUrl ?? null}
+    overlayOpacity={page.overlayOpacity}
+  />
+  {page.content && (
+    <section id="soames-gatsby-content-container" class="soames-gatsby-content">
+      <RemoveContentAreaPadding />
+      <Shortcodes html={page.content} />
+    </section>
+  )}
+</Base>

package/src/routes/blog/[...page].astro

@@ -0,0 +1,88 @@
+---
+// Paginated blog archive / blog roll (parity with blog-post-archive.tsx):
+// HeroHeader + posts as cards grouped 3-per-row + Read More + pagination.
+// Lives at the slug of the WP "Posts page" (Settings > Reading), or /blog/ if
+// none is assigned — the base path is set by the route injected in integration.ts.
+// Hero (title/featured image/overlay) comes from that Posts page when present.
+import Base from "@theme/layouts/Base.astro";
+import HeroHeader from "@theme/components/HeroHeader";
+import { getPosts, getPostsPerPage, getPostsPage, type WpPost } from "../../lib/wp";
+
+export async function getStaticPaths() {
+  const [posts, perPage, postsPage] = await Promise.all([
+    getPosts(),
+    getPostsPerPage(),
+    getPostsPage(),
+  ]);
+  const base = `/${postsPage?.slug || "blog"}`; // must match the injected route pattern
+  const totalPages = Math.max(1, Math.ceil(posts.length / perPage));
+
+  return Array.from({ length: totalPages }, (_, i) => {
+    const pageNum = i + 1;
+    const slice = posts.slice(i * perPage, (i + 1) * perPage);
+    return {
+      params: { page: pageNum === 1 ? undefined : String(pageNum) },
+      props: {
+        posts: slice,
+        pageNum,
+        totalPages,
+        prevPath: pageNum > 1 ? (pageNum === 2 ? `${base}/` : `${base}/${pageNum - 1}/`) : null,
+        nextPath: pageNum < totalPages ? `${base}/${pageNum + 1}/` : null,
+        heroTitle: postsPage?.title || "Blog",
+        heroBg: postsPage?.featuredImage?.sourceUrl ?? null,
+        heroOverlay: postsPage?.overlayOpacity ?? 0.6,
+      },
+    };
+  });
+}
+
+const { posts, pageNum, totalPages, prevPath, nextPath, heroTitle, heroBg, heroOverlay } =
+  Astro.props;
+const fmtDate = (d: string) =>
+  new Date(d).toLocaleDateString("en-US", { year: "numeric", month: "long", day: "2-digit" });
+
+// Group posts 3-per-row (parity with the Gatsby blog roll).
+const rows: WpPost[][] = posts.reduce((groups: WpPost[][], post: WpPost, i: number) => {
+  if (i % 3 === 0) groups.push([post]);
+  else groups[groups.length - 1].push(post);
+  return groups;
+}, []);
+---
+<Base pageTitle={`${heroTitle}${pageNum > 1 ? ` — page ${pageNum}` : ""}`} isHomePage={true}>
+  <HeroHeader title={heroTitle} subhead="" backgroundImage={heroBg} overlayOpacity={heroOverlay} />
+
+  {posts.length === 0 ? (
+    <p>No blog posts found. Add posts to your WordPress site and they'll appear here!</p>
+  ) : (
+    <section class="soames-blog-roll">
+      <div class="container">
+        {rows.map((group) => (
+          <div class="media-container-row">
+            {group.map((post) => (
+              <div class="card p-3 col-12 col-lg-4">
+                <div class="card-wrapper">
+                  <div class="card-box">
+                    <h4 class="card-title mbr-fonts-style display-5">{post.title}</h4>
+                    <h4 class="mbr-fonts-style display-7">{fmtDate(post.date)}</h4>
+                    <div set:html={post.excerpt} />
+                  </div>
+                  <div class="mbr-section-btn text-center">
+                    <a href={`/blog/post/${post.slug}/`} class="btn btn-primary display-4">
+                      <span>Read More</span>
+                    </a>
+                  </div>
+                </div>
+              </div>
+            ))}
+          </div>
+        ))}
+      </div>
+    </section>
+  )}
+
+  <section class="container pb-5">
+    {prevPath && <a href={prevPath}>← Newer posts</a>}
+    {prevPath && nextPath && <span> · </span>}
+    {nextPath && <a href={nextPath}>Older posts →</a>}
+  </section>
+</Base>

package/src/routes/blog/post/[...slug].astro

@@ -0,0 +1,79 @@
+---
+// Single blog post (parity with blog-post.tsx): HeroHeader + two columns —
+// content (article: title, date, body, Bio, prev/next) and a sidebar
+// (featured image + Recent Posts via BlogSidebar). Content via the shortcode parser.
+import { Image } from "astro:assets";
+import Base from "@theme/layouts/Base.astro";
+import HeroHeader from "@theme/components/HeroHeader";
+import Shortcodes from "@theme/components/shortcodes/Shortcodes";
+import Bio from "@theme/components/Bio";
+import BlogSidebar from "@theme/components/BlogSidebar";
+import { getPosts } from "../../../lib/wp";
+
+export async function getStaticPaths() {
+  const posts = await getPosts();
+  return posts.map((post, i) => ({
+    params: { slug: post.slug },
+    props: {
+      post,
+      posts,
+      previous: posts[i + 1] ?? null, // posts are date DESC → next index is older
+      next: posts[i - 1] ?? null,
+    },
+  }));
+}
+
+const { post, posts, previous, next } = Astro.props;
+const img = post.featuredImage;
+const fmtDate = (d: string) =>
+  new Date(d).toLocaleDateString("en-US", { year: "numeric", month: "long", day: "2-digit" });
+---
+<Base pageTitle={post.title} description={post.excerpt}>
+  <HeroHeader title="Blog" subhead="" backgroundImage={null} overlayOpacity={0.6} />
+  <section>
+    <div class="media-container-row">
+      <div class="col-12 col-lg-8">
+        <section id="soames-gatsby-content-container" class="soames-gatsby-blog-content">
+          <article class="blog-post soames-prose" itemscope itemtype="http://schema.org/Article">
+            <header>
+              <h1 itemprop="headline">{post.title}</h1>
+              <p>{fmtDate(post.date)}</p>
+            </header>
+            {post.content && (
+              <section itemprop="articleBody" class="blog-post-content">
+                <Shortcodes html={post.content} prose />
+              </section>
+            )}
+            <hr />
+            <footer>
+              <Bio author={post.author} />
+            </footer>
+          </article>
+          <nav class="blog-post-nav">
+            <ul style="display:flex;flex-wrap:wrap;justify-content:space-between;list-style:none;padding:0">
+              <li>{previous && <a href={`/blog/post/${previous.slug}/`} rel="prev">← {previous.title}</a>}</li>
+              <li>{next && <a href={`/blog/post/${next.slug}/`} rel="next">{next.title} →</a>}</li>
+            </ul>
+          </nav>
+        </section>
+      </div>
+      <div class="col-12 col-lg-4">
+        <section id="soames-gatsby-sidebar-container" class="soames-gatsby-sidebar">
+          {img && img.width && img.height && (
+            <Image
+              src={img.sourceUrl}
+              alt={img.altText}
+              width={img.width}
+              height={img.height}
+              widths={[400, 800]}
+              sizes="(max-width: 1000px) 100vw, 33vw"
+              style="margin-bottom:50px"
+            />
+          )}
+          <h1>Recent Posts</h1>
+          <BlogSidebar posts={posts} currentId={post.databaseId} />
+        </section>
+      </div>
+    </div>
+  </section>
+</Base>

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

@@ -0,0 +1,58 @@
+---
+// Single documentation page (weDocs `docs` CPT). Mirrors the blog post template:
+// HeroHeader + two columns — article content (left) and a hierarchical menu of
+// all doc pages (right), instead of the blog's "Recent Posts". Content is run
+// through the same shortcode parser as posts/pages.
+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 } from "../../lib/wp";
+
+export async function getStaticPaths() {
+  // Derive the [...slug] param from the doc's WP uri (e.g. /docs/getting-started/
+  // → "getting-started", /docs/guide/install/ → "guide/install"). Skip the empty
+  // slug — /docs/ is the landing page (docs/index.astro). Defined inside
+  // getStaticPaths: Astro evaluates this fn in isolation from the frontmatter.
+  const toSlug = (uri: string) =>
+    uri.replace(/^\/+|\/+$/g, "").replace(/^docs\/?/, "");
+
+  const docs = await getDocs();
+  const tree = buildDocTree(docs);
+  return docs
+    .map((doc) => ({ doc, slug: toSlug(doc.uri) }))
+    .filter(({ slug }) => slug.length > 0)
+    .map(({ doc, slug }) => ({
+      params: { slug },
+      props: { doc, tree },
+    }));
+}
+
+const { doc, tree } = Astro.props;
+---
+<Base pageTitle={doc.title} description={doc.excerpt}>
+  <HeroHeader title="Documentation" subhead="" backgroundImage={null} overlayOpacity={0.6} />
+  <section>
+    <div class="media-container-row">
+      <div class="col-12 col-lg-8">
+        <section id="soames-gatsby-content-container" class="soames-gatsby-blog-content">
+          <article class="blog-post soames-prose" itemscope itemtype="http://schema.org/TechArticle">
+            <header>
+              <h1 itemprop="headline">{doc.title}</h1>
+            </header>
+            {doc.content && (
+              <section itemprop="articleBody" class="blog-post-content">
+                <Shortcodes html={doc.content} prose />
+              </section>
+            )}
+          </article>
+        </section>
+      </div>
+      <div class="col-12 col-lg-4">
+        <section id="soames-gatsby-sidebar-container" class="soames-gatsby-sidebar">
+          <DocsSidebar tree={tree} currentId={doc.databaseId} />
+        </section>
+      </div>
+    </div>
+  </section>
+</Base>

package/src/routes/docs/index.astro

@@ -0,0 +1,66 @@
+---
+// Documentation landing (/docs/): a full-width, blog-roll-style grid of cards —
+// one per doc article, no sidebar (parity with the blog archive). Each card links
+// to the doc. Docs are flattened depth-first (parents before children, in
+// menuOrder order). If no docs exist, getDocs() returns [] → empty state.
+import Base from "@theme/layouts/Base.astro";
+import HeroHeader from "@theme/components/HeroHeader";
+import { getDocs, getDocsPage, buildDocTree, type WpDoc, type DocTreeNode } from "../../lib/wp";
+
+const docs = await getDocs();
+// Hero is driven by the WP page chosen in Soames Settings → Documentation page,
+// falling back to the default "Documentation" hero when none is set.
+const docsPage = await getDocsPage();
+
+// Flatten the tree so every doc gets a card, parents ahead of their children.
+const flat: WpDoc[] = [];
+const walk = (nodes: DocTreeNode[]) =>
+  nodes.forEach((n) => {
+    flat.push(n);
+    walk(n.children);
+  });
+walk(buildDocTree(docs));
+
+// Group 3-per-row (parity with the blog roll).
+const rows: WpDoc[][] = flat.reduce((groups: WpDoc[][], doc: WpDoc, i: number) => {
+  if (i % 3 === 0) groups.push([doc]);
+  else groups[groups.length - 1].push(doc);
+  return groups;
+}, []);
+---
+<Base pageTitle={docsPage?.title ?? "Documentation"} description={docsPage?.excerpt || "Documentation and guides."}>
+  <HeroHeader
+    title={docsPage?.title ?? "Documentation"}
+    subhead={docsPage?.excerpt ?? ""}
+    backgroundImage={docsPage?.featuredImage?.sourceUrl ?? null}
+    overlayOpacity={docsPage?.overlayOpacity ?? 0.6}
+  />
+
+  {flat.length === 0 ? (
+    <section class="container pb-5">
+      <p>Documentation is coming soon.</p>
+    </section>
+  ) : (
+    <section class="soames-blog-roll">
+      <div class="container">
+        {rows.map((group) => (
+          <div class="media-container-row">
+            {group.map((doc) => (
+              <div class="card p-3 col-12 col-lg-4">
+                <div class="card-wrapper">
+                  <div class="card-box">
+                    <h4 class="card-title mbr-fonts-style display-5" set:html={doc.title} />
+                    {doc.excerpt && <div set:html={doc.excerpt} />}
+                  </div>
+                  <div class="mbr-section-btn text-center">
+                    <a href={doc.uri} class="btn btn-primary display-4"><span>Read</span></a>
+                  </div>
+                </div>
+              </div>
+            ))}
+          </div>
+        ))}
+      </div>
+    </section>
+  )}
+</Base>