# Fumadocs (Framework Mode, Astro): 快速入門
URL: /zh-TW/docs/astro
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/[framework]/index.zh-TW.mdx

開始使用 Fumadocs

# Set up Fumadocs

Instructions for AI agents to set up Fumadocs on Astro. The setup changes between versions, so run the commands below and read the linked docs instead of writing the setup from memory. Add `.md` to the URL of a docs page to read it as Markdown.

## New Site

Create a new docs site in a new folder, or as a workspace package of a monorepo:

```bash
npx create-fumadocs-app@latest my-docs --template astro --install --yes
```

- `my-docs` is the folder to create.
- `--yes` skips the prompts, and the options you don't pass use their defaults. The options are listed in https://fumadocs.dev/docs/cli/create-fumadocs-app.md

## Existing App

To add docs to an existing app, run the CLI in the folder of the app:

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

- The CLI detects the framework, and adds the docs pages with their own layout beside the existing routes.
- `--i18n` sets up internationalization.
- The CLI asks before it overwrites a file. Without a terminal, it keeps the file and prints its name. Pass `--yes` only when every file it writes can be overwritten.

To set up by hand, or to merge a file that the CLI kept, follow https://fumadocs.dev/docs/astro/manual-installation.md

## After the Setup

Both commands print the next steps. Start the dev server and open the docs, at `/docs` unless the output names another path.

For the tasks that follow, read the docs page of the task first:

- Writing pages: https://fumadocs.dev/docs/astro/markdown.md
- Organizing pages and folders: https://fumadocs.dev/docs/astro/page-conventions.md
- Customizing the UI: https://fumadocs.dev/docs/astro/guides/customize-ui.md
- Changing the theme and colors: https://fumadocs.dev/docs/ui/theme.md
- Other tasks: https://fumadocs.dev/llms.txt lists every docs page.

## 術語 [#terminology]

**Markdown/MDX：** Markdown 是一種用來撰寫格式化文字的標記語言。Fumadocs 原生支援 Markdown 與 MDX (Markdown 的超集) 。

**[Bun](https://bun.sh)：** 一種 JavaScript 執行階段，本指南會使用它來執行指令碼。如果您偏好 Node.js，可以改用 [unrun](https://gugustinette.github.io/unrun/guide/getting-started.html#cli)。

若想進一步自訂，具備一些 React.js 基礎知識會很有幫助。

## 自動安裝 [#automatic-installation]

需要 Node.js 22 或以上版本。

```npm
npm create fumadocs-app
```

系統會詢問您要使用哪一個內建範本：

* **框架**：Next.js、React Router、TanStack Start、Waku 和 Astro。
* **內容來源**：Fumadocs MDX 或 Astro 內容集合。

接著會初始化一個新的 Fumadocs 應用程式，並預設設定好以下功能：

* [LLM 整合](/docs/astro/integrations/llms)。
* [動態中繼資料圖片](/docs/astro/integrations/og)。

<Callout title="要從現有的程式碼庫開始？">
您可以參考[手動安裝](/docs/astro/manual-installation)指南來開始使用。
</Callout>

### 開始享受吧！ [#enjoy]

請在 docs 資料夾中建立您的第一個 MDX 檔案。

```mdx title="content/docs/index.mdx"
---
title: Hello World
---

## Yo what's up
```

以開發模式執行應用程式：

```npm
npm run dev
```

開啟 http://localhost:4321/docs 即可查看您的頁面。

## 常見問題 [#faq]

以下整理了您可能會遇到的一些常見問題。

<Accordions>
<Accordion id="upgrade-fumadocs" title="遇到 API 缺失或程式錯誤的問題？">
該 API 或修正可能只在較新的版本中提供。請[升級 Fumadocs](/docs/astro/upgrade) 後再試一次。
</Accordion>

<Accordion id="change-base-url" title="如何變更文件的基底路由？">
路由由 Astro 處理。請先移動文件路由 (`/docs/*` -&gt; `/info/*`) 。

將 `src/pages/docs` 移至 `src/pages/info`。

最後，請在 `source.ts` 中更新頁面的基礎 URL：

```ts title="lib/source.ts"
import { loader } from 'fumadocs-core/source';

export const source = loader({
  baseUrl: '/info', // 改成新的路徑 [!code highlight]
});
```

範本在 `lib/shared.ts` 中將此值定義為 `docsRoute`，請在該處修改，Markdown 連結便會隨之更新。
</Accordion>

<Accordion id="multi-docs" title="如何實作多份文件？">
建議使用[版面配置頁籤](/docs/ui/layouts/docs#layout-tabs)。
</Accordion>

<Accordion id="custom-layout-docs-page" title="如何在 /docs 中建立不使用文件版面配置的頁面？">
請在 `src/pages/docs/` 中建立一個不使用 `Docs` island 的獨立 `.astro` 頁面，並從 `content/docs` 中移除對應的 MDX 檔案，以免同一個 URL 出現兩次。
</Accordion>
</Accordions>

## 深入了解 [#learn-more]

剛開始接觸嗎？別擔心，我們非常歡迎您提出任何問題。

如果有任何令您困惑的地方，歡迎到 [Github Discussion](https://github.com/fuma-nama/fumadocs/discussions) 提供您的意見回饋！

### 撰寫內容 [#writing-content]

撰寫文件前，請務必閱讀：

<Cards>
<Card href="/docs/markdown" title="Markdown">
/docs/astro/markdown" title="Markdown">
  Fumadocs 提供了一些額外功能，協助您撰寫內容。
</Card>

<Card href="/docs/navigation" title="導覽">
/docs/astro/navigation" title="導覽">
  了解如何自訂導覽結構。
</Card>

<Card href="/docs/page-conventions" title="頁面 Slug 與頁面樹">
/docs/astro/page-conventions" title="頁面 Slug 與頁面樹">
  了解如何組織內容。
</Card>

<Card href="/docs/ui/components" title="元件" description="瀏覽所有可用元件，讓您的文件更豐富" />
</Cards>

### 特殊需求 [#special-needs]

<Cards>
<Card href="/docs/deploying/static" title="設定靜態匯出" description="了解如何為您的文件網站啟用靜態匯出">
/docs/astro/deploying/static
</Card>

<Card href="/docs/internationalization" title="國際化" description="了解如何啟用 i18n">
/docs/astro/internationalization
</Card>

<Card href="/docs/ui/theme" title="色彩主題" description="為 Fumadocs UI 加入主題" />

<Card href="/docs/ui/layouts" title="版面配置" description="自訂您的 Fumadocs UI 版面配置" />
</Cards>