# GitLab Markdown > 原文：[https://docs.gitlab.com/ee/user/markdown.html](https://docs.gitlab.com/ee/user/markdown.html) * [GitLab Flavored Markdown (GFM)](#gitlab-flavored-markdown-gfm) * [Transition from Redcarpet to CommonMark](#transition-from-redcarpet-to-commonmark) * [GFM extends standard Markdown](#gfm-extends-standard-markdown) * [New GFM Markdown extensions](#new-gfm-markdown-extensions) * [Colors](#colors) * [Diagrams and flowcharts](#diagrams-and-flowcharts) * [Mermaid](#mermaid) * [PlantUML](#plantuml) * [Emoji](#emoji) * [Front matter](#front-matter) * [Inline diff](#inline-diff) * [Math](#math) * [Special GitLab references](#special-gitlab-references) * [Task lists](#task-lists) * [Table of contents](#table-of-contents) * [Wiki-specific Markdown](#wiki-specific-markdown) * [Wiki - direct page link](#wiki---direct-page-link) * [Wiki - direct file link](#wiki---direct-file-link) * [Wiki - hierarchical link](#wiki---hierarchical-link) * [Wiki - root link](#wiki---root-link) * [Embedding metrics in GitLab Flavored Markdown](#embedding-metrics-in-gitlab-flavored-markdown) * [Standard Markdown and extensions in GitLab](#standard-markdown-and-extensions-in-gitlab) * [Blockquotes](#blockquotes) * [Multiline blockquote](#multiline-blockquote) * [Code spans and blocks](#code-spans-and-blocks) * [Colored code and syntax highlighting](#colored-code-and-syntax-highlighting) * [Emphasis](#emphasis) * [Multiple underscores in words and mid-word emphasis](#multiple-underscores-in-words-and-mid-word-emphasis) * [Footnotes](#footnotes) * [Headers](#headers) * [Header IDs and links](#header-ids-and-links) * [Horizontal Rule](#horizontal-rule) * [Images](#images) * [Videos](#videos) * [Audio](#audio) * [Inline HTML](#inline-html) * [Details and summary](#details-and-summary) * [Line breaks](#line-breaks) * [Newlines](#newlines) * [Links](#links) * [URL auto-linking](#url-auto-linking) * [Lists](#lists) * [Superscripts / Subscripts](#superscripts--subscripts) * [Tables](#tables) * [Copy from spreadsheet and paste in Markdown](#copy-from-spreadsheet-and-paste-in-markdown) * [References](#references) # GitLab Markdown[](#gitlab-markdown "Permalink") 該 Markdown 指南**僅對 GitLab 的內部 Markdown 渲染系統的條目和文件有效** . 它是**無效**的[GitLab 文檔，網站](https://s0docs0gitlab0com.icopy.site)或[GitLab 的主要網站](https://about.gitlab.com) ，因為它們都使用[Kramdown](https://kramdown.gettalong.org)作為他們的降價引擎. 文檔網站使用擴展的 Kramdown 寶石[GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown) . 有關完整的 Kramdown 參考，請查閱《 [GitLab Kramdown 指南》](https://about.gitlab.com/handbook/markdown-guide/) . **注意：**我們建議您查看[GitLab 本身提供的](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md)此文檔. ## GitLab Flavored Markdown (GFM)[](#gitlab-flavored-markdown-gfm "Permalink") GitLab 使用" GitLab 風味降價"（GFM）. 它以幾種方式擴展了[CommonMark 規范](https://spec.commonmark.org/current/) （基于標準 Markdown），以添加其他有用的功能. 它的靈感來自[GitHub Flavored Markdown](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax) . 您可以在以下區域使用 GFM： * Comments * Issues * 合并要求 * Milestones * 代碼段（代碼段必須以`.md`擴展名命名） * 維基頁面 * 倉庫中的 Markdown 文檔 * Epics 您還可以在 GitLab 中使用其他 RTF 文件. 您可能必須安裝依賴項才能這樣做. 請參閱[`gitlab-markup` gem 項目](https://gitlab.com/gitlab-org/gitlab-markup)以獲取更多信息. ### Transition from Redcarpet to CommonMark[](#transition-from-redcarpet-to-commonmark "Permalink") 從 11.1 開始，GitLab 使用[CommonMark Ruby 庫](https://github.com/gjtorikian/commonmarker)對[Markit](https://github.com/gjtorikian/commonmarker)處理 GitLab 系統中的所有新問題，合并請求，注釋和其他 Markdown 內容. 從 11.3 開始，存儲庫中的 Wiki 頁面和 Markdown 文件（ `*.md` ）也將通過 CommonMark 處理. 從 11.8 開始， [Redcarpet Ruby 庫](https://github.com/vmg/redcarpet)已被刪除，所有問題和注釋，包括 11.1 之前的問題和注釋，現在都可以使用[CommonMark Ruby Library 處理](https://github.com/gjtorikian/commonmarker) . 該文檔網站的[Markdown 引擎](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/108)已于 2018 年 10 月[從 Redcarpet 遷移到 Kramdown](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/108) . 您的存儲庫中可能存在較舊的問題，合并請求或 Markdown 文檔，這些文檔是使用 GitLab 的 RedCarpet 版本的 Markdown 的細微差別編寫的. 由于 CommonMark 使用了稍微嚴格的語法，因此自我們過渡到 CommonMark 以來，這些文檔現在看起來可能會有所不同. 通常很容易修復. 例如，帶嵌套列表的編號列表可能會錯誤顯示： ``` 1. Chocolate - dark - milk ``` 只需在每個嵌套項目中添加一個空格即可使`-`與頂部列表項的第一個字符對齊（本例中為`C` ）： ``` 1. Chocolate - dark - milk ``` 1. Chocolate * dark * milk **注意：**我們將在本文檔中標記 Redcarpet 和 CommonMark Markdown 之間的任何重大差異. 如果您有大量的 Markdown 文件，確定它們是否正確顯示可能很繁瑣. 您可以使用[diff_redcarpet_cmark](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark)工具（不是官方支持的產品）來生成文件列表以及 RedCarpet 和 CommonMark 呈現文件的方式之間的差異. 它可以指示是否需要更改任何內容-通常不需要更改. ### GFM extends standard Markdown[](#gfm-extends-standard-markdown "Permalink") GitLab 充分利用了標準（CommonMark）格式，但還包括對 GitLab 用戶有用的附加功能. 它利用了[Markdown](#new-GFM-markdown-extensions)的[新功能](#new-GFM-markdown-extensions) ，這些[功能](#new-GFM-markdown-extensions)是標準 Markdown 所沒有的： * [Color “chips” written in HEX, RGB or HSL](#colors) * [Diagrams and flowcharts](#diagrams-and-flowcharts) * [Emoji](#emoji) * [Front matter](#front-matter) * [Inline diffs](#inline-diff) * [Math equations and symbols written in LaTeX](#math) * [Special GitLab references](#special-gitlab-references) * [Task Lists](#task-lists) * [Table of Contents](#table-of-contents) * [Wiki specific Markdown](#wiki-specific-markdown) 它還具有[擴展的 Markdown 功能](#standard-markdown-and-extensions-in-gitlab) ，而無需更改標準 Markdown 的使用方式： | 標準減價 | 在 GitLab 中擴展 Markdown | | --- | --- | | [blockquotes](#blockquotes) | [multi-line blockquotes](#multiline-blockquote) | | [code blocks](#code-spans-and-blocks) | [colored code and syntax highlighting](#colored-code-and-syntax-highlighting) | | [emphasis](#emphasis) | [multiple underscores in words](#multiple-underscores-in-words-and-mid-word-emphasis) | | [headers](#headers) | [linkable Header IDs](#header-ids-and-links) | | [images](#images) | [embedded videos](#videos) and [audio](#audio) | | [line breaks](#line-breaks) | [more line break control](#newlines) | | [links](#links) | [automatically linking URLs](#url-auto-linking) | ## New GFM Markdown extensions[](#new-gfm-markdown-extensions "Permalink") ### Colors[](#colors "Permalink") > 如果未正確呈現，請[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#colors) . 可以使用顏色指示器呈現以 HEX，RGB 或 HSL 格式書寫的顏色. 支持的格式（不支持命名的顏色）： * HEX: ``#RGB[A]`` or ``#RRGGBB[AA]`` * RGB: ``RGB[A](R, G, B[, A])`` * HSL: ``HSL[A](H, S, L[, A])`` 反引號內的顏色后面將帶有顏色"碎片"： ``` - `#F00` - `#F00A` - `#FF0000` - `#FF0000AA` - `RGB(0,255,0)` - `RGB(0%,100%,0%)` - `RGBA(0,255,0,0.3)` - `HSL(540,70%,50%)` - `HSLA(540,70%,50%,0.3)` ``` * `#F00` * `#F00A` * `#FF0000` * `#FF0000AA` * `RGB(0,255,0)` * `RGB(0%,100%,0%)` * `RGBA(0,255,0,0.3)` * `HSL(540,70%,50%)` * `HSLA(540,70%,50%,0.3)` ### Diagrams and flowcharts[](#diagrams-and-flowcharts "Permalink") 可以使用[Mermaid](https://s0mermaidjs0github0io.icopy.site/)或[PlantUML](https://plantuml.com)從 GitLab 中的文本生成圖表和流程圖. #### Mermaid[](#mermaid "Permalink") 在 GitLab 10.3 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15107) . 訪問[官方頁面](https://s0mermaidjs0github0io.icopy.site/)以獲取更多詳細信息. 如果您不熟悉使用 Mermaid，或者需要幫助來確定 Mermaid 代碼中的問題，則[Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/)是一個有用的工具，可用于在 Mermaid 圖中創建和解決問題. 為了生成圖表或流程圖，您應該在`mermaid`塊內編寫文本： ``` ```mermaid graph TD; A-->B; A-->C; B-->D; C-->D; ``` ``` 圖 TD; A-> B; A-> C; B-> D; C-> D; 子圖也可以包括： ``` ```mermaid graph TB SubGraph1 --> SubGraph1Flow subgraph "SubGraph 1 Flow" SubGraph1Flow(SubNode 1) SubGraph1Flow -- Choice1 --> DoChoice1 SubGraph1Flow -- Choice2 --> DoChoice2 end subgraph "Main Graph" Node1[Node 1] --> Node2[Node 2] Node2 --> SubGraph1[Jump to SubGraph1] SubGraph1 --> FinalThing[Final Thing] end ``` ``` 圖 TB SubGraph1-> SubGraph1Flow 子圖" SubGraph 1 Flow" SubGraph1Flow（SubNode 1）SubGraph1Flow-Choice1-> DoChoice1 SubGraph1Flow-Choice2-> DoChoice2 結束子圖" Main Graph" Node1 [Node 1]-> Node2 [ Node 2] Node2-> SubGraph1 [Jump to SubGraph1] SubGraph1-> FinalThing [Final Thing]結束 #### PlantUML[](#plantuml "Permalink") 為了使 PlantUML 在 GitLab 中可用，GitLab 管理員需要首先啟用它. 在[PlantUML＆GitLab 中](../administration/integration/plantuml.html)了解更多[信息](../administration/integration/plantuml.html) . ### Emoji[](#emoji "Permalink") > 如果未正確呈現，請[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#emoji) . ``` Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: :zap: You can use emoji anywhere GFM is supported. :v: You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that. If you're new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up one of the supported codes. Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup: ``` 有時候你想  大約添加一些  給你  . 好吧，我們有禮物送給您： 您可以在支持 GFM 的任何地方使用表情符號.  您可以使用它指出一個  或警告  補丁. 如果有人真的改善了你  代碼，給他們發送一些  . 人們會  為此. 如果您是新手，請不要  . 您可以輕松加入表情符號  . 您需要做的只是查找受支持的代碼之一. 有關所有受支持的表情符號代碼的列表，請查閱[表情符號備忘單](https://www.webfx.com/tools/emoji-cheat-sheet/) .  > **注意：**以上表情符號示例在本文檔中使用了硬編碼圖像. 在 GitLab 中呈現時，表情符號可能會出現不同，具體取決于所使用的操作系統和瀏覽器. 大多數 emoji 表情在 macOS，Windows，iOS，Android 上均受本機支持，并且將退回到不支持圖像的基于圖像的表情上. **注意：**在 Linux 上，您可以下載[Noto Color Emoji](https://www.google.com/get/noto/help/emoji/)以獲得完整的本機表情符號支持. Ubuntu 18.04（與許多現代 Linux 發行版一樣）默認情況下已安裝此字體. ### Front matter[](#front-matter "Permalink") 在 GitLab 11.6 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23331) . 首要事項是 Markdown 文檔開頭，內容之前的元數據. 靜態站點生成器（例如[Jekyll](https://jekyllrb.com/docs/front-matter/) ， [Hugo](https://s0gohugo0io.icopy.site/content-management/front-matter/)和許多其他應用程序）可以使用此數據. 當您查看由 GitLab 渲染的 Markdown 文件時，任何前端問題都會按原樣顯示在文檔頂部的框中，位于渲染的 HTML 內容之前. 要查看示例，可以在[GitLab 文檔文件](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/README.md)的源版本和渲染版本之間切換. 在 GitLab 中，僅在 Markdown 文件和 Wiki 頁面中使用前題，而不在支持 Markdown 格式的其他地方使用. 它必須在文檔的最頂部，并且必須在定界符之間，如下所述. 支持以下定界符： * YAML（ `---` ）： ``` --- title: About Front Matter example: language: yaml --- ``` * TOML（ `+++` ）： ``` +++ title = "About Front Matter" [example] language = "toml" +++ ``` * JSON（ `;;;` ）： ``` ;;; { "title": "About Front Matter" "example": { "language": "json" } } ;;; ``` 通過向任何現有定界符添加說明符來支持其他語言. 例如： ``` ---php $title = "About Front Matter"; $example = array( 'language' => "php", ); --- ``` ### Inline diff[](#inline-diff "Permalink") > 如果未正確呈現，請[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#inline-diff) . 使用內聯 diff 標簽，您可以顯示`{+ additions +}`或`[- deletions -]` . 包裝標簽可以是大括號或方括號： ``` - {+ addition 1 +} - [+ addition 2 +] - {- deletion 3 -} - [- deletion 4 -] ``` * {+加法 1 +} * [+加法 2 +] * {-刪除 3-} * [-刪除 4-] * * * 但是，包裝標簽不能混合使用： ``` - {+ addition +] - [+ addition +} - {- deletion -] - [- deletion -} ``` 如果您的差異包含``code``字體的單詞，請確保使用反斜杠`\`來轉義每個反引號``` ，否則差異突出顯示將無法正確呈現： ``` - {+ Just regular text +} - {+ Text with `backticks` inside +} - {+ Text with escaped \`backticks\` inside +} ``` * {+普通文字+} * {+帶有`backticks`文字+} * {+內含轉義的`反引號'的文字+} ### Math[](#math "Permalink") > 如果未正確呈現，請[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#math) . 可以使用[KaTeX](https://github.com/KaTeX/KaTeX)渲染用 LaTeX 語法編寫的數學運算. 在美元符號`$`之間寫的數學將與文本內嵌. 用聲明為`math`的語言在[代碼塊中](#code-spans-and-blocks)編寫的`math`將在單獨的行上呈現： ``` This math is inline $`a^2+b^2=c^2`$. This is on a separate line ```math a^2+b^2=c^2 ``` ``` 此數學`a^2+b^2=c^2`為內聯$ `a^2+b^2=c^2` $. 這是在單獨的行上 ``` a^2+b^2=c^2 ``` *請注意，KaTeX 僅支持 LaTeX 的[子集](https://katex.org/docs/supported.html) .* **注意：**這也適用于 Asciidoctor `:stem: latexmath` . 有關詳細信息，請參見[Asciidoctor 用戶手冊](https://asciidoctor.org/docs/user-manual/#activating-stem-support) . ### Special GitLab references[](#special-gitlab-references "Permalink") GFM 可以識別與 GitLab 相關的特殊參考. 例如，您可以輕松地引用項目中的問題，提交，團隊成員甚至整個團隊. GFM 會將引用轉換為鏈接，以便您可以輕松地在它們之間導航. 此外，GFM 可以識別某些跨項目引用，并且還具有一個速記版本，可以引用同一名稱空間中的其他項目. GFM 將識別以下內容： | references | input | 跨項目參考 | shortcut within same namespace | | --- | --- | --- | --- | | 特定使用者 | `@user_name` | ? | ? | | 特定人群 | `@group_name` | ? | ? | | 整個團隊 | `@all` | ? | ? | | project | `namespace/project>` | ? | ? | | issue | `#123` | `namespace/project#123` | `project#123` | | 合并要求 | `!123` | `namespace/project!123` | `project!123` | | snippet | `$123` | `namespace/project$123` | `project$123` | | epic | `&123` | `group1/subgroup&123` | ? | | 通過 ID 標簽 | `~123` | `namespace/project~123` | `project~123` | | 一詞標簽名稱 | `~bug` | `namespace/project~bug` | `project~bug` | | 多詞標簽名稱 | `~"feature request"` | `namespace/project~"feature request"` | `project~"feature request"` | | 范圍標簽按名稱 | `~"priority::high"` | `namespace/project~"priority::high"` | `project~"priority::high"` | | ID 項目里程碑 | `%123` | `namespace/project%123` | `project%123` | | 一詞里程碑 | `%v1.23` | `namespace/project%v1.23` | `project%v1.23` | | 多詞里程碑 | `%"release candidate"` | `namespace/project%"release candidate"` | `project%"release candidate"` | | 具體提交 | `9ba12248` | `namespace/project@9ba12248` | `project@9ba12248` | | 提交范圍比較 | `9ba12248...b19a04f5` | `namespace/project@9ba12248...b19a04f5` | `project@9ba12248...b19a04f5` | | 倉庫文件參考 | `[README](doc/README)` | ? | ? | | 存儲庫文件行參考 | `[README](doc/README#L13)` | ? | ? | 除此之外，還可以識別和格式化指向某些對象的鏈接. 這些示例包括： * 對問題的評論： `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234#note_101075757"` ，它將呈現為`#1234 (note1)` * 問題設計標簽： `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs"` ，該標簽將顯示為`#1234 (designs)` . * 鏈接到各個設計： `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs/layout.png"` ，它將呈現為`#1234[layout.png]` . ### Task lists[](#task-lists "Permalink") > 如果未正確呈現，請[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#task-lists) . 您可以在支持 Markdown 的任何位置添加任務列表，但是如果它們處于問題，合并請求或注釋中，則只能"單擊"以切換它們. 在其他地方，您必須手動編輯 Markdown 以通過在方括號內添加或刪除`x`來更改狀態. 要創建任務列表，請添加特殊格式的 Markdown 列表. 您可以使用無序列表或有序列表： ``` - [x] Completed task - [ ] Incomplete task - [ ] Sub-task 1 - [x] Sub-task 2 - [ ] Sub-task 3 1. [x] Completed task 1. [ ] Incomplete task 1. [ ] Sub-task 1 1. [x] Sub-task 2 ``` * [x]完成的任務 * []未完成的任務 * []子任務 1 * [x]子任務 2 * []子任務 3 1. [x] Completed task 2. []未完成的任務 1. []子任務 1 2. [x]子任務 2 ### Table of contents[](#table-of-contents "Permalink") 通過在標記行`[[_TOC_]]`上添加標記，您可以將目錄添加到 Markdown 文件，Wiki 頁面或發布/合并請求描述中. 它將顯示為鏈接到各種標題的無序列表. ``` This is an intro sentence to my Wiki page. [[_TOC_]] ## My first heading First section content. ## My second heading Second section content. ``` [](img/markdown_toc_preview_v12_9.png) ### Wiki-specific Markdown[](#wiki-specific-markdown "Permalink") 以下示例顯示了 Wiki 內部鏈接的行為. #### Wiki - direct page link[](#wiki---direct-page-link "Permalink") 僅包含頁面的子彈的鏈接將指向該頁面， *位于 Wiki 的基本級別* . 該代碼段將鏈接到 Wiki 根目錄下的`documentation`頁面： ``` [Link to Documentation](documentation) ``` #### Wiki - direct file link[](#wiki---direct-file-link "Permalink") *相對于當前頁面* ，帶有文件擴展名的鏈接指向該文件. 如果下面的代碼段放在`<your_wiki>/documentation/related`的頁面上，它將鏈接到`<your_wiki>/documentation/file.md` ： ``` [Link to File](file.md) ``` #### Wiki - hierarchical link[](#wiki---hierarchical-link "Permalink") 可以使用`./<page>` ， `../<page>`來相對于當前 Wiki 頁面構建鏈接. 如果此代碼段放在`<your_wiki>/documentation/main`的頁面上，它將鏈接到`<your_wiki>/documentation/related` ： ``` [Link to Related Page](./related) ``` 如果此代碼段放在`<your_wiki>/documentation/related/content`的頁面上，它將鏈接到`<your_wiki>/documentation/main` ： ``` [Link to Related Page](../main) ``` 如果此代碼段放在`<your_wiki>/documentation/main`的頁面上，它將鏈接到`<your_wiki>/documentation/related.md` ： ``` [Link to Related Page](./related.md) ``` 如果此代碼段放在`<your_wiki>/documentation/related/content`的頁面上，它將鏈接到`<your_wiki>/documentation/main.md` ： ``` [Link to Related Page](../main.md) ``` #### Wiki - root link[](#wiki---root-link "Permalink") 以`/`開頭的鏈接是相對于 Wiki 根目錄的. 該代碼段鏈接到`<wiki_root>/documentation` ： ``` [Link to Related Page](/documentation) ``` 該代碼段鏈接到`<wiki_root>/miscellaneous.md` ： ``` [Link to Related Page](/miscellaneous.md) ``` ### Embedding metrics in GitLab Flavored Markdown[](#embedding-metrics-in-gitlab-flavored-markdown "Permalink") 公制圖表可以嵌入到 GitLab 風味 Markdown 中. 有關更多詳細信息，請參見[在 GitLab 風格的 Markdown 中嵌入度量標準](../user/project/integrations/prometheus.html#embedding-metric-charts-within-gitlab-flavored-markdown) . ## Standard Markdown and extensions in GitLab[](#standard-markdown-and-extensions-in-gitlab "Permalink") 所有標準 Markdown 格式均應在 GitLab 中按預期工作. 一些標準功能通過附加功能進行了擴展，而不會影響標準用法. 如果擴展了功能，則新選項將作為子節列出. ### Blockquotes[](#blockquotes "Permalink") 塊引號是突出顯示信息（如邊注）的簡便方法. 它是通過以`>`開頭的 blockquote 行來生成的： ``` > Blockquotes are very handy to emulate reply text. > This line is part of the same quote. Quote break. > This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. ``` > 塊引用非常容易模擬回復文本. 該行是同一報價的一部分. 報價中斷. > 這是一條很長的行，當它換行時仍會被正確引用. 哦，男孩，讓我們繼續寫作，以確保它足夠長，可以實際包裹所有人. 哦，您可以*將* **Markdown**放入 blockquote 中. #### Multiline blockquote[](#multiline-blockquote "Permalink") > 如果未正確呈現，請[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#multiline-blockquote) . GFM 還支持`>>>`圍起來的多行塊引用，從而擴展了標準的 Markdown 標準： ``` >>> If you paste a message from somewhere else that spans multiple lines, you can quote that without having to manually prepend `>` to every line! >>> ``` > 如果您從其他地方粘貼消息 > > 跨越多行， > > 您可以引用它，而不必手動在每行前面加上`>` ！ ### Code spans and blocks[](#code-spans-and-blocks "Permalink") 您可以輕松突出顯示應視為代碼而非簡單文本的任何內容. 簡單的內聯代碼很容易用單個反引號```突出顯示： ``` Inline `code` has `back-ticks around` it. ``` Inline `code` has `back-ticks around` it. * * * 同樣，整個代碼塊可以用三個反引號（ ````` ），三個波浪號（ `~~~` ）或縮進 4 個或更多的空格來圍起來，以實現較大代碼體的相似效果. ``` ```python def function(): #indenting works just fine in the fenced code block s = "Python code" print s ``` Using 4 spaces is like using 3-backtick fences. ``` ``` ~~~ Tildes are OK too. ~~~ ``` 上面的三個示例呈現為： ``` def function(): #indenting works just fine in the fenced code block s = "Python code" print s ``` ``` Using 4 spaces is like using 3-backtick fences. ``` ``` Tildes are OK too. ``` #### Colored code and syntax highlighting[](#colored-code-and-syntax-highlighting "Permalink") > 如果未正確呈現，請[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#colored-code-and-syntax-highlighting) . GitLab 使用[Rouge Ruby 庫](http://rouge.jneen.net/)在代碼塊中突出顯示了更加豐富多彩的語法. 有關支持的語言的列表，請訪問[Rouge 項目 Wiki](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers) . 語法突出顯示僅在代碼塊中受支持，因此在內聯時無法突出顯示代碼. 代碼塊由帶有三個反引號（ ````` ）或三個波浪號（ `~~~` ）的行圍起來，并在第一個圍欄的末尾標識了語言： ``` ```javascript var s = "JavaScript syntax highlighting"; alert(s); ``` ```python def function(): #indenting works just fine in the fenced code block s = "Python syntax highlighting" print s ``` ```ruby require 'redcarpet' markdown = Redcarpet.new("Hello World!") puts markdown.to_html ``` ``` No language indicated, so no syntax highlighting. s = "There is no highlighting for this." But let's throw in a <b>tag</b>. ``` ``` 上面的四個示例呈現為： ``` var s = "JavaScript syntax highlighting"; alert(s); ``` ``` def function(): #indenting works just fine in the fenced code block s = "Python syntax highlighting" print s ``` ``` require 'redcarpet' markdown = Redcarpet.new("Hello World!") puts markdown.to_html ``` ``` No language indicated, so no syntax highlighting. s = "There is no highlighting for this." But let's throw in a <b>tag</b>. ``` ### Emphasis[](#emphasis "Permalink") 在 Markdown 中有多種強調文本的方法. 您可以斜體，粗體，刪除線，以及將這些強調樣式結合在一起. Examples: ``` Emphasis, aka italics, with *asterisks* or _underscores_. Strong emphasis, aka bold, with double **asterisks** or __underscores__. Combined emphasis with **asterisks and _underscores_**. Strikethrough uses two tildes. ~~Scratch this.~~ ``` 強調，又稱斜體，帶有*星號*或*下劃線* . 重點突出，又大膽，帶有雙星**號**或**下劃線** . 結合強調與**星號和*下劃線*** . 刪除線使用兩個波浪號. ~~抓這個.~~ **注意：**刪除線不是 Markdown 核心標準的一部分，而是 GFM 的一部分. #### Multiple underscores in words and mid-word emphasis[](#multiple-underscores-in-words-and-mid-word-emphasis "Permalink") > 如果未正確呈現，請[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#multiple-underscores-in-words) . 僅將單詞的*一部分*斜體化通常是沒有用的，尤其是當您要處理經常帶有多個下劃線的代碼和名稱時. 結果，GFM 通過忽略單詞中的多個下劃線來擴展了標準的 Markdown 標準，以更好地呈現討論代碼的 Markdown 文檔： ``` perform_complicated_task do_this_and_do_that_and_another_thing but_emphasis is_desired _here_ ``` perform_complicated_task do_this_and_do_that_and_another_thing 但是*在這里需要重點* * * * 如果您只想強調單詞的一部分，仍然可以使用星號來完成： ``` perform*complicated*task do*this*and*do*that*and*another thing ``` perform*complicated*task 做*這個* ， *做*那個*和*另一件事 ### Footnotes[](#footnotes "Permalink") 腳注會添加指向注釋的鏈接，該鏈接將在 Markdown 文件的末尾呈現. 要創建腳注，您既需要參考標記，又需要帶有注釋內容的單獨行（文件中的任何地方）. 無論標簽名稱如何，參考標簽的相對順序都決定了呈現的編號. 參考標記可以使用字母和其他字符. 在解決[此錯誤](https://gitlab.com/gitlab-org/gitlab/-/issues/24423)之前，請避免在腳注標簽名稱中使用小寫`w`或下劃線（ `_` ）. ``` A footnote reference tag looks like this: [^1] This reference tag is a mix of letters and numbers. [^footnote-42] [^1]: This is the text inside a footnote. [^footnote-42]: This is another footnote. ``` 腳注參考標記如下所示： <sup id="fnref:1">[1](#fn:1)</sup> 此參考標記是字母和數字的組合. <sup id="fnref:footnote-42">[2](#fn:footnote-42)</sup> ### Headers[](#headers "Permalink") ``` # H1 ## H2 ### H3 #### H4 ##### H5 ###### H6 Alternatively, for H1 and H2, an underline-ish style: Alt-H1 ====== Alt-H2 ------ ``` #### Header IDs and links[](#header-ids-and-links "Permalink") GFM 擴展了標準 Markdown 標準，以便所有 Markdown 呈現的標頭都自動獲取 ID，可以將 ID 鏈接到該 ID，注釋中除外. 懸停時，將顯示到這些 ID 的鏈接，從而可以更輕松地將鏈接復制到標頭以在其他地方使用. 根據以下規則從標頭的內容生成 ID： 1. 所有文本都將轉換為小寫. 2. 刪除所有非單詞文本（例如標點符號或 HTML）. 3. 所有空格都將轉換為連字符. 4. 連續的兩個或多個連字符轉換為 1. 5. If a header with the same ID has already been generated, a unique incrementing number is appended, starting at 1. Example: ``` # This header has spaces in it ## This header has a :thumbsup: in it # This header has Unicode in it: ?? ## This header has spaces in it ### This header has spaces in it ## This header has 3.5 in it (and parentheses) ``` 將生成以下鏈接 ID： 1. `this-header-has-spaces-in-it` 2. `this-header-has-a-in-it` 3. `this-header-has-unicode-in-it-??` 4. `this-header-has-spaces-in-it-1` 5. `this-header-has-spaces-in-it-2` 6. `this-header-has-3-5-in-it-and-parentheses` 請注意，表情符號處理是在生成標題 ID 之前進行的，因此表情符號將轉換為圖像，然后從 ID 中刪除. ### Horizontal Rule[](#horizontal-rule "Permalink") 使用三個或多個連字符，星號或下劃線來創建水平尺非常簡單： ``` Three or more hyphens, --- asterisks, *** or underscores ___ ``` ### Images[](#images "Permalink") Examples: ``` Inline-style (hover to see title text):  Reference-style (hover to see title text): ![alt text1][logo] [logo]: img/markdown_logo.png "Title Text" ``` Inline-style (hover to see title text): [](img/markdown_logo.png) 參考樣式（懸停以查看標題文本）： [](img/markdown_logo.png) #### Videos[](#videos "Permalink") > 如果未正確呈現，請[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#videos) . 鏈接到帶有視頻擴展名的文件的圖像標簽會自動轉換為視頻播放器. 有效的視頻擴展名是`.mp4` ， `.m4v` ， `.mov` ， `.webm`和`.ogv` ： ``` Here's a sample video:  ``` 這是一個示例視頻： [](img/markdown_video.mp4) #### Audio[](#audio "Permalink") > 如果未正確呈現，請[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#audio) . 與視頻類似，帶有音頻擴展名的文件的鏈接標簽會自動轉換為音頻播放器. 有效的音頻擴展名是`.mp3` ， `.oga` ， `.ogg` ， `.spx`和`.wav` ： ``` Here's a sample audio clip:  ``` 這是一個示例音頻剪輯： [](img/markdown_audio.mp3) ### Inline HTML[](#inline-html "Permalink") > 要在第二個示例中[查看](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#inline-html)在 HTML 中呈現的 Markdown，請[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#inline-html) . 您還可以在 Markdown 中使用原始 HTML，通常效果很好. 有關允許的 HTML 標記和屬性的列表，請參見 HTML :: Pipeline 的[SanitizationFilter](https://github.com/jch/html-pipeline/blob/v2.12.3/lib/html/pipeline/sanitization_filter.rb#L42)類的文檔. 除了默認`SanitizationFilter`允許列表，GitLab 允許`span` ， `abbr` ， `details`和`summary`元素. ``` <dl> <dt>Definition list</dt> <dd>Is something people use sometimes.</dd> <dt>Markdown in HTML</dt> <dd>Does *not* work **very** well. HTML <em>tags</em> will <b>work</b>, in most cases.</dd> </dl> ``` Definition list 人們有時會用到的東西. Markdown in HTML *不是*很好**. HTML *標簽*將工作 ，在大多數情況下. * * * 仍然可以在 HTML 標記內使用 Markdown，但前提是包含 Markdown 的行分為各自的行： ``` <dl> <dt>Markdown in HTML</dt> <dd>Does *not* work **very** well. HTML tags will work, in most cases.</dd> <dt>Markdown in HTML</dt> <dd> Does *not* work **very** well. HTML tags will work, in most cases. </dd> </dl> ``` Markdown in HTML *不是*很好**. HTML 標記在大多數情況下都可以使用. Markdown in HTML *不能* 很好地工作. HTML 標記在大多數情況下都可以使用. #### Details and summary[](#details-and-summary "Permalink") > 要在第二個示例中[查看](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#details-and-summary)在 HTML 中呈現的 Markdown，請[在 GitLab 本身中查看它](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#details-and-summary) . 可以使用 HTML 的[`<details>`](https://s0developer0mozilla0org.icopy.site/en-US/docs/Web/HTML/Element/details)和[`<summary>`](https://s0developer0mozilla0org.icopy.site/en-US/docs/Web/HTML/Element/summary)標記折疊內容. 這對于折疊長日志特別有用，因為它們占用更少的屏幕空間. ``` <p> <details> <summary>Click this to collapse/fold.</summary> These details <em>will</em> remain <strong>hidden</strong> until expanded. <pre><code>PASTE LOGS HERE</code></pre> </details> </p> ``` <details title="單擊以折疊/折疊. These details will remain hidden until expanded. PASTE LOGS HERE"><summary>單擊以折疊/折疊.</summary> 這些細節*將*保持**隱藏，**直到擴展. ``` PASTE LOGS HERE ```</details> * * * 這些標記內的 Markdown 也受支持. **注意：**如果 Markdown 無法正確呈現，請嘗試在頁面頂部添加`{::options parse_block_html="true" /}` ，然后將`markdown="span"`添加到開頭的摘要標記中，如下所示： `<summary markdown="span">` . 請記住，在`</summary>`標記之后和`</details>`標記之前留空行，如示例所示： ``` <details> <summary>Click this to collapse/fold.</summary> These details _will_ remain **hidden** until expanded. ``` PASTE LOGS HERE ``` </details> ``` <details title="單擊以折疊/折疊. These details will remain hidden until expanded. PASTE LOGS HERE"><summary>單擊以折疊/折疊.</summary> 這些細節*將*保持隱藏，直到擴展. ``` PASTE LOGS HERE ```</details> ### Line breaks[](#line-breaks "Permalink") 如果先前的文本以兩個換行符結尾，則會插入一個換行符（將開始一個新的段落），例如當您連續兩次按`Enter 鍵`時. 如果僅使用一個換行符（ `按`一次`Enter 鍵` ），則下一個句子將成為同一段落的一部分. 如果要避免長行換行并使它們易于編輯，這很有用： ``` Here's a line for us to start with. This longer line is separated from the one above by two newlines, so it will be a *separate paragraph*. This line is also a separate paragraph, but... These lines are only separated by single newlines, so they *do not break* and just follow the previous lines in the *same paragraph*. ``` 這是我們要開始的一行. 該較長的行與上面的一行由兩個換行符*隔開* ，因此它將是一個*單獨的段落* . 該行也是一個單獨的段落，但是…這些行僅由單個換行符分隔，因此它們*不會中斷*并且僅遵循*同一段落中*的前幾行. #### Newlines[](#newlines "Permalink") GFM 在[處理段落和換行符方面](https://spec.commonmark.org/current/)遵循 Markdown 規范. 段落是一個或多個連續的文本行，由一個或多個空行分隔（第一段末尾有兩個新行）， [如上所述](#line-breaks) . 如果您需要對換行符或換行符進行更多控制，則可以通過以反斜杠或兩個或多個空格結束一行來添加單個換行符. 連續兩個換行符將創建一個新的段落，中間有一個空行： ``` First paragraph. Another line in the same paragraph. A third line in the same paragraph, but this time ending with two spaces.{space}{space} A new line directly under the first paragraph. Second paragraph. Another line, this time ending with a backslash.\ A new line due to the previous backslash. ``` ### Links[](#links "Permalink") 有兩種創建鏈接的方法，即內聯樣式和引用樣式： ``` - This is an [inline-style link](https://www.google.com) - This is a [link to a repository file in the same directory](index.md) - This is a [relative link to a readme one directory higher](../README.md) - This is a [link that also has title text](https://www.google.com "This link takes you to Google!") Using header ID anchors: - This links to [a section on a different Markdown page, using a "#" and the header ID](index.md#overview) - This links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links) Using references: - This is a [reference-style link, see below][Arbitrary case-insensitive reference text] - You can [use numbers for reference-style link definitions, see below][1] - Or leave it empty and use the [link text itself][], see below. Some text to show that the reference links can follow later. [arbitrary case-insensitive reference text]: https://www.mozilla.org/en-US/ [1]: https://slashdot.org [link text itself]: https://www.reddit.com ``` * 這是一個[內聯樣式的鏈接](https://www.google.com) * 這是[指向同一目錄中存儲庫文件](index.html)的[鏈接](index.html) * 這是[指向自述文件的上一級目錄](../README.html)的[相對鏈接](../README.html) * 這是一個[也有標題文字](https://www.google.com "此鏈接將您帶到 Google！")的[鏈接](https://www.google.com "此鏈接將您帶到 Google！") 使用標頭 ID 錨點： * 該鏈接[使用"＃"和標題 ID](index.html#overview)鏈接到[另一個 Markdown 頁面上的部分](index.html#overview) * 這[使用"＃"和標題 ID](#header-ids-and-links)鏈接到[同一頁面上的不同部分.](#header-ids-and-links) 使用參考： * 這是[參考樣式的鏈接，請參見下文](https://www.mozilla.org/en-US/) * 您可以[將數字用于引用樣式的鏈接定義，請參見下文](https://slashdot.org) * 或將其保留為空，并使用[鏈接文本本身](https://www.reddit.com) ，請參見下文. 一些文本表明參考鏈接可以在以后使用. **注意：**相對鏈接不允許引用 Wiki 頁面或項目文件中的 Wiki 頁面中的項目文件. 這樣做的原因是，Wiki 始終位于 GitLab 中的單獨 Git 存儲庫中. 例如，僅當鏈接位于 Wiki Markdown 文件內部時， `[I'm a reference-style link](style)`才會將鏈接指向`wikis/style` . #### URL auto-linking[](#url-auto-linking "Permalink") GFM will auto-link almost any URL you put into your text: ``` - https://www.google.com - https://www.google.com - ftp://ftp.us.debian.org/debian/ - smb://foo/bar/baz - irc://irc.freenode.net/ - http://localhost:3000 ``` * [https://www.google.com](https://www.google.com) * [https://www.google.com](https://www.google.com) * [ftp://ftp.us.debian.org/debian/](ftp://ftp.us.debian.org/debian/) * <smb://foo/bar/baz> * <irc://irc.freenode.net/> * [http://localhost:3000](http://localhost:3000) ### Lists[](#lists "Permalink") 可以輕松創建有序列表和無序列表. 對于有序列表，請在有序列表的每一行的開頭添加希望列表以其開頭的數字，例如`1.` ，后跟一個空格. 在第一個數字之后，使用什么數字都沒有關系，有序列表將按垂直順序自動編號，因此對同一列表中的所有項目重復`1.` .. 如果你開始以外的其他數字`1.` ，它會用它作為第一個數字，并從那里計數. Examples: ``` 1. First ordered list item 2. Another item - Unordered sub-list. 1. Actual numbers don't matter, just that it's a number 1. Ordered sub-list 1. Next ordered sub-list item 4. And another item. ``` 1. 首先訂購的清單項目 2. 另一個項目 * 無序子列表. 3. 實際數字并不重要，只是一個數字 1. 訂購子清單 2. 下一個訂購的子清單項目 4. 還有另一個項目. 對于無序列表，請在無序列表的每一行的開頭添加`-` ， `*`或`+` ，然后加上一個空格，但是您不能混合使用它們. ``` Unordered lists can: - use - minuses They can also: * use * asterisks They can even: + use + pluses ``` 無序列表可以： * use * minuses 他們還可以： * use * asterisks They can even: * use * pluses * * * 如果列表項包含多個段落，則每個后續段落都應縮進到與列表項文本開頭相同的級別. Example: ``` 1. First ordered list item Second paragraph of first item. 1. Another item ``` 1. 首先訂購的清單項目 第一項第二段. 2. Another item * * * 如果第一項的段落沒有縮進適當的空格數，則該段落將出現在列表外部，而不是在列表項下方正確縮進. Example: ``` 1. First ordered list item Paragraph of first item. 1. Another item ``` 1. 首先訂購的清單項目 第一項的段落. 1. 另一個項目 ### Superscripts / Subscripts[](#superscripts--subscripts "Permalink") 當前，CommonMark 和 GFM 不支持 Redcarpet 支持的上標語法（ `x^2` ）. 您可以對上標和下標使用標準的 HTML 語法： ``` The formula for water is H<sub>2</sub>O while the equation for the theory of relativity is E = mc<sup>2</sup>. ``` 水的公式為 H ₂ O，而相對論的公式為 E = mc ² . ### Tables[](#tables "Permalink") 表不是 Markdown 核心規范的一部分，但它們是 GFM 的一部分. 1. 第一行包含標頭，并用"豎線"（ `|` ）分隔. 2. 第二行將標題與單元格分開，并且必須包含三個或更多破折號. 3. 第三行以及隨后的任何行均包含單元格值. * 您**不能**在 Markdown 中將單元格分隔成多行，它們必須保持為單行，但它們可能會很長. 如果需要，還可以包含 HTML `<br>`標記以強制換行. * 像元大小**不必**彼此匹配. 它們很靈活，但必須用管道（ `|` ）分隔. * 您**可以**有空白單元格. Example: ``` | header 1 | header 2 | header 3 | | --- | ------ |---------:| | cell 1 | cell 2 | cell 3 | | cell 4 | cell 5 is longer | cell 6 is much longer than the others, but that's ok. It will eventually wrap the text when the cell is too large for the display size. | | cell 7 | | cell <br> 9 | ``` | 標題 1 | 標頭 2 | 標頭 3 | | --- | --- | --- | | 單元格 1 | 單元格 2 | 單元格 3 | | 單元格 4 | 單元格 5 更長 | 單元格 6 比其他單元格長得多，但這沒關系. 當單元格太大而無法顯示時，它將最終包裹文本. | | 單元格 7 | ? | cell 9 | （另外，你可以通過添加冒號選擇文本列中的對齊`:`第二行中的"破折號"線條的兩側）. 這將影響列中的每個單元格. **注意：** [在 GitLab 本身中](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#tables) ，標題始終在 Chrome 和 Firefox 中左對齊，并在 Safari 中居中. ``` | Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned | | :--- | :---: | ---: | :----------- | :------: | ------------: | | Cell 1 | Cell 2 | Cell 3 | Cell 4 | Cell 5 | Cell 6 | | Cell 7 | Cell 8 | Cell 9 | Cell 10 | Cell 11 | Cell 12 | ``` | 左對齊 | Centered | 右對齊 | 左對齊 | Centered | 右對齊 | | --- | --- | --- | --- | --- | --- | | 單元格 1 | 單元格 2 | 單元格 3 | 單元格 4 | 單元格 5 | 單元格 6 | | 單元格 7 | 單元格 8 | 單元格 9 | 單元格 10 | 單元格 11 | 單元格 12 | #### Copy from spreadsheet and paste in Markdown[](#copy-from-spreadsheet-and-paste-in-markdown "Permalink") 在 GitLab 12.7 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/27205) . 如果您使用電子表格軟件（例如 Microsoft Excel，Google 表格或 Apple Numbers），則可以從電子表格中進行復制，GitLab 會將其粘貼為 Markdown 表. 例如，假設您具有以下電子表格： [](img/markdown_copy_from_spreadsheet_v12_7.png) 選擇單元格并將其復制到剪貼板. 打開一個 GitLab Markdown 條目并粘貼電子表格： [](img/markdown_paste_table_v12_7.png) ## References[](#references "Permalink") * 該文檔從[Markdown-Cheatsheet 中](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)大量利用. * Daring Fireball 上的原始[Markdown 語法指南](https://daringfireball.net/projects/markdown/syntax)是詳細解釋標準 Markdown 的絕佳資源. * 有關 CommonMark 的詳細規范，請參見[CommonMark 規范.](https://spec.commonmark.org/current/) * [CommonMark Dingus](http://try.commonmark.org)是用于測試 CommonMark 語法的便捷工具. 1. 這是腳注中的文本. [?](#fnref:1) 2. 這是另一個腳注. [?](#fnref:footnote-42)