建立文件

建立一個 Markdown 檔案，名為 greeting.md，並將其放在 docs 資料夾下。

website # root directory of your site
├── docs
│   └── greeting.md
├── src
│   └── pages
├── docusaurus.config.js
├── ...

---
description: Create a doc page with rich content.
---

# Hello from Docusaurus

Are you ready to create the documentation site for your open source project?

## Headers

will show up on the table of contents on the upper right

So that your users will know what this page is all about without scrolling down or even without reading too much.

## Only h2 and h3 will be in the TOC by default.

You can configure the TOC heading levels either per-document or in the theme configuration.

The headers are well-spaced so that the hierarchy is clear.

- lists will help you
- present the key points
- that you want your users to remember
  - and you may nest them
    - multiple times

備註

所有在 docs 資料夾下以底線 (_) 開頭的檔案都被視為「部分」頁面，預設會被忽略。

進一步瞭解 導入部分頁面。

文件 Front Matter

Front Matter 用於為您的文件頁面提供額外的中繼資料。Front Matter 是可選的，即使沒有 Front Matter，Docusaurus 也能推斷出所有必要的中繼資料。例如，下面介紹的 文件標籤 功能就需要使用 Front Matter。如需所有可用的欄位，請參閱 API 文件。

文件標籤

標籤在 Front Matter 中宣告，除了 文件側邊欄 之外，還引入了另一個分類維度。

可以內嵌定義標籤，也可以參考在 標籤檔案 中預先定義的標籤（可選，通常是 docs/tags.yml）。

在以下範例中

• docusaurus 參考了在 docs/tags.yml 中預先定義的標籤鍵。
• Releases 是一個內嵌標籤，因為它不存在於 docs/tags.yml 中。

docs/my-doc.md

---
tags:
  - Releases
  - docusaurus
---

# Title

Content

docs/tags.yml

docusaurus:
  label: 'Docusaurus'
  permalink: '/docusaurus'
  description: 'Docs related to the Docusaurus framework'

提示

也可以使用 tags: [Demo, Getting started] 來宣告標籤。

進一步瞭解所有可用的 Yaml 陣列語法。

組織資料夾結構

Markdown 檔案在 docs 資料夾下的排列方式可能會對 Docusaurus 內容產生多種影響。但是，其中大部分影響都可以與檔案結構分離。

文件 ID

每個文件都有一個唯一的 id。預設情況下，文件 id 是文件的名稱（不含副檔名），相對於根目錄下的 docs 資料夾。

例如，greeting.md 的 ID 是 greeting，而 guide/hello.md 的 ID 是 guide/hello。

website # Root directory of your site
└── docs
   ├── greeting.md
   └── guide
      └── hello.md

但是，id 的最後一部分可以由使用者在 Front Matter 中定義。例如，如果 guide/hello.md 的內容定義如下，則其最終 id 為 guide/part1。

---
id: part1
---

Lorem ipsum

在手動編寫側邊欄時，或使用與文件相關的佈局元件或鉤子時，會使用 ID 來參考文件。

文件網址

預設情況下，文件的網址位置是其相對於 docs 資料夾的檔案路徑，但有一些例外。也就是說，如果檔案名稱符合以下其中一項，則檔案名稱不會包含在網址中：

• 命名為 index（不區分大小寫）：docs/Guides/index.md
• 命名為 README（不區分大小寫）：docs/Guides/README.mdx
• 與父資料夾同名：docs/Guides/Guides.md

在所有情況下，預設的 slug 都只會是 /Guides，而不會包含 /index、/README 或重複的 /Guides 區段。

備註

這個慣例與 類別索引慣例 完全相同。但是，isCategoryIndex 設定不會影響文件網址。

使用 slug Front Matter 來變更文件的網址。

例如，假設您的網站結構如下：

website # Root directory of your site
└── docs
    └── guide
        └── hello.md

預設情況下，hello.md 將位於 /docs/guide/hello。您可以將其網址位置變更為 /docs/bonjour

---
slug: /bonjour
---

Lorem ipsum

slug 將附加到文件外掛的 routeBasePath，預設為 /docs。如需如何從網址中移除 /docs 部分，請參閱 僅限文件模式。

備註

可以使用

• 絕對 slug：slug: /mySlug、slug: /...
• 相對 slug：slug: mySlug、slug: ./../mySlug...

如果您希望文件位於根目錄下，並且路徑類似於 https://docusaurus.dev.org.tw/docs/，則可以使用 slug Front Matter：

---
id: my-home-doc
slug: /
---

Lorem ipsum

側邊欄

使用 自動產生側邊欄 時，檔案結構將決定側邊欄結構。

我們建議的檔案系統組織方式是：讓您的檔案系統反映側邊欄結構（這樣您就不需要手動編寫 sidebars.js 檔案），並使用 slug Front Matter 來自訂每個文件的網址。