Markdown語法

Markdown 是一種輕量級標記語言，允許你使用易讀易寫的純文字格式編寫文件。MkDocs 完美支援標準 Markdown，並透過擴充功能強化了技術文件的表現力。

在 MkDocs 中，除了 Markdown 語法外，同時也支援 html 語法，所以如果有需要的話也可以使用，但為了確保撰寫時一致性與乾淨易讀，建議儘量避免。

標題 Headings

# 第一級標題 (h1)
## 第二級標題 (h2)
### 第三級標題 (h3)

文字 Paragraph

粗體：**文字**
斜體：*文字*
刪除線：~~文字~~
超連結：[超連結文字](url)
水平線：---

標註 Mark

標註配置

請先在 mkdocs.yml 中 markdown_extensions 下加入

markdown_extensions:
  - pymdownx.mark

標註語法

==這段很重要==

圖片 Image

![圖片資訊](url)

清單 List

無序清單

- 項目 1
- 細目 2
    - 項目 2.1
    - 項目 2.2

有序清單

1. 項目 1
2. 細目 2
    1. 項目 2.1
    2. 項目 2.2

引用 Blockquote

> 這裡寫引用的內容

程式碼 Code

行內程式碼

`mkdocs serve`

高亮程式碼

```python
def hello_mkdocs():
    print("Hello, MkDocs!")
```

表格 Table

表格內容可以加入超連結等其他格式或圖片

| 項目 | 活動名稱 | 活動時間 | 活動地點 |
|-----|-----|-----|-----|
| 1 | 台北燈節 | YYYYMMDD | 西門徒步區 |
| 2 | 新北燈會 | YYYYMMDD | 三重大都會公園 |

左對齊：:--- (預設)
右對齊：---:
置中對齊：:---:

工作清單 Task List

常用於展示開發進度或確認事項。

工作清單配置

請先在 mkdocs.yml 中 markdown_extensions 下加入

markdown_extensions:
  - pymdownx.tasklist:
      custom_checkbox: true  # 使用漂亮的自定義勾選框（建議開啟）
      clickable_checkbox: true # 如果你希望在網頁上可以直接點擊（雖然不會存回檔案）

工作清單語法

- [x] 已完成事項
- [ ] 待辦事項

分頁標籤 Content Tabs

這是 Material for MkDocs 非常強大的功能，適合用來展示「不同程式語言」的範例。

分頁標籤配置

請先在 mkdocs.yml 中 markdown_extensions 下加入

markdown_extensions:
  - pymdownx.tabbed

分頁標籤語法

=== "Python"
    ```python
    print("Hello")
    ```
=== "JavaScript"
    ```javascript
    console.log("Hello")
    ```

鍵盤符號 Keys

這對於撰寫教學手冊（例如：請按 Ctrl + C）非常美觀。

鍵盤符號配置

請先在 mkdocs.yml 中 markdown_extensions 下加入

markdown_extensions:
  - pymdownx.keys

鍵盤符號語法

++ctrl+c++

註腳 Footnotes

這對於補充專業術語的定義非常有幫助。

註腳配置

請先在 mkdocs.yml 中 markdown_extensions 下加入

markdown_extensions:
  - footnotes  # 開啟註腳功能
  - attr_list  # (選配) 建議也開啟，這能讓註腳更靈活

註腳語法

這是一個帶有註腳的句子[^1]。

[^1]: 這是註腳的內容，會顯示在頁面最下方。

警告框 Admonition

警告框配置

請先在 mkdocs.yml 中 markdown_extensions 下加入

markdown_extensions:
  - admonition
  - pymdownx.details

警告框語法

展開式警告框

!!! info "Lorem ipsum"

    這裡寫內容，可以放入任何 md 的寫法，包括表格

摺疊式警告框

??? info "Lorem ipsum"

    這裡寫內容，可以放入任何 md 的寫法，包括表格

警告框類型

以下是內建的警告框類型，如果覺得不夠也能自己客製化

note

!!! note "這裡寫標題"

    這裡寫內容

abstract

!!! abstract "這裡寫標題"

    這裡寫內容

info

!!! info "這裡寫標題"

    這裡寫內容

tip

!!! tip "這裡寫標題"

    這裡寫內容

success

!!! success "這裡寫標題"

    這裡寫內容

question

!!! question "這裡寫標題"

    這裡寫內容

warning

!!! warning "這裡寫標題"

    這裡寫內容

failure

!!! failure "這裡寫標題"

    這裡寫內容

danger

!!! danger "這裡寫標題"

    這裡寫內容

bug

!!! bug "這裡寫標題"

    這裡寫內容

example

!!! example "這裡寫標題"

    這裡寫內容

quote

!!! quote "這裡寫標題"

    這裡寫內容

客製化警告框

新增 CSS：docs/stylesheets/extra.css

:root {
--md-admonition-icon--pied-piper: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>')
}
.md-typeset .admonition.pied-piper,
.md-typeset details.pied-piper {
border-color: rgb(43, 155, 70);
}
.md-typeset .pied-piper > .admonition-title,
.md-typeset .pied-piper > summary {
background-color: rgba(43, 155, 70, 0.1);
}
.md-typeset .pied-piper > .admonition-title::before,
.md-typeset .pied-piper > summary::before {
background-color: rgb(43, 155, 70);
-webkit-mask-image: var(--md-admonition-icon--pied-piper);
        mask-image: var(--md-admonition-icon--pied-piper);
}

將 CSS 加入到 mkdocs.yml
```
extra_css:
- stylesheets/extra.css
```

在 md 頁面使用

!!! pied-piper "Pied Piper"

    這裡寫內容

數學公式 Math

在 MkDocs (尤其是 Material 主題) 中，數學公式通常是透過 Arithmatex 擴充功能配合 MathJax 渲染的。

數學公式配置

請先在 mkdocs.yml 中 markdown_extensions 下加入

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

extra_javascript:
  - https://polyfill.io/v3/polyfill.min.is?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

數學行內公式

使用單個金錢符號 $...$ 包圍。

$a^2 + b^2 = c^2$

$a^2 + b^2 = c^2$

數學獨立區塊公式

使用雙金錢符號 $$...$$ 包圍，公式會置中顯示。

\[E = mc^2\]

$$
E = mc^2
$$

複雜數學公式

\[ \frac{-b \pm \sqrt{b^2-4ac}}{2a} \]

$$
\frac{-b \pm \sqrt{b^2-4ac}}{2a}
$$