167 lines
3.7 KiB
Plaintext
167 lines
3.7 KiB
Plaintext
---
|
|
title: Docs Layout
|
|
description: The layout of documentation
|
|
---
|
|
|
|
The layout of documentation pages, it includes a sidebar and mobile-only navbar.
|
|
|
|
> It is a server component, you should not reference it in a client component.
|
|
|
|
## Usage
|
|
|
|
Pass your page tree to the component.
|
|
|
|
```tsx title="layout.tsx"
|
|
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
|
|
import { baseOptions } from '@/app/layout.config';
|
|
import type { ReactNode } from 'react';
|
|
|
|
export default function Layout({ children }: { children: ReactNode }) {
|
|
return (
|
|
<DocsLayout {...baseOptions} tree={tree}>
|
|
{children}
|
|
</DocsLayout>
|
|
);
|
|
}
|
|
```
|
|
|
|
{/* <AutoTypeTable
|
|
path="./content/docs/props.ts"
|
|
type="Omit<DocsLayoutProps, 'children' | 'disableThemeSwitch'>"
|
|
/> */}
|
|
|
|
## Sidebar
|
|
|
|
```tsx title="layout.tsx"
|
|
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
|
|
|
|
<DocsLayout
|
|
sidebar={{
|
|
// sidebar options:
|
|
enabled: true,
|
|
}}
|
|
/>;
|
|
```
|
|
|
|
{/* <AutoTypeTable path="./content/docs/props.ts" name="SidebarProps" /> */}
|
|
|
|
### Sidebar Tabs
|
|
|
|
See [Navigation Guide](/docs/navigation/sidebar#sidebar-tabs) for usages.
|
|
|
|
#### Decoration
|
|
|
|
Change the icon/styles of tabs.
|
|
|
|
```tsx
|
|
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
|
|
|
|
<DocsLayout
|
|
sidebar={{
|
|
tabs: {
|
|
transform: (option, node) => ({
|
|
...option,
|
|
icon: 'my icon',
|
|
}),
|
|
},
|
|
}}
|
|
/>;
|
|
```
|
|
|
|
## Nav
|
|
|
|
A mobile-only navbar, we recommend to customise it from `baseOptions`.
|
|
|
|
<div className='max-w-[460px] mx-auto'>
|
|
|
|
|
|
|
|
</div>
|
|
|
|
```tsx
|
|
import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
|
|
|
|
export const baseOptions: BaseLayoutProps = {
|
|
githubUrl: 'https://github.com/fuma-nama/fumadocs',
|
|
nav: {
|
|
title: 'My App',
|
|
},
|
|
};
|
|
```
|
|
|
|
{/* <AutoTypeTable
|
|
path="./content/docs/props.ts"
|
|
type="Omit<NavbarProps, 'children'>"
|
|
/> */}
|
|
|
|
### Transparent Mode
|
|
|
|
To make the navbar background transparent, you can configure transparent mode.
|
|
|
|
```tsx
|
|
import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
|
|
|
|
export const baseOptions: BaseLayoutProps = {
|
|
nav: {
|
|
transparentMode: 'top',
|
|
},
|
|
};
|
|
```
|
|
|
|
| Mode | Description |
|
|
| -------- | ---------------------------------------- |
|
|
| `always` | Always use a transparent background |
|
|
| `top` | When at the top of page |
|
|
| `none` | Disable transparent background (default) |
|
|
|
|
### Replace Navbar
|
|
|
|
To replace the navbar in Docs Layout, set `nav.component` to your own component.
|
|
|
|
```tsx title="layout.tsx"
|
|
import { baseOptions } from '@/app/layout.config';
|
|
import { DocsLayout } from 'fumadocs-ui/layouts/notebook';
|
|
import type { ReactNode } from 'react';
|
|
|
|
export default function Layout({ children }: { children: ReactNode }) {
|
|
return (
|
|
<DocsLayout
|
|
{...baseOptions}
|
|
nav={{
|
|
component: <CustomNavbar />,
|
|
}}
|
|
>
|
|
{children}
|
|
</DocsLayout>
|
|
);
|
|
}
|
|
```
|
|
|
|
Fumadocs uses **CSS Variables** to share the size of layout components, and fit each layout component into appropriate position.
|
|
|
|
You need to override `--fd-nav-height` to the exact height of your custom navbar, this can be done with a CSS stylesheet (e.g. in `global.css`):
|
|
|
|
```css
|
|
:root {
|
|
--fd-nav-height: 80px !important;
|
|
}
|
|
```
|
|
|
|
## Advanced
|
|
|
|
### Disable Prefetching
|
|
|
|
By default, it uses the Next.js Link component with prefetch enabled.
|
|
When the link component appears into the browser viewport, the content (RSC payload) will be prefetched.
|
|
|
|
On Vercel, this may cause a high usage of serverless functions and Data Cache.
|
|
It can also hit the limits of some other hosting platforms.
|
|
|
|
You can disable prefetching to reduce the amount of RSC requests.
|
|
|
|
```tsx
|
|
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
|
|
|
|
<DocsLayout sidebar={{ prefetch: false }} />;
|
|
```
|