@dogsbay/docs-layout 0.2.0-beta.0

package/src/TagList.astro

@@ -0,0 +1,124 @@
+---
+/**
+ * TagList — inline list of tag chips linking to taxonomy term pages.
+ *
+ * Used by DocsLayout to surface page-level tags near the title.
+ * Tags can be flat (`api`) or slash-nested (`api/rest`); each chip
+ * links to `<indexPath>/<tag>/`.
+ *
+ * Two render modes:
+ *
+ *   - **Flat chip** (default) — single muted background, `#tag` style.
+ *     Used when no `prefixes` entry matches the tag's first segment.
+ *
+ *   - **Two-part chip** — when the prefix has a `label` set, the chip
+ *     splits into a muted prefix label + bold leaf value, both
+ *     wearing the prefix's palette color. Different prefixes get
+ *     different colors so a page tagged `concept/a11y` and
+ *     `format/markdown` reads as two visually distinct facets.
+ *
+ * Chip-building logic lives in `./tag-list-data.ts` so it can be
+ * vitested without a render container.
+ *
+ * Hide automatically when `tags` is empty / undefined.
+ *
+ * See plans/tag-display-config.md.
+ */
+import {
+  buildChips,
+  type PrefixDisplay,
+  type TagPaletteName,
+} from "./tag-list-data.js";
+
+interface Props {
+  /** Tag values from `page.meta.tags`. Slash-nested allowed. */
+  tags?: string[];
+  /**
+   * Path prefix for term pages. Default `/tags`. Match the
+   * `taxonomies.tags.indexPath` used at emit time.
+   */
+  indexPath?: string;
+  /**
+   * Per-prefix display config. Key = top-level segment of the tag.
+   * Absent → flat chip rendering for that tag.
+   */
+  prefixes?: Record<string, PrefixDisplay>;
+  /**
+   * Per-tag leaf-label overrides. Key = full slug; value = display
+   * text. URL still uses the slug.
+   */
+  labels?: Record<string, string>;
+  /** Optional aria-label override; default "Tags". */
+  label?: string;
+  class?: string;
+}
+
+const {
+  tags,
+  indexPath = "/tags",
+  prefixes,
+  labels,
+  label: ariaLabel = "Tags",
+  class: className,
+} = Astro.props;
+
+const chips = buildChips(tags, { indexPath, prefixes, labels });
+
+/**
+ * Closed palette → Tailwind class strings. Each entry is one
+ * background+text pair; prefix-keyed colors stay readable in
+ * both light and dark mode by leaning on the `/15` alpha and
+ * `dark:` variants.
+ */
+const PALETTE: Record<TagPaletteName, string> = {
+  blue: "border-blue-500/40 bg-blue-500/15 text-blue-700 dark:text-blue-300",
+  amber:
+    "border-amber-500/40 bg-amber-500/15 text-amber-700 dark:text-amber-300",
+  emerald:
+    "border-emerald-500/40 bg-emerald-500/15 text-emerald-700 dark:text-emerald-300",
+  violet:
+    "border-violet-500/40 bg-violet-500/15 text-violet-700 dark:text-violet-300",
+  rose: "border-rose-500/40 bg-rose-500/15 text-rose-700 dark:text-rose-300",
+  slate:
+    "border-slate-500/40 bg-slate-500/15 text-slate-700 dark:text-slate-300",
+};
+
+const DEFAULT_CLASS =
+  "border-border bg-secondary text-secondary-foreground hover:bg-accent hover:text-accent-foreground";
+---
+
+{chips.length > 0 && (
+  <ul
+    class:list={[
+      "not-prose flex flex-wrap items-center gap-1.5 text-xs",
+      className,
+    ]}
+    aria-label={ariaLabel}
+    data-tag-list
+  >
+    {chips.map((chip) => (
+      <li>
+        <a
+          href={chip.href}
+          class:list={[
+            "inline-flex items-center gap-1 rounded-full border px-2 py-0.5 font-medium transition-colors",
+            chip.color ? PALETTE[chip.color] : DEFAULT_CLASS,
+          ]}
+          data-tag={chip.tag}
+        >
+          {chip.prefixLabel ? (
+            <Fragment>
+              <span class="opacity-70">{chip.prefixLabel}:</span>
+              <span class="font-semibold">{chip.leafLabel}</span>
+            </Fragment>
+          ) : (
+            <Fragment>
+              <span aria-hidden="true">#</span>
+              <span>{chip.leafLabel}</span>
+            </Fragment>
+          )}
+        </a>
+      </li>
+    ))}
+  </ul>
+)}

package/src/TaxonomyIndex.astro

@@ -0,0 +1,148 @@
+---
+/**
+ * TaxonomyIndex — listing of all terms for a taxonomy.
+ *
+ * Reads a `taxonomy-<name>.json` data file (emitted by
+ * `format-astro/src/taxonomy.ts` during `dogsbay site build`) and
+ * renders a flat / hierarchical list of terms with page counts.
+ *
+ * Auto-generated route files (`src/pages<indexPath>/index.astro`)
+ * import this and pass the imported JSON through, plus the
+ * per-taxonomy `prefixes` / `labels` display config so chip text
+ * shows human labels instead of slugs (e.g. "Accessibility"
+ * instead of "concept/a11y").
+ */
+import {
+  resolveTermLabel,
+  type PrefixDisplay,
+} from "./tag-list-data.js";
+
+interface TaxonomyPageRef {
+  slug: string;
+  title: string;
+  url: string;
+}
+
+interface TaxonomyTerm {
+  fullPath: string[];
+  label: string;
+  pages: TaxonomyPageRef[];
+}
+
+interface TaxonomyData {
+  name: string;
+  indexPath: string;
+  hierarchical: boolean;
+  terms: TaxonomyTerm[];
+  pageCount: number;
+}
+
+interface Props {
+  /** The data emitted to `src/data/taxonomy-<name>.json`. */
+  data: TaxonomyData;
+  /**
+   * Per-prefix display config from `taxonomies.<name>.prefixes`.
+   * Provides the human label for top-level segments
+   * (`concept` → "Concept").
+   */
+  prefixes?: Record<string, PrefixDisplay>;
+  /**
+   * Per-slug label overrides from `taxonomies.<name>.labels`.
+   * Display text only — URLs continue to use the slug.
+   */
+  labels?: Record<string, string>;
+  /** Optional override for the rendered heading (default: humanized taxonomy name). */
+  heading?: string;
+  class?: string;
+}
+
+const { data, prefixes, labels, heading, class: className } = Astro.props;
+
+const displayName = heading
+  ?? data.name
+    .replace(/[-_]/g, " ")
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+
+// For hierarchical taxonomies, build a parent→children index so we
+// can render a tree. The data already contains all prefix entries.
+function topLevelTerms(): TaxonomyTerm[] {
+  if (!data.hierarchical) return data.terms;
+  return data.terms.filter((t) => t.fullPath.length === 1);
+}
+
+function childTerms(parent: TaxonomyTerm): TaxonomyTerm[] {
+  if (!data.hierarchical) return [];
+  const parentKey = parent.fullPath.join("/");
+  return data.terms.filter((t) =>
+    t.fullPath.length === parent.fullPath.length + 1 &&
+    t.fullPath.slice(0, -1).join("/") === parentKey
+  );
+}
+
+function termHref(term: TaxonomyTerm): string {
+  return `${data.indexPath}/${term.fullPath.join("/")}/`;
+}
+
+function termText(term: TaxonomyTerm): string {
+  return resolveTermLabel(term.fullPath, prefixes, labels);
+}
+---
+
+<section
+  class:list={["mx-auto max-w-3xl px-6 py-8", className]}
+  data-taxonomy-index
+  data-taxonomy={data.name}
+>
+  <header class="mb-6">
+    <h1 class="text-3xl font-bold tracking-tight">{displayName}</h1>
+    <p class="mt-2 text-sm text-muted-foreground">
+      {data.pageCount} {data.pageCount === 1 ? "page" : "pages"} across{" "}
+      {data.terms.length} {data.terms.length === 1 ? "term" : "terms"}.
+    </p>
+  </header>
+
+  {data.hierarchical ? (
+    <ul class="space-y-3" data-tree>
+      {topLevelTerms().map((term) => (
+        <li>
+          <a
+            href={termHref(term)}
+            class="inline-flex items-baseline gap-2 font-medium text-foreground hover:underline"
+          >
+            <span>{termText(term)}</span>
+            <span class="text-xs text-muted-foreground">({term.pages.length})</span>
+          </a>
+          {childTerms(term).length > 0 && (
+            <ul class="ml-4 mt-1 space-y-1 border-l border-border pl-3">
+              {childTerms(term).map((child) => (
+                <li>
+                  <a
+                    href={termHref(child)}
+                    class="inline-flex items-baseline gap-2 text-sm text-muted-foreground hover:text-foreground hover:underline"
+                  >
+                    <span>{termText(child)}</span>
+                    <span class="text-xs">({child.pages.length})</span>
+                  </a>
+                </li>
+              ))}
+            </ul>
+          )}
+        </li>
+      ))}
+    </ul>
+  ) : (
+    <ul class="flex flex-wrap gap-2">
+      {data.terms.map((term) => (
+        <li>
+          <a
+            href={termHref(term)}
+            class="inline-flex items-center gap-1.5 rounded-full border border-border bg-secondary px-3 py-1 text-sm font-medium text-secondary-foreground transition-colors hover:bg-accent hover:text-accent-foreground"
+          >
+            <span>{termText(term)}</span>
+            <span class="text-xs text-muted-foreground">{term.pages.length}</span>
+          </a>
+        </li>
+      ))}
+    </ul>
+  )}
+</section>

package/src/TaxonomyTerm.astro

@@ -0,0 +1,181 @@
+---
+/**
+ * TaxonomyTerm — page-list view for a single taxonomy term.
+ *
+ * Auto-generated `[...path].astro` term routes import this and pass
+ * a single resolved term entry. For hierarchical taxonomies, the
+ * route file's `getStaticPaths` produces one entry per term path
+ * (including parents), and this component renders pages tagged at
+ * that exact term — children are listed as drill-down links.
+ *
+ * Layout uses `<LinkCard>` from `@dogsbay/ui` so cards stay visually
+ * consistent with anywhere else those components are used (e.g. nav
+ * landing pages, search results). The page descriptions powering
+ * the cards are populated by `format-astro/src/taxonomy.ts`'s
+ * `derivePageDescription` (frontmatter.description, then first-
+ * paragraph fallback).
+ *
+ * Heading, breadcrumbs, and sub-tag pills run through
+ * `resolveTermLabel` so configured `prefixes` / `labels` display
+ * config produces human strings ("Concept / Accessibility") instead
+ * of raw slugs ("concept / a11y"). URLs always use the slug.
+ *
+ * See plans/tag-display-config.md.
+ */
+import LinkCard from "@dogsbay/ui/link-card/LinkCard.astro";
+import Badge from "@dogsbay/ui/badge/Badge.astro";
+import {
+  resolveTermLabel,
+  type PrefixDisplay,
+} from "./tag-list-data.js";
+
+interface TaxonomyPageRef {
+  slug: string;
+  title: string;
+  url: string;
+  description?: string;
+}
+
+interface TaxonomyTerm {
+  fullPath: string[];
+  label: string;
+  pages: TaxonomyPageRef[];
+}
+
+interface TaxonomyData {
+  name: string;
+  indexPath: string;
+  hierarchical: boolean;
+  terms: TaxonomyTerm[];
+  pageCount: number;
+}
+
+interface Props {
+  /** The whole data file (so we can compute child terms for breadcrumbs). */
+  data: TaxonomyData;
+  /** The single term being rendered. */
+  term: TaxonomyTerm;
+  /**
+   * Per-prefix display config from `taxonomies.<name>.prefixes`.
+   * Top-level segments resolve to the configured human label.
+   */
+  prefixes?: Record<string, PrefixDisplay>;
+  /**
+   * Per-slug label overrides from `taxonomies.<name>.labels`.
+   * URLs continue to use the slug.
+   */
+  labels?: Record<string, string>;
+  class?: string;
+}
+
+const { data, term, prefixes, labels, class: className } = Astro.props;
+
+const displayName = data.name
+  .replace(/[-_]/g, " ")
+  .replace(/\b\w/g, (c) => c.toUpperCase());
+
+function childTerms(): TaxonomyTerm[] {
+  if (!data.hierarchical) return [];
+  const parentKey = term.fullPath.join("/");
+  return data.terms.filter((t) =>
+    t.fullPath.length === term.fullPath.length + 1 &&
+    t.fullPath.slice(0, -1).join("/") === parentKey
+  );
+}
+
+// Per-segment human labels for the page title and crumbs. Each
+// position in the fullPath gets its own resolution (top-level uses
+// `prefixes`, deeper levels use `labels[fullSlugUpToHere]`, with
+// the leaf segment as the final fallback).
+function segmentLabel(depth: number): string {
+  return resolveTermLabel(term.fullPath.slice(0, depth + 1), prefixes, labels);
+}
+
+const titleSegments = term.fullPath.map((_, i) => segmentLabel(i));
+
+// Breadcrumb segments — clickable parent paths.
+function breadcrumbs() {
+  const out: { label: string; href: string }[] = [
+    { label: displayName, href: `${data.indexPath}/` },
+  ];
+  for (let i = 0; i < term.fullPath.length - 1; i++) {
+    out.push({
+      label: segmentLabel(i),
+      href: `${data.indexPath}/${term.fullPath.slice(0, i + 1).join("/")}/`,
+    });
+  }
+  return out;
+}
+
+const children = childTerms();
+const crumbs = breadcrumbs();
+---
+
+<section
+  class:list={["mx-auto max-w-5xl px-6 py-8", className]}
+  data-taxonomy-term
+  data-taxonomy={data.name}
+  data-term-path={term.fullPath.join("/")}
+>
+  <nav class="mb-3 text-sm text-muted-foreground" aria-label="Breadcrumbs">
+    {crumbs.map((c, i) => (
+      <span>
+        <a href={c.href} class="hover:text-foreground hover:underline">{c.label}</a>
+        {i < crumbs.length - 1 && <span class="mx-1.5">/</span>}
+      </span>
+    ))}
+  </nav>
+
+  <header class="mb-6">
+    <h1 class="text-3xl font-bold tracking-tight">{titleSegments.join(" / ")}</h1>
+    <p class="mt-2 text-sm text-muted-foreground">
+      {term.pages.length} {term.pages.length === 1 ? "page" : "pages"}
+      {children.length > 0 && (
+        <span> · {children.length} sub-{children.length === 1 ? "term" : "terms"}</span>
+      )}
+    </p>
+  </header>
+
+  {children.length > 0 && (
+    <div class="mb-8">
+      <h2 class="mb-2 text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+        Sub-tags
+      </h2>
+      <ul class="flex flex-wrap gap-2">
+        {children.map((child) => (
+          <li>
+            <a
+              href={`${data.indexPath}/${child.fullPath.join("/")}/`}
+              class="group inline-flex"
+            >
+              <Badge
+                variant="secondary"
+                class="gap-1.5 transition-colors group-hover:bg-accent group-hover:text-accent-foreground"
+              >
+                <span>{resolveTermLabel(child.fullPath, prefixes, labels)}</span>
+                <span class="text-muted-foreground">{child.pages.length}</span>
+              </Badge>
+            </a>
+          </li>
+        ))}
+      </ul>
+    </div>
+  )}
+
+  {term.pages.length > 0 ? (
+    <ul class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3 border-t border-border pt-6">
+      {term.pages.map((page) => (
+        <li>
+          <LinkCard
+            title={page.title}
+            description={page.description}
+            href={page.url}
+            class="h-full"
+          />
+        </li>
+      ))}
+    </ul>
+  ) : (
+    <p class="text-sm text-muted-foreground">No pages tagged here yet.</p>
+  )}
+</section>

package/src/TypeBadge.astro

@@ -0,0 +1,63 @@
+---
+/**
+ * TypeBadge — surfaces the page's `type` (open string).
+ *
+ * Diátaxis values (`tutorial`, `how-to`, `reference`, `explanation`)
+ * get conventional colors; any other type renders with the neutral
+ * fallback. Open string by design — users can add their own types
+ * (e.g. `api-endpoint`, `release-notes`) and they render with the
+ * fallback styling.
+ *
+ * When `href` is set, the badge renders as a link (e.g. to a
+ * `/types/<value>/` browse page); otherwise it's a plain span.
+ * `<DocsLayout>` computes the href from `siteConfig.taxonomyIndexPaths.type`
+ * — set when the user has declared `taxonomies.type:` in their config.
+ */
+interface Props {
+  type?: string;
+  /** Optional link target — renders the badge as `<a>` when set. */
+  href?: string;
+  class?: string;
+}
+
+const { type, href, class: className } = Astro.props;
+
+const visible = type && type.length > 0;
+
+const conventional: Record<string, string> = {
+  tutorial:
+    "border-emerald-500/40 bg-emerald-500/15 text-emerald-700 dark:text-emerald-300",
+  "how-to":
+    "border-sky-500/40 bg-sky-500/15 text-sky-700 dark:text-sky-300",
+  reference:
+    "border-violet-500/40 bg-violet-500/15 text-violet-700 dark:text-violet-300",
+  explanation:
+    "border-orange-500/40 bg-orange-500/15 text-orange-700 dark:text-orange-300",
+};
+
+const fallback =
+  "border-border bg-muted text-muted-foreground";
+
+const style = (type && conventional[type]) || fallback;
+const label = type ? type.replace(/[-_]/g, " ") : "";
+const baseClasses = "inline-flex items-center rounded-full border px-2 py-0.5 text-xs font-semibold capitalize";
+const linkClasses = "transition-colors hover:opacity-80";
+---
+
+{visible && href && (
+  <a
+    href={href}
+    class:list={[baseClasses, linkClasses, style, className]}
+    data-page-type={type}
+  >
+    {label}
+  </a>
+)}
+{visible && !href && (
+  <span
+    class:list={[baseClasses, style, className]}
+    data-page-type={type}
+  >
+    {label}
+  </span>
+)}

package/src/VersionSwitcher.astro

@@ -0,0 +1,86 @@
+---
+/**
+ * VersionSwitcher — dropdown letting readers switch between
+ * declared versions of a docs page. Pure-CSS interaction via
+ * <details>; works without JS.
+ *
+ * Decision logic lives in `./switcher.ts` (shared with
+ * LocaleSwitcher); this file is just rendering.
+ */
+import {
+  type SwitcherMap,
+  type MultiSourceMeta,
+  buildSwitcherRows,
+  fallbackLandingUrl,
+  shouldRenderSwitcher,
+} from "./switcher.js";
+
+interface Props {
+  switcherMap: SwitcherMap;
+  multiSource?: MultiSourceMeta;
+  basePath?: string;
+}
+
+const { switcherMap, multiSource, basePath = "/docs" } = Astro.props;
+const visible = shouldRenderSwitcher("version", switcherMap, multiSource);
+const rows = visible
+  ? buildSwitcherRows({ axis: "version", switcherMap, multiSource: multiSource! })
+  : [];
+const currentRow = rows.find((r) => r.isCurrent);
+const currentLabel = currentRow?.entry.label ?? currentRow?.entry.id ?? "Version";
+---
+
+{visible && (
+  <details class="version-switcher relative">
+    <summary class="flex cursor-pointer items-center gap-1 rounded-md border border-border px-3 py-1.5 text-sm hover:bg-accent">
+      <span class="font-medium">{currentLabel}</span>
+      {currentRow?.entry.eol && (
+        <span class="ml-1 rounded bg-muted px-1 text-[10px] uppercase text-muted-foreground">EOL</span>
+      )}
+      <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="ml-1 transition-transform"><polyline points="6 9 12 15 18 9"/></svg>
+    </summary>
+    <ul class="absolute right-0 z-50 mt-1 min-w-[10rem] rounded-md border border-border bg-popover p-1 text-sm shadow-md">
+      {rows.map((row) => {
+        const href = row.url ?? fallbackLandingUrl(basePath, row.entry.id);
+        const isFallback = row.url === null && !row.isCurrent;
+        return (
+          <li>
+            <a
+              href={href}
+              aria-current={row.isCurrent ? "true" : undefined}
+              class:list={[
+                "flex items-center gap-2 rounded-sm px-2 py-1.5 no-underline",
+                row.isCurrent
+                  ? "bg-accent font-medium text-foreground"
+                  : "text-foreground hover:bg-accent",
+              ]}
+            >
+              <span class="flex-1">{row.entry.label ?? row.entry.id}</span>
+              {row.entry.eol && (
+                <span class="rounded bg-muted px-1 text-[10px] uppercase text-muted-foreground">EOL</span>
+              )}
+              {row.entry.default && !row.isCurrent && (
+                <span class="text-[10px] text-muted-foreground">default</span>
+              )}
+              {isFallback && (
+                <span title="Page not available in this version" class="text-[10px] text-muted-foreground">→</span>
+              )}
+            </a>
+          </li>
+        );
+      })}
+    </ul>
+  </details>
+)}
+
+<style>
+  .version-switcher > summary {
+    list-style: none;
+  }
+  .version-switcher > summary::-webkit-details-marker {
+    display: none;
+  }
+  .version-switcher[open] > summary > svg:last-child {
+    transform: rotate(180deg);
+  }
+</style>

package/src/json-ld.ts

@@ -0,0 +1,55 @@
+/**
+ * JSON-LD helpers — pure functions consumed by DocsLayout to
+ * decide which Schema.org `@type` to emit and to normalize the
+ * `customJsonLd` prop shape.
+ *
+ * The 100daysofdocs SEO audit flagged that DocsLayout was emitting
+ * `Article` for every page regardless of intent — tutorials and
+ * how-to pages should render as `HowTo` for SERP rich results.
+ * This module owns the type selection so it's testable without
+ * spinning up an Astro renderer.
+ */
+
+/**
+ * Map a `meta.type` value (the open-string `pageType` prop on
+ * DocsLayout) to a Schema.org `@type`.
+ *
+ * The mapping intentionally accepts a few common spelling
+ * variants (`"how-to"` / `"howto"`, `"reference"` / `"ref"` /
+ * `"api"`) so writers don't have to learn one canonical spelling
+ * to get the right structured data. Anything else falls back to
+ * `Article`, which is Google's "general docs page" assumption.
+ */
+export function jsonLdTypeFor(pageType: string | undefined): string {
+  switch (pageType) {
+    case "tutorial":
+    case "how-to":
+    case "howto":
+      return "HowTo";
+    case "reference":
+    case "ref":
+    case "api":
+      return "TechArticle";
+    case "course":
+      return "Course";
+    default:
+      return "Article";
+  }
+}
+
+/**
+ * Normalize the `customJsonLd` prop into an array. DocsLayout
+ * accepts either a single object (most common case — one extra
+ * Course / Organization block) or an array (sites that layer
+ * several blocks per page).
+ *
+ * Returns an empty array for `undefined` so the template can
+ * iterate uniformly without conditional rendering.
+ */
+export function normalizeCustomJsonLd(
+  raw: Record<string, unknown> | Record<string, unknown>[] | undefined,
+): Record<string, unknown>[] {
+  if (!raw) return [];
+  if (Array.isArray(raw)) return raw;
+  return [raw];
+}