@jdevalk/astro-seo-graph 0.2.4 → 0.3.0

package/README.md

@@ -2,30 +2,25 @@
 
 Astro integration for [`@jdevalk/seo-graph-core`](../seo-graph-core). Ships a
 `<Seo>` component, route factories for agent-ready schema endpoints, a
-content-collection aggregator, and Zod helpers for content schemas.
-
-> **Status:** `0.1.0` (pre-1.0). The API works and has two real consumers
-> in production (joost.blog and limonaia.house), but a few known warts in
-> the core will be smoothed out in `0.2.x` without breaking changes. See
-> `@jdevalk/seo-graph-core`'s README for the full list.
-
-## What's in v0.1
-
-| API                            | Purpose                                                                                                                                                                                                                                                                 |
-| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`<Seo>`** (`./Seo.astro`)    | Single head component covering `<title>`, meta description, canonical, Open Graph, Twitter card, hreflang alternates, and optional JSON-LD `@graph`. Wraps [`astro-seo`](https://github.com/jonasmerlin/astro-seo) for the meta tags.                                   |
-| **`createSchemaEndpoint`**     | Factory returning an Astro `APIRoute` handler that serves a corpus-wide JSON-LD `@graph` for a content collection.                                                                                                                                                      |
-| **`createSchemaMap`**          | Factory returning an `APIRoute` handler that emits a sitemap-style XML listing of your site's schema endpoints — the discovery point for agent crawlers.                                                                                                                |
-| **`aggregate`**                | Shared engine behind the endpoint factories. Walks a list of entries, runs a caller-supplied mapper, deduplicates by `@id`.                                                                                                                                             |
-| **`seoSchema`, `imageSchema`** | Zod schemas for the `seo` and `image` fields on content collections. Import them into `src/content.config.ts`.                                                                                                                                                          |
-| **`buildAstroSeoProps`**       | Pure-TS logic that powers `<Seo>` — exported for users who want to feed a different head component.                                                                                                                                                                     |
-| **`buildAlternateLinks`**      | Pure helper that turns a `{ hreflang, href }` entry list into normalized `<link rel="alternate">` tags plus an `x-default`. Used internally by `<Seo>`'s `alternates` prop, and exported for non-Astro callers (e.g. CMS plugins feeding their own metadata pipelines). |
-
-## Not in `0.1.x` (coming in `0.2.x`)
-
-- **`createOgRenderer`** — a themeable `satori` + `sharp` wrapper for generating
-  Open Graph images at build time. Pulled out of `0.1` to keep the dep tree
-  free of native binaries. Keep using your own `og-image.ts` for now.
+content-collection aggregator, breadcrumb helpers, and Zod helpers for content
+schemas.
+
+For detailed usage — including all builder signatures, site-type recipes, and
+schema.org best practices — see [AGENTS.md](../../AGENTS.md) in the repository
+root.
+
+## What you get
+
+| API | Purpose |
+|---|---|
+| **`<Seo>`** (`./Seo.astro`) | Single head component covering `<title>`, meta description, canonical, Open Graph, Twitter card, hreflang alternates, and optional JSON-LD `@graph`. Wraps [`astro-seo`](https://github.com/jonasmerlin/astro-seo) for the meta tags. |
+| **`createSchemaEndpoint`** | Factory returning an Astro `APIRoute` handler that serves a corpus-wide JSON-LD `@graph` for a content collection. |
+| **`createSchemaMap`** | Factory returning an `APIRoute` handler that emits a sitemap-style XML listing of your site's schema endpoints — the discovery point for agent crawlers. |
+| **`aggregate`** | Shared engine behind the endpoint factories. Walks a list of entries, runs a caller-supplied mapper, deduplicates by `@id`. |
+| **`seoSchema`, `imageSchema`** | Zod schemas for the `seo` and `image` fields on content collections. Import them into `src/content.config.ts`. |
+| **`buildAstroSeoProps`** | Pure-TS logic that powers `<Seo>` — exported for users who want to feed a different head component. |
+| **`buildAlternateLinks`** | Pure helper that turns a `{ hreflang, href }` entry list into normalized `<link rel="alternate">` tags plus an `x-default`. Used internally by `<Seo>`'s `alternates` prop, and exported for non-Astro callers (e.g. CMS plugins feeding their own metadata pipelines). |
+| **`breadcrumbsFromUrl`** | Derives a breadcrumb trail from an Astro URL. Splits path segments, supports custom display names and segment skipping. Returns `BreadcrumbItem[]` ready to pass to `buildBreadcrumbList`. |
 
 ## Installation
 
@@ -78,6 +73,41 @@ const graph = buildSchemaGraph({
 </html>
 ```
 
+## Breadcrumbs from URL
+
+Derive a breadcrumb trail from an Astro page URL instead of computing it
+manually:
+
+```ts
+import { breadcrumbsFromUrl } from '@jdevalk/astro-seo-graph';
+import { buildBreadcrumbList, makeIds } from '@jdevalk/seo-graph-core';
+
+const ids = makeIds({ siteUrl: 'https://example.com' });
+const url = 'https://example.com/blog/open-source/my-post/';
+
+const items = breadcrumbsFromUrl({
+    url: Astro.url,                          // or any URL / string
+    siteUrl: 'https://example.com',
+    pageName: 'My Post',                     // display name for the current page
+    // homeName: 'Home',                     // optional, defaults to 'Home'
+    // names: { blog: 'Articles' },          // optional, custom segment names
+    // skip: ['category'],                   // optional, segments to omit
+});
+
+const breadcrumb = buildBreadcrumbList({ url, items }, ids);
+// items === [
+//   { name: 'Home', url: 'https://example.com/' },
+//   { name: 'Blog', url: 'https://example.com/blog/' },
+//   { name: 'Open Source', url: 'https://example.com/blog/open-source/' },
+//   { name: 'My Post', url: 'https://example.com/blog/open-source/my-post/' },
+// ]
+```
+
+Segments without a `names` entry are title-cased from their slug
+(`open-source` → `Open Source`). Sites with a base path
+(e.g. `https://example.com/docs`) are supported — pass the base path as part
+of `siteUrl`.
+
 ## hreflang alternates
 
 For multilingual sites, pass an `alternates` prop with one entry per locale.
@@ -181,6 +211,7 @@ export const GET = createSchemaEndpoint({
                     datePublished: post.data.publishDate,
                 },
                 ids,
+                'BlogPosting',
             ),
         ];
     },

package/dist/breadcrumbs.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Breadcrumb derivation helper for Astro pages.
+ *
+ * Pure function: no DOM, no fetch, no Astro runtime. Takes a page URL
+ * (typically `Astro.url`) and derives an ordered breadcrumb trail from
+ * its path segments. The returned `BreadcrumbItem[]` array is passed
+ * straight to `buildBreadcrumbList` from `@jdevalk/seo-graph-core`.
+ *
+ * Callers control display names via the `names` map and can omit
+ * segments via `skip`. Segments without a mapped name are title-cased
+ * from their slug (e.g. `open-source` → `Open Source`).
+ */
+import type { BreadcrumbItem } from '@jdevalk/seo-graph-core';
+export interface BreadcrumbsFromUrlInput {
+    /**
+     * The full page URL. Typically `Astro.url` inside a layout, or any
+     * absolute URL string.
+     */
+    url: URL | string;
+    /**
+     * Site origin with optional base path, e.g. `'https://example.com'`
+     * or `'https://example.com/docs'`. Used to construct absolute URLs
+     * for each crumb. Must not end with a slash.
+     */
+    siteUrl: string;
+    /** Display name for the current (last) page. */
+    pageName: string;
+    /**
+     * Display name for the root crumb. Defaults to `'Home'`.
+     */
+    homeName?: string;
+    /**
+     * Map of path segments to display names. Keys are individual slug
+     * segments (e.g. `'blog'`, `'open-source'`). Segments not in this
+     * map are title-cased from their slug.
+     */
+    names?: Readonly<Record<string, string>>;
+    /**
+     * Segments to exclude from the breadcrumb trail. The pages they
+     * point to are still valid URLs — they just won't appear as crumbs.
+     * For example, `['category']` skips a `/blog/category/` crumb while
+     * still including `/blog/category/open-source/`.
+     */
+    skip?: readonly string[];
+}
+/**
+ * Derive a breadcrumb trail from a page URL.
+ *
+ * Always includes a root ("Home") crumb and the current page as the
+ * last crumb. Intermediate crumbs are derived from path segments
+ * between root and the page, skipping any segments listed in `skip`.
+ *
+ * @returns Ordered `BreadcrumbItem[]`, root first. Pass directly to
+ *          `buildBreadcrumbList`'s `items` field.
+ */
+export declare function breadcrumbsFromUrl(input: BreadcrumbsFromUrlInput): BreadcrumbItem[];
+//# sourceMappingURL=breadcrumbs.d.ts.map

package/dist/breadcrumbs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"breadcrumbs.d.ts","sourceRoot":"","sources":["../src/breadcrumbs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE9D,MAAM,WAAW,uBAAuB;IACpC;;;OAGG;IACH,GAAG,EAAE,GAAG,GAAG,MAAM,CAAC;IAElB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAEzC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAqBD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,cAAc,EAAE,CAkCnF"}

package/dist/breadcrumbs.js

@@ -0,0 +1,69 @@
+/**
+ * Breadcrumb derivation helper for Astro pages.
+ *
+ * Pure function: no DOM, no fetch, no Astro runtime. Takes a page URL
+ * (typically `Astro.url`) and derives an ordered breadcrumb trail from
+ * its path segments. The returned `BreadcrumbItem[]` array is passed
+ * straight to `buildBreadcrumbList` from `@jdevalk/seo-graph-core`.
+ *
+ * Callers control display names via the `names` map and can omit
+ * segments via `skip`. Segments without a mapped name are title-cased
+ * from their slug (e.g. `open-source` → `Open Source`).
+ */
+/**
+ * Title-case a URL slug: split on hyphens, capitalize each word.
+ *
+ * `'open-source'` → `'Open Source'`
+ */
+function titleCaseSlug(slug) {
+    return slug
+        .split('-')
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ');
+}
+/**
+ * Ensure `url` ends with exactly one trailing slash.
+ */
+function trailingSlash(url) {
+    return url.endsWith('/') ? url : url + '/';
+}
+/**
+ * Derive a breadcrumb trail from a page URL.
+ *
+ * Always includes a root ("Home") crumb and the current page as the
+ * last crumb. Intermediate crumbs are derived from path segments
+ * between root and the page, skipping any segments listed in `skip`.
+ *
+ * @returns Ordered `BreadcrumbItem[]`, root first. Pass directly to
+ *          `buildBreadcrumbList`'s `items` field.
+ */
+export function breadcrumbsFromUrl(input) {
+    const { pageName, homeName = 'Home', names = {}, skip = [] } = input;
+    const normalizedSiteUrl = trailingSlash(input.siteUrl);
+    const pageUrl = typeof input.url === 'string' ? new URL(input.url) : input.url;
+    const pageHref = trailingSlash(pageUrl.href);
+    // Derive the path relative to the site origin.
+    const siteOrigin = new URL(normalizedSiteUrl);
+    const relativePath = pageUrl.pathname.slice(siteOrigin.pathname.length);
+    const segments = relativePath.split('/').filter(Boolean);
+    // When the page is the site root, there is only one crumb.
+    if (segments.length === 0) {
+        return [{ name: pageName, url: pageHref }];
+    }
+    const skipSet = new Set(skip);
+    const items = [{ name: homeName, url: normalizedSiteUrl }];
+    // Build intermediate crumbs (everything except the last segment,
+    // which is the current page).
+    let accumulated = siteOrigin.pathname;
+    for (const segment of segments.slice(0, -1)) {
+        accumulated = trailingSlash(accumulated + segment);
+        if (skipSet.has(segment))
+            continue;
+        const name = names[segment] ?? titleCaseSlug(segment);
+        items.push({ name, url: siteOrigin.origin + accumulated });
+    }
+    // Current page is always the last crumb.
+    items.push({ name: pageName, url: pageHref });
+    return items;
+}
+//# sourceMappingURL=breadcrumbs.js.map

package/dist/breadcrumbs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"breadcrumbs.js","sourceRoot":"","sources":["../src/breadcrumbs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA0CH;;;;GAIG;AACH,SAAS,aAAa,CAAC,IAAY;IAC/B,OAAO,IAAI;SACN,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SAC3D,IAAI,CAAC,GAAG,CAAC,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,SAAS,aAAa,CAAC,GAAW;IAC9B,OAAO,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC;AAC/C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAA8B;IAC7D,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,MAAM,EAAE,KAAK,GAAG,EAAE,EAAE,IAAI,GAAG,EAAE,EAAE,GAAG,KAAK,CAAC;IAErE,MAAM,iBAAiB,GAAG,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,OAAO,KAAK,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC;IAC/E,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7C,+CAA+C;IAC/C,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAC9C,MAAM,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACxE,MAAM,QAAQ,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAEzD,2DAA2D;IAC3D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,KAAK,GAAqB,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,iBAAiB,EAAE,CAAC,CAAC;IAE7E,iEAAiE;IACjE,8BAA8B;IAC9B,IAAI,WAAW,GAAG,UAAU,CAAC,QAAQ,CAAC;IACtC,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1C,WAAW,GAAG,aAAa,CAAC,WAAW,GAAG,OAAO,CAAC,CAAC;QACnD,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,SAAS;QACnC,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC;QACtD,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,UAAU,CAAC,MAAM,GAAG,WAAW,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,yCAAyC;IACzC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;IAE9C,OAAO,KAAK,CAAC;AACjB,CAAC"}

package/dist/index.d.ts

@@ -7,4 +7,6 @@ export { buildAstroSeoProps } from './components/seo-props.js';
 export type { SeoProps, AstroSeoProps } from './components/seo-props.js';
 export { buildAlternateLinks } from './alternates.js';
 export type { AlternateLink, BuildAlternateLinksInput } from './alternates.js';
+export { breadcrumbsFromUrl } from './breadcrumbs.js';
+export type { BreadcrumbsFromUrlInput } from './breadcrumbs.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAE1E,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACpE,YAAY,EAAE,qBAAqB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE3F,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAE9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAEzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,YAAY,EAAE,aAAa,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAE1E,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACpE,YAAY,EAAE,qBAAqB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE3F,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAE9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAEzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,YAAY,EAAE,aAAa,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAE/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -8,4 +8,5 @@ export { createSchemaEndpoint, createSchemaMap } from './routes.js';
 export { seoSchema, imageSchema } from './content-helpers.js';
 export { buildAstroSeoProps } from './components/seo-props.js';
 export { buildAlternateLinks } from './alternates.js';
+export { breadcrumbsFromUrl } from './breadcrumbs.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,wEAAwE;AACxE,8EAA8E;AAC9E,sDAAsD;AAEtD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGpE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAE9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAG/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,wEAAwE;AACxE,8EAA8E;AAC9E,sDAAsD;AAEtD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGpE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAE9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAG/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAGtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jdevalk/astro-seo-graph",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Astro integration for @jdevalk/seo-graph-core. Seo component, route factories, content-collection aggregator, Zod content helpers.",
   "keywords": [
     "astro",
@@ -46,7 +46,7 @@
     "astro-seo": "^1.1.0",
     "schema-dts": "^2.0.0",
     "zod": "^3.24.0",
-    "@jdevalk/seo-graph-core": "0.3.0"
+    "@jdevalk/seo-graph-core": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",