@mintlify/cli 4.0.1605 → 4.0.1606

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.1605",
+  "version": "4.0.1606",
   "description": "The Mintlify CLI",
   "engines": {
     "node": ">=18.0.0"
@@ -48,6 +48,7 @@
     "@mintlify/common": "1.0.1224",
     "@mintlify/link-rot": "3.0.1433",
     "@mintlify/models": "0.0.369",
+    "@mintlify/og": "0.0.18",
     "@mintlify/prebuild": "1.0.1383",
     "@mintlify/previewing": "4.0.1456",
     "@mintlify/validation": "0.1.901",
@@ -105,5 +106,5 @@
     "vitest": "2.1.9",
     "vitest-mock-process": "1.0.4"
   },
-  "gitHead": "b853e845313f644ef57686bdac663897f14ce2c4"
+  "gitHead": "400e2092034a4d72ead202b8d8e1e2abbec1f5d8"
 }

package/src/cli.tsx

@@ -12,6 +12,7 @@ import {
   BrokenLinksLog,
   WarningLog,
 } from '@mintlify/previewing';
+import { thumbnailOverrideSchema } from '@mintlify/validation';
 import { render, Text } from 'ink';
 import fs from 'node:fs/promises';
 import path from 'path';
@@ -45,6 +46,7 @@ import { logout } from './logout.js';
 import { mdxLinter } from './mdxLinter.js';
 import { createTelemetryMiddleware } from './middlewares/telemetryMiddleware.js';
 import { mintTestHandler } from './mintTest.js';
+import { ogCommand } from './og.js';
 import {
   buildOverlayRegistryForCheck,
   checkOpenApiFile,
@@ -699,6 +701,43 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
           await terminate(accessibilityCheckTerminateCode || mdxLinterTerminateCode);
         }
       )
+      .command(
+        'og [page]',
+        'Render the social preview (OG) image for a page',
+        (yargs) =>
+          yargs
+            .positional('page', {
+              type: 'string',
+              description: 'Page path, such as guides/webhooks. Defaults to index',
+            })
+            .option('preset', {
+              choices: thumbnailOverrideSchema.shape.preset.unwrap().options,
+              description: 'Try a preset without editing docs.json',
+            })
+            .option('surface', {
+              choices: thumbnailOverrideSchema.shape.surface.unwrap().options,
+              description: 'Try a surface without editing docs.json',
+            })
+            .option('appearance', {
+              choices: thumbnailOverrideSchema.shape.appearance.unwrap().options,
+              description: 'Try an appearance without editing docs.json',
+            })
+            .option('output', {
+              type: 'string',
+              description: 'Where to write the PNG. Defaults to a temporary file',
+            })
+            .option('open', {
+              type: 'boolean',
+              default: true,
+              description: 'Open the image after rendering. Use --no-open in CI',
+            })
+            .example('mint og guides/webhooks', 'Render one page and open it')
+            .example('mint og --preset headline --surface brand', 'Try settings on the home page')
+            .example('mint og --output og.png --no-open', 'Render to a file in CI'),
+        async (argv) => {
+          await terminate(await ogCommand(argv));
+        }
+      )
       .command(
         ['version', 'v'],
         'Display the current version of the CLI and client',

package/src/og.tsx

@@ -0,0 +1,185 @@
+import { parseFrontmatter, slugToTitle } from '@mintlify/common';
+import { renderOgCardPng } from '@mintlify/og';
+import {
+  applyCardThemeOverride,
+  applyThumbnailOverride,
+  buildOgCardInput,
+  checkOgCard,
+  createLocalAssetLoaders,
+  deriveOgThemeParams,
+  getOgPageParams,
+  MAX_OG_ASSET_BYTES,
+  toOgFontAsset,
+  toOgImageAsset,
+  type OgAssetLoaders,
+} from '@mintlify/og/config';
+import { getConfigObj } from '@mintlify/prebuild';
+import { addLog, ErrorLog, SuccessLog, WarningLog } from '@mintlify/previewing';
+import { validateDocsConfig, type ThumbnailOverride } from '@mintlify/validation';
+import { mkdir, mkdtemp, readFile, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import open from 'open';
+
+import { CMD_EXEC_PATH } from './helpers.js';
+
+export type OgCommandOptions = Pick<ThumbnailOverride, 'preset' | 'surface' | 'appearance'> & {
+  page?: string;
+  output?: string;
+  open: boolean;
+};
+
+const REMOTE_TIMEOUT_MS = 5_000;
+const PAGE_EXTENSIONS = ['.mdx', '.md'];
+const MAX_REPORTED_ISSUES = 5;
+
+const readLimited = async (response: Response): Promise<Uint8Array | null> => {
+  const declared = Number(response.headers.get('content-length'));
+  if (declared > MAX_OG_ASSET_BYTES || !response.body) return null;
+
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  for (let result = await reader.read(); !result.done; result = await reader.read()) {
+    size += result.value.byteLength;
+    if (size > MAX_OG_ASSET_BYTES) {
+      await reader.cancel();
+      return null;
+    }
+    chunks.push(result.value);
+  }
+
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+};
+
+const fetchAsset = async (src: string) => {
+  try {
+    const response = await fetch(src, { signal: AbortSignal.timeout(REMOTE_TIMEOUT_MS) });
+    if (!response.ok) return null;
+    const bytes = await readLimited(response);
+    return bytes && { bytes, contentType: response.headers.get('content-type') ?? undefined };
+  } catch {
+    return null;
+  }
+};
+
+const remoteLoaders: OgAssetLoaders = {
+  image: async (src) => {
+    const asset = await fetchAsset(src);
+    return asset && toOgImageAsset(asset.bytes, asset.contentType);
+  },
+  font: async (src) => {
+    const asset = await fetchAsset(src);
+    return asset && toOgFontAsset(asset.bytes);
+  },
+};
+
+const normalizePagePath = (page: string | undefined) =>
+  path.posix
+    .normalize(`/${(page ?? '').replace(/\\/g, '/')}`)
+    .replace(/^\/+|\/+$/g, '')
+    .replace(/\.mdx?$/, '') || 'index';
+
+const pageHref = (pagePath: string) => pagePath.replace(/(^|\/)index$/, '');
+
+const pageCandidates = (pagePath: string) =>
+  [pagePath, `${pagePath}/index`].flatMap((base) =>
+    PAGE_EXTENSIONS.map((extension) => `${base}${extension}`)
+  );
+
+const readPage = async (pagePath: string) => {
+  const root = path.resolve(CMD_EXEC_PATH);
+  for (const candidate of pageCandidates(pagePath)) {
+    const filePath = path.resolve(root, candidate);
+    if (!filePath.startsWith(`${root}${path.sep}`)) return null;
+    try {
+      return await readFile(filePath, 'utf-8');
+    } catch {
+      continue;
+    }
+  }
+  return null;
+};
+
+const stringAttribute = (attributes: Record<string, unknown>, key: string) => {
+  const value = attributes[key];
+  return typeof value === 'string' && value ? value : undefined;
+};
+
+const defaultOutputPath = async (pagePath: string) =>
+  path.join(
+    await mkdtemp(path.join(os.tmpdir(), 'mintlify-og-')),
+    `${pagePath.replace(/\//g, '-')}.png`
+  );
+
+export async function ogCommand(options: OgCommandOptions): Promise<0 | 1> {
+  const rawConfig = await getConfigObj(CMD_EXEC_PATH, 'docs');
+  if (!rawConfig) {
+    addLog(<ErrorLog message="No docs.json found. Run mint og from your docs directory." />);
+    return 1;
+  }
+
+  const validation = validateDocsConfig(rawConfig);
+  if (!validation.success) {
+    const issues = validation.error.issues
+      .slice(0, MAX_REPORTED_ISSUES)
+      .map((issue) => `${issue.path.join('.') || 'docs.json'}: ${issue.message}`);
+    addLog(<ErrorLog message={`docs.json is invalid:\n${issues.join('\n')}`} />);
+    return 1;
+  }
+  const docsConfig = validation.data;
+
+  const pagePath = normalizePagePath(options.page);
+  const contents = await readPage(pagePath);
+  if (contents === null) {
+    addLog(
+      <ErrorLog message={`Couldn't find a page at ${pageCandidates(pagePath).join(', ')}.`} />
+    );
+    return 1;
+  }
+
+  const { attributes } = parseFrontmatter<Record<string, unknown>>(contents);
+  const pageParams = getOgPageParams(
+    {
+      path: pagePath,
+      title:
+        stringAttribute(attributes, 'title') ??
+        stringAttribute(attributes, 'sidebarTitle') ??
+        slugToTitle(pageHref(pagePath)),
+      description: stringAttribute(attributes, 'description'),
+      thumbnail: attributes.thumbnail,
+    },
+    docsConfig
+  );
+  const themeParams = applyThumbnailOverride(
+    applyCardThemeOverride(deriveOgThemeParams(docsConfig), pageParams.thumbnail),
+    options
+  );
+
+  const input = await buildOgCardInput(
+    pageParams,
+    themeParams,
+    createLocalAssetLoaders(CMD_EXEC_PATH, remoteLoaders)
+  );
+  const png = await renderOgCardPng(input);
+
+  const outputPath = options.output
+    ? path.resolve(options.output)
+    : await defaultOutputPath(pagePath);
+  await mkdir(path.dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, new Uint8Array(png));
+
+  for (const warning of checkOgCard(input, themeParams)) {
+    addLog(<WarningLog message={warning} />);
+  }
+  addLog(<SuccessLog message={`Wrote ${outputPath}`} />);
+
+  if (options.open && !process.env.CI) await open(outputPath);
+  return 0;
+}