@dogsbay/docs-layout 0.2.0-beta.96 → 0.2.0-beta.99

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/docs-layout",
-  "version": "0.2.0-beta.96",
+  "version": "0.2.0-beta.99",
   "description": "Standard documentation layout components for Dogsbay",
   "type": "module",
   "exports": {
@@ -30,8 +30,8 @@
     "./json-ld": "./src/json-ld.ts"
   },
   "dependencies": {
-    "@dogsbay/primitives": "0.2.0-beta.96",
-    "@dogsbay/ui": "0.2.0-beta.96"
+    "@dogsbay/primitives": "0.2.0-beta.99",
+    "@dogsbay/ui": "0.2.0-beta.99"
   },
   "devDependencies": {
     "happy-dom": "^20.10.6",

package/src/DocsLayout.astro

@@ -47,7 +47,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, buildArticleJsonLd } from "./json-ld.js";
+import { jsonLdTypeFor, normalizeCustomJsonLd, buildArticleJsonLd, buildWebSiteJsonLd } from "./json-ld.js";
 import { resolveTagKeywords } from "./tag-list-data.js";
 
 interface NavItem {
@@ -623,6 +623,23 @@ const computedCanonical = canonicalUrl
  * raw value if it will not parse, so a typo shows up as itself rather
  * than as "Invalid Date".
  */
+/**
+ * A value as a machine-readable ISO 8601 datetime, or "" when it is
+ * not a date at all.
+ *
+ * Unlike `_formatPostDate`, an unparseable value must NOT pass
+ * through: this feeds `article:published_time` / `modified_time`,
+ * where a malformed datetime is worse than an absent one — a consumer
+ * either ignores the whole article object or shows garbage.
+ * `lastUpdated` is documented as also accepting a version/tag string
+ * ("v2.1"), which must never reach these tags.
+ */
+function isoDate(value: string | undefined): string {
+  if (!value) return "";
+  const d = new Date(value);
+  return Number.isNaN(d.getTime()) ? "" : d.toISOString();
+}
+
 function _formatPostDate(iso: string): string {
   const d = new Date(iso);
   if (Number.isNaN(d.getTime())) return iso;
@@ -682,7 +699,14 @@ const tagKeywords = resolveTagKeywords(tags, tagLabels);
 // Course; everything else → Article. Matches the conventions
 // 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)
+// Structured data is emitted for EVERY page, not only tagged articles.
+// This used to also require `tagKeywords.length > 0`, so an untagged
+// page — a homepage, a landing page, a section index — emitted none at
+// all. An external agent audit reported "No JSON-LD structured data
+// found on homepage" and it was right: the page most likely to be an
+// agent's entry point was the one describing itself the least.
+// Keywords are enrichment, not a precondition for identity.
+const articleJsonLd = ogType === "article"
   ? buildArticleJsonLd({
       type: jsonLdTypeFor(pageType),
       title,
@@ -693,7 +717,12 @@ const articleJsonLd = (ogType === "article" && tagKeywords.length > 0)
       url: computedCanonical,
       headings,
     })
-  : undefined;
+  : buildWebSiteJsonLd({
+      siteName,
+      title,
+      description: metaDescription,
+      url: computedCanonical,
+    });
 
 // `customJsonLd` accepts either a single object or an array.
 // Normalize to an array so we can iterate uniformly. Empty array
@@ -806,6 +835,26 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
     {ogType === "article" && tagKeywords.map((keyword) => (
       <meta property="article:tag" content={keyword} />
     ))}
+    {/* Article dates. `og:type="article"` was declared with no times
+       at all, which is an incomplete article object — crawlers and
+       social cards had no publish date to show even though the page
+       renders one visibly.
+
+       `article:modified_time` falls back to `lastUpdated`, the prop
+       the docs chrome already uses for "Last updated", so a docs page
+       gets a modified time without the blog-only `updatedDate` being
+       set. Only emitted when the value parses as a date: a
+       frontmatter `lastUpdated: v2.1` is a version string, and a
+       malformed datetime is worse than an absent one. */}
+    {ogType === "article" && isoDate(publishedDate) && (
+      <meta property="article:published_time" content={isoDate(publishedDate)} />
+    )}
+    {ogType === "article" && isoDate(updatedDate ?? lastUpdated) && (
+      <meta
+        property="article:modified_time"
+        content={isoDate(updatedDate ?? lastUpdated)}
+      />
+    )}
 
     {/* JSON-LD primary block — Article / HowTo / TechArticle /
        Course depending on `pageType`. Emits keywords as a
@@ -839,10 +888,39 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
       ></script>
     )}
 
+    {/*
+      Theme bootstrap. Inline and BLOCKING on purpose — it must run
+      before first paint or the page flashes light before going dark.
+
+      An explicit choice wins in BOTH directions. Someone on a
+      dark-mode OS who deliberately picked light must stay light, so
+      "light" is checked rather than treated as "not dark". Only the
+      absence of a stored value falls through to the OS preference.
+
+      That fallback is the point of this block. Previously the only
+      condition was `=== "dark"`, so a visitor whose OS is in dark mode
+      got a light page until they found the toggle — and nothing else
+      in the CSS consulted prefers-color-scheme either. It also made
+      dark mode untestable by any tool that emulates the media query
+      (DevTools' Rendering panel, Playwright's colorScheme), because
+      the page did not read it.
+
+      localStorage access throws in some privacy modes; a throw here
+      would skip the class entirely, so it is guarded and degrades to
+      the OS preference.
+    */}
     <script is:inline>
-      if (localStorage.getItem("theme") === "dark") {
-        document.documentElement.classList.add("dark");
-      }
+      (function () {
+        var stored = null;
+        try {
+          stored = localStorage.getItem("theme");
+        } catch (e) {}
+        var dark =
+          stored === "dark" ||
+          (stored !== "light" &&
+            window.matchMedia("(prefers-color-scheme: dark)").matches);
+        if (dark) document.documentElement.classList.add("dark");
+      })();
     </script>
     <slot name="head" />
   </head>

package/src/TagList.astro

@@ -72,8 +72,13 @@ const chips = buildChips(tags, { indexPath, prefixes, labels });
  */
 const PALETTE: Record<TagPaletteName, string> = {
   blue: "border-blue-500/40 bg-blue-500/15 text-blue-700 dark:text-blue-300",
+  // amber-800, not -700, in light mode: amber-700 on amber-500/15 is
+  // 4.48:1 — under 4.5:1 by a hair, and failing regardless of the
+  // opacity bug below. -800 gives 6.32:1. Every other colour clears it
+  // at -700 (4.76–8.60:1). Dark mode is unaffected: text-*-300 on the
+  // same tint over a dark page is 9–12:1 across the palette.
   amber:
-    "border-amber-500/40 bg-amber-500/15 text-amber-700 dark:text-amber-300",
+    "border-amber-500/40 bg-amber-500/15 text-amber-800 dark:text-amber-300",
   emerald:
     "border-emerald-500/40 bg-emerald-500/15 text-emerald-700 dark:text-emerald-300",
   violet:
@@ -108,7 +113,17 @@ const DEFAULT_CLASS =
         >
           {chip.prefixLabel ? (
             <Fragment>
-              <span class="opacity-70">{chip.prefixLabel}:</span>
+              {/*
+                No opacity here. `opacity-70` on the prefix blended the
+                text 30% toward the chip background and put EVERY colour
+                in the palette below 4.5:1 — measured 2.75–3.95:1, worst
+                amber, best slate. It is 12px text, so 4.5:1 applies.
+
+                The prefix/leaf distinction is carried by font-weight
+                instead: the leaf below is font-semibold against the
+                anchor's font-medium. Weight costs no contrast.
+              */}
+              <span>{chip.prefixLabel}:</span>
               <span class="font-semibold">{chip.leafLabel}</span>
             </Fragment>
           ) : (

package/src/json-ld.ts

@@ -100,8 +100,10 @@ export function buildArticleJsonLd(
     "@context": "https://schema.org",
     "@type": type,
     name: title,
-    keywords: keywords.join(", "),
   };
+  // Only when there are any. An empty `keywords: ""` asserts the page
+  // has no topics, which is a different claim from staying silent.
+  if (keywords.length > 0) block.keywords = keywords.join(", ");
 
   if (type === "Article" || type === "TechArticle") {
     block.headline = title;