npm - rspress-plugin-api-extractor - Versions diffs - 0.12.0 → 0.13.0 - Mend

rspress-plugin-api-extractor 0.12.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md +1 -0
package/build-program.js +12 -2
package/build-stages.js +86 -45
package/index.d.ts +1 -84
package/layers/config-resolution.js +40 -1
package/markdown/helpers.js +8 -33
package/package.json +5 -4
package/schemas/config.js +1 -1
package/services/OgService.js +3 -18
package/og-resolver.js +0 -95
package/schemas/opengraph.js +0 -56

package/README.md CHANGED Viewed

@@ -54,6 +54,7 @@ The plugin reads your `.api.json` model and writes one MDX page per public API i
 - Drives single-package sites, multi-package portals, RSPress multiVersion and i18n from one plugin.
 - Handles multi-entry-point packages: it deduplicates re-exports and notes which entry points each item is available from.
 - Writes per-package `llms*.txt` files and in-page actions for pointing an assistant at one package's docs.
+- Gives every generated page complete `<head>` metadata: a canonical link, Open Graph and Twitter card tags, and a schema.org JSON-LD graph describing the package, the page and the documented symbol.
 ## Documentation

package/build-program.js CHANGED Viewed

@@ -10,6 +10,7 @@ import { ShikiCrossLinker } from "./shiki-transformer.js";
 import { VfsRegistry } from "./vfs-registry.js";
 import path from "node:path";
 import { Effect, FileSystem } from "effect";
+import { attributionFacts, packageContext } from "@tsdoctor/seo";
 import { SnapshotService } from "@tsdoctor/snapshot";
 //#region src/build-program.ts
@@ -35,8 +36,16 @@ function generateApiDocs(apiConfig, fileContextMap) {
 		const pageConcurrency = yield* PageConcurrency;
 		const suppressExampleErrors = yield* SuppressExampleErrors;
 		const snapshotSvc = yield* SnapshotService;
-		const { apiPackage, packageName, apiName, outputDir, baseRoute, categories, source, packageJson, llmsPlugin, siteUrl, ogImage } = apiConfig;
+		const { apiPackage, packageName, apiName, outputDir, baseRoute, categories, source, packageJson, llmsPlugin, siteUrl, ogImage, manifest } = apiConfig;
 		const phaseCtx = { packageName };
+		const structuredDataPkg = manifest != null && siteUrl != null ? packageContext({
+			siteUrl,
+			baseRoute,
+			packageName,
+			...manifest.version != null ? { version: manifest.version.toString() } : {},
+			...manifest.description != null ? { description: manifest.description } : {},
+			attribution: attributionFacts(manifest)
+		}) : void 0;
 		const resolvedOutputDir = path.resolve(process.cwd(), outputDir);
 		const buildTime = (/* @__PURE__ */ new Date()).toISOString();
 		const allSnapshots = yield* snapshotSvc.getAllForDirectory(resolvedOutputDir).pipe(Effect.orDie);
@@ -81,7 +90,8 @@ function generateApiDocs(apiConfig, fileContextMap) {
 			...llmsPlugin != null ? { llmsPlugin } : {},
 			...apiConfig.docsRoot != null ? { docsRoot: apiConfig.docsRoot } : {},
 			...siteUrl != null ? { siteUrl } : {},
-			...ogImage != null ? { ogImage } : {}
+			...ogImage != null ? { ogImage } : {},
+			...structuredDataPkg != null ? { structuredDataPkg } : {}
 		}));
 		const changedCount = fileResults.filter((r) => r.status !== "unchanged").length;
 		yield* Effect.logDebug(`Generated ${changedCount} pages`);

package/build-stages.js CHANGED Viewed

@@ -12,10 +12,10 @@ import { InterfacePageGenerator } from "./markdown/page-generators/interface-pag
 import { NamespacePageGenerator } from "./markdown/page-generators/namespace-page.js";
 import { TypeAliasPageGenerator } from "./markdown/page-generators/type-alias-page.js";
 import { VariablePageGenerator } from "./markdown/page-generators/variable-page.js";
-import { createPageMetadata } from "./og-resolver.js";
 import { OgService } from "./services/OgService.js";
 import path from "node:path";
 import { Effect, FileSystem, Metric, Option, Stream } from "effect";
+import { deriveScriptBody, headTags } from "@tsdoctor/seo";
 import { SnapshotService, hashContent, hashFrontmatter } from "@tsdoctor/snapshot";
 import { ApiItemKind } from "@microsoft/api-extractor-model";
 import { ApiItems, EntryPoints, Routes, SyntheticBases } from "@tsdoctor/model";
@@ -328,7 +328,79 @@ function generateSinglePage(workItem, ctx) {
 		const frontmatterData = parsed.data;
 		const relativePathWithExt = `${page.routePath.replace(baseRoute, "").replace(/^\//, "")}.mdx`;
 		const contentHash = hashContent(bodyContent);
-		const frontmatterHash = hashFrontmatter(frontmatterData);
+		const description = frontmatterData.description;
+		const seoEnabled = ctx.siteUrl != null && packageName !== "";
+		let ogImageMetadata;
+		let structuredData;
+		if (seoEnabled) {
+			const siteUrl = ctx.siteUrl;
+			const ogSvc = yield* OgService;
+			const ogImageResult = yield* Effect.result(ogSvc.resolveImage({
+				config: ctx.ogImage,
+				siteUrl,
+				docsRoot: ctx.docsRoot,
+				packageName,
+				...apiName != null ? { apiName } : {}
+			}));
+			if (ogImageResult._tag === "Failure") {
+				const failure = ogImageResult.failure;
+				yield* emit(PluginEvent.ConfigValidationWarning({
+					ctx: {
+						buildId,
+						packageName
+					},
+					field: failure.field,
+					value: failure.value,
+					reason: failure.message,
+					level: "warn"
+				}));
+			} else if (Option.isSome(ogImageResult.success)) ogImageMetadata = ogImageResult.success.value;
+			if (ctx.structuredDataPkg != null) {
+				const graphResult = deriveScriptBody(ctx.structuredDataPkg, {
+					pageRoute: page.routePath,
+					symbolName: item.displayName,
+					description,
+					section: categoryConfig.displayName,
+					publishedTime: buildTime,
+					modifiedTime: buildTime
+				});
+				if (graphResult._tag === "Failure") yield* emit(PluginEvent.ConfigValidationWarning({
+					ctx: {
+						buildId,
+						packageName,
+						route: page.routePath
+					},
+					field: "structuredData",
+					value: ctx.structuredDataPkg.id,
+					reason: `schema.org document assembly failed: ${graphResult.failure._tag}`,
+					level: "warn"
+				}));
+				else structuredData = graphResult.success;
+			}
+		}
+		/**
+		* The final frontmatter for a given pair of timestamps.
+		*
+		* @remarks
+		* Called twice: once with the build time to compute the hash, and once
+		* with the resolved timestamps to write. That is sound only because
+		* `hashFrontmatter` strips every timestamp it can reach — the meta-pair
+		* form and the JSON-LD `datePublished`/`dateModified` keys alike — so the
+		* two calls hash identically. Without that stripping the hash would
+		* depend on the timestamps the hash itself decides.
+		*/
+		const finalFrontmatter = (published, modified) => seoEnabled ? generateFrontmatter(item.displayName, description, categoryConfig.singularName, apiName, headTags({
+			siteUrl: ctx.siteUrl,
+			pageRoute: page.routePath,
+			description,
+			publishedTime: published,
+			modifiedTime: modified,
+			section: categoryConfig.displayName,
+			packageName,
+			...ogImageMetadata != null ? { ogImage: ogImageMetadata } : {},
+			...structuredData != null ? { structuredData } : {}
+		})) : stringifyFrontmatter("", frontmatterData);
+		const frontmatterHash = hashFrontmatter(parseFrontmatter(finalFrontmatter(buildTime, buildTime)).data);
 		let publishedTime;
 		let modifiedTime;
 		let isUnchanged = false;
@@ -368,7 +440,7 @@ function generateSinglePage(workItem, ctx) {
 		}
 		return {
 			workItem,
-			content: page.content,
+			content: seoEnabled ? finalFrontmatter(publishedTime, modifiedTime) + bodyContent : page.content,
 			bodyContent,
 			frontmatter: frontmatterData,
 			contentHash,
@@ -387,9 +459,9 @@ function generateSinglePage(workItem, ctx) {
 function writeSingleFile(result, ctx) {
 	return Effect.gen(function* () {
 		const fileSystem = yield* FileSystem.FileSystem;
-		const { buildId, resolvedOutputDir, buildTime, siteUrl, docsRoot, ogImage, packageName, apiName } = ctx;
-		const { workItem, bodyContent, frontmatter, contentHash, frontmatterHash, publishedTime, modifiedTime, isUnchanged, routePath, relativePathWithExt } = result;
-		const { item, categoryKey, categoryConfig, namespaceMember } = workItem;
+		const { buildId, resolvedOutputDir, buildTime, packageName } = ctx;
+		const { workItem, contentHash, frontmatterHash, publishedTime, modifiedTime, isUnchanged, routePath, relativePathWithExt } = result;
+		const { item, categoryKey, namespaceMember } = workItem;
 		const absolutePath = path.join(resolvedOutputDir, relativePathWithExt);
 		const label = namespaceMember ? namespaceMember.qualifiedName : item.displayName;
 		const snapshot = {
@@ -424,43 +496,7 @@ function writeSingleFile(result, ctx) {
 				routePath
 			};
 		}
-		let finalContent = stringifyFrontmatter(bodyContent, frontmatter);
-		if (siteUrl != null && packageName) {
-			const ogSvc = yield* OgService;
-			const ogImageResult = yield* Effect.result(ogSvc.resolveImage({
-				config: ogImage,
-				siteUrl,
-				docsRoot,
-				packageName,
-				...apiName != null ? { apiName } : {}
-			}));
-			if (ogImageResult._tag === "Failure") {
-				const failure = ogImageResult.failure;
-				yield* emit(PluginEvent.ConfigValidationWarning({
-					ctx: {
-						buildId,
-						packageName
-					},
-					field: failure.field,
-					value: failure.value,
-					reason: failure.message,
-					level: "warn"
-				}));
-			}
-			const ogImageMetadata = ogImageResult._tag === "Success" && Option.isSome(ogImageResult.success) ? ogImageResult.success.value : void 0;
-			const ogMetadataOptions = {
-				siteUrl,
-				pageRoute: routePath,
-				description: frontmatter.description,
-				publishedTime,
-				modifiedTime,
-				section: categoryConfig.displayName,
-				packageName
-			};
-			if (ogImageMetadata) ogMetadataOptions.ogImage = ogImageMetadata;
-			const ogMetadata = createPageMetadata(ogMetadataOptions);
-			finalContent = generateFrontmatter(item.displayName, frontmatter.description, categoryConfig.singularName, apiName, ogMetadata) + bodyContent;
-		}
+		const finalContent = result.content;
 		const fileExisted = yield* fileSystem.exists(absolutePath).pipe(Effect.orElseSucceed(() => false));
 		const dirPath = path.dirname(absolutePath);
 		yield* fileSystem.makeDirectory(dirPath, { recursive: true }).pipe(Effect.orDie);
@@ -793,7 +829,11 @@ function buildPipelineForApi(input) {
 		buildTime: input.buildTime,
 		resolvedOutputDir: input.resolvedOutputDir,
 		...input.suppressExampleErrors != null ? { suppressExampleErrors: input.suppressExampleErrors } : {},
-		...input.llmsPlugin != null ? { llmsPlugin: input.llmsPlugin } : {}
+		...input.llmsPlugin != null ? { llmsPlugin: input.llmsPlugin } : {},
+		...input.docsRoot !== void 0 ? { docsRoot: input.docsRoot } : {},
+		...input.siteUrl != null ? { siteUrl: input.siteUrl } : {},
+		...input.ogImage != null ? { ogImage: input.ogImage } : {},
+		...input.structuredDataPkg != null ? { structuredDataPkg: input.structuredDataPkg } : {}
 	};
 	const writeCtx = {
 		buildId: input.buildId,
@@ -803,7 +843,8 @@ function buildPipelineForApi(input) {
 		...input.siteUrl != null ? { siteUrl: input.siteUrl } : {},
 		...input.ogImage != null ? { ogImage: input.ogImage } : {},
 		...input.packageName != null ? { packageName: input.packageName } : {},
-		...input.apiName != null ? { apiName: input.apiName } : {}
+		...input.apiName != null ? { apiName: input.apiName } : {},
+		...input.structuredDataPkg != null ? { structuredDataPkg: input.structuredDataPkg } : {}
 	};
 	return Stream.fromIterable(input.workItems).pipe(Stream.mapEffect((workItem) => generateSinglePage(workItem, generateCtx), { concurrency: input.pageConcurrency }), Stream.filter((result) => result !== null), Stream.mapEffect((result) => writeSingleFile(result, writeCtx), { concurrency: input.pageConcurrency }), Stream.runFold(() => [], (acc, result) => [...acc, result]));
 }

package/index.d.ts CHANGED Viewed

@@ -1,3 +1,4 @@
+import { OpenGraphImageConfig, OpenGraphImageMetadata, OpenGraphMetadata } from "@tsdoctor/seo";
 import { ApiItemKind, ApiModel } from "@microsoft/api-extractor-model";
 import { Schema } from "effect";
 import "typescript";
@@ -854,90 +855,6 @@ declare const ApiExtractorPlugin: typeof ApiExtractorPluginImpl & {
   };
 };
 //#endregion
-//#region src/schemas/opengraph.d.ts
-/**
- * Structured Open Graph image metadata (alternative to a plain URL string).
- *
- * @public
- */
-declare const OpenGraphImageMetadata: Schema.Struct<{
-  /** Absolute URL of the image. */
-  readonly url: Schema.String;
-  /** HTTPS URL of the image (for secure contexts). */
-  readonly secureUrl: Schema.optional<Schema.String>;
-  /** MIME type of the image (e.g. `"image/png"`). */
-  readonly type: Schema.optional<Schema.String>;
-  /** Image width in pixels. */
-  readonly width: Schema.optional<Schema.Number>;
-  /** Image height in pixels. */
-  readonly height: Schema.optional<Schema.Number>;
-  /** Alt text for the image. */
-  readonly alt: Schema.optional<Schema.String>;
-}>;
-/** @public */
-type OpenGraphImageMetadata = typeof OpenGraphImageMetadata.Type;
-/**
- * Open Graph image: either a plain URL string or structured `OpenGraphImageMetadata`.
- *
- * @public
- */
-declare const OpenGraphImageConfig: Schema.Union<readonly [Schema.String, Schema.Struct<{
-  /** Absolute URL of the image. */
-  readonly url: Schema.String;
-  /** HTTPS URL of the image (for secure contexts). */
-  readonly secureUrl: Schema.optional<Schema.String>;
-  /** MIME type of the image (e.g. `"image/png"`). */
-  readonly type: Schema.optional<Schema.String>;
-  /** Image width in pixels. */
-  readonly width: Schema.optional<Schema.Number>;
-  /** Image height in pixels. */
-  readonly height: Schema.optional<Schema.Number>;
-  /** Alt text for the image. */
-  readonly alt: Schema.optional<Schema.String>;
-}>]>;
-/** @public */
-type OpenGraphImageConfig = typeof OpenGraphImageConfig.Type;
-/**
- * Resolved Open Graph metadata emitted into each generated page's frontmatter.
- *
- * @public
- */
-declare const OpenGraphMetadata: Schema.Struct<{
-  /** Canonical site base URL. */
-  readonly siteUrl: Schema.String;
-  /** Page route path (e.g. `/api/classes/myclass`). */
-  readonly pageRoute: Schema.String;
-  /** Page description for the `og:description` tag. */
-  readonly description: Schema.String;
-  /** ISO 8601 date string for `article:published_time`. */
-  readonly publishedTime: Schema.String;
-  /** ISO 8601 date string for `article:modified_time`. */
-  readonly modifiedTime: Schema.String;
-  /** Article section label (e.g. `"API"`). */
-  readonly section: Schema.String;
-  /** Article tag keywords. */
-  readonly tags: Schema.mutable<Schema.$Array<Schema.String>>;
-  /** Optional structured image metadata. */
-  readonly ogImage: Schema.optional<Schema.Struct<{
-    /** Absolute URL of the image. */
-    readonly url: Schema.String;
-    /** HTTPS URL of the image (for secure contexts). */
-    readonly secureUrl: Schema.optional<Schema.String>;
-    /** MIME type of the image (e.g. `"image/png"`). */
-    readonly type: Schema.optional<Schema.String>;
-    /** Image width in pixels. */
-    readonly width: Schema.optional<Schema.Number>;
-    /** Image height in pixels. */
-    readonly height: Schema.optional<Schema.Number>;
-    /** Alt text for the image. */
-    readonly alt: Schema.optional<Schema.String>;
-  }>>;
-  /** Open Graph object type (e.g. `"article"`). */
-  readonly ogType: Schema.String;
-}>;
-/** @public */
-type OpenGraphMetadata = typeof OpenGraphMetadata.Type;
-//#endregion
 //#region src/serve.d.ts
 /**
  * Which RSPress server {@link serve} runs.

package/layers/config-resolution.js CHANGED Viewed

@@ -3,7 +3,6 @@ import { BuildMetrics } from "./build-metrics.js";
 import { PluginEvent } from "../observability/events.js";
 import { emit, wantsLevel } from "../observability/EventBus.js";
 import { TypeReferenceExtractor } from "../type-reference-extractor.js";
-import { deriveSiteUrl } from "../og-resolver.js";
 import { withPhase } from "../observability/spans.js";
 import { normalizeThemeConfig } from "../markdown/shiki-utils.js";
 import { apiScopeOf, deriveOutputPaths, normalizeBaseRoute, unscopedName } from "../path-derivation.js";
@@ -20,7 +19,9 @@ import { mergeExternalTypes } from "./external-types.js";
 import { registerTypeEnvironments, resolveTsConfigTyped } from "./type-environment.js";
 import path from "node:path";
 import { Effect, Metric } from "effect";
+import { deriveSiteUrl } from "@tsdoctor/seo";
 import { hashContent } from "@tsdoctor/snapshot";
+import { PackageManifest } from "@effected/package-json";
 //#region src/layers/config-resolution.ts
 /**
@@ -61,6 +62,40 @@ function prependImportsToVfs(vfs, apiPackage, packageName, wantTrace) {
 	return payloads;
 }
 /**
+* Decode a loaded package.json into a typed {@link PackageManifest}, degrading
+* to `undefined` when it does not satisfy the codec.
+*
+* @remarks
+* `PackageManifest` is presence-lenient but shape-strict — the private
+* workspace-root shape decodes fine, but one malformed field (a `version` of
+* `"1.0"`, an `author` that is neither a string nor an object) fails the whole
+* decode. That is the right strictness for the SEO layer, which needs real
+* `Person` / `Repository` values rather than the discovery tier's raw unions,
+* but it must never fail a docs build: the failure is surfaced as a
+* `ConfigValidationWarning` (which reaches `issues.json`) and the manifest is
+* simply absent. The same posture as the OG image path in `build-stages.ts`.
+*/
+function decodeManifest(packageJson, buildId, packageName) {
+	return Effect.gen(function* () {
+		if (packageJson == null) return void 0;
+		const decoded = yield* Effect.result(PackageManifest.decode(packageJson));
+		if (decoded._tag === "Failure") {
+			yield* emit(PluginEvent.ConfigValidationWarning({
+				ctx: {
+					buildId,
+					packageName
+				},
+				field: "packageJson",
+				value: packageName,
+				reason: decoded.failure.message,
+				level: "warn"
+			}));
+			return;
+		}
+		return decoded.success;
+	});
+}
+/**
 * Validate plugin options and return an Effect that fails with ConfigValidationError.
 */
 function validateOptions(options, rspressConfig) {
@@ -195,6 +230,7 @@ const makeConfigService = Effect.gen(function* () {
 						cause
 					})
 				}) : void 0;
+				const manifest = yield* decodeManifest(packageJson, buildId, api.packageName);
 				yield* Effect.try({
 					try: () => validateExternalPackages(api.externalPackages, packageJson),
 					catch: (cause) => new ConfigValidationError({
@@ -222,6 +258,7 @@ const makeConfigService = Effect.gen(function* () {
 						categories: resolvedCategories,
 						...resolvedSource != null ? { source: resolvedSource } : {},
 						...packageJson != null ? { packageJson } : {},
+						...manifest != null ? { manifest } : {},
 						...resolvedLlms != null ? { llmsPlugin: resolvedLlms } : {},
 						...siteUrl != null ? { siteUrl } : {},
 						...resolvedOgImage != null ? { ogImage: resolvedOgImage } : {},
@@ -272,6 +309,7 @@ const makeConfigService = Effect.gen(function* () {
 									cause
 								})
 							}) : void 0);
+							const manifest = yield* decodeManifest(packageJson, buildId, api.packageName);
 							yield* Effect.try({
 								try: () => validateExternalPackages(versionExternalPackages || api.externalPackages, packageJson),
 								catch: (cause) => new ConfigValidationError({
@@ -302,6 +340,7 @@ const makeConfigService = Effect.gen(function* () {
 									categories: resolvedCategories,
 									...resolvedSource != null ? { source: resolvedSource } : {},
 									...packageJson != null ? { packageJson } : {},
+									...manifest != null ? { manifest } : {},
 									...resolvedLlms != null ? { llmsPlugin: resolvedLlms } : {},
 									...siteUrl != null ? { siteUrl } : {},
 									...resolvedOgImage != null ? { ogImage: resolvedOgImage } : {},

package/markdown/helpers.js CHANGED Viewed

@@ -5,15 +5,6 @@ import { TypeReferenceExtractor } from "../type-reference-extractor.js";
 //#region src/markdown/helpers.ts
 /**
-* Helper utilities for generating markdown API documentation.
-*
-* This module provides shared utility functions used by the page generators
-* for common tasks like preparing Twoslash examples, generating frontmatter,
-* escaping special characters, and sanitizing IDs.
-*
-* @packageDocumentation
-*/
-/**
 * Generate an "Available from" line for items exported from multiple entry points.
 * Returns empty string if only one entry point or none provided.
 */
@@ -118,7 +109,7 @@ function buildPageTitle(entityName, singularName, apiName) {
 * @param description - Page description for SEO
 * @param singularName - The category singular name (e.g., "Class")
 * @param apiName - Optional API/package display name
-* @param ogMetadata - Optional Open Graph metadata for social sharing
+* @param tags - Optional neutral head tags to render into the `head` array
 * @returns YAML frontmatter string
 *
 * @example
@@ -136,30 +127,14 @@ function buildPageTitle(entityName, singularName, apiName) {
 * // ---
 * ```
 */
-function generateFrontmatter(entityName, description, singularName, apiName, ogMetadata) {
+function generateFrontmatter(entityName, description, singularName, apiName, tags) {
 	const title = buildPageTitle(entityName, singularName, apiName);
-	const meta = (property, content) => ["meta", {
-		property,
-		content: cleanYamlValue(content)
-	}];
-	const headEntries = [];
-	if (ogMetadata) {
-		headEntries.push(meta("og:url", `${ogMetadata.siteUrl}${ogMetadata.pageRoute}`));
-		headEntries.push(meta("og:type", ogMetadata.ogType));
-		headEntries.push(meta("og:description", ogMetadata.description));
-		if (ogMetadata.ogImage) {
-			headEntries.push(meta("og:image", ogMetadata.ogImage.url));
-			if (ogMetadata.ogImage.secureUrl) headEntries.push(meta("og:image:secure_url", ogMetadata.ogImage.secureUrl));
-			if (ogMetadata.ogImage.type) headEntries.push(meta("og:image:type", ogMetadata.ogImage.type));
-			if (ogMetadata.ogImage.width) headEntries.push(meta("og:image:width", String(ogMetadata.ogImage.width)));
-			if (ogMetadata.ogImage.height) headEntries.push(meta("og:image:height", String(ogMetadata.ogImage.height)));
-			if (ogMetadata.ogImage.alt) headEntries.push(meta("og:image:alt", ogMetadata.ogImage.alt));
-		}
-		headEntries.push(meta("article:published_time", ogMetadata.publishedTime));
-		headEntries.push(meta("article:modified_time", ogMetadata.modifiedTime));
-		headEntries.push(meta("article:section", ogMetadata.section));
-		for (const tag of ogMetadata.tags) headEntries.push(meta("article:tag", tag));
-	}
+	const headEntries = (tags ?? []).map((tag) => {
+		const attrs = {};
+		for (const [key, value] of Object.entries(tag.attrs)) attrs[key] = cleanYamlValue(value);
+		if (tag.body != null) attrs.children = cleanYamlValue(tag.body);
+		return [tag.tag, attrs];
+	});
 	const data = {
 		title: cleanYamlValue(title),
 		description: cleanYamlValue(description)

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
 	"name": "rspress-plugin-api-extractor",
-	"version": "0.12.0",
+	"version": "0.13.0",
 	"private": false,
 	"description": "RSPress plugin for generating API documentation from TypeScript API Extractor models",
 	"keywords": [
@@ -43,7 +43,7 @@
 		"@effected/jsonc": "^0.8.0",
 		"@effected/markdown": "^0.7.0",
 		"@effected/npm": "^0.12.1",
-		"@effected/package-json": "^0.12.0",
+		"@effected/package-json": "^0.13.0",
 		"@effected/semver": "^0.5.0",
 		"@effected/store": "^0.5.0",
 		"@effected/tsconfig-json": "^0.6.1",
@@ -53,9 +53,10 @@
 		"@microsoft/api-extractor-model": "^7.33.11",
 		"@shikijs/twoslash": "^4.4.3",
 		"@tsdoctor/bundle": "0.2.0",
-		"@tsdoctor/model": "0.3.0",
+		"@tsdoctor/model": "0.4.0",
 		"@tsdoctor/registry": "0.2.1",
-		"@tsdoctor/snapshot": "0.2.0",
+		"@tsdoctor/seo": "0.1.0",
+		"@tsdoctor/snapshot": "0.2.1",
 		"@typescript/vfs": "^1.6.4",
 		"clsx": "^2.1.1",
 		"effect": "4.0.0-rc.109",

package/schemas/config.js CHANGED Viewed

@@ -1,7 +1,7 @@
 import { PerformanceConfig } from "./performance.js";
 import { ObservabilityConfig } from "./observability.js";
-import { OpenGraphImageConfig } from "./opengraph.js";
 import { Effect, Schema } from "effect";
+import { OpenGraphImageConfig } from "@tsdoctor/seo";
 import { ApiItemKind } from "@microsoft/api-extractor-model";
 //#region src/schemas/config.ts

package/services/OgService.js CHANGED Viewed

@@ -1,25 +1,10 @@
 import { PluginEvent } from "../observability/events.js";
 import { emit } from "../observability/EventBus.js";
-import { imageMimeType, ogAltText, resolveOgUrl } from "../og-resolver.js";
 import { Context, Data, Effect, FileSystem, Layer, Option, Path } from "effect";
+import { imageMimeType, ogAltText, resolveUrl } from "@tsdoctor/seo";
 import { imageSize } from "image-size";
 //#region src/services/OgService.ts
-/**
-* Resolving an API's configured Open Graph image into page metadata.
-*
-* @remarks
-* Replaces the `OpenGraphResolver` class, which did synchronous `node:fs` from
-* inside `Effect.promise`, carried its own sync-island event emitter, and
-* returned `undefined` for all three of its failure modes — indistinguishable
-* from "no image was configured".
-*
-* This is also where phase 4's SEO work lands, which is why the contract is
-* wider than today's single caller needs: it names its failures instead of
-* erasing them.
-*
-* @packageDocumentation
-*/
 const OgImageErrorBase = Data.TaggedError("OgImageError");
 /**
 * A configured OG image that could not be resolved.
@@ -129,7 +114,7 @@ const make = () => Effect.gen(function* () {
 		return facts;
 	});
 	const resolveFromString = (imageUrl, request) => Effect.gen(function* () {
-		const resolvedUrl = resolveOgUrl(request.siteUrl, imageUrl);
+		const resolvedUrl = resolveUrl(request.siteUrl, imageUrl);
 		if (resolvedUrl == null) return yield* Effect.fail(new OgImageError({
 			code: "invalid-url",
 			field: "ogImage",
@@ -147,7 +132,7 @@ const make = () => Effect.gen(function* () {
 	});
 	const resolveFromMetadata = (metadata, request) => Effect.gen(function* () {
 		const { url, secureUrl, type, width, height, alt } = metadata;
-		const resolvedUrl = resolveOgUrl(request.siteUrl, url);
+		const resolvedUrl = resolveUrl(request.siteUrl, url);
 		if (resolvedUrl == null) return yield* Effect.fail(new OgImageError({
 			code: "invalid-url",
 			field: "ogImage.url",

package/og-resolver.js DELETED Viewed

@@ -1,95 +0,0 @@
-//#region src/og-resolver.ts
-/**
-* MIME type mappings for common image formats, used for `og:image:type`.
-*/
-const IMAGE_MIME_TYPES = {
-	jpg: "image/jpeg",
-	jpeg: "image/jpeg",
-	png: "image/png",
-	gif: "image/gif",
-	webp: "image/webp",
-	svg: "image/svg+xml"
-};
-/**
-* The `og:image:type` value for a detected image format, or `undefined` for a
-* format with no mapping.
-*/
-function imageMimeType(type) {
-	if (type == null) return void 0;
-	return IMAGE_MIME_TYPES[type.toLowerCase()];
-}
-/**
-* Turn a configured image URL into an absolute one.
-*
-* @returns The absolute URL, or `undefined` when the input is neither an
-* absolute `http(s)` URL nor a site-root-relative path. A bare relative path
-* is deliberately rejected rather than guessed at — there is no base to
-* resolve it against that would not silently produce a broken link.
-*/
-function resolveOgUrl(siteUrl, url) {
-	if (url.startsWith("http://") || url.startsWith("https://")) return url;
-	if (url.startsWith("/")) return `${siteUrl}${url}`;
-}
-/**
-* Derive the site URL prefix from RSPress's own config.
-*
-* @remarks
-* Replaces the plugin's former `siteUrl` option. RSPress already knows where a
-* site is deployed — {@link https://rspress.rs/api/config/config-basic#siteorigin | `siteOrigin`}
-* plus `base` — so asking for it a second time invited the two to disagree, and
-* a plugin-level answer that contradicted the site's own would silently emit
-* canonical and `og:url` tags pointing at a host the site is not served from.
-*
-* RSPress concatenates as `siteOrigin + base + routePath`, and **this follows
-* its documented fallback exactly**: with no `siteOrigin`, RSPress uses
-* `base + routePath`. So an unset origin yields a ROOT-RELATIVE prefix rather
-* than nothing.
-*
-* That fallback is what makes the tags inspectable in `rspress dev`, where the
-* site is served from `localhost` and no configured origin could be correct
-* anyway. A root-relative `/images/og.png` resolves against the page's own
-* origin in the browser; it is a *relative* path (`images/og.png`, no leading
-* slash) that has no base to resolve against, and this never emits one.
-*
-* @returns The prefix to put in front of a route that already begins with `/`.
-* `""` when the site declares neither `siteOrigin` nor a non-root `base`, which
-* leaves every URL root-relative. Never has a trailing slash, since every
-* caller appends a route starting with `/`.
-*/
-function deriveSiteUrl(siteOrigin, base) {
-	const origin = (siteOrigin ?? "").trim().replace(/\/+$/, "");
-	const path = (base ?? "/").trim();
-	return `${origin}${path === "" || path === "/" ? "" : `/${path.replace(/^\/+/, "").replace(/\/+$/, "")}`}`;
-}
-/** Descriptive alt text for a package's (or one API's) OG image. */
-function ogAltText(packageName, apiName) {
-	return apiName ? `${apiName} - ${packageName} API Documentation` : `${packageName} API Documentation`;
-}
-/**
-* Assemble the complete Open Graph metadata for one documentation page.
-*
-* @remarks
-* Was `OpenGraphResolver.createPageMetadata`. It never touched the resolver's
-* instance state, so it is a free function now rather than a static on a class
-* that no longer exists.
-*/
-function createPageMetadata(options) {
-	return {
-		siteUrl: options.siteUrl,
-		pageRoute: options.pageRoute,
-		description: options.description,
-		publishedTime: options.publishedTime,
-		modifiedTime: options.modifiedTime,
-		section: options.section,
-		tags: [
-			"TypeScript",
-			"API",
-			options.packageName
-		],
-		...options.ogImage != null ? { ogImage: options.ogImage } : {},
-		ogType: "article"
-	};
-}
-//#endregion
-export { createPageMetadata, deriveSiteUrl, imageMimeType, ogAltText, resolveOgUrl };

package/schemas/opengraph.js DELETED Viewed

@@ -1,56 +0,0 @@
-import { Schema } from "effect";
-//#region src/schemas/opengraph.ts
-/**
-* Structured Open Graph image metadata (alternative to a plain URL string).
-*
-* @public
-*/
-const OpenGraphImageMetadata = Schema.Struct({
-	/** Absolute URL of the image. */
-	url: Schema.String,
-	/** HTTPS URL of the image (for secure contexts). */
-	secureUrl: Schema.optional(Schema.String),
-	/** MIME type of the image (e.g. `"image/png"`). */
-	type: Schema.optional(Schema.String),
-	/** Image width in pixels. */
-	width: Schema.optional(Schema.Number),
-	/** Image height in pixels. */
-	height: Schema.optional(Schema.Number),
-	/** Alt text for the image. */
-	alt: Schema.optional(Schema.String)
-});
-/**
-* Open Graph image: either a plain URL string or structured `OpenGraphImageMetadata`.
-*
-* @public
-*/
-const OpenGraphImageConfig = Schema.Union([Schema.String, OpenGraphImageMetadata]);
-/**
-* Resolved Open Graph metadata emitted into each generated page's frontmatter.
-*
-* @public
-*/
-const OpenGraphMetadata = Schema.Struct({
-	/** Canonical site base URL. */
-	siteUrl: Schema.String,
-	/** Page route path (e.g. `/api/classes/myclass`). */
-	pageRoute: Schema.String,
-	/** Page description for the `og:description` tag. */
-	description: Schema.String,
-	/** ISO 8601 date string for `article:published_time`. */
-	publishedTime: Schema.String,
-	/** ISO 8601 date string for `article:modified_time`. */
-	modifiedTime: Schema.String,
-	/** Article section label (e.g. `"API"`). */
-	section: Schema.String,
-	/** Article tag keywords. */
-	tags: Schema.mutable(Schema.Array(Schema.String)),
-	/** Optional structured image metadata. */
-	ogImage: Schema.optional(OpenGraphImageMetadata),
-	/** Open Graph object type (e.g. `"article"`). */
-	ogType: Schema.String
-});
-//#endregion
-export { OpenGraphImageConfig, OpenGraphImageMetadata };