# Fumadocs UI (the default theme of Fumadocs): 文件頁面
URL: /zh-TW/docs/ui/layouts/page
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/layouts/page.zh-TW.mdx

您文件中的一個頁面

Page 是文件頁面的基本元素，其中包含目錄、
頁尾和 Breadcrumb。

For advanced customization that supported options cannot suffice, install via Fumadocs CLI:

```bash
npx @fumadocs/cli@latest customize
```

## 使用方式 [#usage]

請根據您使用的版面配置匯入。

```tsx title="page.tsx" tab="Docs Layout"
import { DocsPage, DocsDescription, DocsTitle, DocsBody } from 'fumadocs-ui/layouts/docs/page';

<DocsPage>
  <DocsTitle>title</DocsTitle>
  <DocsDescription>description</DocsDescription>
  <DocsBody>
    <h2>This heading looks good!</h2>
    It applies the Typography styles, wrap your content here.
  </DocsBody>
</DocsPage>;
```

```tsx title="page.tsx" tab="Notebook Layout"
import { DocsPage, DocsDescription, DocsTitle, DocsBody } from 'fumadocs-ui/layouts/notebook/page';

<DocsPage>
  <DocsTitle>title</DocsTitle>
  <DocsDescription>description</DocsDescription>
  <DocsBody>
    <h2>This heading looks good!</h2>
    It applies the Typography styles, wrap your content here.
  </DocsBody>
</DocsPage>;
```

<Callout type="info" title="小提示">
除了在 `page.tsx` 中使用 `DocsTitle` 算繪標題，您也可以直接將標題寫在 MDX 檔案中。
如此一來，標題就會在 MDX 內文中算繪。
</Callout>

### 頁面操作 [#page-actions]

顯示 GitHub 連結，以及開啟各 AI 工具的快捷連結。

```tsx
import { DocsPage, ViewOptionsPopover } from 'fumadocs-ui/layouts/<layout>/page';

const githubUrl = `https://github.com/fuma-nama/fumadocs/blob/main/content/docs/${encodeURI(page.path)}`

<DocsPage>
  <ViewOptionsPopover githubUrl={githubUrl} />
</DocsPage>;
```

### 最後更新時間 [#last-updated-time]

顯示頁面的最後更新時間。

```tsx
import { DocsPage, PageLastUpdate } from 'fumadocs-ui/layouts/<layout>/page';

const lastModifiedTime: Date | undefined;

<DocsPage>
  {/* 其他內容 */}
  {lastModifiedTime && <PageLastUpdate date={lastModifiedTime} />}
</DocsPage>;
```

至於 `lastModifiedTime`，您可以視情況改用 GitHub 或 CMS 等不同的版本控制來源。

<Tabs items={["Fumadocs MDX","GitHub API"]}>
<Tab>
您可以啟用 [`lastModified`](/docs/mdx/last-modified)。

```tsx
import { source } from '@/lib/source';
const page = source.getPage(['...']);

const lastModifiedTime = page.data.lastModified;
```
</Tab>

<Tab>
若文件託管於 GitHub，您可以使用
[`getGithubLastEdit`](/docs/headless/utils/git-last-edit) 工具函式。

```tsx
import { getGithubLastEdit } from 'fumadocs-core/content/github';

const lastModifiedTime = await getGithubLastEdit({
  owner: 'fuma-nama',
  repo: 'fumadocs',
  // Git 中的檔案路徑
  path: `content/docs/${page.path}`,
});
```
</Tab>
</Tabs>

## 設定 [#configurations]

### 全寬模式 [#full-mode]

若要讓頁面延展並填滿所有可用空間，請將 `full` 傳給頁面元件。
這會強制以彈出視窗的形式顯示目錄。

```tsx
import { DocsPage } from 'fumadocs-ui/layouts/<layout>/page';

<DocsPage full>...</DocsPage>;
```

### 目錄 [#table-of-contents]

列出文章中所有標題的總覽，需要傳入一個標題陣列。

對於 Markdown 和 MDX 文件，您可以使用
[目錄工具](/docs/headless/utils/get-toc)取得。Fumadocs MDX 等內容來源已內建此功能。

```tsx
import { DocsPage } from 'fumadocs-ui/layouts/<layout>/page';

<DocsPage toc={headings}>...</DocsPage>;
```

您可以透過 `tableOfContent` 自訂目錄；在較小的裝置上，則可改用 `tableOfContentPopover`。

```tsx title="page.tsx"
import { DocsPage } from 'fumadocs-ui/layouts/<layout>/page';

return (
  <DocsPage tableOfContent={options} tableOfContentPopover={options}>
    ...
  </DocsPage>
);
```

### $Fumadocs

| Prop         | Type                                                                                                          | Description                                          |
| ------------ | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `container?` | `React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement> \| undefined`                  |                                                      |
| `header?`    | `React.ReactNode`                                                                                             | Custom content in TOC container, before the main TOC |
| `footer?`    | `React.ReactNode`                                                                                             | Custom content in TOC container, after the main TOC  |
| `style?`     | `"block" \| "clerk" \| "normal" \| undefined`                                                                 |                                                      |
| `list?`      | `TOCItemsProps \| React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement> \| undefined` |                                                      |

#### 樣式 [#style]

為目錄選擇其他樣式：

<Wrapper>
<TOCStylePreview>
<TOCStyle value="normal">
軌道線搭配滑塊，標示目前所在的標題 (預設) 。
</TOCStyle>

<TOCStyle value="clerk">
軌道線隨標題層級轉折，設計靈感來自 [Clerk](https://clerk.com)。
</TOCStyle>

<TOCStyle value="block">
不顯示軌道線，改以區塊在目前所在的標題後方滑動。
</TOCStyle>
</TOCStylePreview>
</Wrapper>

```tsx
import { DocsPage } from 'fumadocs-ui/layouts/<layout>/page';

<DocsPage
  tableOfContent={{
    style: 'clerk',
  }}
>
  ...
</DocsPage>;
```

#### 替換目錄 [#replace-toc]

若要替換此元件：

```tsx tab="page.tsx"
import { TOCProvider, TOC, TOCPopover } from './my-toc';

return (
  <DocsPage
    slots={{
      toc: {
        provider: TOCProvider,
        main: TOC,
        popover: TOCPopover,
      },
    }}
  >
    ...
  </DocsPage>
);
```

```tsx tab="my-toc.tsx"
'use client';
import type {
  TOCProps,
  TOCPopoverProps,
  TOCProviderProps,
} from 'fumadocs-ui/layouts/<layout>/page/slots/toc';

export function TOCProvider({ toc, children }: TOCProviderProps) {
  // 接收目錄項目，可透過 React context 向下傳遞
  console.log(toc);
  return children;
}

export function TOC(props: TOCProps) {
  return <div>Hello World</div>;
}

export function TOCPopover(props: TOCPopoverProps) {
  return <div>Popover</div>;
}
```

您可以使用 Fumadocs CLI，以預設實作為基礎開始修改：

```bash tab="Docs Layout"
npx @fumadocs/cli add slots/docs/page/toc
```

```bash tab="Notebook Layout"
npx @fumadocs/cli add slots/notebook/page/toc
```

```bash tab="Flux Layout"
npx @fumadocs/cli add slots/flux/page/toc
```

### 頁尾 [#footer]

頁尾是一種導覽元素，提供兩個按鈕，可跳至上一頁與下一頁。若未指定，則會顯示從頁面樹中找到的相鄰頁面。

您可以透過 `footer` prop 自訂頁尾：

```tsx
import { DocsPage } from 'fumadocs-ui/layouts/<layout>/page';

<DocsPage footer={options}>...</DocsPage>;
```

### $Fumadocs

| Prop     | Type                                             | Description                                                |
| -------- | ------------------------------------------------ | ---------------------------------------------------------- |
| `items?` | `{ previous?: Item; next?: Item; } \| undefined` | Items including information for the next and previous page |

#### 替換頁尾 [#replace-footer]

若要替換此元件：

```tsx tab="page.tsx"
import { DocsPage } from 'fumadocs-ui/layouts/<layout>/page';
import { Footer } from './my-footer';

<DocsPage
  slots={{
    footer: Footer,
  }}
/>;
```

```tsx tab="my-footer.tsx"
'use client';
import type { FooterProps } from 'fumadocs-ui/layouts/<layout>/page/slots/footer';

export function Footer(props: FooterProps) {
  return <div>Hello World</div>;
}
```

您可以使用 Fumadocs CLI，以預設實作為基礎開始修改：

```bash tab="Docs Layout"
npx @fumadocs/cli add slots/docs/page/footer
```

```bash tab="Notebook Layout"
npx @fumadocs/cli add slots/notebook/page/footer
```

```bash tab="Flux Layout"
npx @fumadocs/cli add slots/flux/page/footer
```

### Breadcrumb [#breadcrumb]

一種導覽元素，僅在使用者瀏覽資料夾內的頁面時顯示。

您可以透過 `breadcrumb` 選項自訂 Breadcrumb：

```tsx
import { DocsPage } from 'fumadocs-ui/layouts/<layout>/page';

<DocsPage breadcrumb={options}>...</DocsPage>;
```

### $Fumadocs

| Prop                | Type                                       | Description                                                              |
| ------------------- | ------------------------------------------ | ------------------------------------------------------------------------ |
| `includeRoot?`      | `boolean \| { url: string; } \| undefined` | Include the root folders in the breadcrumb items array. Default: `false` |
| `includePage?`      | `boolean \| undefined`                     | Include the page itself in the breadcrumb items array Default: `false`   |
| `includeSeparator?` | `boolean \| undefined`                     | Count separator as an item Default: `false`                              |

#### 替換 Breadcrumb [#replace-breadcrumb]

若要替換此元件：

```tsx tab="page.tsx"
import { DocsPage } from 'fumadocs-ui/layouts/<layout>/page';
import { Breadcrumb } from './my-breadcrumb';

<DocsPage
  slots={{
    breadcrumb: Breadcrumb,
  }}
/>;
```

```tsx tab="my-breadcrumb.tsx"
'use client';
import type { BreadcrumbProps } from 'fumadocs-ui/layouts/<layout>/page/slots/breadcrumb';

export function Breadcrumb(props: BreadcrumbProps) {
  return <div>Hello World</div>;
}
```

您可以使用 Fumadocs CLI，以預設實作為基礎開始修改：

```bash tab="Docs Layout"
npx @fumadocs/cli add slots/docs/page/breadcrumb
```

```bash tab="Notebook Layout"
npx @fumadocs/cli add slots/notebook/page/breadcrumb
```

```bash tab="Flux Layout"
npx @fumadocs/cli add slots/flux/page/breadcrumb
```

### 容器 [#container]

容器負責控制包覆 Breadcrumb、內文與頁尾的文章外層元素。

若要替換頁面容器：

```tsx tab="page.tsx"
import { DocsPage } from 'fumadocs-ui/layouts/<layout>/page';
import { Container } from './my-container';

<DocsPage
  slots={{
    container: Container,
  }}
/>;
```

```tsx tab="my-container.tsx"
'use client';

export function Container(props: React.ComponentProps<'article'>) {
  return <div />;
}
```

您可以使用 Fumadocs CLI，以預設實作為基礎開始：

```bash tab="Docs Layout"
npx @fumadocs/cli add slots/docs/page/container
```

```bash tab="Notebook Layout"
npx @fumadocs/cli add slots/notebook/page/container
```

```bash tab="Flux Layout"
npx @fumadocs/cli add slots/flux/page/container
```