@apimatic/cli 2.0.0-beta.4 → 2.0.0-beta.5

package/oclif.manifest.json

@@ -118,14 +118,20 @@
     "api:validate": {
       "aliases": [],
       "args": {},
-      "description": "Validate your API specification to ensure it adheres to syntactic and semantic standards.",
+      "description": "Validate the API specification in your 'src/spec' directory, or the one --file or --url points to, to ensure it adheres to syntactic and semantic standards.",
       "examples": [
+        "\u001b[94mapimatic\u001b[39m \u001b[2mapi\u001b[22m \u001b[2mvalidate\u001b[22m",
+        "\u001b[94mapimatic\u001b[39m \u001b[2mapi\u001b[22m \u001b[2mvalidate\u001b[22m \u001b[32m--input\u001b[39m=\u001b[2m./\u001b[22m",
         "\u001b[94mapimatic\u001b[39m \u001b[2mapi\u001b[22m \u001b[2mvalidate\u001b[22m \u001b[32m--file\u001b[39m=\u001b[2m./specs/sample.json\u001b[22m",
         "\u001b[94mapimatic\u001b[39m \u001b[2mapi\u001b[22m \u001b[2mvalidate\u001b[22m \u001b[32m--url\u001b[39m=\u001b[2m\"https://petstore.swagger.io/v2/swagger.json\"\u001b[22m"
       ],
       "flags": {
         "file": {
           "description": "Path to the API specification file to validate",
+          "exclusive": [
+            "url",
+            "input"
+          ],
           "name": "file",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -133,11 +139,23 @@
         },
         "url": {
           "description": "URL to the API specification file to validate (publicly accessible)",
+          "exclusive": [
+            "file",
+            "input"
+          ],
           "name": "url",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
+        "input": {
+          "char": "i",
+          "description": "[default: ./] path to the parent directory containing the 'src' directory, which includes API specifications and configuration files.",
+          "name": "input",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "auth-key": {
           "char": "k",
           "description": "override current authentication state with an authentication key.",
@@ -252,22 +270,15 @@
         "status.js"
       ]
     },
-    "portal:generate": {
+    "plugin:generate": {
       "aliases": [],
       "args": {},
-      "description": "Builds a documentation portal from the OpenAPI documents and Markdown pages in your 'src' directory.\n\nThe portal is built on your machine and written as static files you can host anywhere. Configure it with 'src/apimatic.json', whose 'languages' block gives the portal a page for each SDK language, and whose 'plugin' block, or a 'pluginUrl' in its 'portal' block for a plugin hosted elsewhere, a page for the context plugin.",
+      "description": "Generate a context plugin that teaches an AI coding assistant how to use your SDKs. Requires an input directory containing a `src` directory with your API specification — `apimatic.json` is created if it is not there. It asks for the plugin's name on the first run, and for its languages only when `apimatic.json` records none (`sdk publish` records them). Later runs read both from `apimatic.json` without asking.",
       "examples": [
-        "\u001b[94mapimatic\u001b[39m \u001b[2mportal\u001b[22m \u001b[2mgenerate\u001b[22m",
-        "\u001b[94mapimatic\u001b[39m \u001b[2mportal\u001b[22m \u001b[2mgenerate\u001b[22m \u001b[32m--input\u001b[39m=\u001b[2m./\u001b[22m \u001b[32m--destination\u001b[39m=\u001b[2m./portal\u001b[22m",
-        "\u001b[94mapimatic\u001b[39m \u001b[2mportal\u001b[22m \u001b[2mgenerate\u001b[22m \u001b[32m--zip\u001b[39m"
+        "\u001b[94mapimatic\u001b[39m \u001b[2mplugin\u001b[22m \u001b[2mgenerate\u001b[22m",
+        "\u001b[94mapimatic\u001b[39m \u001b[2mplugin\u001b[22m \u001b[2mgenerate\u001b[22m \u001b[32m--input\u001b[39m=\u001b[2m\"./\"\u001b[22m \u001b[32m--destination\u001b[39m=\u001b[2m\"./plugin\"\u001b[22m"
       ],
       "flags": {
-        "zip": {
-          "description": "write the generated portal as a .zip archive.",
-          "name": "zip",
-          "allowNo": false,
-          "type": "boolean"
-        },
         "input": {
           "char": "i",
           "description": "[default: ./] path to the parent directory containing the 'src' directory, which includes API specifications and configuration files.",
@@ -278,7 +289,7 @@
         },
         "destination": {
           "char": "d",
-          "description": "[default: <input>/portal] path where the portal will be generated.",
+          "description": "[default: <input>/plugin] path where the plugin will be generated.",
           "name": "destination",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -302,48 +313,31 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "portal:generate",
+      "id": "plugin:generate",
       "pluginAlias": "@apimatic/cli",
       "pluginName": "@apimatic/cli",
       "pluginType": "core",
       "strict": true,
-      "summary": "Generate a static API Documentation Portal.",
+      "summary": "Generate a context plugin for your SDKs.",
       "enableJsonFlag": false,
-      "cmdTxt": "\u001b[94mapimatic\u001b[39m \u001b[2mportal\u001b[22m \u001b[2mgenerate\u001b[22m",
+      "cmdTxt": "\u001b[94mapimatic\u001b[39m \u001b[2mplugin\u001b[22m \u001b[2mgenerate\u001b[22m",
       "isESM": true,
       "relativePath": [
         "lib",
         "commands",
-        "portal",
+        "plugin",
         "generate.js"
       ]
     },
-    "portal:serve": {
+    "plugin:publish": {
       "aliases": [],
       "args": {},
-      "description": "Serves the portal described by 'src/apimatic.json' from your machine, reloading the browser as you edit the Markdown pages in 'src/content', reorder them in a 'nav.json', or change the 'portal', 'languages' or 'plugin' block of 'apimatic.json'.\n\nAdding a language or a 'plugin' block, adding or removing a page in 'src/content', creating 'src/static', or changing which documents are in 'src/spec', needs the preview restarted.\n\nNothing is written to disk; run 'apimatic portal generate' to produce the static files.",
+      "description": "Print the commands that publish a generated context plugin to a GitHub repository. The commands are printed for you to run — this command never touches your repository.",
       "examples": [
-        "\u001b[94mapimatic\u001b[39m \u001b[2mportal\u001b[22m \u001b[2mserve\u001b[22m",
-        "\u001b[94mapimatic\u001b[39m \u001b[2mportal\u001b[22m \u001b[2mserve\u001b[22m \u001b[32m--input\u001b[39m=\u001b[2m./\u001b[22m \u001b[32m--port\u001b[39m=\u001b[2m23513\u001b[22m \u001b[32m--open\u001b[39m"
+        "\u001b[94mapimatic\u001b[39m \u001b[2mplugin\u001b[22m \u001b[2mpublish\u001b[22m",
+        "\u001b[94mapimatic\u001b[39m \u001b[2mplugin\u001b[22m \u001b[2mpublish\u001b[22m \u001b[32m--input\u001b[39m=\u001b[2m\"./\"\u001b[22m \u001b[32m--destination\u001b[39m=\u001b[2m\"./plugin\"\u001b[22m"
       ],
       "flags": {
-        "port": {
-          "char": "p",
-          "description": "port to serve the portal on.",
-          "name": "port",
-          "default": 23513,
-          "hasDynamicHelp": false,
-          "helpValue": "23513",
-          "multiple": false,
-          "type": "option"
-        },
-        "open": {
-          "char": "o",
-          "description": "open the portal in the default browser.",
-          "name": "open",
-          "allowNo": false,
-          "type": "boolean"
-        },
         "input": {
           "char": "i",
           "description": "[default: ./] path to the parent directory containing the 'src' directory, which includes API specifications and configuration files.",
@@ -352,10 +346,10 @@
           "multiple": false,
           "type": "option"
         },
-        "auth-key": {
-          "char": "k",
-          "description": "override current authentication state with an authentication key.",
-          "name": "auth-key",
+        "destination": {
+          "char": "d",
+          "description": "[default: <input>/plugin] path where the plugin was generated.",
+          "name": "destination",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -363,31 +357,38 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "portal:serve",
+      "id": "plugin:publish",
       "pluginAlias": "@apimatic/cli",
       "pluginName": "@apimatic/cli",
       "pluginType": "core",
       "strict": true,
-      "summary": "Preview your API Documentation Portal with live reload.",
+      "summary": "Print the git commands for publishing your context plugin to GitHub.",
       "enableJsonFlag": false,
-      "cmdTxt": "\u001b[94mapimatic\u001b[39m \u001b[2mportal\u001b[22m \u001b[2mserve\u001b[22m",
+      "cmdTxt": "\u001b[94mapimatic\u001b[39m \u001b[2mplugin\u001b[22m \u001b[2mpublish\u001b[22m",
       "isESM": true,
       "relativePath": [
         "lib",
         "commands",
-        "portal",
-        "serve.js"
+        "plugin",
+        "publish.js"
       ]
     },
-    "plugin:generate": {
+    "portal:generate": {
       "aliases": [],
       "args": {},
-      "description": "Generate a context plugin that teaches an AI coding assistant how to use your SDKs. Requires an input directory containing a `src` directory with your API specification — `apimatic.json` is created if it is not there. It asks for the plugin's name on the first run, and for its languages only when `apimatic.json` records none (`sdk publish` records them). Later runs read both from `apimatic.json` without asking.",
+      "description": "Builds a documentation portal from the OpenAPI documents and Markdown pages in your 'src' directory.\n\nThe portal is built on your machine and written as static files for any static host, served at its root or, when 'portal.site.url' has a path such as 'https://example.com/docs', at that path. Configure it with 'src/apimatic.json', whose 'languages' block gives the portal a page for each SDK language, and whose 'plugin' block, or a 'pluginUrl' in its 'portal' block for a plugin hosted elsewhere, a page for the context plugin.",
       "examples": [
-        "\u001b[94mapimatic\u001b[39m \u001b[2mplugin\u001b[22m \u001b[2mgenerate\u001b[22m",
-        "\u001b[94mapimatic\u001b[39m \u001b[2mplugin\u001b[22m \u001b[2mgenerate\u001b[22m \u001b[32m--input\u001b[39m=\u001b[2m\"./\"\u001b[22m \u001b[32m--destination\u001b[39m=\u001b[2m\"./plugin\"\u001b[22m"
+        "\u001b[94mapimatic\u001b[39m \u001b[2mportal\u001b[22m \u001b[2mgenerate\u001b[22m",
+        "\u001b[94mapimatic\u001b[39m \u001b[2mportal\u001b[22m \u001b[2mgenerate\u001b[22m \u001b[32m--input\u001b[39m=\u001b[2m./\u001b[22m \u001b[32m--destination\u001b[39m=\u001b[2m./portal\u001b[22m",
+        "\u001b[94mapimatic\u001b[39m \u001b[2mportal\u001b[22m \u001b[2mgenerate\u001b[22m \u001b[32m--zip\u001b[39m"
       ],
       "flags": {
+        "zip": {
+          "description": "write the generated portal as a .zip archive.",
+          "name": "zip",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "input": {
           "char": "i",
           "description": "[default: ./] path to the parent directory containing the 'src' directory, which includes API specifications and configuration files.",
@@ -398,7 +399,7 @@
         },
         "destination": {
           "char": "d",
-          "description": "[default: <input>/plugin] path where the plugin will be generated.",
+          "description": "[default: <input>/portal] path where the portal will be generated.",
           "name": "destination",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -422,31 +423,48 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "plugin:generate",
+      "id": "portal:generate",
       "pluginAlias": "@apimatic/cli",
       "pluginName": "@apimatic/cli",
       "pluginType": "core",
       "strict": true,
-      "summary": "Generate a context plugin for your SDKs.",
+      "summary": "Generate a static API Documentation Portal.",
       "enableJsonFlag": false,
-      "cmdTxt": "\u001b[94mapimatic\u001b[39m \u001b[2mplugin\u001b[22m \u001b[2mgenerate\u001b[22m",
+      "cmdTxt": "\u001b[94mapimatic\u001b[39m \u001b[2mportal\u001b[22m \u001b[2mgenerate\u001b[22m",
       "isESM": true,
       "relativePath": [
         "lib",
         "commands",
-        "plugin",
+        "portal",
         "generate.js"
       ]
     },
-    "plugin:publish": {
+    "portal:serve": {
       "aliases": [],
       "args": {},
-      "description": "Print the commands that publish a generated context plugin to a GitHub repository. The commands are printed for you to run — this command never touches your repository.",
+      "description": "Serves the portal described by 'src/apimatic.json' from your machine, reloading the browser as you edit the Markdown pages in 'src/content', reorder them in a 'nav.json', or change the 'portal', 'languages' or 'plugin' block of 'apimatic.json'.\n\nAdding a language or a 'plugin' block, adding or removing a page in 'src/content', creating 'src/static', changing which documents are in 'src/spec', or changing the path in 'portal.site.url', needs the preview restarted.\n\nNothing is written to disk; run 'apimatic portal generate' to produce the static files.",
       "examples": [
-        "\u001b[94mapimatic\u001b[39m \u001b[2mplugin\u001b[22m \u001b[2mpublish\u001b[22m",
-        "\u001b[94mapimatic\u001b[39m \u001b[2mplugin\u001b[22m \u001b[2mpublish\u001b[22m \u001b[32m--input\u001b[39m=\u001b[2m\"./\"\u001b[22m \u001b[32m--destination\u001b[39m=\u001b[2m\"./plugin\"\u001b[22m"
+        "\u001b[94mapimatic\u001b[39m \u001b[2mportal\u001b[22m \u001b[2mserve\u001b[22m",
+        "\u001b[94mapimatic\u001b[39m \u001b[2mportal\u001b[22m \u001b[2mserve\u001b[22m \u001b[32m--input\u001b[39m=\u001b[2m./\u001b[22m \u001b[32m--port\u001b[39m=\u001b[2m23513\u001b[22m \u001b[32m--open\u001b[39m"
       ],
       "flags": {
+        "port": {
+          "char": "p",
+          "description": "port to serve the portal on.",
+          "name": "port",
+          "default": 23513,
+          "hasDynamicHelp": false,
+          "helpValue": "23513",
+          "multiple": false,
+          "type": "option"
+        },
+        "open": {
+          "char": "o",
+          "description": "open the portal in the default browser.",
+          "name": "open",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "input": {
           "char": "i",
           "description": "[default: ./] path to the parent directory containing the 'src' directory, which includes API specifications and configuration files.",
@@ -455,10 +473,10 @@
           "multiple": false,
           "type": "option"
         },
-        "destination": {
-          "char": "d",
-          "description": "[default: <input>/plugin] path where the plugin was generated.",
-          "name": "destination",
+        "auth-key": {
+          "char": "k",
+          "description": "override current authentication state with an authentication key.",
+          "name": "auth-key",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -466,20 +484,20 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "plugin:publish",
+      "id": "portal:serve",
       "pluginAlias": "@apimatic/cli",
       "pluginName": "@apimatic/cli",
       "pluginType": "core",
       "strict": true,
-      "summary": "Print the git commands for publishing your context plugin to GitHub.",
+      "summary": "Preview your API Documentation Portal with live reload.",
       "enableJsonFlag": false,
-      "cmdTxt": "\u001b[94mapimatic\u001b[39m \u001b[2mplugin\u001b[22m \u001b[2mpublish\u001b[22m",
+      "cmdTxt": "\u001b[94mapimatic\u001b[39m \u001b[2mportal\u001b[22m \u001b[2mserve\u001b[22m",
       "isESM": true,
       "relativePath": [
         "lib",
         "commands",
-        "plugin",
-        "publish.js"
+        "portal",
+        "serve.js"
       ]
     },
     "sdk:generate": {
@@ -748,5 +766,5 @@
       ]
     }
   },
-  "version": "2.0.0-beta.4"
+  "version": "2.0.0-beta.5"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@apimatic/cli",
     "description": "The official CLI for APIMatic.",
-    "version": "2.0.0-beta.4",
+    "version": "2.0.0-beta.5",
     "author": "APIMatic",
     "bin": {
         "apimatic": "./bin/run.js"

package/portal-template/dependency-directories.ts

@@ -1,54 +1,45 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-/**
- * The installations the project's dependencies resolve to. Vite serves a file from outside
- * its allow list only once the module importing it has been transformed, an order a browser
- * cache skips: Safari, holding the importer from an earlier preview on the same port, asked
- * for the TanStack dev entry first and was refused, leaving a blank page. Naming where the
- * links really lead keeps every dependency served whatever the browser asks for first.
- */
-export function dependencyDirectories(projectDirectory: string): string[] {
-  const directories = new Set<string>();
-  for (const packagePath of packagePaths(path.join(projectDirectory, 'node_modules'))) {
-    const installed = realPath(packagePath);
-    if (installed !== undefined) {
-      directories.add(outermostNodeModules(installed));
+// Safari runs a cached entry before its importer is transformed (apimatic-io#2287).
+export function dependencyDirectories(portalProjectDirectory: string): string[] {
+  const modules = path.join(portalProjectDirectory, 'node_modules');
+  return narrowest(
+    packageNames(modules)
+      .filter((name) => fs.lstatSync(path.join(modules, name)).isSymbolicLink())
+      .map((name) => holdingDirectory(fs.realpathSync.native(path.join(modules, name)), name))
+  );
+}
+
+/** The one directory holding them all: the CLI's `node_modules` under npm, the store under pnpm. Each alone when only the disk's root would. */
+function narrowest(directories: string[]): string[] {
+  let common: string | undefined = directories[0];
+  for (const directory of directories.slice(1)) {
+    while (common !== undefined && !isWithin(common, directory)) {
+      common = isRoot(path.dirname(common)) ? undefined : path.dirname(common);
     }
   }
-  return [...directories];
+  return common === undefined ? directories : [common];
 }
 
-function packagePaths(modules: string): string[] {
-  return entries(modules).flatMap((name) => {
-    const packagePath = path.join(modules, name);
-    return name.startsWith('@') ? entries(packagePath).map((scoped) => path.join(packagePath, scoped)) : [packagePath];
-  });
+function packageNames(modules: string): string[] {
+  return fs
+    .readdirSync(modules)
+    .flatMap((name) =>
+      name.startsWith('@') ? fs.readdirSync(path.join(modules, name)).map((scoped) => `${name}/${scoped}`) : [name]
+    );
 }
 
-function entries(directory: string): string[] {
-  try {
-    return fs.readdirSync(directory).filter((name) => !name.startsWith('.'));
-  } catch {
-    return [];
-  }
+/** Where a package and the dependencies installed beside it sit, its scope included. */
+function holdingDirectory(packageDirectory: string, name: string): string {
+  return path.resolve(packageDirectory, ...name.split('/').map(() => '..'));
 }
 
-function realPath(target: string): string | undefined {
-  try {
-    return fs.realpathSync(target);
-  } catch {
-    return undefined;
-  }
+function isRoot(directory: string): boolean {
+  return path.dirname(directory) === directory;
 }
 
-/** The widest installation around a package: under pnpm the whole store sits inside one `node_modules` too. */
-function outermostNodeModules(packageDirectory: string): string {
-  let found = packageDirectory;
-  for (let parent = path.dirname(packageDirectory); parent !== path.dirname(parent); parent = path.dirname(parent)) {
-    if (path.basename(parent) === 'node_modules') {
-      found = parent;
-    }
-  }
-  return found;
+function isWithin(directory: string, target: string): boolean {
+  const relative = path.relative(directory, target);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
 }

package/portal-template/downloads.ts

@@ -2,6 +2,7 @@ import { createReadStream } from 'node:fs';
 import { cp, readdir } from 'node:fs/promises';
 import path from 'node:path';
 import type { Plugin } from 'vite';
+import { withBasePath } from './src/lib/base-path';
 
 /** Where the site offers the downloads: a name the user's static directory is not expected to use. */
 export const DOWNLOADS_ADDRESS = '__downloads';
@@ -15,7 +16,8 @@ export function downloads(directory: string | null): Plugin {
     name: 'apimatic:downloads',
     async configureServer(server) {
       if (directory === null) return;
-      const files = await filesByAddress(directory);
+      // Under the base only, as once built: this runs ahead of Vite's own base handling.
+      const files = await filesByAddress(directory, server.config.base);
       server.middlewares.use((request, response, next) => {
         const file = files.get(decodeURIComponent(new URL(request.url ?? '/', 'http://localhost').pathname));
         if (file === undefined) return next();
@@ -30,12 +32,13 @@ export function downloads(directory: string | null): Plugin {
   };
 }
 
-async function filesByAddress(directory: string): Promise<Map<string, string>> {
+async function filesByAddress(directory: string, base: string): Promise<Map<string, string>> {
   const entries = await readdir(directory, { recursive: true, withFileTypes: true });
   const files = new Map<string, string>();
   for (const entry of entries.filter((candidate) => candidate.isFile())) {
     const file = path.join(entry.parentPath, entry.name);
-    files.set(`/${DOWNLOADS_ADDRESS}/${path.relative(directory, file).split(path.sep).join('/')}`, file);
+    const address = `/${DOWNLOADS_ADDRESS}/${path.relative(directory, file).split(path.sep).join('/')}`;
+    files.set(withBasePath(address, base), file);
   }
   return files;
 }

package/portal-template/portal-config.ts

@@ -3,6 +3,8 @@ import type { Portal } from './src/lib/portal-types';
 
 /** Written by the CLI next to this file before every build or dev-server start. */
 export interface BuildPaths {
+  /** Vite's `base`, the path of the site address that every page and asset is served under: `/`, or `/docs/`. */
+  base: string;
   /** Section slug -> absolute path of an OpenAPI document. */
   specs: Record<string, string>;
   /** Absolute path of the code samples, keyed by path then method; null when there are none. */

package/portal-template/prerender-pages.ts

@@ -2,6 +2,8 @@ import { readdir } from 'node:fs/promises';
 import path from 'node:path';
 import { getSlugs, loader } from 'fumadocs-core/source';
 import type { BuildPaths } from './portal-config.ts';
+import { withBasePath } from './src/lib/base-path';
+import { oauthCallbackPath } from './src/lib/oauth-callback';
 import { openApiSection } from './src/lib/openapi-section.server';
 
 const CONTENT_EXTENSIONS = new Set(['.md', '.mdx']);
@@ -19,7 +21,8 @@ export async function prerenderPages(config: BuildPaths, siteUrl: string | null)
   // Both need absolute URLs, so they are only emitted for a portal that declares its address.
   if (siteUrl) {
     urls.add('/sitemap.xml');
-    urls.add('/robots.txt');
+    // Crawlers read it only at the root of a host.
+    if (config.base === '/') urls.add('/robots.txt');
   }
 
   for (const url of await contentUrls(config.contentDir)) urls.add(url);
@@ -35,8 +38,11 @@ export async function prerenderPages(config: BuildPaths, siteUrl: string | null)
     if (url === '/') urls.add('/index.md');
     else if (!/\.(txt|xml|json)$/.test(url)) urls.add(`${url}.md`);
   }
+  // After the twins, since it is no page of the portal's and has none.
+  urls.add(oauthCallbackPath);
 
-  return [...urls].map((url) => ({ path: url }));
+  // Served paths, or TanStack takes a page starting like the base (`/api/…` under `/api`) as already under it.
+  return [...urls].map((url) => ({ path: withBasePath(url, config.base) }));
 }
 
 async function contentUrls(contentDir: string): Promise<string[]> {

package/portal-template/src/components/api-markdown.tsx

@@ -0,0 +1,32 @@
+import { createMarkdownRenderer } from 'fumadocs-core/content/md';
+import { remarkGfm } from 'fumadocs-core/mdx-plugins/remark-gfm';
+import { DynamicCodeBlock } from 'fumadocs-ui/components/dynamic-codeblock';
+import defaultMdxComponents from 'fumadocs-ui/mdx';
+import { Children, type ComponentProps, type ReactElement } from 'react';
+import { withBasePath } from '@/lib/base-path';
+import { languageOf } from '@/lib/code-titles';
+
+const { Markdown } = createMarkdownRenderer({ remarkPlugins: [remarkGfm] });
+
+const components = {
+  ...defaultMdxComponents,
+  // A root-relative address names a file in the static directory, which the host serves under the base.
+  img: ({ src, ...props }: ComponentProps<'img'>) => (
+    <img {...props} src={typeof src === 'string' && /^\/(?!\/)/.test(src) ? withBasePath(src) : src} />
+  ),
+  pre: CodeBlock
+};
+
+/** The specification's descriptions as Fumadocs renders them, but for its `img: undefined`, which fails the page. */
+export function ApiMarkdown({ md }: { md: string }) {
+  return <Markdown components={components}>{md}</Markdown>;
+}
+
+/** A fenced block, highlighted as Fumadocs highlights one in a description. */
+function CodeBlock({ children }: ComponentProps<'pre'>) {
+  const code = Children.only(children) as ReactElement<{ className?: string; children?: unknown }>;
+  const text = code.props.children;
+  if (typeof text !== 'string') return null;
+  const language = languageOf(code.props.className?.split(' ') ?? []) ?? 'text';
+  return <DynamicCodeBlock lang={language} code={text.trimEnd()} />;
+}

package/portal-template/src/components/api-page.tsx

@@ -1,5 +1,8 @@
 import { createOpenAPIPage } from 'fumadocs-openapi/ui';
+import { withBasePath } from '@/lib/base-path';
 import { mediaAdapters } from '@/lib/media-adapters';
+import { oauthCallbackPath } from '@/lib/oauth-callback';
+import { ApiMarkdown } from './api-markdown';
 import { renderExampleLayout } from './example-layout';
 import { codeUsages, renderUsageTabs } from './usage-tabs';
 
@@ -7,5 +10,9 @@ export const OpenAPIPage = createOpenAPIPage({
   codeUsages,
   generateTypeScriptDefinitions: false,
   content: { renderAPIExampleLayout: renderExampleLayout, renderAPIExampleUsageTabs: renderUsageTabs },
-  mediaAdapters
+  components: { Markdown: ApiMarkdown },
+  mediaAdapters,
+  oauthRedirectUrl: withBasePath(oauthCallbackPath),
+  // Portals under paths of one host keep their playground's saved values apart; at the root the keys stay Fumadocs' own.
+  storageKeyPrefix: `fumadocs-openapi-${withBasePath('/').slice(1)}`
 });

package/portal-template/src/components/authorization-failure.tsx

@@ -0,0 +1,63 @@
+import { buttonVariants } from 'fumadocs-ui/components/ui/button';
+import type { ReactNode } from 'react';
+import { withBasePath } from '@/lib/base-path';
+import type { OAuthCallbackFailure } from '@/lib/oauth-callback';
+
+/** What the OAuth callback says when it stays, instead of sending the browser back to the endpoint. */
+export function AuthorizationFailure({ failure }: { failure: OAuthCallbackFailure }) {
+  switch (failure.kind) {
+    case 'providerError':
+      // Ended, not refused: `server_error` and `temporarily_unavailable` arrive here too.
+      return (
+        <>
+          <Explanation>
+            The provider ended the authorization with <code>{failure.error}</code>
+            {failure.description === null ? '.' : `: ${failure.description}`}
+          </Explanation>
+          <Action href={failure.page}>Back to the endpoint</Action>
+        </>
+      );
+    case 'notStarted':
+      return (
+        <>
+          <Explanation>
+            This page completes an authorization started from an endpoint's playground, and none was started in this
+            browser. Open the endpoint's page and authorize from there.
+          </Explanation>
+          <HomeAction />
+        </>
+      );
+    case 'unknownPage':
+      return (
+        <>
+          <Explanation>
+            The authorization was not started from a page of this site, so it cannot be completed here. Open the
+            endpoint's page and authorize from there.
+          </Explanation>
+          <HomeAction />
+        </>
+      );
+  }
+}
+
+function Explanation({ children }: { children: ReactNode }) {
+  return (
+    <>
+      <h1 className="text-2xl font-semibold">Authorization could not be completed</h1>
+      <p className="text-fd-muted-foreground max-w-md">{children}</p>
+    </>
+  );
+}
+
+// The page that started the authorization is unknown here, so the home page is the one way back.
+function HomeAction() {
+  return <Action href={withBasePath('/')}>Go to the home page</Action>;
+}
+
+function Action({ href, children }: { href: string; children: ReactNode }) {
+  return (
+    <a href={href} className={buttonVariants({ color: 'primary', className: 'mt-4' })}>
+      {children}
+    </a>
+  );
+}

package/portal-template/src/components/markdown-copy-button.tsx

@@ -12,7 +12,7 @@ const LABELS: Record<CopyState, string> = {
   failed: 'Copy failed'
 };
 
-export function MarkdownCopyButton({ markdownUrl, base }: Readonly<{ markdownUrl: string; base: string }>) {
+export function MarkdownCopyButton({ markdownUrl }: Readonly<{ markdownUrl: string }>) {
   const [state, setState] = useState<CopyState>('idle');
 
   useEffect(() => {
@@ -23,7 +23,7 @@ export function MarkdownCopyButton({ markdownUrl, base }: Readonly<{ markdownUrl
 
   const copy = () => {
     setState('copying');
-    copyMarkdown(markdownUrl, base).then(
+    copyMarkdown(markdownUrl).then(
       () => setState('copied'),
       (error: unknown) => {
         console.error(error);