Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(docs): add JSON-LD structured data and Open Graph URLs (#4454)

roboeve[bot]9ec7b61de041
diff --git a/apps/docs/app/[lang]/(home)/components/home-content.tsx b/apps/docs/app/[lang]/(home)/components/home-content.tsx
index 367013034..c5d80c8db 100644
--- a/apps/docs/app/[lang]/(home)/components/home-content.tsx
+++ b/apps/docs/app/[lang]/(home)/components/home-content.tsx
@@ -1,7 +1,9 @@
import type { Metadata } from "next";
+import { JsonLd } from "@/components/geistdocs/json-ld";
import { canonicalAlternates, canonicalRoutes } from "@/lib/geistdocs/canonical";
import { pageTitleMetadata, siteTitle } from "@/lib/geistdocs/metadata-title";
import { staticOgImage } from "@/lib/geistdocs/og";
+import { webSiteStructuredData } from "@/lib/geistdocs/structured-data";
import { ArchitectureDiagram } from "./architecture";
import { CTA } from "./cta";
import { FeatureGrid } from "./feature-grid";
@@ -21,6 +23,7 @@ export const homeMetadata: Metadata = {
description: tagline,
images: [staticOgImage],
type: "website",
+ url: canonicalRoutes.home,
},
twitter: {
...titleMetadata.twitter,
@@ -32,6 +35,7 @@ export const homeMetadata: Metadata = {
export const HomeContent = () => (
<div className="mx-auto w-full max-w-[1080px] pb-8">
+ <JsonLd data={webSiteStructuredData(tagline)} />
<section className="relative isolate flex min-h-[80vh] flex-col items-center justify-center gap-y-5 px-4 pt-24 pb-12 text-center sm:px-12 sm:pb-16 sm:pt-42">
<HeroAudience tagline={tagline} />
</section>
diff --git a/apps/docs/app/[lang]/benchmarks/page.tsx b/apps/docs/app/[lang]/benchmarks/page.tsx
index 48d50d447..93418b37d 100644
--- a/apps/docs/app/[lang]/benchmarks/page.tsx
+++ b/apps/docs/app/[lang]/benchmarks/page.tsx
@@ -16,6 +16,7 @@ export const metadata: Metadata = {
openGraph: {
...titleMetadata.openGraph,
images: ["/benchmarks/opengraph-image"],
+ url: canonicalRoutes.benchmarks,
},
twitter: {
...titleMetadata.twitter,
diff --git a/apps/docs/app/[lang]/docs/[[...slug]]/page.tsx b/apps/docs/app/[lang]/docs/[[...slug]]/page.tsx
index 23a6204a0..5af288531 100644
--- a/apps/docs/app/[lang]/docs/[[...slug]]/page.tsx
+++ b/apps/docs/app/[lang]/docs/[[...slug]]/page.tsx
@@ -3,15 +3,49 @@ import { MobileDocsBar } from "@vercel/geistdocs/mobile-docs-bar";
import { createDocsPage, createPageActions } from "@vercel/geistdocs/pages/docs";
import type { MDXComponents } from "mdx/types";
import { EditOnGithubAction } from "@/components/geistdocs/edit-on-github";
+import { JsonLd } from "@/components/geistdocs/json-ld";
import { getMDXComponents } from "@/components/geistdocs/mdx-components";
import { canonicalAlternates } from "@/lib/geistdocs/canonical";
import { config } from "@/lib/geistdocs/config";
+import { defaultLanguage } from "@/lib/geistdocs/languages";
import { pageTitleMetadata } from "@/lib/geistdocs/metadata-title";
import { staticOgImage } from "@/lib/geistdocs/og";
import { resolveDocsPageTitle } from "@/lib/geistdocs/page-title";
import { geistdocsSource } from "@/lib/geistdocs/source";
+import { docsArticleStructuredData, docsBreadcrumbs } from "@/lib/geistdocs/structured-data";
import { getSiteOrigin } from "@/lib/geistdocs/url";
+type DocsPageEntry = NonNullable<ReturnType<typeof geistdocsSource.source.getPage>>;
+
+const resolveTitle = (page: DocsPageEntry, lang: string): string => {
+ const title = resolveDocsPageTitle({
+ pageTitle: page.data.title,
+ pageUrl: page.url,
+ tree: geistdocsSource.source.getPageTree(lang),
+ });
+ if (!title) throw new Error(`Missing title for docs page ${page.url}`);
+ return title;
+};
+
+const DocsStructuredData = ({ page }: { page: DocsPageEntry }) => {
+ const lang = page.locale ?? defaultLanguage;
+ const title = resolveTitle(page, lang);
+ const pathname = getPublicPath(page.url, config.basePath);
+ const data = docsArticleStructuredData({
+ breadcrumbs: docsBreadcrumbs({
+ pageUrl: pathname,
+ title,
+ tree: geistdocsSource.source.getPageTree(lang),
+ }),
+ description: page.data.description,
+ image: staticOgImage,
+ lang,
+ pathname,
+ title,
+ });
+ return <JsonLd data={data} />;
+};
+
const docsPage = createDocsPage({
config,
pageActions: createPageActions({
@@ -24,25 +58,19 @@ const docsPage = createDocsPage({
return getMDXComponents(components);
},
metadata: ({ metadata, page, params }) => {
- const title = resolveDocsPageTitle({
- pageTitle: page.data.title,
- pageUrl: page.url,
- tree: geistdocsSource.source.getPageTree(params.lang),
- });
- if (!title) throw new Error(`Missing title for docs page ${page.url}`);
- const titleMetadata = pageTitleMetadata(title);
+ const titleMetadata = pageTitleMetadata(resolveTitle(page, params.lang));
+ const pathname = getPublicPath(page.url, config.basePath);
return {
...metadata,
...titleMetadata,
metadataBase: new URL(getSiteOrigin()),
- alternates: canonicalAlternates(
- getPublicPath(page.url, config.basePath),
- metadata.alternates,
- ),
+ alternates: canonicalAlternates(pathname, metadata.alternates),
openGraph: {
...metadata.openGraph,
...titleMetadata.openGraph,
+ type: "article",
+ url: pathname,
// Override with the static OG image for now. To restore dynamic per-page
// OG generation, swap the line below back to:
// images: geistdocsSource.getPageImage(page).url,
@@ -60,7 +88,12 @@ const docsPage = createDocsPage({
tableOfContentPopover: {
enabled: false,
},
- renderTop: ({ data }) => <MobileDocsBar toc={data.toc} />,
+ renderTop: ({ data, page }) => (
+ <>
+ <DocsStructuredData page={page} />
+ <MobileDocsBar toc={data.toc} />
+ </>
+ ),
});
export default docsPage.Page;
diff --git a/apps/docs/app/[lang]/integrations/[slug]/page.tsx b/apps/docs/app/[lang]/integrations/[slug]/page.tsx
index 137e931c9..d82515498 100644
--- a/apps/docs/app/[lang]/integrations/[slug]/page.tsx
+++ b/apps/docs/app/[lang]/integrations/[slug]/page.tsx
@@ -3,8 +3,10 @@ import type { Metadata } from "next";
import Link from "next/link";
import { notFound } from "next/navigation";
import { Suspense } from "react";
+import { JsonLd } from "@/components/geistdocs/json-ld";
import { canonicalAlternates, integrationPath } from "@/lib/geistdocs/canonical";
import { pageTitleMetadata } from "@/lib/geistdocs/metadata-title";
+import { integrationStructuredData } from "@/lib/geistdocs/structured-data";
import { buildConnectionInstall, buildConnectionSetup } from "@/lib/integrations/connection-setup";
import {
getIntegration,
@@ -44,11 +46,17 @@ export const generateMetadata = async ({
}
const title = `${integration.name} Integration`;
const titleMetadata = pageTitleMetadata(title);
+ const canonicalPath = integrationPath(integration.slug);
return {
...titleMetadata,
description: integration.tagline,
- alternates: canonicalAlternates(integrationPath(integration.slug)),
- openGraph: titleMetadata.openGraph,
+ alternates: canonicalAlternates(canonicalPath),
+ openGraph: {
+ ...titleMetadata.openGraph,
+ description: integration.tagline,
+ type: "website",
+ url: canonicalPath,
+ },
twitter: {
...titleMetadata.twitter,
card: "summary_large_image",
@@ -88,6 +96,12 @@ const IntegrationDetailPage = async ({ params }: PageProps<"/[lang]/integrations
return (
<main className="mx-auto w-full max-w-[768px] px-4 pt-16 pb-32 sm:px-6">
+ <JsonLd
+ data={integrationStructuredData({
+ name: integration.name,
+ pathname: integrationPath(integration.slug),
+ })}
+ />
<Link
className="inline-flex items-center gap-1.5 text-gray-800 text-sm transition-colors hover:text-gray-1000"
href="/integrations"
diff --git a/apps/docs/app/[lang]/integrations/page.tsx b/apps/docs/app/[lang]/integrations/page.tsx
index 2a345f48d..e895ef212 100644
--- a/apps/docs/app/[lang]/integrations/page.tsx
+++ b/apps/docs/app/[lang]/integrations/page.tsx
@@ -16,7 +16,7 @@ export const metadata: Metadata = {
...titleMetadata,
description,
alternates: canonicalAlternates(canonicalRoutes.integrations),
- openGraph: titleMetadata.openGraph,
+ openGraph: { ...titleMetadata.openGraph, url: canonicalRoutes.integrations },
twitter: {
...titleMetadata.twitter,
card: "summary_large_image",
diff --git a/apps/docs/app/[lang]/templates/[slug]/page.tsx b/apps/docs/app/[lang]/templates/[slug]/page.tsx
index 0fceb5640..b5cd0db26 100644
--- a/apps/docs/app/[lang]/templates/[slug]/page.tsx
+++ b/apps/docs/app/[lang]/templates/[slug]/page.tsx
@@ -8,8 +8,10 @@ import Link from "next/link";
import { notFound } from "next/navigation";
import type { ComponentProps } from "react";
import { translations } from "@/geistdocs";
+import { JsonLd } from "@/components/geistdocs/json-ld";
import { canonicalAlternates, templatePath } from "@/lib/geistdocs/canonical";
import { pageTitleMetadata } from "@/lib/geistdocs/metadata-title";
+import { breadcrumbListNode } from "@/lib/geistdocs/structured-data";
import { getTemplateEntry, type TemplateEntry, type TemplateFile } from "@/lib/templates/data";
import { templateManifest } from "@/lib/templates/manifest";
import { getSiteOrigin } from "@/lib/geistdocs/url";
@@ -76,13 +78,7 @@ const TemplateDetailPage = async ({ params }: { params: Promise<PageParams> }) =
return (
<>
- <script
- dangerouslySetInnerHTML={{
- __html: JSON.stringify(structuredData).replace(/</g, "\\u003c"),
- }}
- id={`template-structured-data-${entry.slug}`}
- type="application/ld+json"
- />
+ <JsonLd data={structuredData} id={`template-structured-data-${entry.slug}`} />
<main className="mx-auto max-w-[1080px] px-4 pt-10 pb-32 sm:px-6 sm:pt-12">
<Link
className="inline-flex min-h-8 items-center gap-1.5 rounded-sm text-gray-900 text-label-14 no-underline outline-none transition-colors hover:text-gray-1000 focus-visible:ring-2 focus-visible:ring-blue-700 focus-visible:ring-offset-2 focus-visible:ring-offset-background-100 motion-reduce:transition-none"
@@ -181,23 +177,10 @@ const TemplateDetailPage = async ({ params }: { params: Promise<PageParams> }) =
const createStructuredData = (entry: TemplateEntry, canonicalUrl: string) => ({
"@context": "https://schema.org",
"@graph": [
- {
- "@type": "BreadcrumbList",
- itemListElement: [
- {
- "@type": "ListItem",
- item: new URL("/templates", getSiteOrigin()).toString(),
- name: "Templates",
- position: 1,
- },
- {
- "@type": "ListItem",
- item: canonicalUrl,
- name: entry.title,
- position: 2,
- },
- ],
- },
+ breadcrumbListNode([
+ { name: "Templates", pathname: "/templates" },
+ { name: entry.title, pathname: templatePath(entry.slug) },
+ ]),
{
"@type": "SoftwareSourceCode",
codeRepository: entry.sourceRevisionHref,
diff --git a/apps/docs/app/[lang]/templates/page.tsx b/apps/docs/app/[lang]/templates/page.tsx
index 40d7eb5e0..7b61378ec 100644
--- a/apps/docs/app/[lang]/templates/page.tsx
+++ b/apps/docs/app/[lang]/templates/page.tsx
@@ -15,7 +15,11 @@ export const metadata: Metadata = {
...titleMetadata,
description,
alternates: canonicalAlternates(canonicalRoutes.templates),
- openGraph: { ...titleMetadata.openGraph, images: [staticOgImage] },
+ openGraph: {
+ ...titleMetadata.openGraph,
+ images: [staticOgImage],
+ url: canonicalRoutes.templates,
+ },
twitter: {
...titleMetadata.twitter,
card: "summary_large_image",
diff --git a/apps/docs/components/geistdocs/json-ld.tsx b/apps/docs/components/geistdocs/json-ld.tsx
new file mode 100644
index 000000000..732f7f4e8
--- /dev/null
+++ b/apps/docs/components/geistdocs/json-ld.tsx
@@ -0,0 +1,10 @@
+import { serializeJsonLd } from "@/lib/geistdocs/structured-data";
+
+export const JsonLd = ({ data, id }: { data: Record<string, unknown>; id?: string }) => (
+ <script
+ // biome-ignore lint/security/noDangerouslySetInnerHtml: JSON-LD is serialized and escapes HTML start characters.
+ dangerouslySetInnerHTML={{ __html: serializeJsonLd(data) }}
+ id={id}
+ type="application/ld+json"
+ />
+);
diff --git a/apps/docs/lib/geistdocs/metadata-title.test.ts b/apps/docs/lib/geistdocs/metadata-title.test.ts
index 27caeeba4..eacf1c367 100644
--- a/apps/docs/lib/geistdocs/metadata-title.test.ts
+++ b/apps/docs/lib/geistdocs/metadata-title.test.ts
@@ -21,7 +21,7 @@ describe("metadata titles", () => {
expect(metadataTitle(siteTitle)).toEqual({ absolute: siteTitle });
expect(pageTitleMetadata(siteTitle)).toEqual({
title: { absolute: siteTitle },
- openGraph: { title: siteTitle },
+ openGraph: { siteName: "eve", title: siteTitle },
twitter: { title: siteTitle },
});
});
diff --git a/apps/docs/lib/geistdocs/metadata-title.ts b/apps/docs/lib/geistdocs/metadata-title.ts
index f191d29a3..71f91ac96 100644
--- a/apps/docs/lib/geistdocs/metadata-title.ts
+++ b/apps/docs/lib/geistdocs/metadata-title.ts
@@ -1,5 +1,6 @@
import type { Metadata } from "next";
+export const siteName = "eve";
export const siteTitle = "eve – build AI agents that you own";
const siteTitleTemplate = "%s – eve";
@@ -19,14 +20,14 @@ export const metadataTitle = (title: string): NonNullable<Metadata["title"]> =>
export const pageTitleMetadata = (
title: string,
): {
- openGraph: { title: string };
+ openGraph: { siteName: string; title: string };
title: NonNullable<Metadata["title"]>;
twitter: { title: string };
} => {
const resolvedTitle = formatPageTitle(title);
return {
title: metadataTitle(title),
- openGraph: { title: resolvedTitle },
+ openGraph: { siteName, title: resolvedTitle },
twitter: { title: resolvedTitle },
};
};
diff --git a/apps/docs/lib/geistdocs/structured-data.test.ts b/apps/docs/lib/geistdocs/structured-data.test.ts
new file mode 100644
index 000000000..459b6339d
--- /dev/null
+++ b/apps/docs/lib/geistdocs/structured-data.test.ts
@@ -0,0 +1,162 @@
+import { describe, expect, it } from "vitest";
+import {
+ breadcrumbListNode,
+ docsArticleStructuredData,
+ docsBreadcrumbs,
+ integrationStructuredData,
+ serializeJsonLd,
+ webSiteStructuredData,
+} from "./structured-data";
+
+const origin = "http://localhost:3000";
+
+const tree = {
+ name: "Docs",
+ children: [
+ { type: "page", name: "Getting Started", url: "/docs/getting-started" },
+ {
+ type: "folder",
+ name: "Channels",
+ children: [
+ { type: "page", name: "Overview", url: "/docs/channels/overview" },
+ { type: "page", name: "Slack", url: "/docs/channels/slack" },
+ ],
+ },
+ {
+ type: "folder",
+ name: "Sandbox",
+ index: { type: "page", name: "Sandbox", url: "/docs/sandbox" },
+ children: [{ type: "page", name: "Docker", url: "/docs/sandbox/docker" }],
+ },
+ {
+ type: "folder",
+ name: "Guides",
+ children: [
+ { type: "page", name: "Deployment", url: "/docs/guides/deployment" },
+ {
+ type: "folder",
+ name: "Frontend",
+ children: [{ type: "page", name: "Overview", url: "/docs/guides/frontend/overview" }],
+ },
+ ],
+ },
+ ],
+};
+
+describe("structured data", () => {
+ it("escapes HTML start characters in serialized JSON-LD", () => {
+ expect(serializeJsonLd({ name: "</script>" })).toBe('{"name":"\\u003c/script>"}');
+ });
+
+ it("links enclosing folders to their index or first page", () => {
+ expect(docsBreadcrumbs({ pageUrl: "/docs/channels/slack", title: "Slack", tree })).toEqual([
+ { name: "Channels", pathname: "/docs/channels/overview" },
+ { name: "Slack", pathname: "/docs/channels/slack" },
+ ]);
+ expect(docsBreadcrumbs({ pageUrl: "/docs/sandbox/docker", title: "Docker", tree })).toEqual([
+ { name: "Sandbox", pathname: "/docs/sandbox" },
+ { name: "Docker", pathname: "/docs/sandbox/docker" },
+ ]);
+ });
+
+ it("omits a breadcrumb list for top-level pages and folder landing pages", () => {
+ for (const [pageUrl, title] of [
+ ["/docs/getting-started", "Get started"],
+ ["/docs/channels/overview", "Channels"],
+ ["/docs/sandbox", "Sandbox"],
+ ]) {
+ expect(breadcrumbListNode(docsBreadcrumbs({ pageUrl, title, tree }))).toBeUndefined();
+ }
+ });
+
+ it("keeps the page name when a nested folder links to the current page", () => {
+ const entries = docsBreadcrumbs({
+ pageUrl: "/docs/guides/frontend/overview",
+ title: "Build a chat UI",
+ tree,
+ });
+ expect(breadcrumbListNode(entries)?.itemListElement).toEqual([
+ {
+ "@type": "ListItem",
+ item: `${origin}/docs/guides/deployment`,
+ name: "Guides",
+ position: 1,
+ },
+ {
+ "@type": "ListItem",
+ item: `${origin}/docs/guides/frontend/overview`,
+ name: "Build a chat UI",
+ position: 2,
+ },
+ ]);
+ });
+
+ it("describes a docs page as a TechArticle with absolute URLs", () => {
+ const data = docsArticleStructuredData({
+ breadcrumbs: docsBreadcrumbs({ pageUrl: "/docs/channels/slack", title: "Slack", tree }),
+ description: "Mention your agent in Slack.",
+ image: "https://example.com/og.jpg",
+ lang: "en",
+ pathname: "/docs/channels/slack",
+ title: "Slack",
+ });
+ expect(data).toEqual({
+ "@context": "https://schema.org",
+ "@graph": [
+ {
+ "@type": "TechArticle",
+ headline: "Slack",
+ description: "Mention your agent in Slack.",
+ image: "https://example.com/og.jpg",
+ inLanguage: "en",
+ isPartOf: { "@type": "WebSite", name: "eve", url: `${origin}/` },
+ mainEntityOfPage: `${origin}/docs/channels/slack`,
+ publisher: { "@type": "Organization", name: "Vercel", url: "https://vercel.com" },
+ url: `${origin}/docs/channels/slack`,
+ },
+ {
+ "@type": "BreadcrumbList",
+ itemListElement: [
+ {
+ "@type": "ListItem",
+ item: `${origin}/docs/channels/overview`,
+ name: "Channels",
+ position: 1,
+ },
+ {
+ "@type": "ListItem",
+ item: `${origin}/docs/channels/slack`,
+ name: "Slack",
+ position: 2,
+ },
+ ],
+ },
+ ],
+ });
+ });
+
+ it("adds integration breadcrumbs and homepage site identity", () => {
+ expect(integrationStructuredData({ name: "Slack", pathname: "/integrations/slack" })).toEqual({
+ "@context": "https://schema.org",
+ "@type": "BreadcrumbList",
+ itemListElement: [
+ { "@type": "ListItem", item: `${origin}/integrations`, name: "Integrations", position: 1 },
+ {
+ "@type": "ListItem",
+ item: `${origin}/integrations/slack`,
+ name: "Slack",
+ position: 2,
+ },
+ ],
+ });
+ expect(webSiteStructuredData("Like Next.js for agents.")).toEqual({
+ "@context": "https://schema.org",
+ "@type": "WebSite",
+ name: "eve",
+ url: `${origin}/`,
+ description: "Like Next.js for agents.",
+ inLanguage: "en",
+ publisher: { "@type": "Organization", name: "Vercel", url: "https://vercel.com" },
+ });
+ });
+});
diff --git a/apps/docs/lib/geistdocs/structured-data.ts b/apps/docs/lib/geistdocs/structured-data.ts
new file mode 100644
index 000000000..115bcf1d0
--- /dev/null
+++ b/apps/docs/lib/geistdocs/structured-data.ts
@@ -0,0 +1,156 @@
+import { defaultLanguage } from "./languages";
+import { siteName } from "./metadata-title";
+import { getSiteOrigin } from "./url";
+
+type JsonLdNode = Record<string, unknown>;
+
+export interface BreadcrumbEntry {
+ name: string;
+ /** Site-relative pathname. */
+ pathname: string;
+}
+
+/** Serializes JSON-LD for an inline script, escaping `<` so content cannot close the tag. */
+export const serializeJsonLd = (data: JsonLdNode): string =>
+ JSON.stringify(data).replace(/</g, "\\u003c");
+
+const absoluteUrl = (pathname: string): string => new URL(pathname, getSiteOrigin()).toString();
+
+const publisher = (): JsonLdNode => ({
+ "@type": "Organization",
+ name: "Vercel",
+ url: "https://vercel.com",
+});
+
+const webSiteReference = (): JsonLdNode => ({
+ "@type": "WebSite",
+ name: siteName,
+ url: absoluteUrl("/"),
+});
+
+/** Site identity for search engines, rendered once on the homepage. */
+export const webSiteStructuredData = (description: string): JsonLdNode => ({
+ "@context": "https://schema.org",
+ ...webSiteReference(),
+ description,
+ inLanguage: defaultLanguage,
+ publisher: publisher(),
+});
+
+/** Returns a BreadcrumbList, or undefined when there is no trail beyond the page itself. */
+export const breadcrumbListNode = (entries: BreadcrumbEntry[]): JsonLdNode | undefined => {
+ // When a folder links to the current page, keep the page's own name.
+ const unique = entries.filter((entry, index) => entry.pathname !== entries[index + 1]?.pathname);
+ if (unique.length < 2) return;
+ return {
+ "@type": "BreadcrumbList",
+ itemListElement: unique.map((entry, index) => ({
+ "@type": "ListItem",
+ item: absoluteUrl(entry.pathname),
+ name: entry.name,
+ position: index + 1,
+ })),
+ };
+};
+
+interface DocsArticleOptions {
+ breadcrumbs: BreadcrumbEntry[];
+ description?: string;
+ image: string;
+ lang: string;
+ pathname: string;
+ title: string;
+}
+
+export const docsArticleStructuredData = ({
+ breadcrumbs,
+ description,
+ image,
+ lang,
+ pathname,
+ title,
+}: DocsArticleOptions): JsonLdNode => {
+ const url = absoluteUrl(pathname);
+ const graph: JsonLdNode[] = [
+ {
+ "@type": "TechArticle",
+ headline: title,
+ // JSON serialization drops an undefined description.
+ description,
+ image,
+ inLanguage: lang,
+ isPartOf: webSiteReference(),
+ mainEntityOfPage: url,
+ publisher: publisher(),
+ url,
+ },
+ ];
+ const breadcrumbList = breadcrumbListNode(breadcrumbs);
+ if (breadcrumbList) graph.push(breadcrumbList);
+ return { "@context": "https://schema.org", "@graph": graph };
+};
+
+export const integrationStructuredData = ({
+ name,
+ pathname,
+}: {
+ name: string;
+ pathname: string;
+}): JsonLdNode => ({
+ "@context": "https://schema.org",
+ ...breadcrumbListNode([
+ { name: "Integrations", pathname: "/integrations" },
+ { name, pathname },
+ ]),
+});
+
+// Geistdocs owns the page-tree version, which can differ from the docs app's Fumadocs version.
+interface TreeNode {
+ children?: TreeNode[];
+ index?: TreeNode;
+ name?: unknown;
+ type?: string;
+ url?: string;
+}
+
+const firstPageUrl = (node: TreeNode): string | undefined => {
+ if (node.index?.url) return node.index.url;
+ for (const child of node.children ?? []) {
+ if (child.type === "page" && child.url) return child.url;
+ if (child.type === "folder") {
+ const url = firstPageUrl(child);
+ if (url) return url;
+ }
+ }
+};
+
+const findFolderTrail = (node: TreeNode, url: string): TreeNode[] | undefined => {
+ for (const child of node.children ?? []) {
+ if (child.type === "page" && child.url === url) return [];
+ if (child.type !== "folder") continue;
+ if (child.index?.url === url) return [child];
+ const trail = findFolderTrail(child, url);
+ if (trail) return [child, ...trail];
+ }
+};
+
+/**
+ * Builds the docs breadcrumb trail from the sidebar tree: each enclosing folder,
+ * linked to its index or first page, followed by the page itself.
+ */
+export const docsBreadcrumbs = ({
+ pageUrl,
+ title,
+ tree,
+}: {
+ pageUrl: string;
+ title: string;
+ tree: TreeNode;
+}): BreadcrumbEntry[] => {
+ const folders = findFolderTrail(tree, pageUrl) ?? [];
+ const entries = folders.flatMap((folder) => {
+ const pathname = firstPageUrl(folder);
+ return typeof folder.name === "string" && pathname ? [{ name: folder.name, pathname }] : [];
+ });
+ return [...entries, { name: title, pathname: pageUrl }];
+};