跳至主要內容
版本：3.5.2

Markdown 功能

Docusaurus 使用Markdown作為其主要內容撰寫格式。

學習 Markdown

您可以在 10 分鐘內學會 Markdown。

Docusaurus 使用現代工具協助您建立互動式說明文件。

MDX 編譯器將 Markdown 檔案轉換成 React 元件，並讓您在 Markdown 內容中使用 JSX。這讓您可以輕鬆地在內容中穿插 React 元件，並創造令人愉快的學習體驗。

使用 MDX Playground

MDX playground 是您最好的新朋友！

它是一個很有幫助的除錯工具，可以顯示 MDX 編譯器如何將 Markdown 轉換為 React。

選項：選擇正確的格式（MDX 或 CommonMark），以及 Docusaurus 使用的以下外掛程式：remark-gfm、remark-directive、rehype-raw。

MDX 與 CommonMark​

Docusaurus 使用 MDX 編譯器將 .md 和 .mdx 檔案編譯成 React 元件，但語法會根據您的設定以不同的方式來詮釋。

MDX 編譯器支援 2 種格式

  • MDX 格式：一個功能強大的剖析器，允許使用 JSX
  • CommonMark 格式：一個相容於標準的 Markdown 剖析器，不允許使用 JSX

預設情況下，Docusaurus v3 對所有檔案一律使用 MDX 格式（包括 .md 檔案），原因基於歷史因素。

可以透過 siteConfig.markdown.format 設定或 format: md 前置標記手動選擇 CommonMark。

如何使用 CommonMark

如果您計畫使用 CommonMark，我們建議使用 siteConfig.markdown.format: 'detect' 設定。將根據檔案副檔名自動選取適當的格式

  • .md 檔案將採用 CommonMark 格式
  • .mdx 檔案將採用 MDX 格式
實驗性 CommonMark 支援

CommonMark 支援為實驗性質，目前有幾個 限制.

標準功能​

Markdown 是一種語法，讓您能使用可讀性高的語法寫出格式化的內容。

### My Doc Section

Hello world message with some **bold** text, some _italic_ text, and a [link](/)

![img alt](/img/docusaurus.png)
https://127.0.0.1:3000

我的文件區段

問候世界的訊息，包含一些粗體文字、一些斜體文字和一個 連結

img alt

Markdown 具備宣告式

有些人可能假設 Markdown 和 HTML 之間有 1 對 1 的對應關係，例如 ![Preview](/img/docusaurus.png) 永遠會變成 <img src="/img/docusaurus.png" alt="Preview" />，原樣不變。不過，事實並非如此。

Markdown 語法 ![message](url) 僅宣告性地告訴 Docusaurus 此處需要插入一張圖片，但我們可以執行其他操作，例如將 檔案路徑轉換成 URL 路徑，因此產生的標記可能與其他 Markdown 呈現器 (renderer) 的輸出結果不同，或者與等效 JSX/HTML 程式碼的單調手動轉錄不同。

一般而言，您只能假設標記的語義（``` 欄位變成 程式碼區塊；> 變成 引號，依此類推），而非實際已編譯的輸出。

前端說明​

前端說明用於新增中繼資料到您的 Markdown 檔案。所有內容外掛程式都有其自己的前端說明架構，並使用前端說明來豐富從內容或其他設定推斷出的預設中繼資料。

前端說明提供在檔案的頂端，以三個連字號 --- 加以封裝。內容解析為 YAML。

---
title: My Doc Title
more_data:
  - Can be provided
  - as: objects
    or: arrays
---
資訊

每個官方外掛程式的 API 文件清單都列出受支援的屬性

加強你的前言

使用 Markdown 設定檔中 parseFrontMatter 函式 提供你自己的前言剖析器，或加強預設剖析器。

可以重複使用預設剖析器來搭配你自己的客製化專有邏輯。這使得可以實作便利的前言轉換、捷徑，或使用 Docusaurus 外掛程式不支援的前言與外部系統整合。

docusaurus.config.js
export default {
  markdown: {
    parseFrontMatter: async (params) => {
      // Reuse the default parser
      const result = await params.defaultParseFrontMatter(params);

      // Process front matter description placeholders
      result.frontMatter.description =
        result.frontMatter.description?.replaceAll('{{MY_VAR}}', 'MY_VALUE');

      // Create your own front matter shortcut
      if (result.frontMatter.i_do_not_want_docs_pagination) {
        result.frontMatter.pagination_prev = null;
        result.frontMatter.pagination_next = null;
      }

      // Rename an unsupported front matter coming from another system
      if (result.frontMatter.cms_seo_summary) {
        result.frontMatter.description = result.frontMatter.cms_seo_summary;
        delete result.frontMatter.cms_seo_summary;
      }

      return result;
    },
  },
};

引號​

Markdown 引號具有美麗的樣式

> Easy to maintain open source documentation websites.
>
> — Docusaurus
https://127.0.0.1:3000

易於維護的開源文件網站。

— Docusaurus

詳細資訊​

Markdown 可以嵌進 HTML 元素，而 details HTML 元素具有美麗的樣式

### Details element example

<details>
  <summary>Toggle me!</summary>

  This is the detailed content

  ```js
  console.log("Markdown features including the code block are available");
  ```

  You can use Markdown here including **bold** and _italic_ text, and [inline link](https://docusaurus.dev.org.tw)
  <details>
    <summary>Nested toggle! Some surprise inside...</summary>

    😲😲😲😲😲
  </details>
</details>
https://127.0.0.1:3000

詳細元素範例

切換我！

這是詳細內容

console.log("Markdown features including the code block are available");

你可以使用 Markdown，包括粗體和斜體文字，以及 內嵌連結

巢狀切換！內有驚喜...

😲😲😲😲😲

資訊

你可以將你的 <summary> 保持在單一列。請記住 MDX 會為換行符號建立額外的 HTML <p> 段落。。有疑問時，可以使用 MDX 遊樂場 來排除 <details> 繪製問題。