@farming-labs/docs 0.0.9 → 0.0.11

package/dist/index.d.mts

@@ -223,13 +223,36 @@ interface OGConfig {
   endpoint?: string;
   defaultImage?: string;
 }
+/** Single image entry for Open Graph (frontmatter or Next metadata). */
+interface OpenGraphImage {
+  url: string;
+  width?: number;
+  height?: number;
+}
+/** Open Graph block in page frontmatter. When present, used as-is for metadata (replaces generated OG). */
+interface PageOpenGraph {
+  images?: OpenGraphImage[];
+  title?: string;
+  description?: string;
+}
+/** Twitter card block in page frontmatter. When present, used as-is for metadata (replaces generated twitter). */
+interface PageTwitter {
+  card?: "summary" | "summary_large_image";
+  images?: string[];
+  title?: string;
+  description?: string;
+}
 interface PageFrontmatter {
   title: string;
   description?: string;
   tags?: string[];
   icon?: string;
-  /** Path to custom OG image for this page */
+  /** Path to custom OG image for this page (shorthand). Ignored if `openGraph` is set. */
   ogImage?: string;
+  /** Full Open Graph object. When set, replaces any generated OG from config (e.g. dynamic endpoint). */
+  openGraph?: PageOpenGraph;
+  /** Full Twitter card object. When set, replaces any generated twitter from config. */
+  twitter?: PageTwitter;
   /** Sort order in the sidebar. Lower numbers appear first. Pages without `order` are sorted alphabetically after ordered pages. */
   order?: number;
 }
@@ -962,6 +985,20 @@ interface OrderingItem {
   /** Ordering for child pages within this folder */
   children?: OrderingItem[];
 }
+/**
+ * Data passed to the `onCopyClick` callback when the user clicks the copy button
+ * on a code block in the docs.
+ */
+interface CodeBlockCopyData {
+  /** Title of the code block (e.g. from the fenced code block meta string), if present */
+  title?: string;
+  /** Raw code content (the text that was copied to the clipboard) */
+  content: string;
+  /** Current page URL at the time of copy */
+  url: string;
+  /** Language / syntax hint (e.g. "tsx", "bash"), if present */
+  language?: string;
+}
 interface DocsConfig {
   /** Entry folder for docs (e.g. "docs" → /docs) */
   entry: string;
@@ -1058,6 +1095,24 @@ interface DocsConfig {
    * ```
    */
   components?: Record<string, unknown>;
+  /**
+   * Callback fired when the user clicks the copy button on a code block.
+   * Called in addition to the default copy-to-clipboard behavior.
+   * Use it for analytics, logging, or custom behavior.
+   *
+   * @example
+   * ```ts
+   * export default defineDocs({
+   *   entry: "docs",
+   *   theme: fumadocs(),
+   *   onCopyClick(data) {
+   *     console.log("Code copied", data.title, data.language, data.url);
+   *     analytics.track("code_block_copy", { title: data.title, url: data.url });
+   *   },
+   * });
+   * ```
+   */
+  onCopyClick?: (data: CodeBlockCopyData) => void;
   /**
    * Icon registry for sidebar items.
    *
@@ -1279,7 +1334,20 @@ declare function extendTheme(baseTheme: DocsTheme, extensions: Partial<DocsTheme
 declare function resolveTitle(pageTitle: string, metadata?: DocsMetadata): string;
 /**
  * Resolve OG image URL for a page.
+ * Prefers page.openGraph.images[0], then page.ogImage, then config endpoint/default.
  */
 declare function resolveOGImage(page: PageFrontmatter, ogConfig?: OGConfig, baseUrl?: string): string | undefined;
+/**
+ * Build the Open Graph metadata object for a page.
+ * When the page has openGraph in frontmatter, uses it (with title/description filled from page if omitted).
+ * Otherwise uses ogImage or config (dynamic endpoint / defaultImage).
+ */
+declare function buildPageOpenGraph(page: Pick<PageFrontmatter, "title" | "description" | "ogImage" | "openGraph">, ogConfig?: OGConfig, baseUrl?: string): PageOpenGraph | undefined;
+/**
+ * Build the Twitter card metadata object for a page.
+ * When the page has twitter in frontmatter, uses it.
+ * Otherwise builds from ogImage or config (dynamic endpoint).
+ */
+declare function buildPageTwitter(page: Pick<PageFrontmatter, "title" | "description" | "ogImage" | "openGraph" | "twitter">, ogConfig?: OGConfig, baseUrl?: string): PageTwitter | undefined;
 //#endregion
-export { type AIConfig, type BreadcrumbConfig, type CopyMarkdownConfig, type DocsConfig, type DocsMetadata, type DocsNav, type DocsTheme, type FontStyle, type GithubConfig, type LastUpdatedConfig, type LlmsTxtConfig, type OGConfig, type OpenDocsConfig, type OpenDocsProvider, type OrderingItem, type PageActionsConfig, type PageFrontmatter, type SidebarComponentProps, type SidebarConfig, type SidebarFolderNode, type SidebarNode, type SidebarPageNode, type SidebarTree, type ThemeToggleConfig, type TypographyConfig, type UIConfig, createTheme, deepMerge, defineDocs, extendTheme, resolveOGImage, resolveTitle };
+export { type AIConfig, type BreadcrumbConfig, type CodeBlockCopyData, type CopyMarkdownConfig, type DocsConfig, type DocsMetadata, type DocsNav, type DocsTheme, type FontStyle, type GithubConfig, type LastUpdatedConfig, type LlmsTxtConfig, type OGConfig, type OpenDocsConfig, type OpenDocsProvider, type OpenGraphImage, type OrderingItem, type PageActionsConfig, type PageFrontmatter, type PageOpenGraph, type PageTwitter, type SidebarComponentProps, type SidebarConfig, type SidebarFolderNode, type SidebarNode, type SidebarPageNode, type SidebarTree, type ThemeToggleConfig, type TypographyConfig, type UIConfig, buildPageOpenGraph, buildPageTwitter, createTheme, deepMerge, defineDocs, extendTheme, resolveOGImage, resolveTitle };

package/dist/index.mjs

@@ -110,13 +110,74 @@ function resolveTitle(pageTitle, metadata) {
 }
 /**
 * Resolve OG image URL for a page.
+* Prefers page.openGraph.images[0], then page.ogImage, then config endpoint/default.
 */
 function resolveOGImage(page, ogConfig, baseUrl) {
+	if (page.openGraph?.images?.length) return resolveImageUrl(page.openGraph.images[0].url, baseUrl);
 	if (!ogConfig?.enabled) return void 0;
-	if (page.ogImage) return page.ogImage.startsWith("/") || page.ogImage.startsWith("http") ? page.ogImage : `${baseUrl ?? ""}${page.ogImage}`;
+	if (page.ogImage) return resolveImageUrl(page.ogImage, baseUrl);
 	if (ogConfig.type === "dynamic" && ogConfig.endpoint) return `${baseUrl ?? ""}${ogConfig.endpoint}`;
 	return ogConfig.defaultImage;
 }
+function resolveImageUrl(url, baseUrl) {
+	if (url.startsWith("/") || url.startsWith("http")) return url;
+	const base = baseUrl ?? "";
+	return `${base}${base.length > 0 && !base.endsWith("/") ? "/" : ""}${url}`;
+}
+/**
+* Build the Open Graph metadata object for a page.
+* When the page has openGraph in frontmatter, uses it (with title/description filled from page if omitted).
+* Otherwise uses ogImage or config (dynamic endpoint / defaultImage).
+*/
+function buildPageOpenGraph(page, ogConfig, baseUrl) {
+	if (page.openGraph) {
+		const images = page.openGraph.images?.length ? page.openGraph.images.map((img) => ({
+			url: resolveImageUrl(img.url, baseUrl),
+			width: img.width ?? 1200,
+			height: img.height ?? 630
+		})) : void 0;
+		return {
+			title: page.openGraph.title ?? page.title,
+			description: page.openGraph.description ?? page.description,
+			...images && { images }
+		};
+	}
+	const url = resolveOGImage(page, ogConfig, baseUrl);
+	if (!url) return void 0;
+	return {
+		title: page.title,
+		...page.description && { description: page.description },
+		images: [{
+			url,
+			width: 1200,
+			height: 630
+		}]
+	};
+}
+/**
+* Build the Twitter card metadata object for a page.
+* When the page has twitter in frontmatter, uses it.
+* Otherwise builds from ogImage or config (dynamic endpoint).
+*/
+function buildPageTwitter(page, ogConfig, baseUrl) {
+	if (page.twitter) {
+		const images = page.twitter.images?.length ? page.twitter.images.map((url) => resolveImageUrl(url, baseUrl)) : void 0;
+		return {
+			...page.twitter.card && { card: page.twitter.card },
+			...page.twitter.title !== void 0 && { title: page.twitter.title },
+			...page.twitter.description !== void 0 && { description: page.twitter.description },
+			...images && { images }
+		};
+	}
+	const url = resolveOGImage(page, ogConfig, baseUrl);
+	if (!url) return void 0;
+	return {
+		card: "summary_large_image",
+		title: page.title,
+		...page.description && { description: page.description },
+		images: [url]
+	};
+}
 
 //#endregion
-export { createTheme, deepMerge, defineDocs, extendTheme, resolveOGImage, resolveTitle };
+export { buildPageOpenGraph, buildPageTwitter, createTheme, deepMerge, defineDocs, extendTheme, resolveOGImage, resolveTitle };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/docs",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "Modern, flexible MDX-based docs framework — core types, config, and CLI",
   "keywords": [
     "docs",