@dogsbay/docs-layout 0.2.0-beta.44 → 0.2.0-beta.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/docs-layout",
-  "version": "0.2.0-beta.44",
+  "version": "0.2.0-beta.46",
   "description": "Standard documentation layout components for Dogsbay",
   "type": "module",
   "exports": {
@@ -29,8 +29,8 @@
     "./json-ld": "./src/json-ld.ts"
   },
   "dependencies": {
-    "@dogsbay/ui": "0.2.0-beta.44",
-    "@dogsbay/primitives": "0.2.0-beta.44"
+    "@dogsbay/ui": "0.2.0-beta.46",
+    "@dogsbay/primitives": "0.2.0-beta.46"
   },
   "devDependencies": {
     "vitest": "^3.0.0"

package/src/DocsLayout.astro

@@ -44,7 +44,7 @@ import VersionSwitcher from "./VersionSwitcher.astro";
 import LocaleSwitcher from "./LocaleSwitcher.astro";
 import { filterNavByAxis } from "./nav-filter.js";
 import type { LlmProviderName } from "./llm-actions.js";
-import { jsonLdTypeFor, normalizeCustomJsonLd } from "./json-ld.js";
+import { jsonLdTypeFor, normalizeCustomJsonLd, buildArticleJsonLd } from "./json-ld.js";
 import { resolveTagKeywords } from "./tag-list-data.js";
 
 interface NavItem {
@@ -548,15 +548,16 @@ const tagKeywords = resolveTagKeywords(tags, tagLabels);
 // search engines key off for educational / tutorial / reference
 // SERP rendering. See `json-ld.ts` for the full mapping table.
 const articleJsonLd = (ogType === "article" && tagKeywords.length > 0)
-  ? {
-      "@context": "https://schema.org",
-      "@type": jsonLdTypeFor(pageType),
-      headline: title,
-      keywords: tagKeywords.join(", "),
-      ...(metaDescription ? { description: metaDescription } : {}),
-      ...(metaOgImage ? { image: metaOgImage } : {}),
-      ...(computedCanonical ? { url: computedCanonical } : {}),
-    }
+  ? buildArticleJsonLd({
+      type: jsonLdTypeFor(pageType),
+      title,
+      siteName,
+      keywords: tagKeywords,
+      description: metaDescription,
+      image: metaOgImage,
+      url: computedCanonical,
+      headings,
+    })
   : undefined;
 
 // `customJsonLd` accepts either a single object or an array.

package/src/json-ld.ts

@@ -53,3 +53,80 @@ export function normalizeCustomJsonLd(
   if (Array.isArray(raw)) return raw;
   return [raw];
 }
+
+export interface BuildArticleJsonLdOptions {
+  /** Already-resolved Schema.org `@type` (output of jsonLdTypeFor). */
+  type: string;
+  title: string;
+  /** Site name — used as the `provider` Organization for Course. */
+  siteName: string;
+  keywords: string[];
+  description?: string;
+  image?: string;
+  url?: string;
+  /**
+   * Page headings — used to synthesize `step[]` for HowTo. Each
+   * H2 (or H3 if no H2s exist) becomes a HowToStep with a deep
+   * link to the heading id.
+   */
+  headings?: ReadonlyArray<{ depth: number; slug: string; text: string }>;
+}
+
+/**
+ * Build the JSON-LD payload for the page's primary structured-data
+ * block, shaped per `@type`. The earlier implementation emitted
+ * Article-shaped fields (`headline`) regardless of @type, which
+ * meant HowTo / Course pages failed Google's Rich Results
+ * requirements (HowTo needs `name` + `step`, Course needs `name` +
+ * `description` + `provider`). See
+ * `packages/cli/src/audit/rules/seo/json-ld-required-fields.ts`
+ * for the validator that catches this.
+ *
+ * Schema.org's `name` is a Thing-level field accepted by every
+ * @type, so we always emit it. `headline` is added on top for
+ * Article-family types (Article, TechArticle) because Google's
+ * Rich Results validator specifically requires it there. HowTo
+ * gets a synthesized `step[]` from the page's H2 headings (each
+ * H2 = one procedure step); Course gets a `provider` Organization
+ * built from `siteName`.
+ */
+export function buildArticleJsonLd(
+  opts: BuildArticleJsonLdOptions,
+): Record<string, unknown> {
+  const { type, title, siteName, keywords, description, image, url, headings } =
+    opts;
+
+  const block: Record<string, unknown> = {
+    "@context": "https://schema.org",
+    "@type": type,
+    name: title,
+    keywords: keywords.join(", "),
+  };
+
+  if (type === "Article" || type === "TechArticle") {
+    block.headline = title;
+  }
+
+  if (description) block.description = description;
+  if (image) block.image = image;
+  if (url) block.url = url;
+
+  if (type === "HowTo") {
+    let stepHeadings = (headings ?? []).filter((h) => h.depth === 2);
+    if (stepHeadings.length === 0) {
+      stepHeadings = (headings ?? []).filter((h) => h.depth === 3);
+    }
+    block.step = stepHeadings.map((h) => ({
+      "@type": "HowToStep",
+      name: h.text,
+      url: url ? `${url}#${h.slug}` : `#${h.slug}`,
+    }));
+  }
+
+  if (type === "Course") {
+    block.provider = { "@type": "Organization", name: siteName };
+    if (!block.description) block.description = title;
+  }
+
+  return block;
+}