@mintlify/cli 4.0.1605 → 4.0.1606

package/bin/cli.js

@@ -10,6 +10,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { buildGraph, getBrokenExternalLinks } from '@mintlify/link-rot';
 import { addLog, dev, exportSite, validateBuild, ErrorLog, SpinnerLog, SuccessLog, Logs, clearLogs, 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';
@@ -32,6 +33,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, getOpenApiFilenamesFromDocsConfig, } from './openApiCheck.js';
 import { resolveExplicitFiles } from './resolveFiles.js';
 import { scoreHandler } from './score/index.js';
@@ -524,6 +526,37 @@ export const cli = ({ packageName = 'mint' }) => {
             mdxLinterTerminateCode = yield mdxLinter();
         }
         yield 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'), (argv) => __awaiter(void 0, void 0, void 0, function* () {
+        yield terminate(yield ogCommand(argv));
     }))
         .command(['version', 'v'], 'Display the current version of the CLI and client', () => undefined, () => __awaiter(void 0, void 0, void 0, function* () {
         const { cli, client } = getVersions(packageName);

package/bin/og.js

@@ -0,0 +1,145 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { jsx as _jsx } from "react/jsx-runtime";
+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, } from '@mintlify/og/config';
+import { getConfigObj } from '@mintlify/prebuild';
+import { addLog, ErrorLog, SuccessLog, WarningLog } from '@mintlify/previewing';
+import { validateDocsConfig } 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';
+const REMOTE_TIMEOUT_MS = 5000;
+const PAGE_EXTENSIONS = ['.mdx', '.md'];
+const MAX_REPORTED_ISSUES = 5;
+const readLimited = (response) => __awaiter(void 0, void 0, void 0, function* () {
+    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 = [];
+    let size = 0;
+    for (let result = yield reader.read(); !result.done; result = yield reader.read()) {
+        size += result.value.byteLength;
+        if (size > MAX_OG_ASSET_BYTES) {
+            yield 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 = (src) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    try {
+        const response = yield fetch(src, { signal: AbortSignal.timeout(REMOTE_TIMEOUT_MS) });
+        if (!response.ok)
+            return null;
+        const bytes = yield readLimited(response);
+        return bytes && { bytes, contentType: (_a = response.headers.get('content-type')) !== null && _a !== void 0 ? _a : undefined };
+    }
+    catch (_b) {
+        return null;
+    }
+});
+const remoteLoaders = {
+    image: (src) => __awaiter(void 0, void 0, void 0, function* () {
+        const asset = yield fetchAsset(src);
+        return asset && toOgImageAsset(asset.bytes, asset.contentType);
+    }),
+    font: (src) => __awaiter(void 0, void 0, void 0, function* () {
+        const asset = yield fetchAsset(src);
+        return asset && toOgFontAsset(asset.bytes);
+    }),
+};
+const normalizePagePath = (page) => path.posix
+    .normalize(`/${(page !== null && page !== void 0 ? page : '').replace(/\\/g, '/')}`)
+    .replace(/^\/+|\/+$/g, '')
+    .replace(/\.mdx?$/, '') || 'index';
+const pageHref = (pagePath) => pagePath.replace(/(^|\/)index$/, '');
+const pageCandidates = (pagePath) => [pagePath, `${pagePath}/index`].flatMap((base) => PAGE_EXTENSIONS.map((extension) => `${base}${extension}`));
+const readPage = (pagePath) => __awaiter(void 0, void 0, void 0, function* () {
+    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 yield readFile(filePath, 'utf-8');
+        }
+        catch (_a) {
+            continue;
+        }
+    }
+    return null;
+});
+const stringAttribute = (attributes, key) => {
+    const value = attributes[key];
+    return typeof value === 'string' && value ? value : undefined;
+};
+const defaultOutputPath = (pagePath) => __awaiter(void 0, void 0, void 0, function* () {
+    return path.join(yield mkdtemp(path.join(os.tmpdir(), 'mintlify-og-')), `${pagePath.replace(/\//g, '-')}.png`);
+});
+export function ogCommand(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const rawConfig = yield getConfigObj(CMD_EXEC_PATH, 'docs');
+        if (!rawConfig) {
+            addLog(_jsx(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(_jsx(ErrorLog, { message: `docs.json is invalid:\n${issues.join('\n')}` }));
+            return 1;
+        }
+        const docsConfig = validation.data;
+        const pagePath = normalizePagePath(options.page);
+        const contents = yield readPage(pagePath);
+        if (contents === null) {
+            addLog(_jsx(ErrorLog, { message: `Couldn't find a page at ${pageCandidates(pagePath).join(', ')}.` }));
+            return 1;
+        }
+        const { attributes } = parseFrontmatter(contents);
+        const pageParams = getOgPageParams({
+            path: pagePath,
+            title: (_b = (_a = stringAttribute(attributes, 'title')) !== null && _a !== void 0 ? _a : stringAttribute(attributes, 'sidebarTitle')) !== null && _b !== void 0 ? _b : slugToTitle(pageHref(pagePath)),
+            description: stringAttribute(attributes, 'description'),
+            thumbnail: attributes.thumbnail,
+        }, docsConfig);
+        const themeParams = applyThumbnailOverride(applyCardThemeOverride(deriveOgThemeParams(docsConfig), pageParams.thumbnail), options);
+        const input = yield buildOgCardInput(pageParams, themeParams, createLocalAssetLoaders(CMD_EXEC_PATH, remoteLoaders));
+        const png = yield renderOgCardPng(input);
+        const outputPath = options.output
+            ? path.resolve(options.output)
+            : yield defaultOutputPath(pagePath);
+        yield mkdir(path.dirname(outputPath), { recursive: true });
+        yield writeFile(outputPath, new Uint8Array(png));
+        for (const warning of checkOgCard(input, themeParams)) {
+            addLog(_jsx(WarningLog, { message: warning }));
+        }
+        addLog(_jsx(SuccessLog, { message: `Wrote ${outputPath}` }));
+        if (options.open && !process.env.CI)
+            yield open(outputPath);
+        return 0;
+    });
+}