撰寫你的文件

如何配置和撰寫你的 Markdown 來源檔案。

---

檔案配置

你的文件來源應以一般 Markdown 檔案撰寫（見下方的 使用 Markdown 撰寫），並放置在 文件目錄 中。預設情況下，此目錄將被命名為 docs，且存在於專案的最上層，與 mkdocs.yml 設定檔相鄰。

你可以建立的最簡單專案將會看上去和這個類似

mkdocs.yml
docs/
    index.md

依照慣例，你的專案首頁應命名為 index.md（見下方的 索引頁 以取得詳細資訊）。以下任何一個檔案附檔名都可以用於你的 Markdown 來源檔案：markdown、mdown、mkdn、mkd、md。無任何設定的情況下，包含於你的文件目錄中的所有 Markdown 檔案都將會呈現在製作好的網站中。

你也可以透過建立多個 Markdown 檔案，來建立多頁文件

mkdocs.yml
docs/
    index.md
    about.md
    license.md

你使用的檔案配置決定了用於產生網頁的網址。有鑑於上述配置，網頁將會為以下網址產生

/
/about/
/license/

若更適合你的文件配置的話，你也可以將你的 Markdown 檔案包含於巢狀目錄中。

docs/
    index.md
    user-guide/getting-started.md
    user-guide/configuration-options.md
    license.md

巢狀目錄中的來源檔案將會讓網頁以巢狀網址產生，如下

/
/user-guide/getting-started/
/user-guide/configuration-options/
/license/

任何在 文件目錄 中未被辨別為 Markdown 檔案（以它們的檔案附檔名）的檔案，都會由 MkDocs 複製到製作好的網站且不更動。關於詳細資訊，請見下方的 如何連結到圖片和媒體。

索引頁

當有目錄的要求時，預設情況下，大部分網路伺服器會回傳一個索引檔案（一般稱作 index.html）包含於目錄中（若存在的話）。因為這個緣故，所有上述範例的首頁都命名為 index.md，當在建立網站時，MkDocs 會將 index.md 呈現為 index.html。

許多代管儲存庫的網站會對 README 檔案提供特別待遇，當瀏覽一個目錄的內容時，會顯示 README 檔案的內容。因此，MkDocs 會允許你將你的索引頁命名為 README.md 而不是 index.md。這樣一來，當使用者瀏覽你的原始碼時，代管儲存庫的伺服器可以將該目錄的索引頁顯示為 README 檔案。然而，當 MkDocs 呈現你的網站時，檔案將會被重新命名為 index.html，這樣一來伺服器會將它作為一個正確的索引檔案提供服務。

如果在同一個目錄中同時存在 index.md 檔案和 README.md 檔案，則會使用 index.md 檔案，而忽略 README.md 檔案。

設定頁面和導覽

在 mkdocs.yml 檔案中的 nav 組態設定定義了哪些頁面包含在全域網站導覽選單中，以及該選單的結構。如果沒有提供該設定，則會透過找出 說明書目錄 中的所有 Markdown 檔案自動建立導覽。自動建立的導覽組態會根據檔名以字母數字順序進行排序（但索引檔在子區段中永遠都會列在最前面）。如果您想以不同的方式對導覽選單進行排序，則需要手動定義導覽組態。

一個最簡的導覽組態如下所示：

nav:
  - index.md
  - about.md

導覽組態中的所有路徑都必須相對於 docs_dir 組態選項。如果該選項設定為預設值 docs，則上述組態的原始檔將會位於 docs/index.md 和 docs/about.md。

上述範例會在最上方建立兩個導覽項目，其標題是由 Markdown 檔的內容推斷出來的，或者，如果檔內未定義標題，則是由檔名推斷出來的。若要變更 nav 設定中的標題，請在檔名前面加一個標題。

nav:
  - Home: index.md
  - About: about.md

請注意，如果在導覽中為頁面定義了標題，則在整個網站中會對該頁面使用該標題，並會取代在頁面中定義的任何標題。

可以透過在區段標題下共同列出相關頁面，建立導覽子區段。例如：

nav:
  - Home: index.md
  - User Guide:
    - Writing your docs: writing-your-docs.md
    - Styling your docs: styling-your-docs.md
  - About:
    - License: license.md
    - Release Notes: release-notes.md

使用上述組態後，我們可在最上方看到三個項目：「首頁」、「使用者指南」和「關於」。「首頁」是連結至網站首頁的連結。「使用者指南」區段下列出兩個頁面：「撰寫說明文件」和「為說明文件定型」。「關於」區段下又列出兩個頁面：「授權」和「發行說明」。

請注意，區段無法指派頁面。區段僅是子頁面和子區段的容器。您可以依自己的喜好嵌套區段。但是，請特別注意，不要因為過度嵌套導致使用者難以在網站導覽中瀏覽。儘管區段可以反映您的目錄結構，但它們不一定要相同。

任何不在導覽組態中列出的頁面仍然會進行呈現並包含在建置的網站中，但它們不會從全域導覽中連結，也不會包含在 previous 和 next 連結中。這些頁面會處於「隱藏」狀態，除非直接連結到它們。

使用 Markdown 編寫

MkDocs 必須使用 Markdown 來撰寫頁面，Markdown 是一種輕量級標記語言，可取得易於閱讀、易於撰寫的純文字文件，並且可以預測性地轉換成有效的 HTML 文件。

MkDocs 使用 Python-Markdown 函式庫將 Markdown 文件呈現成 HTML。Python-Markdown 與 參考實作 幾乎完全相容，但還是有些非常細微的 差異。

除了 Markdown 基礎 語法 已廣泛應用於所有 Markdown 實作之外，MkDocs 還支援 Python-Markdown 擴充功能，讓 Markdown 語法得以進一步延伸。markdown_extensions 有關如何啟用擴充功能的詳細資料，請參閱 MkDocs 的組態設定。

MkDocs 預設包含一些擴充功能，已在下標出。

內部連結

利用一般 Markdown 連結，MkDocs 就能讓您互相連結您的文件。不過，如果比照下文說明，特別為 MkDocs 格式化這些連結，還有一些額外的優點。

連結到頁面

在文件中連結網頁時，您可以直接套用標準 Markdown 連結 語法，包含您要連結的 Markdown 文件的相對路徑。

Please see the [project license](license.md) for further details.

當 MkDocs 建置執行時，這些 Markdown 連結會自動轉換為指向正確 HTML 頁面的 HTML 超連結。

如果目標文件存在於其他目錄中，您需要確認連結中包含任何相對目錄路徑。

Please see the [project license](../about/license.md) for further details.

MkDocs 使用 toc 延伸功能，為 Markdown 文件中的每個標題產生一個 ID。您可以使用錨點連結，利用此 ID 連結到目標文件中的某一段落。產生的 HTML 會正確轉換連結的路徑部分，不變動錨點部分。

Please see the [project license](about.md#license) for further details.

請注意 ID 是根據標題的文字建立的。所有文字都會轉換為小寫，並將任何不允許的字元（包括空白）轉換為破折號。連續的破折號會簡化為一個破折號。

toc 擴充功能提供了一些組態設定，您可以設定在 mkdocs.yml 組態檔案中，以變更預設行為

• permalink

  在每個標題結尾產生永久連結。預設值：False。

  設定為 True 時，段落符號（¶ 或 ¶）會用作連結文字。設定為字串時，提供的字串會用作連結文字。例如，若要改用雜湊符號 (#)，則請執行

  markdown_extensions:
    - toc:
        permalink: "#"

• baselevel

  標題的基準層級。預設值：1。

  此設定讓標題層級自動調整為符合您 HTML 樣版的階層。例如，如果頁面的 Markdown 文字不應包含高於層級 2 (<h2>) 的標題，請執行

  markdown_extensions:
    - toc:
        baselevel: 2

  這樣，您的文件中所有標題會提升 1 個層級。例如，標題 # Header 會在 HTML 輸出中呈現為層級 2 標題 (<h2>)。

• separator

  字詞分隔符號。預設值：-。

  產生的 ID 中，取代空白的字元。如果您偏好使用底線，請執行

  markdown_extensions:
    - toc:
        separator: "_"

請注意，如果您要定義上述多個設定，您必須在 markdown_extensions 組態選項中，使用單一 toc 項目執行。

markdown_extensions:
  - toc:
      permalink: "#"
      baselevel: 2
      separator: "_"

連結到圖片和媒體

除了 Markdown 原始檔案外，你也可以在您的文件包含其他類型的檔案，它會在建立文件網站時複製過去。這些檔案可能是影像和其他媒體。

例如，假如你的專案文件需要包含一個 GitHub Pages CNAME 檔案 和一個 PNG 格式的螢幕截圖影像，那麼你的檔案配置可能會如下所示

mkdocs.yml
docs/
    CNAME
    index.md
    about.md
    license.md
    img/
        screenshot.png

要將影像包含在你的文件原始檔案中，只需使用任何常規的 Markdown 影像語法即可

Cupcake indexer is a snazzy new project for indexing small cakes.

![Screenshot](img/screenshot.png)

*Above: Cupcake indexer in progress*

當你建立文件時，你的影像現在會被嵌入，而且如果你正在使用 Markdown 編輯器來處理文件，也應該會看到預覽。

從原始 HTML 連結

Markdown 允許文件作者在 Markdown 語法無法滿足作者需求時退回原始 HTML。MkDocs 在這方面沒有限制 Markdown。然而，由於 Markdown 解析器會忽略所有原始 HTML，MkDocs 無法驗證或轉換原始 HTML 中包含的連結。當在原始 HTML 內包含內部連結時，您需要手動適當地設定連結格式，使其符合呈現的文件。

元資料

MkDocs 支援 YAML 和 MultiMarkdown 形式的元資料（通常稱為 front-matter）。元資料包含一系列關鍵字和數值，它們定義在 Markdown 文件的最開始，在文件被 Python-Markdown 處理之前會從文件中移除。MkDocs 會將關鍵字/數值對傳遞給網頁範本。因此，如果某個佈景主題包含支援，任何關鍵字的值都可以在網頁上顯示，或用於控制網頁的呈現。請參閱你佈景主題的文件，以瞭解可能支援哪些關鍵字（如果有）。

除了在範本中顯示資訊外，MkDocs 也支援幾個預定義的元資料關鍵字，這些關鍵字可以變更 MkDocs 對應特定網頁的行為。支援下列關鍵字

• template

  要與目前網頁一起使用的範本。

  預設情況下，MkDocs 使用佈景主題的 main.html 範本來呈現 Markdown 網頁。你可以使用 template 元資料關鍵字，為特定網頁定義不同的範本檔案。範本檔案必須在佈景主題的環境中所定義的路徑上可用。

• title

  要針對文件使用的「標題」。

  MkDocs 將嘗試以以下方式依序判斷文件的標題

  1. 為文件定義的 nav 設定黨的標題。

  2. 文件中 title 元資料關鍵字定義的標題。

  3. 文件主體第一行中的一級 Markdown 標題。
     （Setext 形式 的標題支援於 僅於 MkDocs 1.5 起。）

  4. 文件的檔案名稱。

  在找到網頁標題後，MkDoc 就不會再檢查上述清單中的任何其他來源。

YAML 形式的元資料

YAML 形式的元資料包含 YAML 以 YAML 形式的分隔符號包裝的關鍵字/數值對，以標記元資料的開始和/或結束。文件的第 1 行必須是 ---。元資料結尾於包含結尾分隔符號（--- 或 ...）的第一行。分隔符號之間的內容會被解析為 YAML。

---
title: My Document
summary: A brief description of my document.
authors:
    - Waylan Limberg
    - Tom Christie
date: 2018-07-10
some_url: https://example.com
---
This is the first paragraph of the document.

YAML 能夠偵測資料類型。因此，上方範例中，title、summary 和 some_url 的值為字串，authors 的值為字串清單，date 的值為 datetime.date 物件。請注意 YAML 的鍵名區分大小寫，而 MkDocs 預期所有鍵名均為小寫。YAML 最頂層必須為一組 key/value 成對，這將傳回一個 Python dict。若傳回其他類型的資料，或 YAML 解析器遇到錯誤，MkDocs 將無法辨識區段為元資料，頁面的 meta 屬性將為空，而區段不會從文件移除。

MultiMarkdown 樣式元資料

MultiMarkdown 樣式元資料使用 MultiMarkdown 專案最初推出的格式。資料包含一系列關鍵字和值，這些值定義在 Markdown 文件的開頭，如下所示

Title:   My Document
Summary: A brief description of my document.
Authors: Waylan Limberg
         Tom Christie
Date:    January 23, 2018
blank-value:
some_url: https://example.com

This is the first paragraph of the document.

關鍵字不區分大小寫，且可能包含英文字母、數字、底線和破折號，而且必須以冒號結尾。值包括一行冒號之後的任何內容，甚至可以是空白。

如果某一行由 4 個空白或更多空白縮排，該行會被視為前一個關鍵字值的額外一行。一個關鍵字可以有任意多行。所有行會合併成單一字串。

第一個空白行會結束文件的全部元資料。因此，文件的第一行不能為空白。

表格

Tables 擴充功能增加一個基本表格語法至 Markdown，而許多應用程式都廣泛使用 Markdown。語法相當簡單且通常僅適用於簡單表格資料。

一個簡單的表格如下所示

First Header | Second Header | Third Header
------------ | ------------- | ------------
Content Cell | Content Cell  | Content Cell
Content Cell | Content Cell  | Content Cell

若你希望，可以在表格的每一行增加頭尾線條

| First Header | Second Header | Third Header |
| ------------ | ------------- | ------------ |
| Content Cell | Content Cell  | Content Cell |
| Content Cell | Content Cell  | Content Cell |

透過在分隔線上加入冒號，指定每欄的對齊方式

First Header | Second Header | Third Header
:----------- |:-------------:| -----------:
Left         | Center        | Right
Left         | Center        | Right

請注意，表格儲存格不能包含任何區塊層次元素，且不能包含多行文字。不過，它們可以包含 Markdown 語法規則中定義的內嵌 Markdown。

此外，表格必須以空白行包圍。表格前和後都必須有空白行。

圍欄式程式碼區塊

圍欄式程式碼區塊 擴充功能新增一個可定義程式碼區塊的替代方式，而不使用縮排。

第一行應該包含 3 個或更多反引號 (`) 字元，而最後一行應該包含相同數量的反引號字元 (`)

```
Fenced code blocks are like Standard
Markdown’s regular code blocks, except that
they’re not indented and instead rely on
start and end fence lines to delimit the
code block.
```

使用這種方式時，可以在反引號後面第一行選用指定語言，這會讓任何語法突顯功能知道所使用的語言

```python
def fn():
    pass
```

請注意，圍欄式程式碼區塊不能縮排。因此，它們不能巢狀於清單項目、引用塊等內部。