@mintlify/previewing 4.0.1519 → 4.0.1521

package/dist/__tests__/export-base-path.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/export-base-path.test.js

@@ -0,0 +1,101 @@
+import fse from 'fs-extra';
+import os from 'os';
+import path from 'path';
+import { rewriteCssUrls } from '../local-preview/export-assets.js';
+import { applyBasePathToExport, findBasePathConflict, normalizeExportBasePath, prefixNextAssetPaths, prefixNextStaticPaths, prefixNextStaticPathsInPayload, } from '../local-preview/export-base-path.js';
+import { generateExportLlmsTxt } from '../local-preview/export-llms.js';
+const push = (payload) => `<script>self.__next_f.push(${JSON.stringify([1, payload])})</script>`;
+const readPayload = (html) => [...html.matchAll(/self\.__next_f\.push\((\[1,".*?"\])\)<\/script>/g)]
+    .map((match) => {
+    const parsed = JSON.parse(match[1] ?? '');
+    return Array.isArray(parsed) && typeof parsed[1] === 'string' ? parsed[1] : '';
+})
+    .join('');
+describe('normalizeExportBasePath', () => {
+    it.each([
+        [undefined, ''],
+        ['', ''],
+        ['/', ''],
+        ['docs', '/docs'],
+        ['/docs/', '/docs'],
+        ['/docs/v1', '/docs/v1'],
+    ])('normalizes %s to %s', (input, expected) => {
+        expect(normalizeExportBasePath(input)).toBe(expected);
+    });
+    it.each(['/docs/../etc', '/docs//v1', '/docs?x=1', '/my docs', '/do"cs'])('rejects %s', (input) => {
+        expect(() => normalizeExportBasePath(input)).toThrow('invalid base path');
+    });
+});
+describe('findBasePathConflict', () => {
+    it('returns the first page that starts with the base path', () => {
+        expect(findBasePathConflict(['/', '/quickstart', '/docs/intro'], '/docs')).toBe('/docs/intro');
+        expect(findBasePathConflict(['/', '/docs'], '/docs')).toBe('/docs');
+    });
+    it('ignores pages that only share a prefix, and exports without a base path', () => {
+        expect(findBasePathConflict(['/docsearch', '/guides/docs'], '/docs')).toBeUndefined();
+        expect(findBasePathConflict(['/docs/intro'], '')).toBeUndefined();
+    });
+});
+describe('prefixNextAssetPaths', () => {
+    it('prefixes chunk base and asset literals but not runtime concatenations', () => {
+        const source = 'let t="/_next/",r=1;e.v("/_next/static/media/worker.js");x={path:"/_next/image"};let a=r.assetPrefix+"/_next/"+p';
+        expect(prefixNextAssetPaths(source, '/docs')).toBe('let t="/docs/_next/",r=1;e.v("/docs/_next/static/media/worker.js");x={path:"/docs/_next/image"};let a=r.assetPrefix+"/_next/"+p');
+    });
+});
+describe('prefixNextStaticPaths', () => {
+    it('prefixes static attributes and flight chunk lists but not escaped text', () => {
+        const html = [
+            '<script src="/_next/static/chunks/a.js" async=""></script>',
+            '<link rel="stylesheet" href="/docs/_next/static/css/b.css"/>',
+            push('9:I[123,["/_next/static/chunks/a.js","/_next/static/chunks/c.js"],"default"]\n'),
+            push('b:["$","code",null,{"children":"\\"/_next/static/chunks/escaped.js\\""}]\n'),
+        ].join('');
+        const result = prefixNextStaticPaths(html, '/docs');
+        expect(result).toContain('<script src="/docs/_next/static/chunks/a.js"');
+        expect(result).toContain('href="/docs/_next/static/css/b.css"');
+        const payload = readPayload(result);
+        expect(payload).toContain('9:I[123,["/docs/_next/static/chunks/a.js","/docs/_next/static/chunks/c.js"]');
+        expect(payload).toContain('\\"/_next/static/chunks/escaped.js\\"');
+    });
+    it('leaves html untouched without a base path', () => {
+        const html = '<script src="/_next/static/chunks/a.js"></script>' +
+            push('9:I[1,["/_next/static/chunks/a.js"]]\n');
+        expect(prefixNextStaticPaths(html, '')).toBe(html);
+    });
+});
+describe('prefixNextStaticPathsInPayload', () => {
+    it('prefixes chunk paths in a saved rsc payload but not escaped text', () => {
+        const payload = `1:I[123,["/_next/static/chunks/a.js"],"default"]\n3:["$","p",null,{"children":"\\"/_next/static/x.js\\""}]\n`;
+        expect(prefixNextStaticPathsInPayload(payload, '/docs')).toBe(payload.replace('["/_next/static/chunks/a.js"]', '["/docs/_next/static/chunks/a.js"]'));
+        expect(prefixNextStaticPathsInPayload(payload, '')).toBe(payload);
+    });
+});
+describe('applyBasePathToExport', () => {
+    let exportDir;
+    beforeEach(async () => {
+        exportDir = await fse.mkdtemp(path.join(os.tmpdir(), 'mint-export-base-path-test-'));
+    });
+    afterEach(async () => {
+        await fse.remove(exportDir);
+    });
+    it('patches html and turbopack chunks inside the export', async () => {
+        await fse.outputFile(path.join(exportDir, 'guides', 'index.html'), '<script src="/_next/static/chunks/a.js"></script>');
+        await fse.outputFile(path.join(exportDir, '_next', 'static', 'chunks', 'turbopack-1.js'), 'let t="/_next/";');
+        await fse.outputFile(path.join(exportDir, 'images', 'app.js'), 'let t="/_next/";');
+        await fse.outputFile(path.join(exportDir, 'guides', 'index.txt'), '1:I[1,["/_next/static/chunks/a.js"],"default"]\n');
+        await applyBasePathToExport(exportDir, '/docs');
+        await expect(fse.readFile(path.join(exportDir, 'guides', 'index.html'), 'utf8')).resolves.toBe('<script src="/docs/_next/static/chunks/a.js"></script>');
+        await expect(fse.readFile(path.join(exportDir, '_next', 'static', 'chunks', 'turbopack-1.js'), 'utf8')).resolves.toBe('let t="/docs/_next/";');
+        await expect(fse.readFile(path.join(exportDir, 'images', 'app.js'), 'utf8')).resolves.toBe('let t="/_next/";');
+        await expect(fse.readFile(path.join(exportDir, 'guides', 'index.txt'), 'utf8')).resolves.toBe('1:I[1,["/docs/_next/static/chunks/a.js"],"default"]\n');
+    });
+});
+describe('base path aware css and llms.txt', () => {
+    it('makes root-relative urls in local css relative to the stylesheet', () => {
+        const css = rewriteCssUrls('@font-face{src:url(/_next/static/media/inter.woff2)}', undefined, '/_next/static/chunks/app.css', () => undefined);
+        expect(css).toBe('@font-face{src:url(../media/inter.woff2)}');
+    });
+    it('prefixes llms.txt links with the base path', () => {
+        expect(generateExportLlmsTxt({ name: 'Conduit' }, [{ href: '/quickstart', title: 'Quickstart' }], ['/quickstart'], '/docs')).toBe('# Conduit\n\n## Docs\n\n- [Quickstart](/docs/quickstart)\n');
+    });
+});

package/dist/__tests__/export.test.js

@@ -1,7 +1,7 @@
 import fse from 'fs-extra';
 import os from 'os';
 import path from 'path';
-import { generatePages, writeStaticUserInfo } from '../local-preview/export.js';
+import { generatePages, withIndexRouteAliases, writeStaticUserInfo, } from '../local-preview/export.js';
 import { getGroupFilteredRoutes } from '../local-preview/getGroupFilteredRoutes.js';
 describe('getGroupFilteredRoutes', () => {
     it('prunes routes outside the selected groups', () => {
@@ -21,6 +21,20 @@ describe('getGroupFilteredRoutes', () => {
         expect(routes).toEqual(['/', '/index', '/quickstart', '/authenticated']);
     });
 });
+describe('withIndexRouteAliases', () => {
+    it('adds the parent route for nested index pages', () => {
+        expect(withIndexRouteAliases(['/', '/index', '/agent/index', '/agent/slack'])).toEqual([
+            '/',
+            '/index',
+            '/agent/index',
+            '/agent',
+            '/agent/slack',
+        ]);
+    });
+    it('does not duplicate routes that are already listed', () => {
+        expect(withIndexRouteAliases(['/cli', '/cli/index'])).toEqual(['/cli', '/cli/index']);
+    });
+});
 describe('generatePages', () => {
     let outputDir;
     beforeEach(async () => {

package/dist/local-preview/export-assets.d.ts

@@ -3,6 +3,7 @@ export type LocalizeAssetsResult = {
     downloaded: string[];
     failed: string[];
 };
+export declare function walkFiles(dir: string): AsyncGenerator<string>;
 export declare function collectAssetPaths(exportDir: string): Promise<Set<string>>;
 export declare function rewriteCssUrls(css: string, cssUrl: string | undefined, cssAssetPath: string, onAsset: (assetPath: string) => void): string;
 export declare function localizeAssets(exportDir: string, fetchAsset?: FetchAsset): Promise<LocalizeAssetsResult>;

package/dist/local-preview/export-assets.js

@@ -6,7 +6,7 @@ const ASSET_PATH_PATTERN = new RegExp(`${MINT_EXPORT_ASSETS_PREFIX.replace(/\//g
 const CSS_URL_PATTERN = /url\(\s*(['"]?)([^'")]+)\1\s*\)/g;
 const CODE_LANGUAGE_PATTERN = /\slanguage="([^"]+)"/g;
 const CONCURRENCY = 10;
-async function* walkFiles(dir) {
+export async function* walkFiles(dir) {
     for (const entry of await fse.readdir(dir, { withFileTypes: true })) {
         const entryPath = path.join(dir, entry.name);
         if (entry.isDirectory()) {
@@ -54,6 +54,9 @@ export function rewriteCssUrls(css, cssUrl, cssAssetPath, onAsset) {
     return css.replace(CSS_URL_PATTERN, (match, quote, rawUrl) => {
         if (rawUrl.startsWith('data:') || rawUrl.startsWith('#'))
             return match;
+        if (!cssUrl && rawUrl.startsWith('/') && !rawUrl.startsWith('//')) {
+            return `url(${quote}${path.posix.relative(path.posix.dirname(cssAssetPath), rawUrl)}${quote})`;
+        }
         let absoluteUrl;
         try {
             absoluteUrl = new URL(rawUrl.startsWith('//') ? `https:${rawUrl}` : rawUrl, cssUrl).toString();

package/dist/local-preview/export-base-path.d.ts

@@ -0,0 +1,6 @@
+export declare function normalizeExportBasePath(value: string | undefined): string;
+export declare const findBasePathConflict: (routes: string[], basePath: string) => string | undefined;
+export declare const prefixNextAssetPaths: (source: string, basePath: string) => string;
+export declare const prefixNextStaticPathsInPayload: (payload: string, basePath: string) => string;
+export declare const prefixNextStaticPaths: (html: string, basePath: string) => string;
+export declare function applyBasePathToExport(exportDir: string, basePath: string): Promise<void>;

package/dist/local-preview/export-base-path.js

@@ -0,0 +1,43 @@
+import { normalizeBasePath } from '@mintlify/common';
+import fse from 'fs-extra';
+import path from 'path';
+import { walkFiles } from './export-assets.js';
+const CHUNK_BASE_PATH_PATTERN = /(?<=[=(,:]\s*)(["'])\/_next\//g;
+const NEXT_STATIC_IN_PAYLOAD_PATTERN = /(?<!\\)"\/_next\/static\//g;
+const NEXT_STATIC_IN_HTML_PATTERN = /(?<!\\)(\\?)"\/_next\/static\//g;
+const BASE_PATH_PATTERN = /^(\/[\w-]+)+$/;
+export function normalizeExportBasePath(value) {
+    const basePath = normalizeBasePath(value?.trim());
+    if (basePath && !BASE_PATH_PATTERN.test(basePath)) {
+        throw new Error(`invalid base path: ${value}`);
+    }
+    return basePath;
+}
+export const findBasePathConflict = (routes, basePath) => basePath
+    ? routes.find((route) => route === basePath || route.startsWith(`${basePath}/`))
+    : undefined;
+export const prefixNextAssetPaths = (source, basePath) => source.replace(CHUNK_BASE_PATH_PATTERN, (_match, quote) => `${quote}${basePath}/_next/`);
+export const prefixNextStaticPathsInPayload = (payload, basePath) => payload.replace(NEXT_STATIC_IN_PAYLOAD_PATTERN, `"${basePath}/_next/static/`);
+export const prefixNextStaticPaths = (html, basePath) => html.replace(NEXT_STATIC_IN_HTML_PATTERN, `$1"${basePath}/_next/static/`);
+export async function applyBasePathToExport(exportDir, basePath) {
+    const nextStaticDir = path.join(exportDir, '_next', 'static');
+    if (!basePath || !(await fse.pathExists(nextStaticDir)))
+        return;
+    for await (const file of walkFiles(exportDir)) {
+        if (file.endsWith('.html') || path.basename(file) === 'index.txt') {
+            const source = await fse.readFile(file, 'utf8');
+            const patched = file.endsWith('.html')
+                ? prefixNextStaticPaths(source, basePath)
+                : prefixNextStaticPathsInPayload(source, basePath);
+            if (patched !== source)
+                await fse.writeFile(file, patched, 'utf8');
+            continue;
+        }
+        if (!file.startsWith(nextStaticDir + path.sep) || !file.endsWith('.js'))
+            continue;
+        const source = await fse.readFile(file, 'utf8');
+        const patched = prefixNextAssetPaths(source, basePath);
+        if (patched !== source)
+            await fse.writeFile(file, patched, 'utf8');
+    }
+}

package/dist/local-preview/export-llms.d.ts

@@ -1 +1 @@
-export declare function generateExportLlmsTxt(docsConfig: unknown, generatedNav: unknown, routes: string[]): string;
+export declare function generateExportLlmsTxt(docsConfig: unknown, generatedNav: unknown, routes: string[], basePath?: string): string;

package/dist/local-preview/export-llms.js

@@ -24,7 +24,7 @@ function collectPages(entry, pages) {
     }
 }
 const escapeLinkText = (text) => text.replace(/([[\]])/g, '\\$1');
-export function generateExportLlmsTxt(docsConfig, generatedNav, routes) {
+export function generateExportLlmsTxt(docsConfig, generatedNav, routes, basePath = '') {
     const config = isRecord(docsConfig) ? docsConfig : {};
     const name = getString(config, 'name') ?? 'Documentation';
     const description = getString(config, 'description');
@@ -34,6 +34,6 @@ export function generateExportLlmsTxt(docsConfig, generatedNav, routes) {
     const exportedRoutes = new Set(routes);
     const lines = [...pages.values()]
         .filter((page) => exportedRoutes.has(page.href))
-        .map((page) => `- [${escapeLinkText(page.title)}](${page.href})${page.description ? `: ${page.description}` : ''}\n`);
+        .map((page) => `- [${escapeLinkText(page.title)}](${basePath}${page.href})${page.description ? `: ${page.description}` : ''}\n`);
     return header + lines.join('');
 }

package/dist/local-preview/export.d.ts

@@ -1,5 +1,6 @@
 import { ArgumentsCamelCase } from 'yargs';
+export declare const withIndexRouteAliases: (routes: string[]) => string[];
 export declare function generatePages(baseUrl: string, routes: string[], outputDir: string, rootRoute?: string): Promise<number>;
 export declare function writeStaticUserInfo(tmpDir: string, groups: string[] | undefined): Promise<void>;
-export declare function writeLlmsTxt(tmpDir: string, routes: string[]): Promise<void>;
+export declare function writeLlmsTxt(tmpDir: string, routes: string[], basePath?: string): Promise<void>;
 export declare const exportSite: (argv: ArgumentsCamelCase) => Promise<void>;

package/dist/local-preview/export.js

@@ -13,6 +13,7 @@ import { CLIENT_PATH, CMD_EXEC_PATH, VERSION_PATH, NEXT_PUBLIC_PATH, NEXT_PROPS_
 import { addLog, clearLogs } from '../logging-state.js';
 import { ErrorLog, SpinnerLog, SuccessLog, WarningLog } from '../logs.js';
 import { localizeAssets } from './export-assets.js';
+import { applyBasePathToExport, findBasePathConflict, normalizeExportBasePath, } from './export-base-path.js';
 import { generateExportLlmsTxt } from './export-llms.js';
 import { getGroupFilteredRoutes } from './getGroupFilteredRoutes.js';
 import { setupNext } from './setupNext.js';
@@ -37,6 +38,10 @@ function prepareRoutesForExport(routes, groups) {
         rootRoute: firstAccessibleRoute,
     };
 }
+const INDEX_SUFFIX = '/index';
+export const withIndexRouteAliases = (routes) => [
+    ...new Set(routes.flatMap((route) => route.endsWith(INDEX_SUFFIX) ? [route, route.slice(0, -INDEX_SUFFIX.length) || '/'] : [route])),
+];
 async function withExportConsoleSilenced(task) {
     const originalConsole = {
         log: console.log,
@@ -122,9 +127,9 @@ export async function generatePages(baseUrl, routes, outputDir, rootRoute) {
     await Promise.all(Array.from({ length: Math.min(CONCURRENCY, routes.length) }, () => worker()));
     return failedPageCount;
 }
-async function startServer() {
+async function startServer(basePath) {
     const app = express();
-    const requestHandler = await setupNext();
+    const requestHandler = await setupNext(basePath ? { assetPrefix: basePath } : undefined);
     app.use('/', express.static(NEXT_PUBLIC_PATH));
     app.all('*', (req, res) => requestHandler(req, res));
     const server = createServer(app);
@@ -148,7 +153,7 @@ export async function writeStaticUserInfo(tmpDir, groups) {
         user: { groups },
     });
 }
-async function bundleStaticAssets(tmpDir, groups) {
+async function bundleStaticAssets(tmpDir, groups, basePath) {
     const nextStaticSrc = path.join(CLIENT_PATH, '.next', 'static');
     if (await pathExists(nextStaticSrc)) {
         await fse.copy(nextStaticSrc, path.join(tmpDir, '_next', 'static'));
@@ -162,12 +167,13 @@ async function bundleStaticAssets(tmpDir, groups) {
         }
     }
     await writeStaticUserInfo(tmpDir, groups);
-    await fse.copy(path.join(EXPORT_SCRIPTS_DIR, 'serve.js'), path.join(tmpDir, 'serve.js'));
+    const serveScript = await fse.readFile(path.join(EXPORT_SCRIPTS_DIR, 'serve.js'), 'utf8');
+    await fse.writeFile(path.join(tmpDir, 'serve.js'), serveScript.replace("const BASE_PATH = '';", `const BASE_PATH = ${JSON.stringify(basePath)};`));
     await fse.copy(path.join(EXPORT_SCRIPTS_DIR, 'README.md'), path.join(tmpDir, 'README.md'));
     await fse.copy(path.join(EXPORT_SCRIPTS_DIR, 'start-docs.sh'), path.join(tmpDir, 'Start Docs.command'));
     await fse.copy(path.join(EXPORT_SCRIPTS_DIR, 'start-docs.bat'), path.join(tmpDir, 'Start Docs.bat'));
 }
-export async function writeLlmsTxt(tmpDir, routes) {
+export async function writeLlmsTxt(tmpDir, routes, basePath = '') {
     const llmsTxtPath = path.join(tmpDir, 'llms.txt');
     if (await pathExists(llmsTxtPath))
         return;
@@ -175,16 +181,17 @@ export async function writeLlmsTxt(tmpDir, routes) {
         fse.readJson(path.join(NEXT_PROPS_PATH, 'docs.json')).catch(() => undefined),
         fse.readJson(path.join(NEXT_PROPS_PATH, 'generatedDocsNav.json')).catch(() => undefined),
     ]);
-    await fse.writeFile(llmsTxtPath, generateExportLlmsTxt(docsConfig, generatedNav, routes), 'utf8');
+    await fse.writeFile(llmsTxtPath, generateExportLlmsTxt(docsConfig, generatedNav, routes, basePath), 'utf8');
 }
 async function closeServer(server) {
     await new Promise((resolve) => {
         server.close(() => resolve());
     });
 }
-async function generateExportArchive(routes, outputPath, groups) {
-    const { server, port } = await startServer();
-    const { routes: routesToGenerate, rootRoute } = prepareRoutesForExport(routes, groups);
+async function generateExportArchive(routes, outputPath, groups, basePath) {
+    const { server, port } = await startServer(basePath);
+    const { routes: preparedRoutes, rootRoute } = prepareRoutesForExport(routes, groups);
+    const routesToGenerate = withIndexRouteAliases(preparedRoutes);
     let tmpDir;
     try {
         clearLogs();
@@ -198,8 +205,9 @@ async function generateExportArchive(routes, outputPath, groups) {
             throw new Error(`failed to export: ${failedPageCount} page(s) could not be generated.`);
         }
         addLog(_jsx(SpinnerLog, { message: "collecting static assets..." }));
-        await bundleStaticAssets(exportDir, groups);
-        await writeLlmsTxt(exportDir, routes);
+        await bundleStaticAssets(exportDir, groups, basePath);
+        await applyBasePathToExport(exportDir, basePath);
+        await writeLlmsTxt(exportDir, routes, basePath);
         addLog(_jsx(SpinnerLog, { message: "bundling external assets..." }));
         const { failed } = await localizeAssets(exportDir);
         addLog(_jsx(SpinnerLog, { message: "creating zip archive..." }));
@@ -225,6 +233,13 @@ export const exportSite = async (argv) => {
     const clientVersion = argv['client-version'];
     const localClientVersion = argv['local-client-version'];
     const groups = argv.groups;
+    let basePath = '';
+    try {
+        basePath = normalizeExportBasePath(argv.basePath);
+    }
+    catch (err) {
+        await fatal(err instanceof Error ? err.message : 'invalid base path');
+    }
     const cliVersion = argv.cliVersion;
     const disableOpenApi = argv.disableOpenapi;
     const outputPath = path.resolve(argv.output);
@@ -268,10 +283,14 @@ export const exportSite = async (argv) => {
     catch (err) {
         await fatal(err instanceof Error && err.message ? err.message : 'failed to collect routes');
     }
+    const conflictingRoute = findBasePathConflict(routes, basePath);
+    if (conflictingRoute) {
+        await fatal(`--base-path ${basePath} conflicts with the page ${conflictingRoute}. Pages can't start with the base path, so pick a different one.`);
+    }
     addLog(_jsx(SpinnerLog, { message: "starting local server..." }));
-    process.env.MINT_EXPORT = JSON.stringify({ groups });
+    process.env.MINT_EXPORT = JSON.stringify({ groups, basePath: basePath || undefined });
     try {
-        await generateExportArchive(routes, outputPath, groups);
+        await generateExportArchive(routes, outputPath, groups, basePath);
     }
     catch (err) {
         await fatal(err instanceof Error && err.message ? err.message : 'export failed');

package/dist/local-preview/setupNext.d.ts

@@ -19,4 +19,6 @@
  *
  * @returns the request handler provided by next.js
  */
-export declare const setupNext: () => Promise<any>;
+export declare const setupNext: ({ assetPrefix }?: {
+    assetPrefix?: string;
+}) => Promise<any>;

package/dist/local-preview/setupNext.js

@@ -22,7 +22,7 @@ import { CLIENT_PATH, NEXT_CONFIG_PATH, NEXT_ROUTER_SERVER_PATH, NEXT_SIDE_EFFEC
  *
  * @returns the request handler provided by next.js
  */
-export const setupNext = async () => {
+export const setupNext = async ({ assetPrefix } = {}) => {
     const hostname = process.env.HOSTNAME || 'localhost';
     let config;
     try {
@@ -38,7 +38,7 @@ export const setupNext = async () => {
         }
         throw err;
     }
-    process.env.__NEXT_PRIVATE_STANDALONE_CONFIG = JSON.stringify(config);
+    process.env.__NEXT_PRIVATE_STANDALONE_CONFIG = JSON.stringify(assetPrefix === undefined ? config : { ...config, assetPrefix });
     // The server.js provided by next.js's standalone build does a similar import of this file.
     // Not sure what side effects are being created, but want to change as little as possible.
     // Also, Windows requires us to use `pathToFileURL` (see #899)