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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/docs-layout",
-  "version": "0.2.0-beta.98",
+  "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.98",
-    "@dogsbay/ui": "0.2.0-beta.98"
+    "@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

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;