如何使用 Markdown 語言撰寫技術文件

Adobe 技術文件中的文章是以名為 Markdown 的精簡化標記語言寫成，這種語言容易閱讀及學習。

我們目前是將 Adobe 文件內容儲存在 GitHub，而 GitHub 使用的 Markdown 版本稱為 GitHub Flavored Markdown (GFM)，可提供額外功能滿足常見的格式需求。 此外，Adobe 更適度擴充 Markdown 效能，以支援註釋、提示和內嵌影片等特定的說明相關功能。

Markdown 基本介紹

以下章節介紹使用 Markdown 撰寫的基礎知識。

標題

若要建立標題，請在文字行的開頭使用井字號 (#)：

# This is level 1 (article title)
## This is level 2
### This is level 3
#### This is level 4
##### This is level 5

基本文字

使用 Markdown 時，標示段落並不需要特殊語法。

若要將文字的格式設為​ 粗體，請以雙星號括住文字。 若要將文字的格式設為​ 斜體，請以單星號括住文字：

   This text is **bold**.
   This text is *italic*.
   This text is both ***bold and italic***.

若要略過 Markdown 格式字元，請在該字元前使用「\」：

This is not \*italicized\* type.

編號清單與項目符號清單

若要建立項目符號清單，請在文字行的開頭使用 1. 或 1)，但同一份清單內請勿混用不同格式。 您不必指定編號， GitHub 會自動完成編號工作。

1. This is step 1.
1. This is the next step.
1. This is yet another step, the third.

顯示結果：

若要建立項目符號清單，請在文字行的開頭使用「*」、「-」或「+」，但同一份清單內請勿混用不同格式。 (請勿在同一份文件中混用項目符號格式，例如 * 和 +)。

* First item in an unordered list.
* Another item.
* Here we go again.

顯示結果：

清單內也可以內嵌清單，並在清單項目間新增內容。

1. Set up your table and code blocks.
1. Perform this step.

   ![screen](https://experienceleague.adobe.com/docs/contributor/assets/adobe_standard_logo.png?lang=zh-Hant)

1. Make sure that your table looks like this:

   | Hello | World |
   |---|---|
   | How | are you? |

1. This is the fourth step.

   >[!NOTE]
   >
   >This is note text.

1. Do another step.

顯示結果：

表格

表格並非 Markdown 核心規格的一部分，但 Adobe 可在某些情況下支援表格。 Markdown 的儲存格不支援多行清單。 避免在表格中輸入多行文字，會是最理想的作法。 您可以使用直立線 (|) 字元勾勒出行、列，藉此建立表格。 連字號會建立各欄標題，直立線符號則能分隔各欄。 在表格前面加上一個空白行，以確保表格成功轉譯。

| Header | Another header | Yet another header |
|--- |--- |--- |
| row 1 | column 2 | column 3 |
| row 2 | row 2 column 2 | row 2 column 3 |

顯示結果：

Markdown 要呈現簡單的表格沒有問題。 不過，若表格的儲存格內包含多個段落或清單，就會難以呈現。 如果是這類內容，建議您使用其他格式，例如改為標題與文字。

如需建立表格的詳細資訊，請參閱：

連結

內嵌連結使用的 Markdown 語法是由超連結文字的 [link text] 部分，以及緊接在後的連結網址或檔案名稱 (file-name.md) 部分所組成。

[link text](file-name.md)

[Adobe](https://www.adobe.com)

顯示結果：

Adobe

若連結的是同一存放庫內的文章 (交叉參照)，請使用相對連結。 您可使用所有相對連結運算元，例如「/」(目前目錄)、「…/」(上一層目錄) 和「…/…/」(上兩層目錄)。

See [Overview example article](../../overview.md)

如需連結的詳細資訊，請參閱本指南中的連結一文，瞭解連結語法。

影像

![Adobe Logo](/docs/contributor/assets/adobe_standard_logo.png "Hover text")

顯示結果：

程式碼片段

Markdown 支援將程式碼片段內嵌在句子中，或以「包圍型」獨立片段形式插入句子之間。 如需詳細資訊，請參閱Markdown對程式碼區塊的原生支援

使用反引號 (`) 在段落中建立內嵌程式碼樣式。若要建立特定的多行程式碼區塊，請在程式碼區塊前後加上三個反引號 (```) (在 Markdown 中稱為「包圍型程式碼區塊」，在 AEM 中只是一個「程式碼區塊」元件)。若要使用包圍型程式碼區塊，請在第一組反引號之後加上程式碼語言，讓 Markdown 可以正確地標示程式碼語法。範例：``javascript`

範例：

This is `inline code` within a paragraph of text.

顯示結果：

This is inline code within a paragraph of text.

這是包圍型程式碼片段：

function test() {
 console.log("notice the blank line before this function?");

自訂 Markdown 擴充功能

Adobe 文章中大部分的文章格式都會使用標準 Markdown，例如段落、連結、清單與標題。 若需要更豐富的格式變化，可在文章中使用 Markdown 擴充功能，例如：

在每一行的開頭使用 Markdown 區塊引號 (「>」)，繫結擴充元件 (例如註釋)。

部分常見的 Markdown 元素 (例如標題和程式碼區塊) 會包含擴充屬性。 如需變更預設屬性，請在元件之後新增參數，並置於大括弧內 (「/{ /}」)。 擴充屬性會以實例說明。

註釋區塊

您可以選擇使用這些註釋類型，以吸引讀者注意特定內容：

一般來說，註釋區塊應節制使用，註釋太多可能會造成干擾。 雖然註釋區塊也支援程式碼片段、影像、清單和連結，但請試著讓註釋區塊簡單明瞭。

>[!NOTE]
>
>This is a standard NOTE block.

>[!TIP]
>
>This is a standard TIP.

>[!IMPORTANT]
>
>This is an IMPORTANT note.

顯示結果：

影片

原生 Markdown 不會轉譯內嵌影片，但您可以使用此 Markdown 擴充功能達成此目的。

>[!VIDEO](https://video.tv.adobe.com/v/29770/?quality=12)

顯示結果：

類似項目

AEM 中的「類似項目」元件會出現在文章結尾處。 這會顯示相關連結。 文章輸出時，可採用相同的第 2 層標題 (##) 格式，不必加入迷你目錄。

顯示結果：

UICONTROL 和 DNL

我們所有 Markdown 說明內容一開始會使用機器翻譯工具來進行本地化。 如果說明內容從未進行過本地化，那麼我們將保留機器翻譯。 但是，如果說明內容過去已經進行過本地化，那麼機器翻譯的內容將充當預留位置，而內容部分則在進行人工翻譯中。

``

在進行機器翻譯期間，系統會勾選標示為 `` 的項目，並根據本地化資料庫來決定適當的翻譯。 若 UI 當未經過本地化，此標記將允許系統保留該特定語言的英文 UI 參照 (即 義大利文的 Analytics 參照)。

來源內容範例：

``

我們使用「不要翻譯」列表來設定規則，讓機器翻譯引擎知道哪些應該保留英文內容。 最常見的項目為解決方案的完整名稱，如「Adobe Analytics」、「Adobe Campaign」和「Adobe Target」。 但是，可能有我們需要強制引擎使用英文的情況，因為所考慮的名詞可能是用作特定專業用語或是一般用語。 最明顯的情況為解決方案的簡短名稱，如「Analytics」、「Campaign」和「Target」等。 機器很難理解這些是解決方案名稱而不是通用名詞。 該標記也可以用作一定要保留為英文或文字較短部分的第三方名稱/特性，例如必須保留為英文的短語或句子。

來源內容範例：

Gotcha 與疑難排解

替代文字

包含底線的替代文字無法正確轉譯。 舉例來說，請避免使用下列文字：

![Settings_Step_2](/assets/settings_step_2.png)

我們最理想的作法是在檔名中使用連字號 (「-」) 而非底線 (「_」)。

![Settings-Step-2](/assets/settings-step-2.png)

單引號與雙引號

您將文字複製到 Markdown 編輯器時，這些文字可能會含有「聰明」(彎曲) 的單引號或雙引號。 這些引號需要編碼或變更為基本的單引號或雙引號。 否則檔案發佈後，畫面可能會出現奇怪的字元，像是：It’s

在此提供這些標點符號的「聰明版」編碼：

角括弧

若要在檔案中的文字 (而非程式碼) 使用角括弧 (像是要表示預留位置)，請手動編碼角括弧。 否則，Markdown 會認為這些角括弧代表 HTML 標籤。

例如，將<script name>編碼為<script name>

標題中的 & 符號

不可在標題中使用 & 符號。 請改用「與」或「和」，或使用 & 編碼。

另請參閱

Markdown 資源