本网站由 Middleman 生成,这是一个被 Web 开发人员广泛使用的博客和静态站点生成器 ( SSG )。 Markdown 语言是所有 SSG 结构的一部分。Markdown 是一种轻量级的标记语言,可用于在纯文本文档中添加格式化元素,旨在可以在任何文本编辑器中轻松编写。
对于 GitLab.cn,我们使用 kramdown,这是一个高级 Markdown 引擎,具有许多其他引擎所没有的有趣功能,例如内联属性列表(IAL),它可以实现超越标准 Markdown 的简单样式选项。
如果您从未使用过 Markdown,请不要担心,它很容易学习,甚至更易于使用。一旦您习惯了它,就会惊讶于它是多么的方便。并且当你使用的技术不支持 markdown 时,你会怀念它的。
GitLab 中大多数文本区域中都支持 Markdown 语法,但并不是所有的文本区都支持 kramdown。对于 GitLab.com、Jihulab.com、GitLab CE、GitLab EE、GitLab JH 的文本区域,目前的 Markdown 引擎是 CommonMarker。在这里你可以找到它们的 markdown 风格指南。
本指南旨在让每个人都可以更轻松地使用 kramdown 功能并节省大量时间为 GitLab.cn 编写内容 ,包括 Handbook 页面、网站页面、博客文章以及 handbook 项目中的所有其他内容。
## Heading h2
### Heading h3
#### Heading h4
Output
注意:
h1
标题,因为它们已经作为页面标题显示在每个页面开头位置,而且每个页面不应出现一个以上的 h1
。
当你使用一个顶级标题,或 <h1> 时,你在该标题和页面上的其余内容之间建立了语义关系,描述了它是关于什么的。如果你在同一个页面上使用第二个 <h1>,就会造成一些潜在的混乱,因为有人或搜索引擎可能会把这看作是第一个 <h1> 之后的内容与这个新的 <h1> 的开始之间的语义关系的结束。 SEO Guide
h2
(##
) 开始内容的编写,并遵循 h2 → h3 → h4的顺序,请勿跳过标题元素,如 h2 → h4。
六个标题元素,H1 到 H6,表示章节标题。尽管标题的顺序和出现不受 HTML DTD 的限制,但文档不应跳级(例如,从 H1 到 H3),因为将这类文档转换为其他表现形式时往往会有问题。 W3C -
#
始终与其旁边的文本之间保留一个空格,否则将无法正确展示。
只需编写文本行即可获得常规段落。如果您在两行之间按回车键,则这两行将合并为一个段落,称为 wrapping text]。但如果在它们之间留一个空行,它们将被分成两段。
在某些 Git 工具中,在 MR 时通过额外的换行符使得 diffs
内容更容易理解,但是 GitLab 的 Web 界面以及许多桌面 Git 工具具有在行内突出显示子字符串更改以及并排或类似版本比较的功能,因此没有必要用于人工换行。
拆分长行(最好最多 100 个字符)可以更轻松地提供对小块文本的反馈。不要在段落中断行的最后一个单词后留下空格,除非您希望使用 <br>
来进行换行。
This text is a paragraph.
This won't be another paragraph, it will join the line above it.
This will be another paragraph, as it has a blank line above it.
Output
This text is a paragraph. This won't be another paragraph, it will join the line above it.
This will be another paragraph, as it has a blank line above it.
如果您需要额外的换行(或行之间的一些额外空间),您可以简单地使用 HTML 换行标签 <br>
,这样会在其上方和下方留空行:
Text A
<!-- blank line -->
<br>
<!-- blank line -->
Text B
Output
Text A
Text B
3 个或更多破折号的序列将产生一条水平线,我们使用 4 作为标准,达到这个数量就会生成水平线,在它前后会留出空行:
Text
<!-- blank line -->
----
<!-- blank line -->
Text
Output
Text
Text
要显示粗体或斜体文本:
**
或下划线 __
括起来*
或下划线 _
括起来***
或下划线 ___
括起来This is **bold** and this is _italic_.
This is ***bold and italic***.
Output
This is bold and this is italic.
This is bold and italic.
Markdown 本身不支持带下划线的文本。如有必要,您可以使用 HTML 标签 ins
( <ins>underlined text</ins>
) 对其进行硬编码,但不建议这样做。
有很多不同的方式可以用来显示带有 Markdown 标记的链接,但为了保持一些标准,让我们尝试仅使用以下选项。
重要说明:
我们推荐使用内联链接,例如 [Text to display](link)
,因为它们更易于维护。要在新标签页中打开内联链接,您可以在末尾添加 {:target="_blank"}
,,例如:[Text to display](link){:target="_blank"}
引用 gitlab.cn
上的链接时使用相对链接。例如,指向我们博客 handbook 的链接应该是这样的:/handbook/marketing/blog/
而不是这样的https://gitlab.cn/handbook/marketing/blog/
。
但对于指向 JihuLab.com 或其他站外链接,必须使用完整链接,包括http:
。
如果您要向页面添加电子邮件地址,请务必使用 mailto
以避免创建无效的链接。例如:example@gitlab.com
[example@gitlab.com](mailto:example@gitlab.com)
当单个页面上有重复的链接时,您可以选择使用标识符。
请将标识符放在段落(或部分)的末尾,按首字母顺序排列。
[Text to display][identifier] will display a link.
[Another text][another-identifier] will do the same. Hover the mouse over it to see the title.
[This link] will do the same as well. It works as the identifier itself.
[This link][] (same as above), has a second pair of empty brackets to indicate that the following parenthesis does not contain a link.
<https://example.com> works too. Must be used for explicit links.
<!-- Identifiers, in alphabetical order -->
[another-identifier]: https://example.com "This example has a title"
[identifier]: http://example1.com
[this link]: http://example2.com
Output
Text to display will display a link.
Another text will do the same. Hover the mouse over it to see the title.
This link will do the same as well. It works as the identifier itself.
This link (same as above), has a second pair of empty brackets to indicate that the following parenthesis does not contain a link.
https://example.com works too. Must be used for explicit links.
注意:
[link]
和 [multiple words too]
。有序和无序列表的生成都都非常容易,有很多方法可以达到相同的效果,但是为了标准的统一,我们使用以下方法。
始终使用 3 个空格来缩进嵌套列表(以创建子项)。
小技巧:不要在项目之间留空行,除非你有理由这样做。
重要提示:始终在段落或标题与后续列表之间保留空行!否则列表将无法展示。
创建有序列表非常容易:
Paragraph:
1. Item one
1. Sub item one
2. Sub item two
3. Sub item three
2. Item two
Output
Paragraph:
还有一个小技巧实用且可以避免数字错误,就是对所有项目使用 “1”。Markdown 引擎会按照正确的顺序输出它们。
Paragraph:
1. Item one
1. Sub item one
1. Sub item two
1. Item two
1. Item three
Output
Paragraph:
无序列表也很容易创建:
Paragraph:
- Item 1
- Item 2
- Item 3
- Sub item 1
- Sub item 2
- Item 4
Output
Paragraph:
假设出于某种原因,您想将列表拆分为不同的部分。可以使用 ^
符号来指示列表的结尾和下一个列表的开头:
- list one - item 1
- list one - item 2
- sub item 1
- sub item 2
- list one - item 3
^
- list two - item A
- list two - item B
^
- list three - item _i_
- list three - item _ii_
Output
要将图像插入到 Markdown 文件中,请使用 
. 该路径可以是网站的相对路径,也可以是外部图像的完整 URL。支持的格式为 .png
、.jpg
、.gif
,也支持部分 .svg
文件,具体取决于其结构。

还可以使用标识符,就像链接那样 [links](#links)
:
![Semantic description of image][identifier]
通过以下方式,为图片添加标题:
*My caption*
对于可点击的图像,只需将图像标记包装成链接即可:
[*My caption*][gitlab.cn]
Output
重要提示
/source/images/
下的适当目录中,只允许截图和公共领域的图像,请勿使用有版权的图片。ALT
,它代表_替代文本_。 包含描述性的替代文本有助于增强每个访问者的可访问性,并且应始终包含在图像中。添加替代文字时,请务必描述图像的内容和功能。除了可访问性的好处之外,ALT
对 SEO 也很有用,并且在由于某种原因浏览器未加载该图像时显示。orange-cat.jpg
而不是 image-01.jpg
。通过 Markdown 插入图表有两种方法:
请参阅 GitLab 文档中 有关如何使用 Mermaid 的示例。
您可以在 Markdown 块中使用 PlantUML。例如:
```plantuml
!define ICONURL https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/v2.1.0
skinparam defaultTextAlignment center
!include ICONURL/common.puml
!include ICONURL/font-awesome-5/gitlab.puml
!include ICONURL/font-awesome-5/java.puml
!include ICONURL/font-awesome-5/rocket.puml
!include ICONURL/font-awesome/newspaper_o.puml
FA_NEWSPAPER_O(news,good news!,node) #White {
FA5_GITLAB(gitlab,GitLab.com,node) #White
FA5_JAVA(java,PlantUML,node) #White
FA5_ROCKET(rocket,Integrated,node) #White
}
gitlab ..> java
java ..> rocket
```
Output
有两种显示视频的方式:在 HTML5 <video>
标签内和在 <iframe>
标签内。
<iframe>
中 src
的 URL,并在其前面加上 https:
(注意没有//
),将组合的内容替换下面的 src 内容:<!-- blank line -->
<figure class="video_container">
<iframe src="https://player.bilibili.com/player.html?aid=973234051&bvid=BV1844y1r76m&cid=341483466&page=1" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
<!-- blank line -->
Output
这种方法适用于 YouTube 和其他 <iframe>
标签内的嵌入视频。
<iframe>
中 src
的 URL,并将其替换下面的 src 内容:<!-- blank line -->
<figure class="video_container">
<iframe src="https://www.youtube.com/embed/enMumwvLAug" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
<!-- blank line -->
Output
此方法适用于上传到可从公网通过 URL 或相对路径检索到的某个位置的任何视频文件 path/to/video.mp4
。
<video>
guide.mp4
、.ogg
和 .webm
src
URL<!-- blank line -->
<figure class="video_container">
<video controls="true" allowfullscreen="true" poster="path/to/poster_image.png">
<source src="path/to/video.mp4" type="video/mp4">
<source src="path/to/video.ogg" type="video/ogg">
<source src="path/to/video.webm" type="video/webm">
</video>
</figure>
<!-- blank line -->
Output
注意:如果您没有 w3schools 推荐的视频格式,您可以选择一种其他的,但很可能并非所有设备和浏览器都支持您的视频。上面的视频(仅 .mp4
)适用于适用于 macOS、Android 和 Windows 的 Mozilla Firefox,以及适用于 Android 和 Windows 的 Chrome。但它可能不适用于其他设备/浏览器,例如适用于 macOS 和 iOS 的 Chrome 或 Safari。事实上,最好的选择是使用 YouTube 或 Vimeo 在 <iframe>
标签中嵌入视频。
对于任何其他视频,例如来自 Vimeo 或 Google Drive 的视频,仅抓取视频 iframe,然后像我们对 YouTube 视频 所做的那样,将其包裹在 <iframe>
中以 <figure class="video_container">
提高响应速度。复制并粘贴以下代码,仅将 iframe URL替换为您自己的 URL:
<!-- blank line -->
<figure class="video_container">
<iframe src="https://drive.google.com/file/d/0B6m34D8cFdpMZndKTlBRU0tmczg/preview" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
<!-- blank line -->
Output
要在同一页面上显示多个视频,只需 figure
在您希望它们显示的位置重复代码块,将视频 ID 替换为与您的视频对应的相应 ID。
要在一个序列中显示多个视频,只需复制 figure
代码块并根据需要多次粘贴。在块之间留空行,请不要删除空格,否则您的视频可能无法正常渲染。
<!-- blank line -->
<figure class="video_container">
<iframe src="https://drive.google.com/file/d/0B6m34D8cFdpMZndKTlBRU0tmczg/preview" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
<figure class="video_container">
<iframe src="https://drive.google.com/file/d/0B6m34D8cFdpMZndKTlBRU0tmczg/preview" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
<figure class="video_container">
<iframe src="https://drive.google.com/file/d/0B6m34D8cFdpMZndKTlBRU0tmczg/preview" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
<!-- blank line -->
使用 kramdown 创建目录非常简单!ToC 将自动包含文档中的每个标题,除非您不希望包含它。您无需为每个标题单独添加锚点,这是完全是自动的。
----
## On this page
{:.no_toc}
- TOC
{:toc}
----
与往常一样,请在标记前后各留一个空行。但由四个破折号开始和结束不是必需的,但建议在整个 GitLab.cn 中保持相同的标准。
当不想在 ToC 中包含标题可以使用 {:.no_toc}
。只需在标题下方添加它,它就不会包含在 ToC 中。实际上 no_toc
是一个 自定义类,如本指南后面所述。
在本页面的最开始,可以找到输出的 ToC。
同时也可以使用有序 ToC,在列表的开头显示数字。只需使用有序列表的标记,kramdown 就会展示您想要的内容:
1. TOC
{:toc}
表格对于 Markdown 极具挑战性。因此,我们有两种可能的方法:尽可能使用 Markdown,但如果您需要非常高级的表格布局,您可以自由地将它们添加到 HTML 标签中。
Markdown is not a replacement for HTML, or even close to it. (John Gruber)
正如 Markdown 的创建者 John Gruber 所解释的那样,它不是为了取代 HTML 而创建的,因此有些情况我们无法避免使用 HTML。对于复杂的表格,就是这种情况。
下表有一个标题(第一行),然后是定义所需对齐方式的标记(破折号和冒号),然后是表格主体。您可以继续添加分隔符以创建后续表格主体。
无论您如何准备表格,其设计都将取决于为它们定义的 CSS 样式。
如果您想将 自定义类和/或自定义 ID 归因于元素,{: .custom-class #custom-id}
则可以使用最后一个标记。<table>
最后一个标记 {: .custom-class #custom-id}
可以用于将一个自定义类和/或自定义ID 指向 <table>
元素的情况。
| Default aligned | Left aligned | Center aligned | Right aligned |
|-----------------|:-------------|:---------------:|---------------:|
| First body part | Second cell | Third cell | fourth cell |
| Second line | foo | **strong** | baz |
| Third line | quux | baz | bar |
|-----------------+--------------+-----------------+----------------|
| Second body | | | |
| 2nd line | | | |
|-----------------+--------------+-----------------+----------------|
| Third body | | | Foo |
{: .custom-class #custom-id}
Output
Default aligned | Left aligned | Center aligned | Right aligned |
---|---|---|---|
First body part | Second cell | Third cell | fourth cell |
Second line | foo | strong | baz |
Third line | quux | baz | bar |
Second body | |||
2nd line | Hello World | ||
Third body | Foo |
前面的示例中对称使用了 | 、空格和破折号,以帮助未来的页面开发人员,对称性不是必需的。 |
如果您需要合并行或列,或者需要更复杂的布局,一些开发工具可以帮助您创建自己的复杂表格。这个 table generator 或许可以帮助你做到这一点。
要在表格单元格中添加编号列表,请在标题和表格之间添加一个空行才能正确展示表格。否则,文本和格式将不会出现。
有关表格的更多信息,请参阅 kramdown 语法指南。
折叠部分内容用于隐藏信息,直到用户通过点击摘要文本来显示它。隐藏的内容内联显示。例如,这段代码:
<details>
<summary markdown="span">This is the summary text, click me to expand</summary>
This is the detailed text.
We can still use markdown, but we need to take the additional step of using the `parse_block_html` option as described in the [Mix HTML + Markdown Markup section](#mix-html--markdown-markup).
You can learn more about expected usage of this approach in the [GitLab UI docs](https://gitlab-org.gitlab.io/gitlab-ui/?path=/story/base-collapse--default) though the solution we use above is specific to usage in markdown.
</details>
结果是:
This is the detailed text.
We can still use markdown, but we need to take the additional step of using the parse_block_html
option as described in the Mix HTML + Markdown Markup section.
You can learn more about expected usage of this approach in the GitLab UI docs though the solution we use above is specific to usage in markdown.
GitLab Handbook 还支持详细信息的嵌套。
<details>
<summary markdown="span">First level collapsible item</summary>
**Lorem ipsum dolor sit amet...**
<details>
<summary markdown="span">Second level collapsible item</summary>
*Sed ut perspiciatis unde omnis iste natus...*
</details>
</details>
结果是:
Lorem ipsum dolor sit amet…
Sed ut perspiciatis unde omnis iste natus…
要在折叠标题中添加表格,请务必添加:
<details markdown="1">
使用 kramdown 显示代码块有几个选择,大多数情况会使用反引号 `
。
这是一个 `in-line`
代码块。
Output
In-line
This is an in-line
code block.
```
def hello
puts "Hello world!"
end
```
高亮显示语法 Fenced Highlighted
```ruby
def hello
puts "Hello world!"
end
```
or
```
def hello
puts "Hello world!"
end
```
{: .language-ruby}
Output
Fenced
def hello
puts "Hello world!"
end
Fenced Highlighted
def hello
puts "Hello world!"
end
or
def hello
puts "Hello world!"
end
在每行之前添加 4 个空格:
def hello
puts "Hello world!"
end
Indented Highlighted
def hello
puts "Hello world!"
end
{: .language-ruby}
Output
Indented
def hello
puts "Hello world!"
end
Indented Highlighted
def hello
puts "Hello world!"
end
在每行之前添加 4 个空格,当在代码块中显示代码块时使用。
```
def hello
puts "Hello world!"
end
```
Output
Nested
```
def hello
puts "Hello world!"
end
```
将每个项目的文本缩进 3 个空格,在代码块和列表项之间留空行,缩进 5 个空格会识别代码块:
1. Item 1
1. Item 2
```ruby
def hello
puts "Hello world!"
end
```
1. Item 3
Output
Item 2
def hello
puts "Hello world!"
end
块引用是提及他人引用的好资源,就像我们在 上面 所做的那样。此外,可用于强调一个句子或一个小段落。
> This is a blockquote.
> On multiple lines.
That may be lazy.
>
> This is the second paragraph.
----
> This is a paragraph.
>
> > A nested blockquote.
>
> ### Headers work
>
> * lists too
>
> and all other block-level **elements**.
>
> Even code blocks:
>
> def hello
> puts "Hello world!"
> end
> {: .language-ruby}
Output
This is a blockquote. On multiple lines. That may be lazy.
This is the second paragraph.
This is a paragraph.
A nested blockquote.
Headers work
- lists too
and all other block-level elements.
Even a code block:
def hello puts "Hello world!" end
This is a regular paragraph.
**Note:** a note is something that needs to be mentioned but is apart from the context.
{: .note}
Output
This is a regular paragraph.
Note: a note is something that needs to be mentioned but is apart from the context.
作用类似于注释,内容不会被渲染。Markdown markup
This is a paragraph
{::comment}
This is a comment which is
completely ignored.
{:/comment}
... paragraph continues here.
Regular HTML markup
<!-- This is accepted as a comment too -->
Output
This is a paragraph … paragraph continues here.
可以在任意位置添加锚点:
[](){: name="hello-world"}
Some text
或使用简单的 ID:
Some text
{: #hello-world}
可以使用 Font Awesome 图标。
Regular
### <i class="fas fa-puzzle-piece" aria-hidden="true"></i> Puzzle Icon
{: #puzzle}
And you can go further, such as the following.
Styled
### <i class="fab fa-gitlab fa-fw" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i> Purple GitLab Tanuki
{: #tanuki-purple}
### <i class="fab fa-gitlab fa-fw" style="color:rgb(252,109,38); font-size:.85em" aria-hidden="true"></i> Orange GitLab Tanuki
{: #tanuki-orange}
Output
Regular
Styled
当在标题上这样做时,需要给它一个自定义 ID(例如,{: #puzzle}
),否则由 kramdown 自动创建的 ID 看起来会很尴尬。
当您希望将图标显示为列表时使用 fa-fw
类,它们将与旁边的文本对齐。
使用 Markdown 定义 CSS 类、元素 ID 和属性的方式非常独特。
但当您知道如何使用时,会爱上它的!看看使用 kramdown 做到这一点有多容易:
Paragraph
{: .class .class-1 .class-2}
Paragraph
{: #custom-id}
Paragraph
{: .class .class-1 #custom-id-1}
## Heading
{: .class .class-1 #custom-id-2}
Paragraph
{: .class #custom-id-3 style="padding-top:0" key="value"}
## Heading {#hello}
List:
- {: .class} List item with custom class
- {:#id} List item with custom id
To a [link]{: #link}, in-line.
This is a [link][google-es]{:hreflang="es"} in Spanish.
[link]: https://google.com
[google-es]: https://google.es
Output
当您的图片边缘没有明显边框时,应使用 shadow
CSS 类。当使用具有白色背景或带有文本的截图(例如,我们用户界面的屏幕截图)时,就会发生这种情况,这张图片可能会被误认为是文本的一部分:
现在如果将 shadow
类应用于该图片,它会从文本中突出显示:
要做到这一点,在图片标记之后添加 {: .shadow}
标记即可:
{: .shadow}
正如 前文 所述,你可以添加 note
类段落:
Note: this is something I don't want to call attention to.
Markup:
**Note:** this is something I don't want to call attention to.
{: .note}
使用以下特殊类为标题或段落添加一个自定义类。
GitLab Orange
Markup:
### GitLab Orange Heading
{: .gitlab-orange}
GitLab Purple
Markup:
### GitLab Purple Heading
{: .gitlab-purple}
默认情况下,文本将始终向左对齐,以下几个选项可以使用自定义类改变文字对齐方向:
.text-center
.text-right
.text-justify
出于演示目的,它们在 警告框 中对齐,但这也可应用于常规段落和标题。
Align to the center
Center-aligned
Alert box markup:
Center-aligned
{: .alert .alert-info .text-center}
Paragraph markup:
Center-aligned
{: .text-center}
Heading markup:
### Center-aligned
{: .text-center}
Align to the right
Right-aligned
Right-aligned
{: .alert .alert-info .text-right}
Justify
Justified
Justified
{: .alert .alert-info .text-justify}
对于习惯使用常规 Markdown 的人来说,将 HTML 标签与 Markdown 混合使用几乎是“不可想象的”。而这一切都在这份文件中!
在文档开头使用以下标记:
{::options parse_block_html="true" /}
就可混合使用所有内容:
Something in **markdown**.
<p>Then an HTML tag with crazy **markup** _all over_ the place!</p>
Output
Something in markdown.
Then an HTML tag with crazy markup all over the place!
You can close the markup parser tag at any point, if you want to:
{::options parse_block_html="false" /}
为了将注释和警告块添加到彩色框中,我们使用 Bootstrap 的 panel blocks 和 alert boxes。
彩色部分用于非常特定的目的,不得过度使用。
当您的描述包含多个段落或一个长段落时,请使用面板。对于单个和短段落,请改用警告框。
使用面板时,请确保将 HTML 解析器标记添加到文档正文的开头:{::options parse_block_html="true" /}
。
根据您想要呈现给用户的内容复制粘贴以下代码并仅替换描述。可用的颜色有:蓝色 (info
)、绿色 (success
)、琥珀色 (warning
) 和红色 (danger
),如下所示。
使用以下代码,以获得重要的说明和其他信息:
<div class="panel panel-info">
**Note**
{: .panel-heading}
<div class="panel-body">
NOTE DESCRIPTION
</div>
</div>
对于单个段落,请使用警告框:
My important paragraph.
{: .alert .alert-info}
蓝色面板渲染如下:
Note
NOTE DESCRIPTION
蓝色警报框渲染如下:
My important paragraph.
如果您希望警报框内的文本也为蓝色,就需要将 自定义样式 应用于 markdown 文档。它们将覆盖现有样式,将以下 style
样式添加到文件末尾。
<style>
.alert-info {
color: rgb(49,112,143) !important;
}
</style>
对警告可以使用以下代码,例如使用不当可能会产生不同结果的信息:
<div class="panel panel-warning">
**Warning**
{: .panel-heading}
<div class="panel-body">
WARNING DESCRIPTION
</div>
</div>
应用于单个段落,请使用警告框:
My warning paragraph.
{: .alert .alert-warning}
琥珀色面板渲染如下:
Warning
WARNING DESCRIPTION
琥珀色警报框渲染如下:
My warning paragraph.
如果您希望警报框内的文本也为琥珀色,就需要将 自定义样式 应用于 markdown 文档。它们将覆盖现有样式,将以下 style
样式添加到文件末尾。
<style>
.alert-warning {
color: rgb(138,109,59) !important;
}
</style>
将以下代码用于关键警告,例如会导致数据丢失的命令:
<div class="panel panel-danger">
**Danger**
{: .panel-heading}
<div class="panel-body">
DANGER DESCRIPTION
</div>
</div>
应用于单个段落,请使用警告框:
My danger paragraph.
{: .alert .alert-danger}
红色面板渲染如下:
Danger
DANGER DESCRIPTION
红色警报框渲染如下:
My danger paragraph.
如果您希望警报框内的文本也为红色,就需要将 自定义样式 应用于 markdown 文档。它们将覆盖现有样式,将以下 style
样式添加到文件末尾。
<style>
.alert-danger {
color: rgb(169,68,66) !important;
}
</style>
您可以将绿色和红色面板或警告框组合用于“注意事项”:
<div class="panel panel-success">
**Do's**
{: .panel-heading}
<div class="panel-body">
THINGS TO DO
</div>
</div>
或者,使用警告框:
TO DO.
{: .alert .alert-success}
Not to do:
<div class="panel panel-danger">
**Don'ts**
{: .panel-heading}
<div class="panel-body">
THINGS NOT TO DO
</div>
</div>
或者,使用警告框:
NOT TO DO.
{: .alert .alert-danger}
通过这样做,“DO'S” 的绿色面板将如下所示:
Do's
THINGS TO DO
或者,如果您选择了警报框:
TO DO.
如果您希望警报框内的文本也为绿色,就需要将 自定义样式 应用于 markdown 文档。它们将覆盖现有样式,将以下 style
样式添加到文件末尾。
<style>
.alert-green {
color: rgb(60,118,61) !important;
}
</style>
对于您在红色面板中的 "DON'TS" 将如下所示:
Don'ts
THINGS NOT TO DO
或者,如果您选择了红色警报框:
NOT TO DO.
默认情况下,Bootstrap 可以使用所有前面提到的警告框和面板。如果我们想要不同的颜色,我们需要 自定义样式。在[ GitLab.cn] 我们可以使用橙色和紫色的,如下所示。
使用面板时,不要忘记将 HTML 解析器标记添加到文件的开头, 以便能够混合 HMTL + Markdown: {::options parse_block_html="true" /}
。
Heading
Text in markdown.
面板块标记:
<div class="panel panel-gitlab-orange">
**Heading**
{: .panel-heading}
<div class="panel-body">
Text in markdown.
</div>
</div>
My text in an orange box.
Box block markup:
My text in an orange box.
{: .alert .alert-gitlab-orange}
Heading
Text in markdown.
Panel block markup:
<div class="panel panel-gitlab-purple">
**Heading**
{: .panel-heading}
<div class="panel-body">
Text in markdown.
</div>
</div>
My text in an purple box.
Box block markup:
My text in an purple box.
{: .alert .alert-gitlab-purple}
在 CTA 中用于博客文章中的 Webcast 公告。您也可以将其与 HMTL 解析器 一起用于其他目的:
The webcast I want to announce - Register here!
{::options parse_block_html="true" /}
<i class="fab fa-gitlab" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i>
The webcast I want to announce - [Register here][webcast-link]!
<i class="fab fa-gitlab" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i>
{: .alert .alert-webcast}
在 Markdown 中:
<style>
.purple {
color:inherit;
}
.purple:hover {
color:rgb(107,79,187);
}
</style>
加:
Hey! Hover the cursor over me and guess what?! :)
{: .purple}
Equals to:
Output
Hey! Hover the cursor over me and guess what?! :)
<style>
标签直接写在 Markdown 文件中!
嵌入 Google Docs、Sheets、Slides 以及几乎所有提供 iframe 的内容都很容易。您唯一需要做的就是在 Markdown 文件中使用以下代码,并从要嵌入的文档中替换 iframe:
<figure class="video_container">
<iframe IFRAME CONTENT></iframe>
</figure>
对于 Google 产品,打开您的文档后,点击 File -> Publish to the web 即可,例如:
选择 Embed 检查设施,单击 Publish 并负责 <iframe>
,然后转到您的 markdown 文件并将 iframe 包装到 <figure>
带有响应 video_container
类的标签中,如开头所示。
让我们以这个 simple spreadsheet 为例,按照 上面 的信息找到 iframe:
复制下面的代码并粘贴到您的 Markdown 文件中(在其上下各留一个空行),然后用你自己的 <iframe>
替换:
<figure class="video_container">
<iframe src="https://docs.google.com/spreadsheets/d/1jAnvYpRmNu8BISIrkYGTLolOTmlCoKLbuHVWzCXJSY4/pubhtml?widget=true&headers=false"></iframe>
</figure>
让我们用这个 GitLab slide deck.来举例说明,按照以下步骤 上面 找到的 iframe:
复制下面的代码并粘贴到您的 Markdown 文件中(在其上下各留一个空行),然后用你自己的 <iframe>
替换:
<figure class="video_container">
<iframe src="https://docs.google.com/presentation/d/e/2PACX-1vS_iuMXnp61wlo4amm5nvHr4Ir8VUzisJSBsr7YEL7fKWAiT-9bmehyngtb9TYaFEsFnRokCyIXwsvY/embed?start=false&loop=false&delayms=3000" frameborder="0" width="960" height="569" allowfullscreen="true" mozallowfullscreen="true" webkitallowfullscreen="true"></iframe>
</figure>
不推荐嵌入 Google Docs,推荐将您的文档内容转换为 Markdown。如果您无论如何都需要嵌入它,请按照我们为 Google Sheets 和 Slides 提供的相同说明和相同逻辑,<iframe>
用 <figure>
标签包裹:
<figure class="video_container">
<iframe src="https://docs.google.com/document/d/1mHhOhvvrz7xgUPyn5VWCNuKgew5MRRGZp761B9prPqs/pub?embedded=true"></iframe>
</figure>
要从 SlideShare 嵌入,请转到要嵌入的文档并点击幻灯片下方的 Share 按钮,复制 Embed 下的代码并将其放在 figure
标签内。
请注意仅包含 iframe 内容并删除其他内容。SlideShare 还会在嵌入代码中添加一些其他信息,您必须删除这些信息,否则 markdown 页面将被破坏。
例如,我们想在 GitLab 页面上加入 Ivan 演讲的幻灯片,复制嵌入代码并删除除 iframe 外的所有其他内容,结果是这样的:
<figure>
<iframe src="//www.slideshare.net/slideshow/embed_code/key/EixD8OUMBX65Jy" width="595" height="485" frameborder="0" marginwidth="0" marginheight="0" scrolling="no" style="border:1px solid #CCC; border-width:1px; margin-bottom:5px; max-width: 100%;" allowfullscreen> </iframe>
</figure>
您可以放心地省略该 <figure>
标签,因为 SlideShare widget 已经是响应式的,但我们以这种方式显示是为了与手册的其余部分保持一致。
要将 GitLab 代码片段 嵌入 到 Markdown 文件中,请从公开的代码段中复制嵌入代码并将其粘贴到文件中。
Markup:
<!-- leave a blank line here -->
<script src="https://gitlab.com/gitlab-org/gitlab-ce/snippets/1717978.js"></script>
<!-- leave a blank line here -->
Renders:
请使用 JihuLab.com 上提供的编辑器、以下代码编辑器之一或您习惯的代码编辑器来编写 Markdown 文档。
不建议使用普通的文本编辑器如 Google Docs、Microsoft Word 或 macOS 的 Pages 来编写,然后复制粘贴到 Markdown,因为它很可能会带来一些不同编码(非 UTF-8)的字符,这将导致 Markdown 无法正确展示。
如果你需要导入一个已经在文本编辑器中写好的文本,在 Mac 上使用 command+shift+V,或者在 Windows 或 Linux 上使用 control+shift+V 将其粘贴到你的markdown 文件中,通过不带格式的粘贴来减少麻烦。但也不能保证一定会成功,所以要仔细检查你的 HTML 输出。
GitLab.cn 提供的编辑器
常见的代码编辑器
Markdown 编辑器(同时输入和预览 )
如果您不习惯编写 Markdown,这些编辑器可能会有所帮助。下图是在 Mou 上编辑的文件的截图。左侧是正在编写的 Markdown 文档,右侧是输出的预览。预览不会与最终结果完全相同,但它是一个非常好的参考,可以让您在输入时对正在执行的操作有一个很好的了解。
StackEdit is awesome too, you can work on a markdown file even if you're away from your computer, or out of resources. It works from every major browser and automatically saves your work to Google Drive. StackEdit 也好用,可以在计算机资源不足时或在手机和平板上处理 Markdown 文件,适用于所有主流浏览器,并自动保存到 Google Drive。
始终在块级标记元素之间留空行,列表项之间除外。示例:
---- (markup for horizontal line)
<!-- blank line -->
Paragraph.
<!-- blank line -->
Do not leave blank lines within list items:
<!-- blank line -->
- Item 1
- Item 2
- Item 3
http://an-example.com
。control+cmd+space
唤出 Emoji 菜单或使用像Emoji Finder这样的网站。请不要过度使用它们!raw
file 以供参考,您将准确了解所有内容是如何编写以产生您在此页面上看到的结果的。还有什么您知道但这里没有描述的内容吗?欢迎贡献!