Open ericvlog opened 1 year ago
Adobe 技術文件中的文章是以名為 Markdown 的精簡化標記語言寫成,這種語言容易閱讀及學習。
我們目前是將 Adobe 文件內容儲存在 GitHub,而 GitHub 使用的 Markdown 版本稱為 GitHub Flavored Markdown (GFM),可提供額外功能滿足常見的格式需求。 此外,Adobe 更適度擴充 Markdown 效能,以支援註釋、提示和內嵌影片等特定的說明相關功能。
以下章節介紹使用 Markdown 撰寫的基礎知識。
若要建立標題,請在文字行的開頭使用井字號 (#):
使用 Markdown 時,標示段落並不需要特殊語法。
若要將文字的格式設為粗體,請以雙星號括住文字。 若要將文字的格式設為斜體,請以單星號括住文字:
若要略過 Markdown 格式字元,請在該字元前使用「\」:
若要建立項目符號清單,請在文字行的開頭使用 1. 或 1),但同一份清單內請勿混用不同格式。 您不必指定編號, GitHub 會自動完成編號工作。
1.
1)
顯示結果:
若要建立項目符號清單,請在文字行的開頭使用「*」、「-」或「+」,但同一份清單內請勿混用不同格式。 (請勿在同一份文件中混用項目符號格式,例如 * 和 +)。
清單內也可以內嵌清單,並在清單項目間新增內容。
Set up your table and code blocks.
Perform this step.
Make sure that your table looks like this:
This is the fourth step.
Do another step.
表格並非 Markdown 核心規格的一部分,但 Adobe 可在某些情況下支援表格。 Markdown 的儲存格不支援多行清單。 避免在表格中輸入多行文字,會是最理想的作法。 您可以使用直立線 (|) 字元勾勒出行、列,藉此建立表格。 連字號會建立各欄標題,直立線符號則能分隔各欄。 在表格前面加上一個空白行,以確保表格成功轉譯。
Markdown 要呈現簡單的表格沒有問題。 不過,若表格的儲存格內包含多個段落或清單,就會難以呈現。 如果是這類內容,建議您使用其他格式,例如改為標題與文字。
如需建立表格的詳細資訊,請參閱:
內嵌連結使用的 Markdown 語法是由超連結文字的 [link text] 部分,以及緊接在後的連結網址或檔案名稱 (file-name.md) 部分所組成。
[link text]
(file-name.md)
[link text](file-name.md)
Adobe
若連結的是同一存放庫內的文章 (交叉參照),請使用相對連結。 您可使用所有相對連結運算元,例如「/」(目前目錄)、「…/」(上一層目錄) 和「…/…/」(上兩層目錄)。
如需連結的詳細資訊,請參閱本指南中的連結一文,瞭解連結語法。
Markdown 支援將程式碼片段內嵌在句子中,或以「包圍型」獨立片段形式插入句子之間。 如需詳細資訊,請參閱 Markdown 對程式碼片段的原生支援
使用反引號 (`) 在段落中建立內嵌程式碼樣式。若要建立特定的多行程式碼區塊,請在程式碼區塊前後加上三個反引號 ( `) (在 Markdown 中稱為「包圍型程式碼區塊」,在 AEM 中只是一個「程式碼區塊」元件)。若要使用包圍型程式碼區塊,請在第一組反引號之後加上程式碼語言,讓 Markdown 可以正確地標示程式碼語法。範例:` javascript
`
`) (在 Markdown 中稱為「包圍型程式碼區塊」,在 AEM 中只是一個「程式碼區塊」元件)。若要使用包圍型程式碼區塊,請在第一組反引號之後加上程式碼語言,讓 Markdown 可以正確地標示程式碼語法。範例:`
javascript
範例:
This is inline code within a paragraph of text.
inline code
這是包圍型程式碼片段:
Adobe 文章中大部分的文章格式都會使用標準 Markdown,例如段落、連結、清單與標題。 若需要更豐富的格式變化,可在文章中使用 Markdown 擴充功能,例如:
在每一行的開頭使用 Markdown 區塊引號 (「>」),繫結擴充元件 (例如註釋)。
部分常見的 Markdown 元素 (例如標題和程式碼區塊) 會包含擴充屬性。 如需變更預設屬性,請在元件之後新增參數,並置於大括弧內 (「/{ /}」)。 擴充屬性會以實例說明。
您可以選擇使用這些註釋類型,以吸引讀者注意特定內容:
[!NOTE]
[!TIP]
[!IMPORTANT]
[!CAUTION]
[!WARNING]
[!ADMINISTRATION]
[!AVAILABILITY]
[!PREREQUISITES]
[!ERROR]
[!INFO]
[!SUCCESS]
一般來說,註釋區塊應節制使用,註釋太多可能會造成干擾。 雖然註釋區塊也支援程式碼片段、影像、清單和連結,但請試著讓註釋區塊簡單明瞭。
原生 Markdown 不會轉譯內嵌影片,但您可以使用此 Markdown 擴充功能達成此目的。
AEM 中的「類似項目」元件會出現在文章結尾處。 這會顯示相關連結。 文章輸出時,可採用相同的第 2 層標題 (##) 格式,不必加入迷你目錄。
我們所有 Markdown 說明內容一開始會使用機器翻譯工具來進行本地化。 如果說明內容從未進行過本地化,那麼我們將保留機器翻譯。 但是,如果說明內容過去已經進行過本地化,那麼機器翻譯的內容將充當預留位置,而內容部分則在進行人工翻譯中。
``
在進行機器翻譯期間,系統會勾選標示為 `` 的項目,並根據本地化資料庫來決定適當的翻譯。 若 UI 當未經過本地化,此標記將允許系統保留該特定語言的英文 UI 參照 (即 義大利文的 Analytics 參照)。
來源:
注意
在三個標記選項中,這是提高品質內容最重要的一項,且屬於強制規定。
[!DNL]
我們使用「不要翻譯」列表來設定規則,讓機器翻譯引擎知道哪些應該保留英文內容。 最常見的項目為解決方案的完整名稱,如「Adobe Analytics」、「Adobe Campaign」和「Adobe Target」。 但是,可能有我們需要強制引擎使用英文的情況,因為所考慮的名詞可能是用作特定專業用語或是一般用語。 最明顯的情況為解決方案的簡短名稱,如「Analytics」、「Campaign」和「Target」等。 機器很難理解這些是解決方案名稱而不是通用名詞。 該標記也可以用作一定要保留為英文或文字較短部分的第三方名稱/特性,例如必須保留為英文的短語或句子。
包含底線的替代文字無法正確轉譯。 舉例來說,請避免使用下列文字:
我們最理想的作法是在檔名中使用連字號 (「-」) 而非底線 (「_」)。
您將文字複製到 Markdown 編輯器時,這些文字可能會含有「聰明」(彎曲) 的單引號或雙引號。 這些引號需要編碼或變更為基本的單引號或雙引號。 否則檔案發佈後,畫面可能會出現奇怪的字元,像是:It’s
在此提供這些標點符號的「聰明版」編碼:
“
”
’
‘
若要在檔案中的文字 (而非程式碼) 使用角括弧 (像是要表示預留位置),請手動編碼角括弧。 否則,Markdown 會認為這些角括弧代表 HTML 標籤。
舉例來說,請將 <script name> 編碼如下 <script name>
<script name>
<script name>
不可在標題中使用 & 符號。 請改用「與」或「和」,或使用 & 編碼。
&
Adobe 技術文件中的文章是以名為 Markdown 的精簡化標記語言寫成,這種語言容易閱讀及學習。
我們目前是將 Adobe 文件內容儲存在 GitHub,而 GitHub 使用的 Markdown 版本稱為 GitHub Flavored Markdown (GFM),可提供額外功能滿足常見的格式需求。 此外,Adobe 更適度擴充 Markdown 效能,以支援註釋、提示和內嵌影片等特定的說明相關功能。
Markdown 基本介紹
以下章節介紹使用 Markdown 撰寫的基礎知識。
標題
若要建立標題,請在文字行的開頭使用井字號 (#):
基本文字
使用 Markdown 時,標示段落並不需要特殊語法。
若要將文字的格式設為粗體,請以雙星號括住文字。 若要將文字的格式設為斜體,請以單星號括住文字:
若要略過 Markdown 格式字元,請在該字元前使用「\」:
編號清單與項目符號清單
若要建立項目符號清單,請在文字行的開頭使用
1.
或1)
,但同一份清單內請勿混用不同格式。 您不必指定編號, GitHub 會自動完成編號工作。顯示結果:
若要建立項目符號清單,請在文字行的開頭使用「*」、「-」或「+」,但同一份清單內請勿混用不同格式。 (請勿在同一份文件中混用項目符號格式,例如 * 和 +)。
顯示結果:
清單內也可以內嵌清單,並在清單項目間新增內容。
顯示結果:
Set up your table and code blocks.
Perform this step.
Make sure that your table looks like this:
This is the fourth step.
Do another step.
表格
表格並非 Markdown 核心規格的一部分,但 Adobe 可在某些情況下支援表格。 Markdown 的儲存格不支援多行清單。 避免在表格中輸入多行文字,會是最理想的作法。 您可以使用直立線 (|) 字元勾勒出行、列,藉此建立表格。 連字號會建立各欄標題,直立線符號則能分隔各欄。 在表格前面加上一個空白行,以確保表格成功轉譯。
顯示結果:
Markdown 要呈現簡單的表格沒有問題。 不過,若表格的儲存格內包含多個段落或清單,就會難以呈現。 如果是這類內容,建議您使用其他格式,例如改為標題與文字。
如需建立表格的詳細資訊,請參閱:
連結
內嵌連結使用的 Markdown 語法是由超連結文字的
[link text]
部分,以及緊接在後的連結網址或檔案名稱(file-name.md)
部分所組成。[link text](file-name.md)
顯示結果:
Adobe
若連結的是同一存放庫內的文章 (交叉參照),請使用相對連結。 您可使用所有相對連結運算元,例如「/」(目前目錄)、「…/」(上一層目錄) 和「…/…/」(上兩層目錄)。
如需連結的詳細資訊,請參閱本指南中的連結一文,瞭解連結語法。
影像
顯示結果:
程式碼片段
Markdown 支援將程式碼片段內嵌在句子中,或以「包圍型」獨立片段形式插入句子之間。 如需詳細資訊,請參閱 Markdown 對程式碼片段的原生支援
使用反引號 (
`
) 在段落中建立內嵌程式碼樣式。若要建立特定的多行程式碼區塊,請在程式碼區塊前後加上三個反引號 (`) (在 Markdown 中稱為「包圍型程式碼區塊」,在 AEM 中只是一個「程式碼區塊」元件)。若要使用包圍型程式碼區塊,請在第一組反引號之後加上程式碼語言,讓 Markdown 可以正確地標示程式碼語法。範例:`
javascript
範例:
顯示結果:
This is
inline code
within a paragraph of text.這是包圍型程式碼片段:
自訂 Markdown 擴充功能
Adobe 文章中大部分的文章格式都會使用標準 Markdown,例如段落、連結、清單與標題。 若需要更豐富的格式變化,可在文章中使用 Markdown 擴充功能,例如:
在每一行的開頭使用 Markdown 區塊引號 (「>」),繫結擴充元件 (例如註釋)。
部分常見的 Markdown 元素 (例如標題和程式碼區塊) 會包含擴充屬性。 如需變更預設屬性,請在元件之後新增參數,並置於大括弧內 (「/{ /}」)。 擴充屬性會以實例說明。
註釋區塊
您可以選擇使用這些註釋類型,以吸引讀者注意特定內容:
[!NOTE]
[!TIP]
[!IMPORTANT]
[!CAUTION]
[!WARNING]
[!ADMINISTRATION]
[!AVAILABILITY]
[!PREREQUISITES]
[!ERROR]
[!ADMINISTRATION]
[!INFO]
[!SUCCESS]
一般來說,註釋區塊應節制使用,註釋太多可能會造成干擾。 雖然註釋區塊也支援程式碼片段、影像、清單和連結,但請試著讓註釋區塊簡單明瞭。
顯示結果:
影片
原生 Markdown 不會轉譯內嵌影片,但您可以使用此 Markdown 擴充功能達成此目的。
顯示結果:
類似項目
AEM 中的「類似項目」元件會出現在文章結尾處。 這會顯示相關連結。 文章輸出時,可採用相同的第 2 層標題 (##) 格式,不必加入迷你目錄。
顯示結果:
UICONTROL 和 DNL
我們所有 Markdown 說明內容一開始會使用機器翻譯工具來進行本地化。 如果說明內容從未進行過本地化,那麼我們將保留機器翻譯。 但是,如果說明內容過去已經進行過本地化,那麼機器翻譯的內容將充當預留位置,而內容部分則在進行人工翻譯中。
``
在進行機器翻譯期間,系統會勾選標示為 `` 的項目,並根據本地化資料庫來決定適當的翻譯。 若 UI 當未經過本地化,此標記將允許系統保留該特定語言的英文 UI 參照 (即 義大利文的 Analytics 參照)。
範例:
來源:
注意
在三個標記選項中,這是提高品質內容最重要的一項,且屬於強制規定。
[!DNL]
我們使用「不要翻譯」列表來設定規則,讓機器翻譯引擎知道哪些應該保留英文內容。 最常見的項目為解決方案的完整名稱,如「Adobe Analytics」、「Adobe Campaign」和「Adobe Target」。 但是,可能有我們需要強制引擎使用英文的情況,因為所考慮的名詞可能是用作特定專業用語或是一般用語。 最明顯的情況為解決方案的簡短名稱,如「Analytics」、「Campaign」和「Target」等。 機器很難理解這些是解決方案名稱而不是通用名詞。 該標記也可以用作一定要保留為英文或文字較短部分的第三方名稱/特性,例如必須保留為英文的短語或句子。
範例:
來源:
Gotcha 與疑難排解
替代文字
包含底線的替代文字無法正確轉譯。 舉例來說,請避免使用下列文字:
我們最理想的作法是在檔名中使用連字號 (「-」) 而非底線 (「_」)。
單引號與雙引號
您將文字複製到 Markdown 編輯器時,這些文字可能會含有「聰明」(彎曲) 的單引號或雙引號。 這些引號需要編碼或變更為基本的單引號或雙引號。 否則檔案發佈後,畫面可能會出現奇怪的字元,像是:It’s
在此提供這些標點符號的「聰明版」編碼:
“
”
’
‘
角括弧
若要在檔案中的文字 (而非程式碼) 使用角括弧 (像是要表示預留位置),請手動編碼角括弧。 否則,Markdown 會認為這些角括弧代表 HTML 標籤。
舉例來說,請將
<script name>
編碼如下<script name>
標題中的 & 符號
不可在標題中使用 & 符號。 請改用「與」或「和」,或使用
&
編碼。另請參閱
Markdown 資源