Sync (#2696)

* Core: Support client-side loader

* Fix: handle absolute paths in fetchDocs function (#2692)

* Fix: handle absolute paths in fetchDocs function

* Core: Support absolute URLs in search fetch client

---------

Co-authored-by: Fuma Nama <[email protected]>

* Bump deps

* UI: Align menu behaviour on notebook layout with home layout

* Core: make serialization API lower level

* migrate examples

* docgen: fix async transform

* downgrade tanstack start

see TanStack/router#5967

* Bump deps

* UI: refactor internals

* Docs: experiment mcp server

* Docs: introduce OpenAPI loader integration

* Docs: introduce client-side loader

* fix registry

* Chore: try OIDC

* CLI: fix recursive build

* Version Packages (#2690)

---------

Co-authored-by: Mustafa Keskin <[email protected]>

Author: fuma-nama

.github/workflows/release.yml

@@ -6,6 +6,9 @@ on:
       - dev
 
 concurrency: ${{ github.workflow }}-${{ github.ref }}
+permissions:
+  id-token: write
+  contents: read
 
 jobs:
   release:
@@ -35,4 +38,3 @@ jobs:
           version: pnpm run version
         env:
           GITHUB_TOKEN: ${{ secrets.UPDATE_TEMPLATE_SSH_KEY }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

.prettierignore

@@ -29,5 +29,5 @@ apps/docs/content/docs/ui/typescript.mdx
 packages/mdx-remote/test/fixtures/**/*.js
 packages/mdx-remote/test/fixtures/**/*.json
 packages/core/test/fixtures/page-trees/**/*.json
-build/
+
 routeTree.gen.ts

apps/docs/app/api/[transport]/route.ts

@@ -0,0 +1,83 @@
+import { DataSourceId, orama } from '@/lib/orama/client';
+import { createMcpHandler } from 'mcp-handler';
+import { z } from 'zod';
+import { ProvideLinksToolSchema } from '@/lib/chat/inkeep-qa-schema';
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
+import { generateText } from 'ai';
+
+const openai = createOpenAICompatible({
+  name: 'inkeep',
+  apiKey: process.env.INKEEP_API_KEY,
+  baseURL: 'https://api.inkeep.com/v1',
+});
+
+const handler = createMcpHandler(
+  (server) => {
+    server.registerTool(
+      'search',
+      {
+        title: 'Search Docs',
+        description: 'Search docs pages with a query',
+        inputSchema: z.object({
+          query: z.string('the search query'),
+        }),
+      },
+      async ({ query }) => {
+        const result = await orama.search({
+          term: query,
+          datasources: [DataSourceId],
+          limit: 50,
+        });
+
+        return {
+          content: result.hits.map((hit) => ({
+            type: 'text',
+            text: JSON.stringify(hit.document),
+          })),
+        };
+      },
+    );
+
+    server.registerTool(
+      'ask-ai',
+      {
+        title: 'Ask AI',
+        description: 'Ask another specialized AI a question for more info',
+        inputSchema: z.object({
+          message: z.string(),
+        }),
+      },
+      async ({ message }) => {
+        const result = await generateText({
+          model: openai('inkeep-qa-sonnet-4'),
+          tools: {
+            provideLinks: {
+              inputSchema: ProvideLinksToolSchema,
+            },
+          },
+          messages: [
+            {
+              role: 'user',
+              content: message,
+            },
+          ],
+        });
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: result.text,
+            },
+          ],
+        };
+      },
+    );
+  },
+  {},
+  {
+    basePath: '/api',
+  },
+);
+
+export { handler as GET, handler as POST };

apps/docs/app/og/[...slug]/route.tsx

@@ -15,12 +15,10 @@ export async function GET(
   if (!page) notFound();
 
   return new ImageResponse(
-    (
-      <MetadataImage
-        title={page.data.title}
-        description={page.data.description}
-      />
-    ),
+    <MetadataImage
+      title={page.data.title}
+      description={page.data.description}
+    />,
     await getImageResponseOptions(),
   );
 }

apps/docs/components/contributor-count.tsx

@@ -3,8 +3,7 @@ import Image from 'next/image';
 import { cn } from '@/lib/cn';
 import { fetchContributors } from '@/lib/get-contributors';
 
-export interface ContributorCounterProps
-  extends HTMLAttributes<HTMLDivElement> {
+export interface ContributorCounterProps extends HTMLAttributes<HTMLDivElement> {
   repoOwner: string;
   repoName: string;
   displayCount?: number;

apps/docs/content/docs/headless/source-api/index.mdx

@@ -11,7 +11,7 @@ description: Turn a content source into a unified interface
 - Assign URL to each page.
 - Output useful utilities to interact with content.
 
-It doesn't rely on the real file system (zero `node:fs` usage), a virtual storage is also allowed.
+It is a server-side API, but doesn't rely on the real file system (zero `node:fs` usage), a virtual storage is also allowed.
 
 ## Usage
 
@@ -160,3 +160,35 @@ import { source } from '@/lib/source';
 // language -> pages
 const entries = source.getLanguages();
 ```
+
+## Client API
+
+Loader API is best when used in RSC environments, which allows passing JSX nodes across the server-client boundary.
+
+For non-RSC environments, it provides a tiny serialization layer.
+
+```ts tab="Server"
+import { source } from '@/lib/source';
+
+// where you pass loader data
+async function loader() {
+  const pageTree = source.getPageTree();
+
+  return {
+    pageTree: await source.serializePageTree(pageTree),
+  };
+}
+```
+
+```tsx tab="Client"
+import { useFumadocsLoader } from 'fumadocs-core/source/client';
+
+function MyComponent() {
+  // receives loader data
+  const data = useLoaderData();
+  const { pageTree } = useFumadocsLoader(data);
+
+  // now render it (e.g. via Fumadocs UI)
+  return <DocsLayout tree={pageTree}>...</DocsLayout>;
+}
+```

apps/docs/content/docs/ui/internationalization/next.mdx

@@ -162,7 +162,7 @@ export default async function Layout({
 
   return (
     // [!code highlight]
-    <DocsLayout {...baseOptions(lang)} tree={source.pageTree[lang]}>
+    <DocsLayout {...baseOptions(lang)} tree={source.getPageTree(lang)}>
       {children}
     </DocsLayout>
   );

apps/docs/content/docs/ui/openapi/index.mdx

@@ -3,8 +3,12 @@ title: OpenAPI
 description: Generating docs for OpenAPI schema
 ---
 
-<Callout type="warning" title="Server Component Only">
-  It only works under RSC environments.
+<Callout type="warning" title="Before Reading">
+
+- Only OpenAPI 3.0 and 3.1 are supported.
+- It only works under RSC
+  environments.
+
 </Callout>
 
 ## Manual Setup
@@ -32,7 +36,7 @@ Add the following line:
 @import 'fumadocs-openapi/css/preset.css';
 ```
 
-### Configure Pages
+### Configure Plugin
 
 Create an OpenAPI instance on the server.
 
@@ -76,6 +80,34 @@ export default defineClientConfig({
 });
 ```
 
+### Generate Pages
+
+<Tabs items={["MDX Files", "Virtual Files"]}>
+<Tab>
+
+You can generate MDX files directly from your OpenAPI schema.
+
+Create a script:
+
+```js title="scripts/generate-docs.ts"
+import { generateFiles } from 'fumadocs-openapi';
+import { openapi } from '@/lib/openapi';
+
+void generateFiles({
+  input: openapi,
+  output: './content/docs',
+  // we recommend to enable it
+  // make sure your endpoint description doesn't break MDX syntax.
+  includeDescription: true,
+});
+```
+
+Generate docs with the script:
+
+```bash
+bun ./scripts/generate-docs.ts
+```
+
 Add the `APIPage` component to your MDX Components.
 
 ```tsx title="mdx-components.tsx"
@@ -93,33 +125,60 @@ export function getMDXComponents(components?: MDXComponents): MDXComponents {
 }
 ```
 
-### Generate Files
+</Tab>
+<Tab>
 
-You can generate MDX files directly from your OpenAPI schema.
-
-Create a script:
+You can also use it without generating real files by integrating into [Loader API](/docs/headless/source-api/source).
 
-```js title="scripts/generate-docs.ts"
-import { generateFiles } from 'fumadocs-openapi';
+```ts title="lib/source.ts"
+import { loader, multiple } from 'fumadocs-core/source';
+import { openapiPlugin, openapiSource } from 'fumadocs-openapi/server';
+import { docs } from 'fumadocs-mdx:collections/server';
 import { openapi } from '@/lib/openapi';
 
-void generateFiles({
-  input: openapi,
-  output: './content/docs',
-  // we recommend to enable it
-  // make sure your endpoint description doesn't break MDX syntax.
-  includeDescription: true,
-});
+export const source = loader(
+  // [!code ++:6]
+  multiple({
+    docs: docs.toFumadocsSource(),
+    openapi: await openapiSource(openapi, {
+      baseDir: 'openapi',
+    }),
+  }),
+  {
+    baseUrl: '/docs',
+    plugins: [openapiPlugin()],
+    // ...
+  },
+);
 ```
 
-> Only OpenAPI 3.0 and 3.1 are supported.
+It shares a different type from your original source, explicit handling of OpenAPI pages might be necessary (e.g. in your page component).
 
-Generate docs with the script:
+```tsx title="docs/[[...slug]]/page.tsx"
+import { APIPage } from '@/components/api-page';
 
-```bash
-bun ./scripts/generate-docs.ts
+function Page() {
+  const page = source.getPage('...');
+
+  if (page.data.type === 'openapi') {
+    return (
+      <DocsPage full>
+        <h1 className="text-[1.75em] font-semibold">{page.data.title}</h1>
+
+        <DocsBody>
+          <APIPage {...page.data.getAPIPageProps()} />
+        </DocsBody>
+      </DocsPage>
+    );
+  }
+
+  // your original flow below...
+}
 ```
 
+</Tab>
+</Tabs>
+
 ## Features
 
 The official OpenAPI integration supports: