From cc80f5b19073a4e351b7d85340516e1c6295c3ae Mon Sep 17 00:00:00 2001 From: Fuma Nama Date: Fri, 20 Dec 2024 19:09:26 +0800 Subject: [PATCH] Docs: Add guide for static export --- apps/docs/content/docs/mdx/index.mdx | 12 ++-- apps/docs/content/docs/mdx/meta.json | 3 +- apps/docs/content/docs/mdx/transform.mdx | 69 --------------------- apps/docs/content/docs/ui/meta.json | 1 + apps/docs/content/docs/ui/static-export.mdx | 24 +++++++ packages/ui/src/components/layout/toc.tsx | 2 +- 6 files changed, 33 insertions(+), 78 deletions(-) delete mode 100644 apps/docs/content/docs/mdx/transform.mdx create mode 100644 apps/docs/content/docs/ui/static-export.mdx diff --git a/apps/docs/content/docs/mdx/index.mdx b/apps/docs/content/docs/mdx/index.mdx index 7bfc2e320..357d8f7c1 100644 --- a/apps/docs/content/docs/mdx/index.mdx +++ b/apps/docs/content/docs/mdx/index.mdx @@ -37,6 +37,12 @@ const config = { export default withMDX(config); ``` + + + The Next.js config must be a `.mjs` file since Fumadocs is ESM-only. + + + ### Defining Collections **Collection** refers to a collection containing a certain type of files, there's two types of collections: @@ -116,12 +122,6 @@ Once you run `next dev` or `next build`, it generates a `.source` folder in root The folder contains all output data and its types, you should add it to `.gitignore`. - - -The Next.js config must be a `.mjs` file since Fumadocs is ESM-only. - - - The `fumadocs-mdx` command generates types for `.source` folder without running Next.js, you can add it as a post install script. ```json title="package.json" diff --git a/apps/docs/content/docs/mdx/meta.json b/apps/docs/content/docs/mdx/meta.json index 00b765601..97583ffc3 100644 --- a/apps/docs/content/docs/mdx/meta.json +++ b/apps/docs/content/docs/mdx/meta.json @@ -15,7 +15,6 @@ "---Features---", "last-modified", "image", - "manifest", - "!transform" + "manifest" ] } diff --git a/apps/docs/content/docs/mdx/transform.mdx b/apps/docs/content/docs/mdx/transform.mdx deleted file mode 100644 index 82e52bb0e..000000000 --- a/apps/docs/content/docs/mdx/transform.mdx +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Transform -description: Runtime Transformation on collection entries ---- - -## Introduction - -Fumadocs MDX bundles collection entries during build time, but this introduced some limitations on the configurations, forcing the output must be serializable. - -You can use `transform` to transform collection entries on Next.js runtime. -It includes extra benefits: - -- Unserializable output (e.g. functions) -- Server/Client Components -- Reference other parts of your Next.js apps - -### How does it works? - -This is possible by performing a transformation again on the bundled collection entries. -Everything is done on Next.js runtime, so using server/client components on `transform` is possible. - -Be careful that: - -- **Not cached by bundlers:** avoid expensive calculations in `transform`. -- **Use async imports:** Fumadocs MDX has to bundle the config file with esbuild before loading it. If importing a specific file results in errors, consider to use async import (`await import()`) instead. - -### Usage - -Pass a transform function. - -```ts -import { defineCollections } from 'fumadocs-mdx/config'; - -export const blog = defineCollections({ - type: 'doc', - transform: (entry) => { - return { - ...entry, - test: 'hello world', - }; - }, - // other props -}); -``` - -You can also use imports inside the function. - -```ts -import React from 'react'; -import { defineCollections } from 'fumadocs-mdx/config'; - -export const blog = defineCollections({ - type: 'doc', - transform: async (entry) => { - const { Component } = await import('./my-server-component'); - return { - ...entry, - test: React.createElement(Component, { - // props - }), - }; - }, - // other props -}); -``` - -### Build-time Transform - -To transform collection entries during build time, use [Schema](/docs/mdx/collections#schema) with [Zod `transform`](https://zod.dev/?id=transform) instead. diff --git a/apps/docs/content/docs/ui/meta.json b/apps/docs/content/docs/ui/meta.json index e48b04952..2a913ae69 100644 --- a/apps/docs/content/docs/ui/meta.json +++ b/apps/docs/content/docs/ui/meta.json @@ -10,6 +10,7 @@ "...", "---Setup---", "manual-installation", + "static-export", "(integrations)", "---Writing---", "markdown", diff --git a/apps/docs/content/docs/ui/static-export.mdx b/apps/docs/content/docs/ui/static-export.mdx new file mode 100644 index 000000000..728e50d7a --- /dev/null +++ b/apps/docs/content/docs/ui/static-export.mdx @@ -0,0 +1,24 @@ +--- +title: Static Export +description: Enable static export with Fumadocs +--- + +## Overview + +Fumadocs is fully compatible with Next.js static export, allowing you to export the app as a static HTML site without a Node.js server. + +```js title="next.config.mjs" +/** + * @type {import('next').NextConfig} + */ +const nextConfig = { + output: 'export', +}; +``` + +### Search + +The search functionality of Fumadocs rely on route handlers, which is not supported by static export. + +With the default search powered by Orama, you can build the search indexes statically following the [Orama Search](/docs/headless/search/orama#static-export) guide. +This allows the route handler to be statically cached into a single file, and search will be computed on browser instead. diff --git a/packages/ui/src/components/layout/toc.tsx b/packages/ui/src/components/layout/toc.tsx index fe7881e93..6512915fa 100644 --- a/packages/ui/src/components/layout/toc.tsx +++ b/packages/ui/src/components/layout/toc.tsx @@ -52,7 +52,7 @@ export function Toc(props: HTMLAttributes) { } as object } > -
+
{props.children}