@dineway-ai/plugin-seo-graph 0.1.7

package/src/opengraph.ts

@@ -0,0 +1,327 @@
+import type { PublicPageContext, PageMetadataContribution } from "dineway";
+
+import type { SeoSettings } from "./settings.js";
+
+/**
+ * Generate Open Graph and Twitter Card meta contributions.
+ * og:type is "article" for all content types (posts, pages, videos).
+ */
+/**
+ * Bare language codes that need a specific region suffix
+ * (where the region doesn't match the language code).
+ */
+const FIX_LOCALES: Record<string, string> = {
+	ca: "ca_ES",
+	en: "en_US",
+	el: "el_GR",
+	et: "et_EE",
+	ja: "ja_JP",
+	sq: "sq_AL",
+	uk: "uk_UA",
+	vi: "vi_VN",
+	zh: "zh_CN",
+};
+
+/**
+ * Complete set of valid Facebook/Open Graph locales.
+ */
+const VALID_LOCALES = new Set([
+	"af_ZA",
+	"ak_GH",
+	"am_ET",
+	"ar_AR",
+	"as_IN",
+	"ay_BO",
+	"az_AZ",
+	"be_BY",
+	"bg_BG",
+	"bn_IN",
+	"bp_IN",
+	"br_FR",
+	"bs_BA",
+	"ca_ES",
+	"cb_IQ",
+	"ck_US",
+	"co_FR",
+	"cs_CZ",
+	"cx_PH",
+	"cy_GB",
+	"da_DK",
+	"de_DE",
+	"el_GR",
+	"em_ZM",
+	"en_GB",
+	"en_PI",
+	"en_UD",
+	"en_US",
+	"eo_EO",
+	"es_ES",
+	"es_LA",
+	"es_MX",
+	"et_EE",
+	"eu_ES",
+	"fa_IR",
+	"fb_LT",
+	"ff_NG",
+	"fi_FI",
+	"fo_FO",
+	"fr_CA",
+	"fr_FR",
+	"fy_NL",
+	"ga_IE",
+	"gl_ES",
+	"gn_PY",
+	"gu_IN",
+	"gx_GR",
+	"ha_NG",
+	"he_IL",
+	"hi_IN",
+	"hr_HR",
+	"ht_HT",
+	"hu_HU",
+	"hy_AM",
+	"id_ID",
+	"ig_NG",
+	"ik_US",
+	"is_IS",
+	"it_IT",
+	"iu_CA",
+	"ja_JP",
+	"ja_KS",
+	"jv_ID",
+	"ka_GE",
+	"kk_KZ",
+	"km_KH",
+	"kn_IN",
+	"ko_KR",
+	"ks_IN",
+	"ku_TR",
+	"ky_KG",
+	"la_VA",
+	"lg_UG",
+	"li_NL",
+	"ln_CD",
+	"lo_LA",
+	"lt_LT",
+	"lv_LV",
+	"mg_MG",
+	"mi_NZ",
+	"mk_MK",
+	"ml_IN",
+	"mn_MN",
+	"mr_IN",
+	"ms_MY",
+	"mt_MT",
+	"my_MM",
+	"nb_NO",
+	"nd_ZW",
+	"ne_NP",
+	"nl_BE",
+	"nl_NL",
+	"nn_NO",
+	"nr_ZA",
+	"ns_ZA",
+	"ny_MW",
+	"om_ET",
+	"or_IN",
+	"pa_IN",
+	"pl_PL",
+	"ps_AF",
+	"pt_BR",
+	"pt_PT",
+	"qc_GT",
+	"qr_GR",
+	"qu_PE",
+	"qz_MM",
+	"rm_CH",
+	"ro_RO",
+	"ru_RU",
+	"rw_RW",
+	"sa_IN",
+	"sc_IT",
+	"se_NO",
+	"si_LK",
+	"sk_SK",
+	"sl_SI",
+	"sn_ZW",
+	"so_SO",
+	"sq_AL",
+	"sr_RS",
+	"ss_SZ",
+	"st_ZA",
+	"su_ID",
+	"sv_SE",
+	"sw_KE",
+	"sy_SY",
+	"sz_PL",
+	"ta_IN",
+	"te_IN",
+	"tg_TJ",
+	"th_TH",
+	"tk_TM",
+	"tl_PH",
+	"tl_ST",
+	"tn_BW",
+	"tr_TR",
+	"ts_ZA",
+	"tt_RU",
+	"tz_MA",
+	"uk_UA",
+	"ur_PK",
+	"uz_UZ",
+	"ve_ZA",
+	"vi_VN",
+	"wo_SN",
+	"xh_ZA",
+	"yi_DE",
+	"yo_NG",
+	"zh_CN",
+	"zh_HK",
+	"zh_TW",
+	"zu_ZA",
+	"zz_TR",
+]);
+
+/**
+ * Convert a locale to a valid Facebook/Open Graph locale.
+ *
+ * 1. Check bare language codes against known fixes (e.g. "en" -> "en_US")
+ * 2. Normalize hyphens to underscores (e.g. "en-GB" -> "en_GB")
+ * 3. Expand 2-letter codes to xx_XX format
+ * 4. Validate against the full Facebook locale list
+ * 5. Fall back to en_US if no valid match
+ */
+function toOgLocale(locale: string): string {
+	// Known bare-code fixes
+	if (FIX_LOCALES[locale]) return FIX_LOCALES[locale];
+
+	// Normalize hyphens to underscores
+	let normalized = locale.replace("-", "_");
+
+	// Expand bare 2-letter codes to xx_XX
+	if (normalized.length === 2) {
+		normalized = normalized.toLowerCase() + "_" + normalized.toUpperCase();
+	}
+
+	// If it's a valid Facebook locale, use it
+	if (VALID_LOCALES.has(normalized)) return normalized;
+
+	// Try deriving xx_XX from the language part
+	const lang = normalized.substring(0, 2).toLowerCase();
+	const derived = lang + "_" + lang.toUpperCase();
+	if (VALID_LOCALES.has(derived)) return derived;
+
+	return "en_US";
+}
+
+export function generateOpengraph(
+	page: PublicPageContext,
+	settings: SeoSettings,
+	ogTitle: string,
+	description: string | null,
+	canonical: string | null,
+	locale: string,
+): PageMetadataContribution[] {
+	const contributions: PageMetadataContribution[] = [];
+	const path = page.path || "/";
+
+	// Skip most OG tags on 404
+	if (path === "/404") {
+		if (page.siteName) {
+			contributions.push({ kind: "property", property: "og:site_name", content: page.siteName });
+		}
+		contributions.push({ kind: "property", property: "og:locale", content: toOgLocale(locale) });
+		return contributions;
+	}
+
+	// og:type - "article" for content pages, "website" for archives/homepage
+	const isContent = page.kind === "content";
+	contributions.push({
+		kind: "property",
+		property: "og:type",
+		content: isContent ? "article" : "website",
+	});
+
+	// og:title
+	if (ogTitle) {
+		contributions.push({ kind: "property", property: "og:title", content: ogTitle });
+	}
+
+	// og:description
+	if (description) {
+		contributions.push({ kind: "property", property: "og:description", content: description });
+	}
+
+	// og:image
+	if (page.image) {
+		contributions.push({ kind: "property", property: "og:image", content: page.image });
+	}
+
+	// og:url
+	if (canonical) {
+		contributions.push({ kind: "property", property: "og:url", content: canonical });
+	}
+
+	// og:site_name
+	if (page.siteName) {
+		contributions.push({ kind: "property", property: "og:site_name", content: page.siteName });
+	}
+
+	// og:locale
+	contributions.push({ kind: "property", property: "og:locale", content: toOgLocale(locale) });
+
+	// Article meta
+	if (isContent && page.articleMeta) {
+		if (page.articleMeta.publishedTime) {
+			contributions.push({
+				kind: "property",
+				property: "article:published_time",
+				content: page.articleMeta.publishedTime,
+			});
+		}
+		if (page.articleMeta.modifiedTime) {
+			contributions.push({
+				kind: "property",
+				property: "article:modified_time",
+				content: page.articleMeta.modifiedTime,
+			});
+		}
+		if (page.articleMeta.author) {
+			contributions.push({
+				kind: "property",
+				property: "article:author",
+				content: page.articleMeta.author,
+			});
+		}
+	}
+
+	// Twitter Card
+	contributions.push({
+		kind: "meta",
+		name: "twitter:card",
+		content: page.image ? "summary_large_image" : "summary",
+	});
+
+	if (ogTitle) {
+		contributions.push({ kind: "meta", name: "twitter:title", content: ogTitle });
+	}
+	if (description) {
+		contributions.push({ kind: "meta", name: "twitter:description", content: description });
+	}
+	if (page.image) {
+		contributions.push({ kind: "meta", name: "twitter:image", content: page.image });
+	}
+
+	// Twitter site handle from settings
+	const twitterUrl = settings.socials.find(
+		(s) => s.includes("twitter.com/") || s.includes("x.com/"),
+	);
+	if (twitterUrl) {
+		const handle = twitterUrl.split("/").pop();
+		if (handle) {
+			contributions.push({ kind: "meta", name: "twitter:site", content: `@${handle}` });
+		}
+	}
+
+	return contributions;
+}

package/src/robots.ts

@@ -0,0 +1,29 @@
+import type { PublicPageContext } from "dineway";
+
+const SNIPPET_DIRECTIVES = "max-snippet:-1, max-image-preview:large, max-video-preview:-1";
+
+const NOINDEX_PATHS = new Set(["/search"]);
+
+/**
+ * Generate meta robots value.
+ *
+ * - Normal pages: index, follow + snippet directives
+ * - Noindex pages: noindex, follow + snippet directives
+ * - 404/error: omit entirely (return null)
+ */
+export function generateRobots(page: PublicPageContext): string | null {
+	const path = page.path || "/";
+
+	// 404: omit robots entirely
+	if (path === "/404") return null;
+
+	// Check for noindex: explicit setting or known noindex paths
+	const explicitRobots = page.seo?.robots || "";
+	const isNoindex = explicitRobots.includes("noindex") || NOINDEX_PATHS.has(path);
+
+	if (isNoindex) {
+		return `noindex, follow, ${SNIPPET_DIRECTIVES}`;
+	}
+
+	return `index, follow, ${SNIPPET_DIRECTIVES}`;
+}

package/src/schema/article.ts

@@ -0,0 +1,70 @@
+import { buildArticle as coreBuildArticle } from "@jdevalk/seo-graph-core";
+import type { IdFactory, Reference } from "@jdevalk/seo-graph-core";
+import type { PublicPageContext } from "dineway";
+
+import type { SeoSettings } from "../settings.js";
+import { getSiteEntityId } from "./organization.js";
+
+/**
+ * Build the Article (or BlogPosting) schema node.
+ * Output on all content types that support authorship.
+ * Required: headline, datePublished, author, publisher.
+ */
+export function buildArticle(
+	page: PublicPageContext,
+	settings: SeoSettings,
+	siteName: string,
+	canonical: string | null,
+	ogTitle: string,
+	description: string | null,
+	locale: string,
+	ids: IdFactory,
+	blogId: string | null,
+	keywords?: string[],
+	articleSection?: string,
+): Record<string, unknown> | null {
+	const pageUrl = canonical || page.url;
+
+	// Required fields per spec - if missing, don't output
+	if (!ogTitle || !page.articleMeta?.publishedTime) return null;
+
+	const siteEntityId = getSiteEntityId(settings, ids);
+	const webPageRef: Reference = { "@id": ids.webPage(pageUrl) };
+
+	// When a Blog entity exists, link the posting to both WebPage and Blog.
+	const isPartOf: Reference | Reference[] = blogId ? [webPageRef, { "@id": blogId }] : webPageRef;
+
+	// Copyright fields from settings.
+	const copyrightHolder: Reference | undefined = settings.copyrightYear
+		? { "@id": siteEntityId }
+		: undefined;
+
+	const piece = coreBuildArticle(
+		{
+			url: pageUrl,
+			isPartOf: isPartOf as Reference,
+			author: {
+				"@id": ids.person,
+				name: settings.personName || siteName,
+			},
+			publisher: { "@id": siteEntityId },
+			headline: ogTitle,
+			description: description || "",
+			datePublished: new Date(page.articleMeta.publishedTime),
+			dateModified: page.articleMeta.modifiedTime
+				? new Date(page.articleMeta.modifiedTime)
+				: undefined,
+			inLanguage: locale,
+			image: page.image ? { "@id": ids.primaryImage(pageUrl) } : undefined,
+			copyrightHolder,
+			copyrightYear: settings.copyrightYear || undefined,
+			license: settings.licenseUrl || undefined,
+			keywords: keywords?.length ? keywords.join(", ") : undefined,
+			articleSection: articleSection || undefined,
+		},
+		ids,
+		"BlogPosting",
+	);
+
+	return piece;
+}

package/src/schema/breadcrumb.ts

@@ -0,0 +1,158 @@
+import type { BreadcrumbItem } from "@jdevalk/seo-graph-core";
+import type { PublicPageContext } from "dineway";
+
+import type { BreadcrumbRule, SeoSettings } from "../settings.js";
+
+const TRAILING_SLASH_RE = /\/$/;
+const TRIM_SLASHES_RE = /^\/+|\/+$/g;
+const PAGINATION_SEGMENT_RE = /^\d+$/;
+const YEAR_SEGMENT_RE = /^\d{4}$/;
+const MONTH_SEGMENT_RE = /^\d{1,2}$/;
+const SEGMENT_SEPARATOR_RE = /[-_]+/g;
+const WORD_START_RE = /\b\w/g;
+
+/**
+ * Compute the breadcrumb item list for a page, or `null` when no
+ * breadcrumb should be emitted (homepage, 404, single-item trails).
+ *
+ * Priority order:
+ *   1. Per-`pageType` rule match (from `settings.breadcrumbRules`)
+ *   2. Path derivation from `page.path`, with segment label overrides
+ *      from `settings.breadcrumbLabels`
+ *
+ * Trails are always absolute URLs (prefixed with `siteUrl`) and always
+ * start with a `Home` crumb.
+ */
+export function buildBreadcrumbs(
+	page: PublicPageContext,
+	settings: SeoSettings,
+	siteUrl: string,
+): BreadcrumbItem[] | null {
+	// Homepage and 404 never emit breadcrumbs — single-item trails
+	// provide no value and crawlers don't want them.
+	const path = page.path || "/";
+	if (path === "/" || path === "/404") return null;
+
+	const baseUrl = siteUrl.replace(TRAILING_SLASH_RE, "");
+	const pageUrl = page.canonical || page.url;
+
+	// Layer 1: rule match by pageType
+	const rule = settings.breadcrumbRules[page.pageType];
+	if (rule && rule.length > 0) {
+		return applyRule(rule, page, baseUrl, pageUrl);
+	}
+
+	// Layer 2: path derivation with label map
+	return derivePath(page, settings, baseUrl, pageUrl);
+}
+
+function applyRule(
+	rule: BreadcrumbRule,
+	page: PublicPageContext,
+	baseUrl: string,
+	pageUrl: string,
+): BreadcrumbItem[] | null {
+	const items: BreadcrumbItem[] = [];
+	for (const crumb of rule) {
+		const name = crumb.label === "{title}" ? page.title || "" : crumb.label;
+		const href = resolveHref(crumb.href, baseUrl, pageUrl);
+		items.push({ name, url: href });
+	}
+	return items.length > 1 ? items : null;
+}
+
+/**
+ * Resolve a rule's `href` placeholder or relative URL to an absolute one.
+ * - Undefined or `{path}` → current page URL
+ * - Starts with `/` → prefixed with siteUrl
+ * - Anything else → returned as-is (assumed already absolute)
+ */
+function resolveHref(href: string | undefined, baseUrl: string, pageUrl: string): string {
+	if (!href || href === "{path}") return pageUrl;
+	if (href.startsWith("/")) return `${baseUrl}${href}`;
+	return href;
+}
+
+function derivePath(
+	page: PublicPageContext,
+	settings: SeoSettings,
+	baseUrl: string,
+	pageUrl: string,
+): BreadcrumbItem[] | null {
+	const items: BreadcrumbItem[] = [{ name: "Home", url: `${baseUrl}/` }];
+
+	// Strip leading/trailing slashes and split.
+	const trimmed = (page.path || "").replace(TRIM_SLASHES_RE, "");
+	if (!trimmed) return null;
+
+	const segments = trimmed.split("/");
+	let accumulated = "";
+	const hasTrailingSlash = (page.path || "").endsWith("/");
+
+	for (let i = 0; i < segments.length; i++) {
+		const segment = segments[i];
+		if (segment === undefined) continue;
+		accumulated += `/${segment}`;
+
+		if (shouldSkipSegment(segment, segments, i)) {
+			continue;
+		}
+
+		const isLast = i === segments.length - 1;
+		// Last crumb uses page.title if present (authoritative); earlier
+		// crumbs come from the label map or default cleaning.
+		const label =
+			isLast && page.title
+				? page.title
+				: settings.breadcrumbLabels[segment] || defaultCleanSegment(segment);
+
+		// For the last crumb, use the canonical URL so fragment/query
+		// normalization from the canonical plugin is preserved. For
+		// intermediate crumbs, build the absolute URL from the segment.
+		const url = isLast ? pageUrl : `${baseUrl}${accumulated}${hasTrailingSlash ? "/" : ""}`;
+
+		items.push({ name: label, url });
+	}
+
+	return items.length > 1 ? items : null;
+}
+
+/**
+ * Noise segments that should not appear as crumbs:
+ *   - `/YYYY/` or `/MM/` — year/month archive segments
+ *   - `/page/N` pagination — both the literal `page` and the number
+ *
+ * When a segment is skipped, subsequent crumbs still accumulate the
+ * URL correctly (so `/blog/2025/my-post` → `Home > Blog > My Post`
+ * with the last crumb pointing at the full canonical path).
+ */
+function shouldSkipSegment(segment: string, all: string[], index: number): boolean {
+	// /.../page/N — both segments
+	const next = all[index + 1];
+	if (
+		segment === "page" &&
+		index < all.length - 1 &&
+		next !== undefined &&
+		PAGINATION_SEGMENT_RE.test(next)
+	) {
+		return true;
+	}
+	const prev = all[index - 1];
+	if (index > 0 && prev === "page" && PAGINATION_SEGMENT_RE.test(segment)) {
+		return true;
+	}
+
+	// Pure numeric year (4 digits) or month (1-2 digits) archive segments
+	if (YEAR_SEGMENT_RE.test(segment)) return true;
+	if (MONTH_SEGMENT_RE.test(segment)) return true;
+
+	return false;
+}
+
+/**
+ * Default segment cleaner: replace dashes/underscores with spaces and
+ * title-case the result. `"open-source"` → `"Open Source"`.
+ */
+function defaultCleanSegment(segment: string): string {
+	return segment.replace(SEGMENT_SEPARATOR_RE, " ").replace(WORD_START_RE, (c) => c.toUpperCase());
+}

package/src/schema/endpoints.ts

@@ -0,0 +1,69 @@
+import type { PluginContext } from "dineway";
+
+import { buildPageUrl } from "../urls.js";
+
+/**
+ * One entry in the schema map: a URL backed by a published content record.
+ */
+export interface SchemaMapEntry {
+	/** Absolute URL of the live page. */
+	url: string;
+	/** Collection slug, for example `posts` or `pages`. */
+	collection: string;
+	/** ISO-8601 last-modified timestamp. */
+	updatedAt: string;
+}
+
+/**
+ * Enumerate every published URL the site exposes for agent/crawler discovery.
+ */
+export async function listSchemaEntries(ctx: PluginContext): Promise<SchemaMapEntry[]> {
+	if (!ctx.content) return [];
+	const siteUrl = ctx.site.url;
+	if (!siteUrl) return [];
+
+	const { SchemaRegistry, isI18nEnabled, getI18nConfig } = await import("dineway");
+	const { getDb } = await import("dineway/runtime");
+	const db = await getDb();
+	const registry = new SchemaRegistry(db);
+	const collections = await registry.listCollections();
+
+	const cfg =
+		isI18nEnabled() && getI18nConfig()
+			? getI18nConfig()!
+			: { locales: ["en"], defaultLocale: "en", prefixDefaultLocale: false };
+
+	const entries: SchemaMapEntry[] = [];
+
+	for (const collection of collections) {
+		if (!collection.urlPattern) continue;
+
+		let cursor: string | undefined;
+		do {
+			const page = await ctx.content.list(collection.slug, {
+				limit: 100,
+				cursor,
+				where: { status: "published" },
+			});
+			for (const item of page.items) {
+				if (!item.slug) continue;
+				const locale = item.locale || cfg.defaultLocale;
+
+				const url = buildPageUrl({
+					locale,
+					slug: item.slug,
+					siteUrl,
+					cfg,
+					urlPattern: collection.urlPattern,
+				});
+				if (!url) continue;
+
+				const updatedAt = item.updatedAt || item.createdAt || new Date(0).toISOString();
+				entries.push({ url, collection: collection.slug, updatedAt });
+			}
+			cursor = page.cursor;
+		} while (cursor);
+	}
+
+	return entries;
+}