如何用 Markdown 編寫文件

本頁面介紹了我們如何在 MDN Web 文件上使用 Markdown 編寫文件。我們選擇了 GitHub 風格的 Markdown (GFM) 作為基礎,並添加了擴充套件以支援 MDN 所需的功能。

基礎:GitHub 風格的 Markdown

MDN Markdown 的基礎是 GitHub 風格的 Markdown (GFM):https://github.github.com/gfm/。這意味著本頁面未明確說明的任何內容都可以參考 GFM 規範。GFM 又是 CommonMark 的超集 (https://spec.commonmark.org/)。

GFM 規範定義了兩種基本的連結型別

  • 行內連結,其中連結目的地緊跟在連結文字之後給出。
  • 參考連結,其中連結目的地在文件的其他地方定義。

在 MDN 上,我們傾向於使用行內連結,因為它們更容易閱讀和維護,而不會丟失上下文。這是在 MDN 上編寫連結的首選方式

md
[Macarons](https://en.wikipedia.org/wiki/Macaron) are delicious but tricky to make.

然而,在某些情況下,參考連結因其緊湊性而更合適。例如,縮小寬表格可以使其更容易審閱和編輯。

md
| Name                 | Features                                                                                         |
| -------------------- | ------------------------------------------------------------------------------------------------ |
| [Macarons][macarons] | Delicious but tricky to make. Add more class to a tea party than almost any other confectionary. |
| [Biscotti][biscotti] | Crisp and easier to make.                                                                        |

[macarons]: https://en.wikipedia.org/wiki/Macaron
[biscotti]: https://en.wikipedia.org/wiki/Biscotti

在極少數需要使用參考連結的情況下,請確保它們緊跟在使用它們的上下文之後。

程式碼塊示例

在 GFM 和 CommonMark 中,作者可以使用“程式碼圍欄”來劃分 <pre> 塊。開頭的程式碼圍欄後面可以跟一些文字,這被稱為“資訊字串”。程式碼示例的語言必須使用資訊字串的第一個詞指定,這將用於為該塊提供語法高亮。支援以下詞語

  • 程式語言
    • JavaScript
      • js - JavaScript
      • ts - TypeScript
      • jsx - React JSX
      • tsx - React TSX
    • C 語言家族
      • c - C
      • cpp - C++
      • cs - C#
      • java - Java
    • 其他
      • python - Python
      • php - PHP
      • rust - Rust
      • glsl - GLSL (OpenGL 著色器)
      • sql - SeQueL 命令
      • wat - WebAssembly
      • webidl - Web 介面定義語言
  • 樣式
    • css - CSS
    • scss - Sass (SCSS)
    • less - Less
  • 標記語言
    • html - HTML
    • svg - SVG
    • xml - XML
    • mathml - MathML
    • md - Markdown
    • latex - LaTeX
  • 命令提示符
    • bash - Bash/Shell
    • batch - Batch (Windows Shell)
    • powershell - PowerShell
  • 配置/資料檔案
    • json - JSON
    • ini - INI
    • yaml - YAML
    • toml - TOML
    • sql - SQL 資料庫
    • ignore - Gitignore 檔案
    • apacheconf - Apache 配置
    • nginx - NGINX 配置
  • 模板
    • django - Django 模板
    • svelte - Svelte 模板
    • hbs - Handlebars 模板
    • pug - Pug 模板(可由 Express 使用)
  • 其他
    • plain - 純文字
    • diff - Diff 檔案
    • http - HTTP 頭部
    • regex - 正則表示式
    • uri - URI 和 URL

例如

md
```js
const greeting = "I will get JavaScript syntax highlighting";
```

如果您希望使用的語法高亮不在上述列表中,您應該將程式碼塊標記為 plain。可以透過 GitHub 上討論的流程 請求新增其他語言。

注意:請嚴格按照上面列出的語言識別符號使用。例如,不允許使用 javascript,您必須編寫 js

禁止程式碼檢查

作者可以向任何語言識別符號新增 -nolint 字尾

md
```html-nolint
<p>
I will not be linted.
</p>
```

這樣的程式碼塊將獲得適當的語法高亮,並會被即時示例系統識別,但會被程式碼檢查工具或 Prettier 等自動格式化工具忽略。作者應使用此後綴來顯示無效程式碼或不應由程式碼檢查工具或格式化工具修復的替代格式。

附加類(資訊字串)

GFM 支援資訊字串,允許作者提供有關程式碼塊的附加資訊。在 MDN 上,資訊字串會轉換為類名。

作者可以提供以下資訊字串之一

  • example-good:將此示例樣式設定為好示例(應遵循的示例)
  • example-bad:將此示例樣式設定為壞示例(應避免的示例)
  • hidden:不在頁面中渲染此程式碼塊。這用於即時示例。

例如

md
```js example-good
const greeting = "I'm a good example";
```

```js example-bad
const greeting = "I'm a bad example";
```

```js hidden
const greeting = "I'm a secret greeting";
```

這些將渲染為

js
const greeting = "I'm a good example";
js
const greeting = "I'm a bad example";

討論參考

此問題已解決於

備註、警告和標註

作者可以使用 GFM 警報語法 來特別突出內容。警報分為三種類型:備註、警告和標註。

注意:MDN Web 文件在支援 GFM 警報之前,已支援帶有其自身語法的警報,並將其稱為“noteblocks”。MDN 不支援以下 GFM 警報:[!TIP][!CAUTION][!IMPORTANT]。GFM 不支援 [!CALLOUT]

  • 要新增備註,請建立一個塊引用,其第一行是 [!NOTE]
  • 要新增警告,請建立一個塊引用,其第一行是 [!WARNING]
  • 要新增標註,請建立一個塊引用,其第一行是 [!CALLOUT]

備註和警告會在輸出開頭新增本地化的 Note:Warning:,而標註則不會。這使得標註成為作者想要提供自定義標題時的良好選擇。

透過塊引用中的空行,可以像普通段落一樣生成多行。此外,沒有空格的多行也像普通 Markdown 行一樣處理,並連線起來。

塊引用可以包含程式碼塊或其他塊元素。

示例

備註

md
> [!NOTE]
> This is how you write a note.
>
> It can have multiple lines.

這將生成以下 HTML

html
<div class="notecard note">
  <p><strong>Note:</strong> This is how you write a note.</p>
  <p>It can have multiple lines.</p>
</div>

此 HTML 將渲染為一個高亮框

注意:這就是如何編寫備註。

它可以有多行。

警告

md
> [!WARNING]
> This is how you write a warning.
>
> It can have multiple paragraphs.

這將生成以下 HTML

html
<div class="notecard warning">
  <p><strong>Warning:</strong> This is how you write a warning.</p>
  <p>It can have multiple paragraphs.</p>
</div>

此 HTML 將渲染為一個高亮框

警告:這就是如何編寫警告。

它可以有多個段落。

標註

md
> [!CALLOUT]
>
> **This is how you write a callout.**
>
> It can have multiple paragraphs.

這將生成以下 HTML

html
<div class="callout">
  <p><strong>This is how you write a callout.</strong></p>
  <p>It can have multiple paragraphs.</p>
</div>

此 HTML 將渲染為一個高亮框

這就是如何編寫標註。

它可以有多個段落。

包含程式碼塊的備註

此示例包含一個程式碼塊。

md
> [!NOTE]
> This is how you write a note.
>
> It can contain code blocks.
>
> ```js
> const s = "I'm in a code block";
> ```
>
> Like that.

這將生成以下 HTML

html
<div class="notecard note">
  <p><strong>Note:</strong> This is how you write a note.</p>
  <p>It can contain code blocks.</p>
  <pre class="brush: js">const s = "I'm in a code block";</pre>
  <p>Like that.</p>
</div>

此 HTML 將與程式碼塊一起渲染

注意:這就是如何編寫備註。

它可以包含程式碼塊。

js
const s = "I'm in a code block";

就像這樣。

討論參考

此問題已解決於 https://github.com/mdn/content/issues/3483

定義列表

定義列表在 MDN 中廣泛使用,但 GFM 不支援。MDN 引入了一種自定義的定義列表格式,它是 GFM 無序列表 (<ul>) 的修改形式。在此格式中

  • GFM <ul> 包含任意數量的頂級 GFM <li> 元素。
  • 每個頂級 GFM <li> 元素必須包含一個 GFM <ul> 元素作為其最終元素。
  • 這個最終巢狀的 <ul> 必須包含一個 GFM <li> 元素,其文字內容必須以“: ”(冒號後跟一個空格)開頭。此元素可以包含塊元素,包括段落、程式碼塊、嵌入列表和備註。

這些頂級 GFM <li> 元素中的每一個都將轉換為 <dt>/<dd> 對,如下所示

  • 頂級 GFM <li> 元素將被解析為 GFM <li> 元素,其內部內容將構成 <dt> 的內容,但最終巢狀的 <ul> 不會包含在 <dt> 中。
  • 最終巢狀的 <ul> 中的 <li> 元素將被解析為 GFM <li> 元素,其內部內容將構成 <dd> 的內容,但開頭的“: ”將被丟棄。

例如,這是一個 <dl>

md
- term1
  - : My description of term1
- `term2`
  - : My description of term2

    It can have multiple paragraphs, and code blocks too:

    ```js
    const thing = 1;
    ```

在 GFM/CommonMark 中,這將生成以下 HTML

html
<ul>
  <li>
    <p>term1</p>
    <ul>
      <li>: My description of term1</li>
    </ul>
  </li>
  <li>
    <p><code>term2</code></p>
    <ul>
      <li>
        <p>: My description of term2</p>
        <p>It can have multiple paragraphs, and code blocks too:</p>
        <pre>
          <code class="brush: js">const thing = 1;</code>
        </pre>
      </li>
    </ul>
  </li>
</ul>

在 MDN 上,這將生成以下 HTML

html
<dl>
  <dt>
    <p>term1</p>
  </dt>
  <dd>My description of term1</dd>
  <dt>
    <p><code>term2</code></p>
  </dt>
  <dd>
    <p>My description of term2</p>
    <p>It can have multiple paragraphs, and code blocks too:</p>
    <pre>
       <code class="brush: js">const thing = 1;</code>
    </pre>
  </dd>
</dl>

使用此語法編寫的定義列表必須由 <dt>/<dd> 元素對組成。使用此語法,不可能編寫包含多個連續 <dt> 元素或多個連續 <dd> 元素的列表:解析器會將其視為錯誤。我們預計 MDN 上的幾乎所有定義列表都將適用此限制,對於不適用的列表,作者可以回退到原始 HTML。

這是不允許的

md
- `param1`, `param2`, `param3`
  - : My description of `param1`
  - : My description of `param2`
  - : My description of `param3`

作為一種變通方法,當作者需要將多個 <dt> 項與單個 <dd> 關聯時,可以考慮將它們作為單個 <dt> 提供,其中包含多個術語,用逗號分隔,如下所示

md
- `param1`, `param2`, `param3`
  - : My description of params 1, 2, and 3

此處描述的語法的理由是,它與期望 CommonMark 的工具(例如 Prettier 或 GitHub 預覽)配合得很好,同時編寫和解析起來也相當容易。

討論參考

此問題已解決於 https://github.com/mdn/content/issues/4367

表格

GFM 提供了建立表格的語法,我們在 MDN 中使用了它。然而,有時 GFM 表格不符合我們的需求

  • GFM 語法僅支援 HTML 中可用功能的一個子集。如果您需要使用 GFM 不支援的表格功能,請使用 HTML 來建立表格。
  • 如果表格的 GFM 表示形式寬度超過 150 個字元,請使用 HTML 來建立表格。
  • 我們支援一種特殊型別的表格,稱為“屬性表”,它有自己的 CSS 類,因此始終是 HTML。

因此,一般原則是,作者應儘可能使用 GFM Markdown 語法,並在必要時或 HTML 更具可讀性時回退到原始 HTML。有關更多資訊,請參閱何時使用 HTML 表格

GFM 表格語法樣式

在 GFM 表格語法中,作者可以省略行的開頭和結尾管道符。然而,為了可讀性,MDN 作者必須包含這些管道符。此外,作者必須在行中提供尾隨空格,以便列中的所有單元格在純文字中長度相同。

也就是說,MDN 作者必須使用這種樣式

md
| Heading 1 | Heading 2 | Heading 3 |
| --------- | --------- | --------- |
| cell 1    | cell 2    | cell 3    |
| cell 4    | cell 5    | cell 6    |

而不是這種樣式

md
| Heading 1 | Heading 2 | Heading 3 |
| --------- | --- |----------------------|
| cell 1 | cell 2 | cell 3 |
cell 4 | cell 5 | cell 6

表格由 Prettier 格式化,因此作者依賴工具來正確格式化表格。

何時使用 HTML 表格

作者應使用 HTML 表格而非 GFM 語法的三種主要情況

  1. 表格使用了 GFM 不支援的功能(見下文)。
  2. GFM 表格太寬而無法閱讀。
  3. 作者需要一種特殊型別的表格,稱為“屬性表”。

GFM 不支援的表格功能

GFM 表格語法的主要限制是

  • GFM 表格必須有標題行。
  • GFM 表格不能有標題列。
  • GFM 不會解析表格單元格中的 GFM 塊元素。例如,您不能在表格單元格中包含列表。
  • GFM 表格無法分配類。
  • GFM 不支援 <table><tr><th><td> 以外的任何表格元素。
  • GFM 不支援任何表格元素屬性,如 colspanrowspanscope

如果作者需要使用任何不支援的功能,他們應該用 HTML 編寫表格。

請注意,我們不建議在表格中普遍使用 <caption> 元素,因為這也會排除 GFM 語法。

GFM 表格最大寬度

即使表格可以用 GFM 編寫,有時使用 HTML 也會更好,因為 GFM 對錶格採用“ASCII 藝術”方法,當表格行很長時不易閱讀。考慮以下表格

html
<table>
  <tr>
    <th>A heading 1</th>
    <th>A heading 2</th>
    <th>A heading 3</th>
    <th>A heading 4</th>
    <th>A heading 5</th>
    <th>A heading 6</th>
  </tr>
  <tr>
    <td>Something shortish</td>
    <td>
      Something much longer that really goes into a lot of detail about
      something, so much so that the table formatting starts to look bad in GFM
      format.
    </td>
    <td>Something shortish</td>
    <td>
      Another cell with lots of text in it, that also really goes into a lot of
      detail about something, so much so that the table formatting starts to
      look bad in GFM format.
    </td>
    <td>Something shortish</td>
    <td>Something shortish</td>
  </tr>
</table>

在 GFM 中,它看起來像

md
| A heading 1        | A heading 2                                                                                                                                         | A heading 3        | A heading 4                                                                                                                                                              | A heading 5        | A heading 6        |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | ------------------ |
| Something shortish | Something much longer that really goes into a lot of detail about something, so much so that the table formatting starts to look bad in GFM format. | Something shortish | Another cell with lots of text in it, that also really goes into a lot of detail about something, so much so that the table formatting starts to look bad in GFM format. | Something shortish | Something shortish |

在這種情況下,最好使用 HTML。

這導致了以下指導原則:如果表格的 Markdown 表示形式寬度超過 150 個字元,請使用 HTML 來建立表格

屬性表

屬性表是一種特定型別的表格,用於在特定型別的一組頁面中顯示結構化的屬性-值內容。這些表格有兩列:第一列是標題列,列出屬性;第二列列出此特定項的值。例如,以下是 PannerNode 介面的屬性表

輸入數量 1
輸出數量 0
通道計數模式 “explicit”
聲道數 2
通道解釋 “speakers”

這些頁面無法在 GFM 中表示,因為它們有標題列,因此作者在這種情況下應使用 HTML。為了獲得特殊樣式,作者應將 "properties" 類應用於表格

html
<table class="properties"></table>

討論參考

此問題已解決於 https://github.com/mdn/content/issues/4325https://github.com/mdn/content/issues/7342https://github.com/mdn/content/issues/7898#issuecomment-913265900

上標和下標

作者在必要時可以使用 HTML <sup><sub> 元素,但如果可能,應使用替代方案。特別是

  • 對於冪運算,使用 ^ 符號:2^53
  • 對於序數表示式,如 1st,更傾向於使用“first”這樣的單詞。
  • 對於腳註,不要標記腳註引用,例如 <sup>[1]</sup>

討論參考

此問題已解決於 https://github.com/mdn/content/issues/4578

頁面摘要

頁面摘要是頁面中的第一個“內容”段落——出現在頁面前言和任何側邊欄頁面橫幅宏之後的第一個文字。

此摘要用於搜尋引擎最佳化 (SEO),並且也由某些宏自動包含在頁面列表中。因此,第一個段落應該既簡潔又富有資訊。

討論參考

此問題已解決於 https://github.com/mdn/content/issues/3923

作者在散文中使用宏來模板化常見的連結模式,或包含特定的程式碼塊或文字

md
The **`margin`** [CSS](/en-US/docs/Web/CSS) property sets the margin area on all four sides of an element.
It is a shorthand for {{cssxref("margin-top")}}, {{cssxref("margin-right")}}, {{cssxref("margin-bottom")}}, and {{cssxref("margin-left")}}.
…

有關更多資訊,請參閱使用宏