@apimatic/cli 1.4.0 → 2.0.0-beta.1

package/portal-template/src/lib/request-examples.ts

@@ -0,0 +1,72 @@
+import type { useOperationContext } from 'fumadocs-openapi/ui';
+import { isJsonObject } from './json';
+
+export type RequestExample = Pick<
+  ReturnType<typeof useOperationContext>['examples'][number],
+  'id' | 'name' | 'description'
+>;
+type Location = 'path' | 'query' | 'header' | 'cookie';
+type Resolve = (node: unknown) => unknown;
+
+interface Example {
+  summary?: string;
+  description?: string;
+}
+
+// Fumadocs upgrades a 3.0 document's singular `example` into an example keyed `default`.
+const PLACEHOLDER_IDS = new Set(['_default', 'default', 'Example']);
+
+// The order codegen-v2 consults when the request body names no example ids.
+const NAMING_ORDER: Location[] = ['query', 'header', 'path'];
+
+export class Parameter {
+  private constructor(
+    public readonly location: Location,
+    private readonly examples: Map<string, Example>
+  ) {}
+
+  public static listIn(operation: unknown, pathItem: unknown, resolve: Resolve): Parameter[] {
+    return [...parametersOf(operation), ...parametersOf(pathItem)].flatMap(
+      (entry) => Parameter.from(resolve(entry), resolve) ?? []
+    );
+  }
+
+  private static from(entry: unknown, resolve: Resolve): Parameter | undefined {
+    if (!isJsonObject(entry) || !isLocation(entry.in) || typeof entry.name !== 'string') {
+      return undefined;
+    }
+    const examples = isJsonObject(entry.examples)
+      ? Object.entries(entry.examples)
+          .map(([id, example]): [string, unknown] => [id, resolve(example)])
+          .filter(isExampleEntry)
+      : [];
+    return new Parameter(entry.in, new Map(examples));
+  }
+
+  public namedExamples(): [string, Example][] {
+    return [...this.examples].filter(([id]) => !PLACEHOLDER_IDS.has(id));
+  }
+}
+
+export function requestExamples(bodyExamples: RequestExample[], parameters: Parameter[]): RequestExample[] {
+  const named = NAMING_ORDER.flatMap((location) =>
+    parameters.filter((parameter) => parameter.location === location).map((parameter) => parameter.namedExamples())
+  ).find((examples) => examples.length > 0);
+  if (bodyExamples.length > 1 || !PLACEHOLDER_IDS.has(bodyExamples[0].id) || named === undefined) {
+    return bodyExamples;
+  }
+  return named.map(([id, { summary, description }]) => ({ id, name: summary || id, description }));
+}
+
+function parametersOf(node: unknown): unknown[] {
+  return isJsonObject(node) && Array.isArray(node.parameters) ? node.parameters : [];
+}
+
+function isLocation(value: unknown): value is Location {
+  return value === 'path' || value === 'query' || value === 'header' || value === 'cookie';
+}
+
+function isExampleEntry(entry: [string, unknown]): entry is [string, Example] {
+  return isJsonObject(entry[1]) && 'value' in entry[1];
+}
+

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

@@ -0,0 +1,21 @@
+import { portal } from './portal';
+
+/**
+ * Absolute URL of a page, or null when the portal has no configured address.
+ * Canonical links and the sitemap are both omitted in that case rather than
+ * guessed, since a wrong canonical is worse than none.
+ */
+export function absoluteUrl(pageUrl: string): string | null {
+  if (!portal.siteUrl) return null;
+  return portal.siteUrl + pageUrl;
+}
+
+export function canonicalLink(pageUrl: string): { rel: string; href: string }[] {
+  const href = absoluteUrl(pageUrl);
+  return href === null ? [] : [{ rel: 'canonical', href }];
+}
+
+export function renderRobots(): string {
+  const sitemap = absoluteUrl('/sitemap.xml');
+  return ['User-agent: *', 'Allow: /', ...(sitemap === null ? [] : ['', `Sitemap: ${sitemap}`])].join('\n') + '\n';
+}

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

@@ -0,0 +1,51 @@
+import type * as PageTree from 'fumadocs-core/page-tree';
+import { createGetUrl } from 'fumadocs-core/source';
+
+export const docsRoute = '/';
+
+/**
+ * Where the reference pages of every specification are mounted, one folder per section
+ * beneath it. Shared so the navigation transformer positions the same folder the OpenAPI
+ * sections are written into.
+ */
+export const apiBaseDir = 'api';
+
+const getDocsUrl = createGetUrl(docsRoute);
+
+/** Whether a page at `url` sits among these nodes, at any depth. */
+export function containsUrl(nodes: PageTree.Node[], url: string): boolean {
+  return nodes.some((node) => {
+    if (node.type === 'page') {
+      return node.url === url;
+    }
+    return node.type === 'folder' && (node.index?.url === url || containsUrl(node.children, url));
+  });
+}
+
+export function getPageMarkdownUrl(page: { slugs: string[]; locale?: string }) {
+  const segments = [...page.slugs];
+  if (segments.length === 0) {
+    segments.push('index.md');
+  } else {
+    segments[segments.length - 1] += '.md';
+  }
+
+  return { segments, url: getDocsUrl(segments, page.locale) };
+}
+
+export function slugsFromSplat(splat: string | undefined): string[] {
+  return (splat ?? '')
+    .split('/')
+    .filter((segment) => segment.length > 0)
+    .map(encodeURI);
+}
+
+/** @returns page slugs */
+export function decodeMarkdownUrl(segments: string[]) {
+  if (segments.length === 0) return [];
+
+  const out = [...segments];
+  out[out.length - 1] = (out.at(-1) ?? '').replace(/\.md$/, '');
+  if (out.length === 1 && out[0] === 'index') out.pop();
+  return out;
+}

package/portal-template/src/lib/shiki-bundle.ts

@@ -0,0 +1,104 @@
+import { createBundledHighlighter } from 'shiki/core';
+import { createJavaScriptRegexEngine } from 'shiki/engine/javascript';
+
+// Re-exported untouched: Fumadocs imports it from the `shiki` entry point this file stands
+// in for, though the bundle itself builds its highlighter on the JavaScript engine.
+export { createOnigurumaEngine } from 'shiki/engine/oniguruma';
+
+type LanguageImport = () => Promise<unknown>;
+
+/**
+ * Stands in for the `shiki` entry point Fumadocs imports to build its highlighter (see the
+ * alias in `vite.config.ts`). That entry carries Shiki's whole catalogue as dynamic imports,
+ * so the bundler emits a chunk per grammar and a one-endpoint portal ships some ten megabytes
+ * of them for languages nothing on the site is written in. Only what a generated portal can
+ * contain is bundled; Fumadocs falls back to plain text for anything outside this map, so an
+ * unlisted language renders unhighlighted rather than broken.
+ */
+const languages = {
+  // The seven the CLI generates SDKs for (src/types/sdk/generate.ts).
+  csharp: () => import('shiki/dist/langs/csharp.mjs'),
+  go: () => import('shiki/dist/langs/go.mjs'),
+  java: () => import('shiki/dist/langs/java.mjs'),
+  php: () => import('shiki/dist/langs/php.mjs'),
+  python: () => import('shiki/dist/langs/python.mjs'),
+  ruby: () => import('shiki/dist/langs/ruby.mjs'),
+  typescript: () => import('shiki/dist/langs/typescript.mjs'),
+
+  // Shell commands, and the shapes a response or a specification is shown in.
+  http: () => import('shiki/dist/langs/http.mjs'),
+  json: () => import('shiki/dist/langs/json.mjs'),
+  jsonc: () => import('shiki/dist/langs/jsonc.mjs'),
+  shellscript: () => import('shiki/dist/langs/shellscript.mjs'),
+  shellsession: () => import('shiki/dist/langs/shellsession.mjs'),
+  xml: () => import('shiki/dist/langs/xml.mjs'),
+  yaml: () => import('shiki/dist/langs/yaml.mjs'),
+
+  // What the Markdown pages beside the reference are written in.
+  css: () => import('shiki/dist/langs/css.mjs'),
+  diff: () => import('shiki/dist/langs/diff.mjs'),
+  graphql: () => import('shiki/dist/langs/graphql.mjs'),
+  html: () => import('shiki/dist/langs/html.mjs'),
+  javascript: () => import('shiki/dist/langs/javascript.mjs'),
+  jsx: () => import('shiki/dist/langs/jsx.mjs'),
+  markdown: () => import('shiki/dist/langs/markdown.mjs'),
+  sql: () => import('shiki/dist/langs/sql.mjs'),
+  tsx: () => import('shiki/dist/langs/tsx.mjs')
+} satisfies Record<string, LanguageImport>;
+
+/**
+ * Shiki's own bundle resolves `ts` or `yml` through an alias table beside its grammars; a
+ * hand-built map has none, so an alias reaches Fumadocs as an unknown language and is replaced
+ * with `text`. Each shares its grammar's import, as Shiki's `bundledLanguagesAlias` does, so
+ * the bundler still emits one chunk per language rather than one per spelling. Taken from
+ * Shiki's `bundledLanguagesInfo`; `test/portal-template.test.ts` holds them to it.
+ */
+const aliases: Record<string, keyof typeof languages> = {
+  'c#': 'csharp',
+  cs: 'csharp',
+  py: 'python',
+  rb: 'ruby',
+  ts: 'typescript',
+  cts: 'typescript',
+  mts: 'typescript',
+  js: 'javascript',
+  cjs: 'javascript',
+  mjs: 'javascript',
+  bash: 'shellscript',
+  sh: 'shellscript',
+  shell: 'shellscript',
+  zsh: 'shellscript',
+  console: 'shellsession',
+  yml: 'yaml',
+  md: 'markdown',
+  gql: 'graphql'
+};
+
+export type BundledLanguage = keyof typeof languages;
+
+/** The grammar a fence's language names, by its own name or an alias; null for one not bundled. */
+export function bundledLanguage(name: string): BundledLanguage | null {
+  if (Object.hasOwn(languages, name)) {
+    return name as BundledLanguage;
+  }
+  return Object.hasOwn(aliases, name) ? aliases[name] : null;
+}
+
+const bundledLanguages = {
+  ...languages,
+  ...Object.fromEntries(Object.entries(aliases).map(([alias, id]) => [alias, languages[id]]))
+} as never;
+
+/** The two Fumadocs asks for by default; the rest of Shiki's themes are never requested. */
+const bundledThemes = {
+  'github-light': () => import('shiki/dist/themes/github-light.mjs'),
+  'github-dark': () => import('shiki/dist/themes/github-dark.mjs')
+} as never;
+
+export const createHighlighter = createBundledHighlighter({
+  langs: bundledLanguages,
+  themes: bundledThemes,
+  engine: () => createJavaScriptRegexEngine()
+});
+
+export { createJavaScriptRegexEngine };

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

@@ -0,0 +1,20 @@
+import { absoluteUrl } from './seo';
+import { source } from './source.server';
+
+export function renderSitemap(): string {
+  const urls = ['/', ...source.getPages().map((page) => page.url)];
+  const entries = [...new Set(urls)]
+    .map((url) => `  <url>\n    <loc>${escapeXml(absoluteUrl(url) ?? url)}</loc>\n  </url>`)
+    .join('\n');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${entries}\n</urlset>\n`;
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;');
+}

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

@@ -0,0 +1,27 @@
+import { loader } from 'fumadocs-core/source';
+import { lucideIconsPlugin } from 'fumadocs-core/source/lucide-icons';
+import { openapiPlugin } from 'fumadocs-openapi/server';
+import { docsRoute } from './shared';
+import { docs, generated } from './source';
+import { GENERATED_SOURCE, navigationTransformer, OPENAPI_SOURCE, tabsTransformer } from './navigation';
+import { openApiSource } from './openapi.server';
+
+// Reads every OpenAPI document off disk, so this only runs at build time, inside server
+// functions and server route handlers. Importing it from client code fails the build.
+// The generated and reference pages go in under the keys the transformer tells them apart by.
+export const source = loader(
+  {
+    docs: docs.toFumadocsSource(),
+    [GENERATED_SOURCE]: generated.toFumadocsSource(),
+    [OPENAPI_SOURCE]: await openApiSource()
+  },
+  {
+    baseUrl: docsRoute,
+    plugins: [lucideIconsPlugin(), openapiPlugin()],
+    // No fallback tree: it is built from the files that became no node, and `nav.json` never
+    // does, so every build would otherwise grow a second tree that nothing renders and that
+    // the sidebar payload carries to every visitor. The tabs are formed from the root once it
+    // is ordered, which is why their transformer comes second.
+    pageTree: { transformers: [navigationTransformer(), tabsTransformer()], generateFallback: false }
+  }
+);

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

@@ -0,0 +1,49 @@
+import { defineDocs } from 'fumadocs-mdx/macro';
+import { applyMdxPreset } from 'fumadocs-mdx/config';
+import { rehypeCodeDefaultOptions } from 'fumadocs-core/mdx-plugins';
+import rehypeRaw from 'rehype-raw';
+import { rehypeCodeTitles, rehypeKeepCodeMeta } from './rehype-code-titles';
+
+// What `rehype-raw` must hand on untouched, being MDX's own nodes rather than HTML.
+const MDX_NODE_TYPES = ['mdxFlowExpression', 'mdxJsxFlowElement', 'mdxJsxTextElement', 'mdxTextExpression', 'mdxjsEsm'];
+
+// The CLI copies the source's pages here. Relative, because the macro embeds the literal in the
+// browser bundle, and an absolute one would publish the build machine's directories.
+//
+// This module is imported by the browser bundle, so it must stay free of anything that touches
+// the filesystem. The loader that reads the OpenAPI documents lives in `source.server.ts`.
+export const docs = defineDocs({
+  dir: 'content',
+  docs: { async: true, postprocess: { includeProcessedMarkdown: true } },
+  // Restricted to our own file, replacing the default of every .json and .yaml in the
+  // content directory. Without it a leftover `meta.json` is loaded as a folder's metadata
+  // and applied before the transformer runs -- and since a metadata file hides whatever it
+  // does not name, the transformer could not put those pages back.
+  meta: { files: ['**/nav.json'] }
+});
+
+// The pages the CLI writes into this project, resolved against the Vite root like `content`.
+export const generated = defineDocs({
+  dir: 'generated',
+  docs: {
+    async: true,
+    // Its components give their own Markdown, where a string would keep them as JSX tags.
+    postprocess: { includeProcessedMarkdown: { output: 'function' } },
+    // Options given here replace Fumadocs' defaults, hence the preset.
+    mdxOptions: applyMdxPreset({
+      // A remote image is never fetched for its size, which would make the build depend on its host.
+      remarkImageOptions: { external: false },
+      // The SDK pages' design heads a block with its title alone, without Fumadocs' language icon.
+      rehypeCodeOptions: { ...rehypeCodeDefaultOptions, icon: false },
+      // The SDK docs' HTML fails the build unrendered; not sanitized, as it comes from the owner's own spec.
+      // The titles go in after it, and ahead of `rehypeCode`, the first of the defaults, which reads them.
+      rehypePlugins: (defaults) => [
+        rehypeKeepCodeMeta,
+        [rehypeRaw, { passThrough: MDX_NODE_TYPES }],
+        rehypeCodeTitles,
+        ...defaults
+      ]
+    })
+  },
+  meta: { files: ['**/nav.json'] }
+});

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

@@ -0,0 +1,37 @@
+import type * as PageTree from 'fumadocs-core/page-tree';
+import type { LayoutTab } from 'fumadocs-ui/layouts/shared';
+import { containsUrl, docsRoute } from './shared';
+
+/**
+ * One tab per root folder at the top of the tree, which is every top-level node once the tabs
+ * transformer has run. Given to the layout rather than left to Fumadocs, which links a tab to
+ * its folder's first direct page and so leaves out a tab holding only folders -- as the API
+ * reference does whenever its operations are grouped. Each stays bound to its folder, which is
+ * how the active tab is found.
+ */
+export function portalTabs(tree: PageTree.Root): LayoutTab[] {
+  return tree.children.flatMap((node) => {
+    if (node.type !== 'folder' || node.root !== true) return [];
+    // Home keeps the order the root nav.json gives, which need not put the home page first.
+    const url = containsUrl([node], docsRoute) ? docsRoute : firstPageUrl(node);
+    return url === undefined
+      ? []
+      : [{ title: node.name, description: node.description, icon: node.icon, url, $folder: node }];
+  });
+}
+
+/**
+ * Depth first, as the sidebar lists them, so the tab opens on the page at its top. A link
+ * that leaves the portal is passed over, as Fumadocs passes it over for a folder's own link.
+ */
+function firstPageUrl(folder: PageTree.Folder): string | undefined {
+  if (folder.index !== undefined) return folder.index.url;
+  for (const child of folder.children) {
+    if (child.type === 'page' && !child.external) return child.url;
+    if (child.type === 'folder') {
+      const url = firstPageUrl(child);
+      if (url !== undefined) return url;
+    }
+  }
+  return undefined;
+}

package/portal-template/src/router.tsx

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

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

@@ -0,0 +1,194 @@
+import { createFileRoute, getRouteApi, isNotFound, isRedirect, notFound } from '@tanstack/react-router';
+import { createServerFn } from '@tanstack/react-start';
+import { docs, generated } from '@/lib/source';
+import { source } from '@/lib/source.server';
+import { PortalLayout } from '@/lib/layout';
+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 { 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 { slimOpenAPIPageProps } from '@/lib/openapi-slim';
+
+const rootRoute = getRouteApi('__root__');
+
+/**
+ * The collections a Markdown page is compiled into, by the loader source it came from. A
+ * page's `path` is relative to its own collection's directory, so it is looked up there.
+ */
+const collections = { docs, generated };
+
+export const Route = createFileRoute('/$')({
+  component: Page,
+  loader: async ({ params }) => {
+    const slugs = slugsFromSplat(params._splat);
+    const data = await loadPage(slugs);
+
+    if (data.type === 'docs') {
+      await collections[data.collection].getPage(data.path)?.preload();
+    }
+    return data;
+  },
+  head: ({ loaderData, params }) => {
+    const title = loaderData && loaderData.type !== 'home' ? `${loaderData.title} | ${portal.name}` : portal.name;
+    const description = loaderData?.description ?? portal.description;
+    const pageUrl = `/${slugsFromSplat(params._splat).join('/')}`;
+    const absolute = absoluteUrl(pageUrl);
+    return {
+      // Without the og:* pair, a documentation link pasted into Slack, Teams or LinkedIn
+      // unfurls as a bare URL.
+      meta: [
+        { title },
+        ...(description ? [{ name: 'description', content: description }] : []),
+        { property: 'og:title', content: title },
+        ...(description ? [{ property: 'og:description', content: description }] : []),
+        { property: 'og:type', content: 'website' },
+        { property: 'og:site_name', content: portal.name },
+        ...(absolute ? [{ property: 'og:url', content: absolute }] : []),
+        { name: 'twitter:card', content: 'summary' }
+      ],
+      links: canonicalLink(pageUrl)
+    };
+  }
+});
+
+const serverLoader = createServerFn({
+  method: 'GET'
+})
+  .validator((slugs: string[]) => slugs)
+  .middleware([staticFunctionMiddleware])
+  .handler(async ({ data: slugs }) => {
+    const page = source.getPage(slugs);
+
+    if (!page) {
+      // A project without content/index.md(x) still gets a landing page.
+      if (slugs.length === 0) {
+        return { type: 'home' as const, title: portal.name, description: portal.description };
+      }
+      throw notFound();
+    }
+
+    if (page.type === 'openapi') {
+      return {
+        type: 'openapi' as const,
+        title: page.data.title,
+        description: page.data.description ?? null,
+        props: slimOpenAPIPageProps(page.data.getOpenAPIPageProps())
+      };
+    }
+
+    return {
+      type: 'docs' as const,
+      collection: page.type,
+      title: page.data.title,
+      description: page.data.description ?? null,
+      path: page.path,
+      markdownUrl: getPageMarkdownUrl(page).url
+    };
+  });
+
+// The condition `staticFunctionMiddleware` itself uses to answer from the prerendered cache
+// instead of calling the handler.
+const answeredFromStaticCache = process.env.NODE_ENV === 'production' && typeof document !== 'undefined';
+
+/**
+ * An unknown URL has no prerendered response, and the middleware fetches one without checking
+ * the status, so `.json()` throws on whatever the host returns for a missing file and the
+ * error boundary renders in place of the not-found page. Only the cache path is rewritten,
+ * where a failed fetch can only mean the page does not exist; everywhere else -- the prerender
+ * pass, `portal serve` -- a real failure still surfaces.
+ */
+async function loadPage(slugs: string[]) {
+  try {
+    return await serverLoader({ data: slugs });
+  } catch (error) {
+    if (!answeredFromStaticCache || isNotFound(error) || isRedirect(error)) throw error;
+    // A missing page is the ordinary reason to land here, but a network failure or a host
+    // answering with its own error page fails the same way, so the cause is named rather
+    // than assumed.
+    console.error('Falling back to the not-found page; loading this page failed with:', error);
+    throw notFound();
+  }
+}
+
+function Content({
+  collection,
+  path,
+  markdownUrl
+}: Readonly<{ collection: keyof typeof collections; path: string; markdownUrl: string }>) {
+  const page = collections[collection].getPage(path);
+  if (!page) throw new Error(`unknown page: ${path}`);
+
+  const { toc } = use(page.load());
+  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();
+
+  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} />
+        {/* 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}
+      </div>
+      <DocsBody>
+        <PageBody components={useMDXComponents()} />
+      </DocsBody>
+    </DocsPage>
+  );
+}
+
+function Home({ title, description }: Readonly<{ title: string; description: string | null }>) {
+  return (
+    <DocsPage>
+      <DocsTitle>{title}</DocsTitle>
+      {description ? <DocsDescription>{description}</DocsDescription> : null}
+      <DocsBody>
+        <p>Use the navigation to browse the API reference and guides.</p>
+      </DocsBody>
+    </DocsPage>
+  );
+}
+
+function Page() {
+  const page = useFumadocsLoader(Route.useLoaderData());
+  const { pageTree } = useFumadocsLoader(rootRoute.useLoaderData());
+  let content: ReactNode;
+
+  if (page.type === 'home') {
+    content = <Home title={page.title} description={page.description} />;
+  } else if (page.type === 'openapi') {
+    content = (
+      <DocsPage full>
+        <DocsTitle>{page.title}</DocsTitle>
+        <DocsBody>
+          <OpenAPIPage {...page.props} />
+        </DocsBody>
+      </DocsPage>
+    );
+  } else {
+    content = (
+      <Suspense>
+        <Content collection={page.collection} path={page.path} markdownUrl={page.markdownUrl} />
+      </Suspense>
+    );
+  }
+
+  return <PortalLayout tree={pageTree}>{content}</PortalLayout>;
+}

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

@@ -0,0 +1,56 @@
+import { createRootRoute, HeadContent, Outlet, Scripts } from '@tanstack/react-router';
+import { createServerFn } from '@tanstack/react-start';
+import { staticFunctionMiddleware } from '@tanstack/start-static-server-functions';
+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 { portal } from '@/lib/portal';
+
+// The sidebar tree is the same on every page. Loaded here, once, it is written to a single
+// cache file instead of being repeated in every page's own loader payload.
+const loadPageTree = createServerFn({ method: 'GET' })
+  .middleware([staticFunctionMiddleware])
+  .handler(async () => ({ pageTree: await source.serializePageTree(source.getPageTree()) }));
+
+// 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 } : {}) }]
+  : [];
+
+// A portal fixed to one mode keeps to it whatever the visitor's system prefers, and offers no
+// way out: the layout hides the switch, and the `D` hotkey is turned off here.
+const theme =
+  portal.colorMode === 'both'
+    ? undefined
+    : { forcedTheme: portal.colorMode, defaultTheme: portal.colorMode, enableSystem: false, hotKey: false as const };
+
+export const Route = createRootRoute({
+  loader: () => loadPageTree(),
+  head: () => ({
+    meta: [
+      { charSet: 'utf-8' },
+      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
+      { title: portal.name },
+      ...(portal.description ? [{ name: 'description', content: portal.description }] : [])
+    ],
+    links: [{ rel: 'stylesheet', href: appCss }, ...iconLinks]
+  }),
+  component: RootComponent
+});
+
+function RootComponent() {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <HeadContent />
+      </head>
+      <body className="flex flex-col min-h-screen">
+        <RootProvider search={{ SearchDialog }} theme={theme}>
+          <Outlet />
+        </RootProvider>
+        <Scripts />
+      </body>
+    </html>
+  );
+}

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

@@ -0,0 +1,9 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { source } from '@/lib/source.server';
+import { createFromSource } from 'fumadocs-core/search/server';
+
+const server = createFromSource(source, { language: 'english' });
+
+export const Route = createFileRoute('/api/search.json')({
+  server: { handlers: { GET: () => server.staticGET() } }
+});

package/portal-template/src/routes/llms-full[.]txt.ts

@@ -0,0 +1,10 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { renderFull } from '@/lib/llms.server';
+
+export const Route = createFileRoute('/llms-full.txt')({
+  server: {
+    handlers: {
+      GET: async () => new Response(await renderFull())
+    }
+  }
+});