@grove-dev/astro 0.5.3 → 0.6.0

package/src/layouts/Seo.astro

@@ -8,16 +8,20 @@
  * has a sensible default derived from the site config and the Astro URL.
  *
  * Renders:
- *   - <title>, meta description, canonical link
+ *   - <title>, meta description, canonical link, robots
  *   - Open Graph (og:*) for Facebook, LinkedIn, Discord, Slack, etc.
  *   - Twitter Card (twitter:*) for X / Twitter
- *   - JSON-LD WebSite + Organization on every page
- *   - JSON-LD SoftwareSourceCode (or custom) when `jsonLd` is provided
- *     (e.g. on /items/[slug] for the per-item structured data)
+ *   - JSON-LD WebSite+Organization identity graph on every page
+ *     (built by @grove-dev/core's `siteSchema`, with a SearchAction
+ *     pointing at the directory's browse page)
+ *   - Per-page JSON-LD nodes when `jsonLd` is provided (SoftwareSourceCode
+ *     on record pages, CollectionPage/ItemList/BreadcrumbList on
+ *     collection and taxonomy pages, ...)
  *
  * Noindex is opt-in via the `noindex` prop. By default everything is
- * indexable; the only noindex target today is the thin /submit wrapper.
+ * indexable; noindex targets today are /submit, /404, and /empty.
  */
+import { siteSchema, validateJsonLd, type JsonLdNode } from '@grove-dev/core';
 
 interface Props {
   title: string;
@@ -26,10 +30,18 @@ interface Props {
     name: string;
     description?: string;
     repoUrl?: string;
+    /** Header logo path under `public/` — used as Organization logo when set. */
+    logo?: string;
+    /** BCP-47 language tag (e.g. "en"). Drives og:locale + JSON-LD inLanguage. */
+    locale?: string;
+    /** Twitter/X handle (e.g. "@grove") — emitted as twitter:site. */
+    twitter?: string;
   };
   searchPath?: string;
   /** Open Graph / Twitter image. Default: /og-image.svg. Should be absolute or root-relative. */
   image?: string;
+  /** Alt text for the OG/Twitter image. Default: "<site name> social preview". */
+  imageAlt?: string;
   /** og:type. Default: "website". Use "article" for blog posts / changelog. */
   type?: 'website' | 'article' | 'profile';
   /** Set true to add noindex,nofollow. */
@@ -44,6 +56,7 @@ const {
   site: siteConfig,
   searchPath = '/items',
   image = '/og-image.svg',
+  imageAlt,
   type = 'website',
   noindex = false,
   jsonLd,
@@ -63,54 +76,67 @@ if (!Astro.site) {
 const siteUrl = Astro.site;
 const canonical = new URL(Astro.url.pathname, siteUrl).toString();
 const ogImage = new URL(image, siteUrl).toString();
+const ogImageAlt = imageAlt ?? `${siteConfig.name} social preview`;
+const locale = siteConfig.locale ?? 'en';
 
 // Truncate description for OG/Twitter where longer is worse (160–200 chars).
 function truncate(s: string, max: number): string {
   if (s.length <= max) return s;
-  return s.slice(0, max - 1).trimEnd() + '\u2026';
+  return s.slice(0, max - 1).trimEnd() + '…';
 }
 const shortDescription = truncate(description, 200);
 
-// WebSite + Organization JSON-LD. These are site-wide identity signals
-// that should appear on every page (Google uses them for site links
-// and the knowledge panel).
-const websiteLd = {
-  '@context': 'https://schema.org',
-  '@type': 'WebSite',
+// WebSite+Organization identity graph — site-wide signals that appear on
+// every page (Google uses them for site links and the knowledge panel).
+// Built by core's `siteSchema` so the @id graph shape is shared with the
+// rest of the JSON-LD registry; the SearchAction is appended here because
+// the browse path is an adapter concern, not a core one.
+const bareSiteUrl = siteUrl.toString().replace(/\/$/, '');
+const [siteLd] = siteSchema({
+  url: bareSiteUrl,
   name: siteConfig.name,
   description: siteConfig.description ?? description,
-  url: siteUrl.toString().replace(/\/$/, ''),
-  inLanguage: 'en',
-  potentialAction: {
-    '@type': 'SearchAction',
-    target: `${siteUrl.toString().replace(/\/$/, '')}${searchPath}?q={search_term_string}`,
-    'query-input': 'required name=search_term_string',
-  },
-};
-
-const organizationLd = {
-  '@context': 'https://schema.org',
-  '@type': 'Organization',
-  name: siteConfig.name,
-  url: siteUrl.toString().replace(/\/$/, ''),
-  logo: new URL('/og-image.svg', siteUrl).toString(),
+  inLanguage: locale,
+  orgName: siteConfig.name,
+  orgUrl: bareSiteUrl,
+  ...(siteConfig.logo ? { orgLogo: new URL(siteConfig.logo, siteUrl).toString() } : {}),
   ...(siteConfig.repoUrl ? { sameAs: [siteConfig.repoUrl] } : {}),
+});
+siteLd.potentialAction = {
+  '@type': 'SearchAction',
+  target: `${bareSiteUrl}${searchPath}?q={search_term_string}`,
+  'query-input': 'required name=search_term_string',
 };
 
+const perPageNodes = jsonLd ? (Array.isArray(jsonLd) ? jsonLd : [jsonLd]) : null;
+
+// Dev-only well-formedness check — surfaces malformed nodes (relative
+// URLs, missing @context, duplicate @ids) in the terminal during
+// `astro dev` without ever failing or slowing a production build.
+if (import.meta.env.DEV && perPageNodes) {
+  const issues = validateJsonLd(perPageNodes as JsonLdNode[]);
+  for (const issue of issues) {
+    console.warn(`[grove seo] ${Astro.url.pathname}: ${issue.message}`);
+  }
+}
+
 // Pre-stringify the JSON-LD payloads in the frontmatter so the
 // template body just interpolates the resulting strings. For SSR
 // this saves the JSON.stringify call on every render; for static
 // builds the cost is unchanged but the template reads cleaner.
-const websiteLdJson = JSON.stringify(websiteLd);
-const organizationLdJson = JSON.stringify(organizationLd);
-const perPageLdJson = jsonLd ? JSON.stringify(Array.isArray(jsonLd) ? jsonLd : [jsonLd]) : null;
+const siteLdJson = JSON.stringify(siteLd);
+const perPageLdJson = perPageNodes ? JSON.stringify(perPageNodes) : null;
 ---
 
 <!-- Primary meta -->
 <title>{title}</title>
 <meta name="description" content={description} />
 <link rel="canonical" href={canonical} />
-{noindex && <meta name="robots" content="noindex,nofollow" />}
+{noindex ? (
+  <meta name="robots" content="noindex,nofollow" />
+) : (
+  <meta name="robots" content="index,follow,max-image-preview:large" />
+)}
 
 <!-- Open Graph -->
 <meta property="og:type" content={type} />
@@ -120,22 +146,22 @@ const perPageLdJson = jsonLd ? JSON.stringify(Array.isArray(jsonLd) ? jsonLd : [
 <meta property="og:image" content={ogImage} />
 <meta property="og:image:width" content="1200" />
 <meta property="og:image:height" content="630" />
-<meta property="og:image:alt" content={`${siteConfig.name} social preview`} />
+<meta property="og:image:alt" content={ogImageAlt} />
 <meta property="og:site_name" content={siteConfig.name} />
-<meta property="og:locale" content="en" />
+<meta property="og:locale" content={locale} />
 
 <!-- Twitter Card -->
 <meta name="twitter:card" content="summary_large_image" />
+{siteConfig.twitter && <meta name="twitter:site" content={siteConfig.twitter} />}
 <meta name="twitter:title" content={title} />
 <meta name="twitter:description" content={shortDescription} />
 <meta name="twitter:image" content={ogImage} />
-<meta name="twitter:image:alt" content={`${siteConfig.name} social preview`} />
+<meta name="twitter:image:alt" content={ogImageAlt} />
 
-<!-- JSON-LD: site-wide identity -->
-<script is:inline type="application/ld+json" set:html={websiteLdJson} />
-<script is:inline type="application/ld+json" set:html={organizationLdJson} />
+<!-- JSON-LD: site-wide identity graph -->
+<script is:inline type="application/ld+json" set:html={siteLdJson} />
 
-<!-- JSON-LD: per-page (SoftwareSourceCode for /items/[slug], etc.) -->
+<!-- JSON-LD: per-page (SoftwareSourceCode, CollectionPage, BreadcrumbList, ...) -->
 {perPageLdJson && (
   <script
     is:inline

package/src/lib/index.ts

@@ -23,7 +23,6 @@ export * from "./lenses.js";
 export * from "./search.js";
 export * from "./taxonomy-counts.js";
 export * from "./display.js";
-export * from "./load-collections.js";
 export * from "./icon-registry.js";
 export * from "./icon-kinds.js";
 export * from "./packaged-icons.js";

package/src/server/collections.ts

@@ -1,8 +1,10 @@
 import type { Collection, CollectionEntry } from "@grove-dev/core";
-import { findRelated, runCollection } from "@grove-dev/core";
-import { readFile, readdir } from "node:fs/promises";
-import { join, resolve } from "node:path";
-import { parse as parseYaml } from "yaml";
+import { collectionSchema, findRelated, runCollection } from "@grove-dev/core";
+import { absoluteUrl, ogPath, type PageSeo, seoDescription, seoTitle } from "./seo.js";
+
+// Collection YAML loading lives in @grove-dev/core (it also feeds the
+// sitemap and OG-image pipelines there); re-exported for page code.
+export { loadCollections } from "@grove-dev/core";
 
 interface RouteHint {
   routeSlug?: string;
@@ -123,10 +125,12 @@ export interface CollectionPageModel {
   total: number;
   isEmpty: boolean;
   entries: CollectionEntry[];
-  /** ItemList JSON-LD block. Pass to BaseLayout as the `jsonLd` prop
-   *  so it ships in the document head and is indexable by search
-   *  engines as a list of `SoftwareApplication` items. */
+  /** CollectionPage + ItemList + BreadcrumbList JSON-LD nodes. Ships
+   *  through `seo.jsonLd`; kept here too for backward compatibility. */
   jsonLd?: unknown;
+  /** Complete head block: honors the collection's `seo.title`,
+   *  `seo.description`, and `seo.index` overrides. Pass to BaseLayout. */
+  seo: PageSeo;
   related: Array<{ slug: string; title: string; url: string }>;
 }
 
@@ -140,6 +144,9 @@ export interface CollectionIndexModel {
     count: number;
     url: string;
   }>;
+  /** Head block for the /collections/ index — present when the caller
+   *  passes a site config. */
+  seo?: PageSeo;
 }
 
 export interface CollectionTeaserModel {
@@ -151,7 +158,7 @@ export function getCollectionPageModel(
   collection: Collection,
   entries: CollectionEntry[],
   allCollections: Collection[],
-  site?: { name?: string; url?: string },
+  site?: { name?: string; url?: string; siteUrl?: string; blueprintConfig?: { labelPlural?: string } },
 ): CollectionPageModel {
   const result = runCollection(collection, entries);
   const related = findRelated(collection, allCollections, 4).map((c) => ({
@@ -159,28 +166,43 @@ export function getCollectionPageModel(
     title: c.title,
     url: `/collections/${c.slug}/`,
   }));
-  // ItemList JSON-LD. Search engines can use this to surface
-  // individual entries directly from the collection URL.
-  // Cap at 50 entries to keep the JSON-LD payload bounded;
-  // search engines don't index beyond that anyway.
-  const itemListElement = result.entries.slice(0, 50).map((entry, index) => ({
-    "@type": "ListItem",
-    position: index + 1,
-    item: {
-      "@type": "SoftwareApplication",
+  const siteUrl = (site?.siteUrl ?? site?.url ?? "https://example.com").replace(/\/$/, "");
+  const siteName = site?.name ?? "";
+  const plural = site?.blueprintConfig?.labelPlural ?? "items";
+  const pageUrl = absoluteUrl(siteUrl, `collections/${collection.slug}/`);
+  // CollectionPage + ItemList + BreadcrumbList. The ItemList is capped
+  // at 50 entries to keep the payload bounded; search engines don't
+  // index list markup beyond that anyway.
+  const jsonLd = collectionSchema({
+    url: pageUrl,
+    name: collection.seo?.title ?? collection.title,
+    description: collection.seo?.description ?? collection.description,
+    items: result.entries.slice(0, 50).map((entry) => ({
+      url: entry.url.startsWith("http") ? entry.url : absoluteUrl(siteUrl, entry.url),
       name: entry.title,
-      url: entry.url,
-      description: entry.description,
-    },
-  }));
-  const jsonLd = {
-    "@context": "https://schema.org",
-    "@type": "ItemList",
-    name: collection.title,
-    description: collection.description,
-    url: site?.url ? `${site.url.replace(/\/$/, "")}/collections/${collection.slug}/` : undefined,
-    numberOfItems: result.entries.length,
-    itemListElement,
+      ...(entry.description ? { description: entry.description } : {}),
+    })),
+    crumbs: [
+      { url: `${siteUrl}/`, name: "Home" },
+      { url: absoluteUrl(siteUrl, "collections/"), name: "Collections" },
+      { url: pageUrl, name: collection.title },
+    ],
+  });
+  // The curator's `seo.title` / `seo.description` overrides win
+  // verbatim; the fallback pattern advertises the list size. A
+  // collection marked `seo.index: false` renders with noindex.
+  const seo: PageSeo = {
+    title:
+      collection.seo?.title ??
+      seoTitle(`${collection.title} — ${result.entries.length} ${plural}`, siteName),
+    description: seoDescription(
+      collection.seo?.description,
+      collection.description,
+    ),
+    image: ogPath("collection", collection.slug),
+    ...(siteName ? { imageAlt: `${collection.title} — ${siteName}` } : {}),
+    jsonLd: jsonLd as unknown as Record<string, unknown>[],
+    noindex: collection.seo?.index === false,
   };
   return {
     collection: {
@@ -196,26 +218,60 @@ export function getCollectionPageModel(
     entries: result.entries,
     related,
     jsonLd,
+    seo,
   };
 }
 
 export function getCollectionIndexModel(
   collections: Collection[],
   entries: CollectionEntry[],
+  site?: { name?: string; url?: string; siteUrl?: string; blueprintConfig?: { labelPlural?: string } },
 ): CollectionIndexModel {
+  const rows = collections.map((c) => {
+    const result = runCollection(c, entries);
+    return {
+      slug: c.slug,
+      title: c.title,
+      description: c.description,
+      kind: c.kind,
+      count: result.entries.length,
+      url: `/collections/${c.slug}/`,
+    };
+  });
+  let seo: PageSeo | undefined;
+  if (site) {
+    const siteUrl = (site.siteUrl ?? site.url ?? "https://example.com").replace(/\/$/, "");
+    const siteName = site.name ?? "";
+    const plural = site.blueprintConfig?.labelPlural ?? "items";
+    const title = seoTitle("Collections", siteName);
+    const description = seoDescription(
+      undefined,
+      `${rows.length} curated and generated collections of ${plural} on ${siteName || "this site"} — hand-picked lists kept in sync with the source files.`,
+    );
+    seo = {
+      title,
+      description,
+      image: ogPath("default"),
+      jsonLd: collectionSchema({
+        url: absoluteUrl(siteUrl, "collections/"),
+        name: title,
+        description,
+        items: rows.map((row) => ({
+          url: absoluteUrl(siteUrl, row.url),
+          name: row.title,
+          ...(row.description ? { description: row.description } : {}),
+        })),
+        crumbs: [
+          { url: `${siteUrl}/`, name: "Home" },
+          { url: absoluteUrl(siteUrl, "collections/"), name: "Collections" },
+        ],
+      }) as unknown as Record<string, unknown>[],
+    };
+  }
   return {
     total: collections.length,
-    collections: collections.map((c) => {
-      const result = runCollection(c, entries);
-      return {
-        slug: c.slug,
-        title: c.title,
-        description: c.description,
-        kind: c.kind,
-        count: result.entries.length,
-        url: `/collections/${c.slug}/`,
-      };
-    }),
+    collections: rows,
+    ...(seo ? { seo } : {}),
   };
 }
 
@@ -231,33 +287,6 @@ export function getCollectionTeaserModel(
   };
 }
 
-/**
- * Load all `Collection` YAML files from `<cwd>/data/collections/*.yml`.
- *
- * Returns an empty array if the directory does not exist. Parse
- * errors are NOT swallowed — they surface so real problems
- * (malformed YAML, permission errors) are not hidden.
- */
-export async function loadCollections(cwd: string): Promise<Collection[]> {
-  const dir = resolve(cwd, "data/collections");
-  let files: string[];
-  try {
-    files = await readdir(dir);
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
-    throw err;
-  }
-  const out: Collection[] = [];
-  for (const f of files.filter((f) => f.endsWith(".yml"))) {
-    const raw = parseYaml(await readFile(join(dir, f), "utf8"));
-    if (!raw || typeof raw !== "object") {
-      throw new Error(`Invalid collection YAML: ${f}`);
-    }
-    out.push(raw as Collection);
-  }
-  return out;
-}
-
 /**
  * Reverse lookup — given a record, return the slugs of every
  * curated collection that includes it. Walks each collection's

package/src/server/index.ts

@@ -2,3 +2,4 @@ export * from './directory.js';
 export * from './models.js';
 export * from './collections.js';
 export * from './github-repo.js';
+export * from './seo.js';