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

package/portal-template/spec-reload.ts

@@ -1,24 +1,27 @@
-import path from 'node:path';
 import type { Plugin } from 'vite';
 
+/** The extensions of the files a specification is read from and refers to: the CLI's own list, held to it by a test. */
+export const SPEC_FILE_EXTENSIONS = ['.json', '.yaml', '.yml'];
+
 /**
- * Reloads the preview when a file beside a specification changes. The specifications are read
- * at run time rather than imported, so Vite's module graph never learns of them, and the
- * reference pages are built once per server module evaluation.
+ * Reloads the preview when a specification file in the specification directory changes, as a document may refer
+ * to parts kept in another folder there. The specifications are read at run time rather than imported, so Vite's
+ * module graph never learns of them, and the reference pages are built once per evaluation.
  */
-export function specReload(specs: Record<string, string>): Plugin {
-  const directories = [...new Set(Object.values(specs).map((file) => path.posix.dirname(file)))];
-  const isInSpecDirectory = (file: string) => directories.some((directory) => file.startsWith(`${directory}/`));
+export function specReload(specDirectory: string): Plugin {
+  const isSpecFile = (file: string) =>
+    file.startsWith(`${specDirectory}/`) &&
+    SPEC_FILE_EXTENSIONS.some((extension) => file.toLowerCase().endsWith(extension));
 
   return {
     name: 'apimatic:spec-reload',
     apply: 'serve',
     configureServer(server) {
-      server.watcher.add(directories);
+      server.watcher.add(specDirectory);
     },
     // Sent to each environment: the server runner re-evaluates every module, the browser reloads.
     hotUpdate({ file }) {
-      if (!isInSpecDirectory(file)) return;
+      if (!isSpecFile(file)) return;
       this.environment.hot.send({ type: 'full-reload' });
       return [];
     }

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);

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

@@ -1,5 +1,7 @@
-export async function copyMarkdown(rootRelativeUrl: string, base: string): Promise<void> {
-  const url = `${base.replace(/\/$/, '')}${rootRelativeUrl}`;
+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]);

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
   });
 }