Markdown
如何撰寫文件
簡介
Fumadocs 為標記語言 MDX 提供了許多實用的擴充功能。以下簡要介紹 Fumadocs 預設的 MDX 語法。
MDX 並非 Fumadocs 唯一支援的格式。事實上，您可以使用任何算繪器，例如無頭式 CMS。
詳情請參閱自訂內容來源。
MDX
我們建議使用 MDX，它是 Markdown 的超集，支援 JSX 語法。 您可以匯入元件並在文件中使用，甚至能直接撰寫 JavaScript。
請參閱：
import { Component } from './component';
<Component name="Hello" />
## Heading
### Heading
#### Heading
Hello World, **Bold**, _Italic_, ~~Hidden~~
1. First
2. Second
3. Third
- Item 1
- Item 2
> Quote here
| Table | Description |
| ----- | ----------- |
| Hello | World |Frontmatter
Fumadocs 預設支援 YAML 格式的 frontmatter，其中 title 在 Fumadocs UI 中代表頁面標題 (h1) 。
---
title: This is a document
---
...因此，撰寫 Markdown/MDX 時通常不會使用 h1 標題 (# Heading) ，除非您有自訂的頁面標題算繪邏輯。
若您的內容來源支援，也可以在程式碼中匯出 frontmatter。匯出的值會合併並覆蓋 YAML frontmatter，且可以讀取 props：
---
title: Deploy
---
export const frontmatter = {
description: `Deploy your ${props.framework} site.`,
};在 Fumadocs MDX 中
您可以使用 schema 選項新增 frontmatter 屬性。詳情請參閱自訂 frontmatter。
自動連結
內部連結會使用您 React 框架的 <Link /> 元件，以支援預先載入並避免整頁重新載入。
基於安全考量，外部連結會自動加上預設的 rel="noreferrer noopener" target="_blank" 屬性。
[My Link](https://github.github.com/gfm)
This also works: https://github.github.com/gfm.卡片
適合用來加入連結。
import { HomeIcon } from 'lucide-react';
<Cards>
<Card href="/docs" title="Documentation">
Browse the full documentation.
</Card>
<Card title="href is optional">Cards can hold plain content too.</Card>
<Card icon={<HomeIcon />} href="/" title="Home">
You can include icons too.
</Card>
</Cards>「延伸閱讀」區塊
您可以參考以下寫法：
import { getPageTreePeers } from 'fumadocs-core/page-tree';
import { source } from '@/lib/source';
<Cards>
{getPageTreePeers(source.getPageTree(), '/docs/my-page').map((peer) => (
<Card key={peer.url} title={peer.name} href={peer.url}>
{peer.description}
</Card>
))}
</Cards>;這會以卡片形式列出同一資料夾中的其他頁面。
Callouts
適合用來加入提示或警告，預設即已內建。您可以指定 Callout 的類型：
info(預設)warn/warningerrorsuccessidea
<Callout>Hello World</Callout>
<Callout title="Title" type="warn">
Hello World
</Callout>
<Callout title="Title" type="error">
Hello World
</Callout>
<Callout title="Title" type="idea">
Hello World
</Callout>標題
你好，世界
標題
你好，世界
標題
你好，世界
標題
每個標題都會自動加上錨點，並將空格等無效字元轉換為有效格式 (例如 Hello World 會轉為 hello-world) 。
# Hello `World`目錄設定
目錄 (TOC) 會根據標題自動產生，您也可以自訂標題在目錄中的呈現方式：
# Heading [!toc]
This heading will be hidden from TOC.
# Another Heading [toc]
This heading will **only** be visible in TOC, you can use it to add additional TOC items.
Like headings rendered in a React component:
<MyComp />自訂錨點
您可以加上 [#slug] 來自訂標題錨點。
# heading [#my-heading-id]您也可以搭配目錄設定一起使用，例如：
# heading [toc] [#my-heading-id]若要讓他人透過連結直接前往特定標題，請將標題 ID 加到雜湊片段 (hash fragment) 中：/page#my-heading-id。
程式碼區塊
預設已透過 Rehype Code 支援語法突顯。
```js
console.log('Hello World');
```
```js title="My Title"
console.log('Hello World');
```行號
顯示行號，亦可搭配 Twoslash 及其他 transformer 使用。
```ts twoslash lineNumbers
const a = 'Hello World';
// ^?
console.log(a);
```您可以設定行號的起始值。
```js lineNumbers=4
function main() {
console.log('starts from 4');
return 0;
}
```Shiki Transformers
我們支援部分 Shiki Transformers，讓您能夠突顯特定行或為其設定樣式。
```tsx
// 突顯單行
<div>Hello World</div> // [!code highlight]
// 突顯特定字詞
// [!code word:Fumadocs]
<div>Fumadocs</div>
// diff 樣式
console.log('hewwo'); // [!code --]
console.log('hello'); // [!code ++]
// 聚焦
return new ResizeObserver(() => {}) // [!code focus]
```頁籤群組
```ts tab="Tab 1"
console.log('A');
```
```ts tab="Tab 2"
console.log('B');
```console.log('A');若要加入持久化 ID，請在第一個程式碼區塊上定義 tab-group：
```ts tab="Tab 1" tab-group="my-custom-group"
console.log('A');
```
```ts tab="Tab 2"
console.log('B');
```console.log('A');另一個群組：
console.log('A');在頁籤群組中使用 MDX
頁籤群組由 remarkCodeTab remark 外掛提供，Fumadocs MDX 預設會啟用此外掛。若要在頁籤值中使用 MDX，請啟用它的 parseMdx 選項：
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
remarkCodeTabOptions: {
parseMdx: true,
},
},
});```ts tab="<Building /> Tab 1"
console.log('A');
```
```ts tab="<Rocket /> Tab 2"
console.log('B');
```console.log('A');引入
引用另一個檔案 (也可以是 Markdown/MDX 文件) 。Fumadocs MDX 透過 Remark 引入 預設啟用此功能。
請在 <include> 標籤中指定目標檔案路徑 (相對於該 MDX 檔案本身) 。
<include>./another.mdx</include>請參閱引入的其他用法。
Props
頁面的 props 可在 MDX 中透過 props 存取。例如，位於 [framework] 資料夾中的頁面，會從其路徑參數取得 framework：
## Deploy on {props.framework}
Deploy your {props.framework} site.表達式在目錄、搜尋索引以及提供給 LLM 的 Markdown 中，同樣會被替換為其計算後的值。在 Astro 頁面上，上方標題的 ID 會是 deploy-on-astro。
您也可以將自訂 props 傳遞給頁面。
Show
依條件算繪內容。Fumadocs MDX 預設已透過 Remark Show 啟用此功能。
when 是可讀取 props 的 JavaScript 表達式：
<show when={props.framework === 'astro'}>
## Adapters
Add an adapter to your Astro config.
</show>此區段只會在 framework 為 astro 的頁面上算繪。在其他頁面上，這個區段也不會出現在目錄、搜尋索引，以及提供給 LLM 的 Markdown 中。
您也可以用 <show> 包住步驟：
### 建置 [step]
<show when={props.framework === 'astro'}>
### 新增轉接器 [step]
</show>
### 部署 [step]未算繪的步驟不會計入編號：在 Astro 頁面上，Deploy 是第 3 步；在其他頁面上則是第 2 步。
頁籤群組中的程式碼區塊也是如此。只有在對應的程式碼區塊有算繪時，該頁籤才會顯示。
NPM 指令
可用來產生各種套件管理器的套件安裝指令。
```npm
npm i next -D
```詳情請參閱 remark-npm。
步驟
適合用來標示指南中的步驟，啟用與設定方式請參閱 remark-steps。
### Installation [step]
### Write Code [step]
### Deploy [step]其他元件
您可以在 MDX 文件中設定並使用內建元件，例如 Tabs、Accordion 和 Zoomable Image。
其他功能
您可能也會感興趣：
How is this guide?
最後更新於
General Translation
Ferry Health
assistant-ui
Inkeep