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

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

@@ -0,0 +1,60 @@
+import { useEffect, useState } from 'react';
+import { buttonVariants } from 'fumadocs-ui/components/ui/button';
+import { Check, Copy, X } from 'lucide-react';
+import { copyMarkdown } from '@/lib/copy-markdown';
+
+type CopyState = 'idle' | 'copying' | 'copied' | 'failed';
+
+const LABELS: Record<CopyState, string> = {
+  idle: 'Copy Markdown',
+  copying: 'Copy Markdown',
+  copied: 'Copied Markdown',
+  failed: 'Copy failed'
+};
+
+export function MarkdownCopyButton({ markdownUrl }: Readonly<{ markdownUrl: string }>) {
+  const [state, setState] = useState<CopyState>('idle');
+
+  useEffect(() => {
+    if (state !== 'copied' && state !== 'failed') return;
+    const timeout = window.setTimeout(() => setState('idle'), 1500);
+    return () => window.clearTimeout(timeout);
+  }, [state]);
+
+  const copy = () => {
+    setState('copying');
+    copyMarkdown(markdownUrl).then(
+      () => setState('copied'),
+      (error: unknown) => {
+        console.error(error);
+        setState('failed');
+      }
+    );
+  };
+
+  return (
+    <>
+      <button
+        type="button"
+        disabled={state === 'copying'}
+        onClick={copy}
+        className={buttonVariants({
+          color: 'secondary',
+          size: 'sm',
+          className: 'gap-2 [&_svg]:size-3.5 [&_svg]:text-fd-muted-foreground'
+        })}
+      >
+        <StateIcon state={state} />
+        {LABELS[state]}
+      </button>
+      {/* A focused button's own text change isn't reliably announced. */}
+      <output className="sr-only">{state === 'copied' || state === 'failed' ? LABELS[state] : ''}</output>
+    </>
+  );
+}
+
+function StateIcon({ state }: Readonly<{ state: CopyState }>) {
+  if (state === 'copied') return <Check />;
+  if (state === 'failed') return <X />;
+  return <Copy />;
+}

package/portal-template/src/components/plugin-install.tsx

@@ -1,22 +1,23 @@
 import { useSyncExternalStore } from 'react';
 import { asMarkdown } from 'fumadocs-core/server';
 import { CommandBlock } from './command-block';
+import { fullAddress } from '@/lib/base-path';
 import { installCommand } from '@/lib/install-command';
 import { portal } from '@/lib/portal';
 
-// The origin never changes while the page is open, so there is nothing to subscribe to.
+// The address never changes while the page is open, so there is nothing to subscribe to.
 const noSubscribe = () => () => {};
 
-/** The prerender cannot know where the portal is hosted, so the browser swaps in its own origin. */
+/** The prerender cannot know where the portal is hosted, so the browser swaps in its own address. */
 export function PluginInstall({ path }: Readonly<{ path: string }>) {
   // Ahead of the hook, which only React may call; either branch is taken in every render of one environment.
   if (asMarkdown()) {
     return <CommandBlock command={installCommand(path, portal.siteUrl)} />;
   }
-  const origin = useSyncExternalStore(
+  const site = useSyncExternalStore(
     noSubscribe,
-    () => window.location.origin,
+    () => fullAddress('/'),
     () => portal.siteUrl
   );
-  return <CommandBlock command={installCommand(path, origin)} />;
+  return <CommandBlock command={installCommand(path, site)} />;
 }

package/portal-template/src/components/sdk-actions.tsx

@@ -2,6 +2,7 @@ import type { ReactNode } from 'react';
 import { asMarkdown } from 'fumadocs-core/server';
 import { buttonVariants } from 'fumadocs-ui/components/ui/button';
 import { Code, Download, Package } from 'lucide-react';
+import { withBasePath } from '@/lib/base-path';
 
 export interface SdkActionsProps {
   download: string;
@@ -22,7 +23,7 @@ export function SdkActions({ download, source, packageUrl, registry }: Readonly<
   // The page's Markdown twin, which the page actions and llms-full.txt hand to an AI assistant.
   if (asMarkdown()) {
     const links = [
-      `[Download SDK](${download})`,
+      `[Download SDK](${withBasePath(download)})`,
       source ? `[View source](${source})` : null,
       packageUrl ? `[View on ${registry}](${packageUrl})` : null
     ];
@@ -64,7 +65,7 @@ interface LinkProps {
 /** A plain link, not a route: the zip is a file the site serves beside its pages. */
 export function DownloadLink({ href, className, children }: Readonly<LinkProps>) {
   return (
-    <a href={href} download className={className}>
+    <a href={withBasePath(href)} download className={className}>
       {children}
     </a>
   );

package/portal-template/src/components/sdk-cards.tsx

@@ -2,6 +2,7 @@ import type { ReactNode } from 'react';
 import Link from 'fumadocs-core/link';
 import { asMarkdown } from 'fumadocs-core/server';
 import { ArrowDownToLine, ArrowRight, ExternalLink as ExternalLinkIcon } from 'lucide-react';
+import { withBasePath } from '@/lib/base-path';
 import { CommandBlock } from './command-block';
 import { LanguageLogo, LogoTile } from './logos';
 import { DownloadLink, ExternalLink, LINK, QUIET_LINK, SdkActions, type SdkActionsProps } from './sdk-actions';
@@ -40,7 +41,7 @@ function LinkContext({ name }: Readonly<{ name: string }>) {
 export function SdkCard({ language, name, page, install, ...actions }: Readonly<SdkCardProps>) {
   if (asMarkdown()) {
     const command = install ? `\`${install}\` · ` : '';
-    return [`- [${name}](${page}): ${command}`, <SdkActions key="actions" {...actions} />];
+    return [`- [${name}](${withBasePath(page)}): ${command}`, <SdkActions key="actions" {...actions} />];
   }
   const { download, source, packageUrl, registry } = actions;
   return (

package/portal-template/src/components/search.tsx

@@ -13,6 +13,8 @@ import {
 import { useDocsSearch } from 'fumadocs-core/search/client';
 import { staticClient } from 'fumadocs-core/search/client/orama-static';
 import { useI18n } from 'fumadocs-ui/contexts/i18n';
+import { useMemo } from 'react';
+import { withBasePath } from '@/lib/base-path';
 
 export default function DefaultSearchDialog(props: SharedProps) {
   const { locale } = useI18n();
@@ -20,10 +22,15 @@ export default function DefaultSearchDialog(props: SharedProps) {
     // Served with an extension so hosts and CDNs give it a JSON content type; without one
     // it went out as application/octet-stream, which some of them attach or refuse.
     client: staticClient({
-      from: '/api/search.json',
+      from: withBasePath('/api/search.json'),
       locale
     })
   });
+  // Served URLs, since the dialog navigates by href (search-navigation.test.ts), memoised so its highlight stays put.
+  const results = useMemo(
+    () => (query.data === 'empty' ? null : query.data?.map((item) => ({ ...item, url: withBasePath(item.url) }))),
+    [query.data]
+  );
 
   return (
     <SearchDialog search={search} onSearchChange={setSearch} isLoading={query.isLoading} {...props}>
@@ -34,7 +41,7 @@ export default function DefaultSearchDialog(props: SharedProps) {
           <SearchDialogInput />
           <SearchDialogClose />
         </SearchDialogHeader>
-        <SearchDialogList items={query.data !== 'empty' ? query.data : null} />
+        <SearchDialogList items={results} />
       </SearchDialogContent>
     </SearchDialog>
   );

package/portal-template/src/lib/base-path.ts

@@ -0,0 +1,14 @@
+/// <reference types="vite/client" />
+
+// Undefined outside Vite, as under the template's unit tests; Fumadocs guards it the same way.
+const BASE = typeof import.meta.env === 'undefined' ? '/' : import.meta.env.BASE_URL;
+
+/** A portal-relative path as the host serves it, under `base`: Vite's own unless one is given. */
+export function withBasePath(path: string, base: string = BASE): string {
+  return `${base.replace(/\/$/, '')}${path}`;
+}
+
+/** A portal-relative path's full address as the browser sees it; the path itself where there is no window. */
+export function fullAddress(path: string): string {
+  return typeof window === 'undefined' ? path : new URL(withBasePath(path), window.location.origin).toString();
+}

package/portal-template/src/lib/code-titles.ts

@@ -27,3 +27,11 @@ export const CODE_BLOCK_TITLES: Readonly<Record<BundledLanguage, string>> = {
   sql: 'SQL',
   tsx: 'TSX'
 };
+
+const LANGUAGE_CLASS = 'language-';
+
+/** The language a fence names, from the class `remark-rehype` gives its `code`. */
+export function languageOf(classes: unknown[]): string | undefined {
+  const languageClass = classes.find((name) => typeof name === 'string' && name.startsWith(LANGUAGE_CLASS));
+  return typeof languageClass === 'string' ? languageClass.slice(LANGUAGE_CLASS.length) : undefined;
+}

package/portal-template/src/lib/copy-markdown.ts

@@ -0,0 +1,14 @@
+import { withBasePath } from './base-path';
+
+export async function copyMarkdown(rootRelativeUrl: string, base?: string): Promise<void> {
+  const url = withBasePath(rootRelativeUrl, base);
+  // Handed over unresolved, so Safari still counts the write as part of the click.
+  const markdown = fetchMarkdown(url);
+  await Promise.all([navigator.clipboard.write([new ClipboardItem({ 'text/plain': markdown })]), markdown]);
+}
+
+async function fetchMarkdown(url: string): Promise<string> {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`Failed to fetch ${url}: ${response.status}`);
+  return response.text();
+}

package/portal-template/src/lib/install-command.ts

@@ -1,13 +1,13 @@
 const ABSOLUTE = /^https?:\/\//i;
 
 // Quoted, so a `&` or a space in the address stays one argument in any shell a reader pastes it into.
-export function installCommand(path: string, origin: string | null): string {
-  return `npx context-plugins install "${installAddress(path, origin)}"`;
+export function installCommand(path: string, site: string | null): string {
+  return `npx context-plugins install "${installAddress(path, site)}"`;
 }
 
-function installAddress(path: string, origin: string | null): string {
-  if (ABSOLUTE.test(path) || origin === null) {
+function installAddress(path: string, site: string | null): string {
+  if (ABSOLUTE.test(path) || site === null) {
     return path;
   }
-  return `${origin.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`;
+  return `${site.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`;
 }

package/portal-template/src/lib/layout.shared.tsx

@@ -1,4 +1,5 @@
 import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
+import { withBasePath } from './base-path';
 import { portal } from './portal';
 
 export function baseOptions(): BaseLayoutProps {
@@ -30,12 +31,13 @@ const LOGO_SIZE = 'h-6 w-auto max-w-none';
 function Logo() {
   const { logo } = portal;
   if (!logo) return null;
-  if (logo.light === logo.dark) return <img src={logo.light} alt="" className={LOGO_SIZE} />;
+  const [light, dark] = [withBasePath(logo.light), withBasePath(logo.dark)];
+  if (light === dark) return <img src={light} alt="" className={LOGO_SIZE} />;
   // Both are in the page and CSS shows one, so the right one is there before any script runs.
   return (
     <>
-      <img src={logo.light} alt="" className={`${LOGO_SIZE} dark:hidden`} />
-      <img src={logo.dark} alt="" className={`hidden ${LOGO_SIZE} dark:block`} />
+      <img src={light} alt="" className={`${LOGO_SIZE} dark:hidden`} />
+      <img src={dark} alt="" className={`hidden ${LOGO_SIZE} dark:block`} />
     </>
   );
 }

package/portal-template/src/lib/llms.server.ts

@@ -1,15 +1,35 @@
+import type * as PageTree from 'fumadocs-core/page-tree';
 import { llms } from 'fumadocs-core/source';
 import { stringify } from 'yaml';
 import { getMDXComponents } from '@/components/mdx';
+import { withBasePath } from './base-path';
 import { operationLabels } from './openapi-labels';
 import { slimOpenAPIPageProps } from './openapi-slim';
-import { source } from './source.server';
+import { type PortalPage, source } from './source.server';
 import { portal } from './portal';
 
-type PortalPage = ReturnType<typeof source.getPages>[number];
 type ReferencePage = Extract<PortalPage, { type: 'openapi' }>;
 
-const index = llms(source);
+// `llms()` links each page by its tree node's URL and has no base of its own; titles are found by `$ref`.
+const index = llms({
+  ...source,
+  getPageTree: (locale?: string) => {
+    const root = source.getPageTree(locale);
+    return { ...root, children: root.children.map(servedNode) };
+  }
+});
+
+function servedNode(node: PageTree.Node): PageTree.Node {
+  if (node.type === 'page') return { ...node, url: withBasePath(node.url) };
+  if (node.type === 'folder') {
+    return {
+      ...node,
+      index: node.index && { ...node.index, url: withBasePath(node.index.url) },
+      children: node.children.map(servedNode)
+    };
+  }
+  return node;
+}
 
 export async function renderPage(page: PortalPage): Promise<string> {
   return await render(page, true);
@@ -34,14 +54,18 @@ export function renderHome(): string {
 }
 
 async function renderContent(page: Exclude<PortalPage, ReferencePage>): Promise<string> {
-  return `# ${page.data.title} (${page.url})\n\n${await page.data.getText('processed', { components: getMDXComponents() })}`;
+  return `# ${page.data.title} (${withBasePath(page.url)})\n\n${await page.data.getText('processed', { components: getMDXComponents() })}`;
 }
 
 /** An operation's page, with the part of its specification that page renders: what an assistant reads best. */
 function renderReference(page: ReferencePage, withSpecification: boolean): string {
   const props = slimOpenAPIPageProps(page.data.getOpenAPIPageProps());
   const endpoints = operationLabels(props, (signature) => `\`${signature}\``);
-  const sections = [`# ${page.data.title} (${page.url})`, endpoints.join('\n'), page.data.description ?? ''];
+  const sections = [
+    `# ${page.data.title} (${withBasePath(page.url)})`,
+    endpoints.join('\n'),
+    page.data.description ?? ''
+  ];
   if (withSpecification) {
     // Its tags and the document's description are the portal's to show, and would come with every operation.
     const { info, tags: _tags, ...document } = props.payload.bundled as Record<string, unknown> & {

package/portal-template/src/lib/oauth-callback.ts

@@ -0,0 +1,63 @@
+/**
+ * The one redirect URI a portal owner registers with their OAuth provider, instead of the
+ * address of every endpoint page that can start an authorization. The CLI keeps the user's
+ * pages off it, in `src/types/portal/content-tree.ts`.
+ */
+export const oauthCallbackPath = '/oauth/callback';
+
+/** The cookie the playground writes before it leaves, naming the page that started the flow. */
+const PAGE_COOKIE_NAME = 'fumadocs-openapi-oauth';
+const PAGE_COOKIE = new RegExp(`(?:^|;\\s*)${PAGE_COOKIE_NAME}=([^;]+)`);
+
+/** What the callback does with the browser that lands on it. */
+export type OAuthCallback =
+  /** Sends it back to the page that started the flow, with the provider's answer still attached. */
+  | { kind: 'return'; url: string }
+  /** Stays, to show the error the provider ended the authorization with, and a link back to that page. */
+  | { kind: 'providerError'; error: string; description: string | null; page: string }
+  /** Stays, since the cookie names no page: no authorization was started in this browser. */
+  | { kind: 'notStarted' }
+  /** Stays, since the cookie names a page on another site, or one that cannot be read. */
+  | { kind: 'unknownPage' };
+
+/** Every outcome but sending the browser on, which leaves the callback before it renders again. */
+export type OAuthCallbackFailure = Exclude<OAuthCallback, { kind: 'return' }>;
+
+/**
+ * The provider answers in the query for the authorization code flow and in the fragment for the
+ * implicit one, an error included. Only an authorization this browser started is answered with
+ * the provider's error: anyone can link here with an `error_description` of their own.
+ */
+export function oauthCallback(cookie: string, location: Pick<Location, 'origin' | 'search' | 'hash'>): OAuthCallback {
+  const value = PAGE_COOKIE.exec(cookie)?.[1];
+  if (value === undefined) return { kind: 'notStarted' };
+
+  let page: URL;
+  try {
+    page = new URL(decodeURIComponent(value), location.origin);
+  } catch {
+    return { kind: 'unknownPage' };
+  }
+  // Anything else is an open redirect, carrying the authorization code to another site.
+  if (page.origin !== location.origin) return { kind: 'unknownPage' };
+
+  const query = new URLSearchParams(location.search);
+  const answer = query.has('error') ? query : new URLSearchParams(location.hash.slice(1));
+  const error = answer.get('error');
+  if (error !== null) {
+    return { kind: 'providerError', error, description: answer.get('error_description'), page: page.href };
+  }
+
+  // Whole, not as a path: a path of `//evil.test/x` would be read as another site's address.
+  page.search = location.search;
+  page.hash = location.hash;
+  return { kind: 'return', url: page.href };
+}
+
+/**
+ * The playground leaves the cookie for the session, so a later visit would be sent back to the
+ * last page that started an authorization. Forgotten once read, it names only the flow just started.
+ */
+export function forgetStartingPage(): void {
+  document.cookie = `${PAGE_COOKIE_NAME}=; path=/; max-age=0`;
+}

package/portal-template/src/lib/portal-types.ts

@@ -10,14 +10,14 @@ export interface PortalLink {
   external: boolean;
 }
 
-/** Site-relative, one per colour mode; the same URL twice when one image serves both. */
+/** Portal-relative, one per colour mode; the same URL twice when one image serves both. */
 export interface PortalLogo {
   light: string;
   dark: string;
 }
 
 export interface PortalFavicon {
-  /** Site-relative, and inside the static directory. */
+  /** Portal-relative, and inside the static directory. */
   url: string;
   type: string | null;
 }
@@ -25,7 +25,7 @@ export interface PortalFavicon {
 export interface Portal {
   name: string;
   description: string | null;
-  /** Origin only, with no trailing slash. */
+  /** The site address, with no trailing slash. */
   siteUrl: string | null;
   logo: PortalLogo | null;
   favicon: PortalFavicon | null;

package/portal-template/src/lib/rehype-code-titles.ts

@@ -1,5 +1,5 @@
 import { parseCodeBlockAttributes } from 'fumadocs-core/mdx-plugins/codeblock-utils';
-import { CODE_BLOCK_TITLES } from './code-titles';
+import { CODE_BLOCK_TITLES, languageOf } from './code-titles';
 import { bundledLanguage } from './shiki-bundle';
 
 interface HastNode {
@@ -11,8 +11,6 @@ interface HastNode {
   children?: HastNode[];
 }
 
-const LANGUAGE_CLASS = 'language-';
-
 /** Where `remarkCodeTab` puts a tabbed block, by its own tabs or an MDX `<Tabs>`: the tab already names it. */
 const CODE_TABS = new Set(['CodeBlockTab', 'Tab', 'TabsContent']);
 
@@ -40,8 +38,8 @@ export function rehypeCodeTitles() {
       return;
     }
     const classes = Array.isArray(code.properties?.className) ? code.properties.className : [];
-    const languageClass = classes.find((name) => typeof name === 'string' && name.startsWith(LANGUAGE_CLASS));
-    const language = typeof languageClass === 'string' ? bundledLanguage(languageClass.slice(LANGUAGE_CLASS.length)) : null;
+    const name = languageOf(classes);
+    const language = name === undefined ? null : bundledLanguage(name);
     const meta = typeof code.properties?.metastring === 'string' ? code.properties.metastring : '';
     // Read as `rehypeCode` reads it, which shows no title for a bare or unquoted one.
     const { title } = parseCodeBlockAttributes(meta, ['title']).attributes;

package/portal-template/src/lib/remark-image-references.ts

@@ -0,0 +1,35 @@
+/** An mdast node, as far as images and the definitions they refer to go. */
+interface MarkdownNode {
+  type: string;
+  identifier?: string;
+  url?: string;
+  title?: string | null;
+  alt?: string | null;
+  position?: unknown;
+  children?: MarkdownNode[];
+}
+
+/** Writes `![alt][ref]` as `![alt](url)`, the only form Fumadocs' `remarkImage` imports. page.ts checks the same. */
+export function remarkImageReferences() {
+  return (tree: MarkdownNode) => {
+    const definitions = new Map<string, MarkdownNode>();
+    const define = (node: MarkdownNode) => {
+      // The first definition of a label wins, as CommonMark reads them.
+      if (node.type === 'definition' && node.identifier !== undefined && !definitions.has(node.identifier)) {
+        definitions.set(node.identifier, node);
+      }
+      node.children?.forEach(define);
+    };
+    define(tree);
+
+    const inline = (node: MarkdownNode): MarkdownNode => {
+      const definition = node.type === 'imageReference' ? definitions.get(node.identifier ?? '') : undefined;
+      if (definition !== undefined) {
+        return { type: 'image', url: definition.url, title: definition.title, alt: node.alt, position: node.position };
+      }
+      if (node.children !== undefined) node.children = node.children.map(inline);
+      return node;
+    };
+    inline(tree);
+  };
+}

package/portal-template/src/lib/search-content.ts

@@ -0,0 +1,28 @@
+import { remark } from 'remark';
+
+/** An mdast node, as far as finding images goes. */
+interface MarkdownNode {
+  type: string;
+  position?: { start: { offset?: number }; end: { offset?: number } };
+  children?: MarkdownNode[];
+}
+
+const IMAGES = new Set(['image', 'imageReference']);
+
+// Without GFM, as the search dialog renders a result.
+const markdown = remark();
+
+/** Markdown without its images, as Fumadocs indexes a page of its own, and otherwise as written. */
+export function withoutImages(text: string): string {
+  let kept = '';
+  let from = 0;
+  for (const { position } of imagesIn(markdown.parse(text))) {
+    kept += text.slice(from, position?.start.offset ?? from);
+    from = position?.end.offset ?? from;
+  }
+  return kept + text.slice(from);
+}
+
+function imagesIn(node: MarkdownNode): MarkdownNode[] {
+  return IMAGES.has(node.type) ? [node] : (node.children ?? []).flatMap(imagesIn);
+}

package/portal-template/src/lib/search-options.ts

@@ -0,0 +1,7 @@
+import { parseSearchWith, stringifySearchWith } from '@tanstack/react-router';
+
+/** Query values as text: under a base path the router rewrites the address through these, and JSON loses some. */
+export const searchOptions = {
+  parseSearch: parseSearchWith((value) => value),
+  stringifySearch: stringifySearchWith(JSON.stringify)
+};

package/portal-template/src/lib/source.server.ts

@@ -25,3 +25,5 @@ export const source = loader(
     pageTree: { transformers: [navigationTransformer(), tabsTransformer()], generateFallback: false }
   }
 );
+
+export type PortalPage = ReturnType<typeof source.getPages>[number];

package/portal-template/src/router.tsx

@@ -1,12 +1,14 @@
 import { createRouter as createTanStackRouter } from '@tanstack/react-router';
 import { routeTree } from './routeTree.gen';
 import { NotFound } from '@/components/not-found';
+import { searchOptions } from '@/lib/search-options';
 
 export function getRouter() {
   return createTanStackRouter({
     routeTree,
     defaultPreload: 'intent',
     scrollRestoration: true,
-    defaultNotFoundComponent: NotFound
+    defaultNotFoundComponent: NotFound,
+    ...searchOptions
   });
 }

package/portal-template/src/routes/$.tsx

@@ -3,23 +3,18 @@ import { createServerFn } from '@tanstack/react-start';
 import { docs, generated } from '@/lib/source';
 import { source } from '@/lib/source.server';
 import { PortalLayout } from '@/lib/layout';
+import { fullAddress } from '@/lib/base-path';
 import { getPageMarkdownUrl, slugsFromSplat } from '@/lib/shared';
 import { portal } from '@/lib/portal';
 import { absoluteUrl, canonicalLink } from '@/lib/seo';
 import { useFumadocsLoader } from 'fumadocs-core/source/client';
 import { usePathname } from 'fumadocs-core/framework';
-import {
-  DocsBody,
-  DocsDescription,
-  DocsPage,
-  DocsTitle,
-  MarkdownCopyButton,
-  ViewOptionsPopover
-} from 'fumadocs-ui/layouts/notebook/page';
+import { DocsBody, DocsDescription, DocsPage, DocsTitle, ViewOptionsPopover } from 'fumadocs-ui/layouts/notebook/page';
 import { staticFunctionMiddleware } from '@tanstack/start-static-server-functions';
 import { Suspense, use, type ReactNode } from 'react';
 import { useMDXComponents } from '@/components/mdx';
 import { OpenAPIPage } from '@/components/api-page';
+import { MarkdownCopyButton } from '@/components/markdown-copy-button';
 import { slimOpenAPIPageProps } from '@/lib/openapi-slim';
 
 const rootRoute = getRouteApi('__root__');
@@ -135,14 +130,15 @@ function Content({
   const PageBody = page.body;
   const pathname = usePathname();
   // Named, or the popover reads `window.location.href` and sends the reader's query and hash on.
-  const pageUrl = typeof window === 'undefined' ? pathname : new URL(pathname, window.location.origin).toString();
+  const pageUrl = fullAddress(pathname);
 
   return (
     <DocsPage toc={toc} full={page.full}>
       <DocsTitle>{page.title}</DocsTitle>
       <DocsDescription>{page.description}</DocsDescription>
       <div className="flex flex-row gap-2 items-center border-b -mt-4 pb-6">
-        <MarkdownCopyButton markdownUrl={markdownUrl} />
+        {/* Keyed so a new page starts at "Copy Markdown", not at the last page's result. */}
+        <MarkdownCopyButton key={markdownUrl} markdownUrl={markdownUrl} />
         {/* Sends the reader to an external AI vendor, so a portal published under someone
             else's brand can turn it off. */}
         {portal.pageActions ? <ViewOptionsPopover markdownUrl={markdownUrl} pageUrl={pageUrl} /> : null}

package/portal-template/src/routes/__root.tsx

@@ -5,6 +5,7 @@ import { source } from '@/lib/source.server';
 import appCss from '@/styles/app.css?url';
 import { RootProvider } from 'fumadocs-ui/provider/tanstack';
 import SearchDialog from '@/components/search';
+import { withBasePath } from '@/lib/base-path';
 import { portal } from '@/lib/portal';
 
 // The sidebar tree is the same on every page. Loaded here, once, it is written to a single
@@ -15,7 +16,13 @@ const loadPageTree = createServerFn({ method: 'GET' })
 
 // Without one the browser tab shows the blank-document icon on every page.
 const iconLinks = portal.favicon
-  ? [{ rel: 'icon', href: portal.favicon.url, ...(portal.favicon.type ? { type: portal.favicon.type } : {}) }]
+  ? [
+      {
+        rel: 'icon',
+        href: withBasePath(portal.favicon.url),
+        ...(portal.favicon.type ? { type: portal.favicon.type } : {})
+      }
+    ]
   : [];
 
 // A portal fixed to one mode keeps to it whatever the visitor's system prefers, and offers no

package/portal-template/src/routes/api/search[.]json.ts

@@ -1,9 +1,30 @@
 import { createFileRoute } from '@tanstack/react-router';
-import { source } from '@/lib/source.server';
+import { withoutImages } from '@/lib/search-content';
+import { type PortalPage, source } from '@/lib/source.server';
 import { createFromSource } from 'fumadocs-core/search/server';
 
-const server = createFromSource(source, { language: 'english' });
+// Fumadocs indexes a reference page's description as written, so results show its images, without the path.
+const server = createFromSource(
+  { ...source, getPages: (language?: string) => source.getPages(language).map(searchable) },
+  { language: 'english' }
+);
 
 export const Route = createFileRoute('/api/search.json')({
   server: { handlers: { GET: () => server.staticGET() } }
 });
+
+/** A reference page as Fumadocs indexes a page of its own: without images. */
+function searchable(page: PortalPage): PortalPage {
+  if (page.type !== 'openapi') return page;
+  const { description, structuredData } = page.data;
+  const contents = structuredData.contents.map((item) => ({ ...item, content: withoutImages(item.content) }));
+  // Both alike, or Fumadocs no longer finds the description among the contents and indexes it a second time.
+  return {
+    ...page,
+    data: {
+      ...page.data,
+      description: description && withoutImages(description),
+      structuredData: { ...structuredData, contents }
+    }
+  };
+}