Markdown 基本语法

1 简介

Markdown 是一种轻量级标记语言，它允许人们使用易读易写的纯文本格式编写文档。最初 Markdown 主要用于网络写作，之后为了适应更多的写作场景，又产生了很多扩展语法，目前最流程的扩展语法是 GitHub Flavored Markdown（GFM）。

本篇主要讲述 Markdown 基础语法和 GFM 扩展语法，以满足读者在 GitLab 上编写文档的需求。

更多关于 Markdown 的内容可参考书籍《了不起的 Markdown》。

2 Markdown 常见语法

2.1 字体

2.1.1 标题

在 Markdown 语法中，支持两种标题标记：底线（-/=）和 #。

使用 # 的语法（推荐）

语法说明：
- 在行首插入 # 标记出标题。
- # 的个数代表标题的等级。
- 该语法支持六级标题。
  
  示例：
使用底线的语法

语法说明：
- - 为一级标题， = 为二级标题。
- 至少 2 个底线符号。
- 该语法只支持两级标题。
  
  示例：
使用规范
- 推荐使用 # 标记标题，便于阅读和维护。
- 标题的前后各空 1 行（除非标题在文档开头）， # 与标题文本之间加一个空格。
- 标题的开头和结尾都不要有多余的空格。
- 标题的结尾不要有标点符号（包括句号、逗号、冒号、分号等）

2.1.2 粗体和斜体

在 Markdown 语法中，粗体由 2 个 * 或 2 个 _ 包裹，斜体由 1 个 * 或 1 个 _ 包裹。

示例：

使用规范
- 推荐粗体使用 2 个 * 包裹，斜体使用 1 个 * 包裹，增加可读性。
- 在粗体和斜体语法标记的内部，不建议有空格。

2.1.3 删除线

需要添加删除线的内容由 2 个 ~ 包裹。

示例：

2.2 段落与换行

Markdown 段落没有特殊格式，直接编写，段落之间使用空行来标记。

使用规范
- 如果行与行之间没有空行，则视为同一段落。
- 如果行与行之间有空行，则视为不同的段落。
- 空行是指行内什么都没有，或只有空格和制表符。
- 段内换行，需要在上一行的结尾插入两个及以上的空格，然后按回车键。
  
  示例：

2.3 分隔线

在 Markdown 语法中，分隔线由 3 个及以上的 * / - / _ 标记。

使用规范
- 分隔线须使用 3 个及以上的 * / - / `_ 标记。
- 行内不能有其他字符。
- 可以在标记符中间加空格。
  
  示例：

2.4 有序列表

在 Markdown 中支持使用有序列表和无序列表。

有序列表

语法说明：
- 数字序号+英文句号+空格+列表内容
  
  示例：
无序列表

语法说明：
- */-/_+英文句号+空格+列表内容
  
  示例：
嵌套列表

语法说明：
- 列表中可以嵌套列表。
- 有序列表和无序列表可以相互嵌套。
  
  示例：
  
```Markdown
- 第一层列表 TAB - 第二层列表 TAB + TAB - 第三层列表 ```
使用规范
- 建议使用 - 标记无序列表，便于阅读。
- 如果列表项中有换行，建议无序列表项使用 3 个空格，有序列表使用 2 个空格，列表项之间空 1 行，便于区分多行列表项的开始和结束。
```
-   这个列表项   
   有换行

-   这个没有换行

1.  这个有序列表
   有换行

2.  这个没有换行
```

2.5 图片

在 Markdown 语法中，插入图片的语法如下：

![图片替代文字](图片地址)

语法说明
- “图片替代文字” 在图片无法正常显示时显示，一般可以为空。
- “图片地址” 可以是本地图片的路径（支持绝对路径和相对路径），也可以是网络图片的路径。
- 该语法无法指定图片的宽度和高度。如需指定图片的宽度和高度，请使用 HTML 的 <img> 标签，具体请参见本文档 “3.3 图片与 <img> 标签”。
  
  示例：
使用规范
- 推荐使用相对路径，便于文档的传递。
- 推荐使用 <img> 标签插入图片，便于文档的排版布局。

2.6 表格

在扩展语法 GFM 中表格的语法如下：

| 表头 | 左对齐 | 右对齐 | 居中 |
| ------ | :----- | -----: | :----: |
| 单元格 | 单元格 | 单元格 | 单元格 |
| 单元格 | 单元格 | 单元格 | 单元格 |

语法说明
- 单元格使用 | 分隔，建议最前和最后都使用 | ，方便阅读。
- 单元格和 | 之间的空格会被移除。
- 表头与其他行用 - 分隔。
- 块级元素（代码区块、引用区块）不能插入表格中。
- Markdown 原生语法不支持合并表格中的单元格，可通过 HTML 中的 <table> 标签实现合并单元格，详见《3.4 表格与 <table> 标签》
  
  示例：
使用规范
- 在表格的前后各空 1 行。
- 在每一行的最前和最后都使用 | ，每一行中的 | 尽量对齐。
- 该语法不适合庞大复杂的表格，特殊样式的表格建议使用 HTML 的 <table> 标签，具体请
- 参见本文档 “3.4 表格与 <table> 标签”。

2.7 链接

2.7.1 文字链接

文字链接就是把链接地址直接写在文本中，用方括号包括链接文字，后紧跟括号包括的链接地址。

[链接文字](链接地址)

示例：

使用规范
- 如果链接地址过多，使用该语法可能降低文档的可读性，建议使用引用链接。

2.7.2 引用链接

引用链接是把链接地址作为 “变量” 先在 Markdown 文件的页尾定义好，然后在正文中进行引用。

语法说明
- 链接标记可以有字母、数字、空格和标点符号。
- 链接标记不区分大小写。
- 定义的链接内容可以放在当前文档的任意位置，建议放在页尾。
- 当链接地址为当罗地址时，需以 http/https 开头，否则可能会被识别得本地地址。
  
  示例：

2.7.3 网址链接

在 Markdown 中，将网络地址或邮箱地址使用 <> 包裹起来会被自动转换为超链接。

<URL 或邮箱地址>

2.7.4 锚点

锚点，也被称为书签，用来标记文档的特定位置。可以使用锚点跳转到当前文档或其他文档中指定的位置。

语法说明
- [锚点描述](锚点名)
- 锚点名建议使用字母和数字，中文可能不支持。
- 锚点名中不能含有空格和特殊字符。
- 锚点名可以是目标文档的路径，借此可时间文档间的跳转。
- 锚点名区分英文大小写。
- 锚点名中不能含有空格和特殊字符。
- 使用 HTML 的 <a> 标签做锚点更为灵活，详见《3.4 锚点与 <a> 标签》
  
  示例：
  1. 文档内的跳转
  2. 文档间的跳转
    - 向下跳转
```
[content](/content)
[第一章](/content/C1.md)
```
    - 同级跳转
```
[下一章](./C2.md)
[上一章](./C1.md)
```
    - 返回目录
```
[返回目录](../README.md)
```
    - 多级跳转
```
[多级跳转](../../content/C1.md)
```

2.8 行内代码与代码块

行内代码

语法说明：
- 行内代码使用 ` 包裹。
  
  示例：
代码块

语法说明：
- 基础语法：以【Tab】键或 4 个空格开头。
- GFM 扩展语法提供了围栏代码块：使用 ``` 或 ~~~ 包裹。
  
  示例：
使用规范
- ` 可以包裹行内代码，也可以包裹需转义或强调的字段。
- 如果代码超过 1 行，推荐使用 GFM 扩展语法提供的围栏代码块，并显示的声明语言，以便于阅读。
- 代码块中编写 Shell 命令时：
  - 在行尾添加一个 \ 避免命令换行，提高源码可读性。
  - Shell 命令如果没有输出内容，则命令前不加 $，Shell 命令如果有输出内容，则命令前加上 $，以此区分命令和输出的内容。

2.9 引用

语法说明

> 标记引用。
多行引用也可以在每一行的开头都插入 >。
引用中可以嵌套引用。
引用中可以使用其他的 Markdown 语法。

示例：

使用规范
- 推荐在 > 之后添加一个空格。
- 推荐每一行引用都使用 > ，空行也是。

2.10 转义

在 Markdown 文件中如果想插入一些不想被渲染的标记符号时，可以使用 / 进行转义。可被转义的特殊符号如下。

示例：

3 HTML 元素

3.1 定制字体样式

3.3.1 下划线

需要添加下划线的内容由 HTML 的 <u> 标签包裹。

示例：

下划线

<u>下划线</u>

3.1.2 修改字体、字号、字体颜色等

当需要使用其他字体、字号、字体颜色时，可以借助 HTML 的 <font> 标签来实现。相同的效果也可以使用 <span> 标签来实现，<span> 可以通过 style 来批量修改字体效果，具体请参考 HTML 教程。

示例：

大小为1的字体 orangered颜色的字我是华文彩云黑体

<font size=1>大小为1的字体</font>
<font color=orangered size=4>orangered颜色的字</font>
<font face="STCAIYUN">我是华文彩云</font>
<font color=#0099ff size=6 face="黑体">黑体</font>

3.2 行内代码

行内代码可使用 <code> 标签来包裹。

示例：

这是 行内代码 示例

这是 <code>行内代码</code> 示例

3.3 图片与 `<img>` 标签

Markdown 可以使用普通的 <img> 标签指定图片的高度与宽度。

<img> 标签常用属性：

src 源属性，其值是图像的地址（URL 地址或本地路径）。
alt 替换文本属性，当图片不能正常显示时显示的文本提示。
title 图片标题，当鼠标移动到图片上时显示的文本提示。
style 设置图片的具体样式：
- zoom 设置图片整体的缩放比例。
- width 设置图片的宽度，单位可为 pt 、px 、em 等。
- height 设置图片的高度，单位可为 pt 、px 、em 等。

示例：

<img src="/pics/robot.jpg" alt="robot" title="title" style="zoom:50%;" />

<img src="/pics/robot.jpg" style="width:30em;" />

<img src="/pics/robot.jpg" style="height:30em;" />

3.3.1 图片水平居中

通过 margin 属性

margin:0 auto

 <div style="text-align: center; width: 500px; border: green solid 1px;">
 <img alt="" src="https://www.baidu.com/img/baidu_jgylogo3.gif" style="margin: 0 auto;" />
 </div>

CSS + HTML：在 HTML 中利用 “img-center” 类标记，在 CSS 文件中对 “img-center” 设置。

HTML 文件中：

 <img class="img-center" src="https://www.baidu.com/img/baidu_jgylogo3.gif" />

CSS 文件中：

 /*图片单独一行，居中显示*/
 .img-center{
    max-width: 14cm;
    display: block; /* 将 img 元素设置为块级元素 */
    margin-left: auto; /* 左右外边距自动调整，实现水平居中 */
    margin-right: auto;
    margin-top: .5em;
    margin-bottom: .5em;
 }

text-align:centers

 <div style="text-align: center; width: 500px; border: green solid1px;">
    <img alt="" src="https://www.baidu.com/img/baidu_jgylogo3.gif" style="display: inline-block;" />
 </div>

3.3.2 图片垂直居中

利用 高==行高 实现：这种方法要注明高度才可以使用。

<div style="text-align: center; width: 500px;height:200px; lineheight:200px; border: green solid 1px;">
  <img alt="" src="https://www.baidu.com/img/baidu_jgylogo3.gif" style="display: inline-block; vertical-align: middle;" />
</div>

利用 table 实现：这种方法利用了 table 的垂直居中属性。

<div style="text-align: center; width: 500px;height:200px; display:table;border: green solid 1px;">
  <span style="display: table-cell; vertical-align: middle; ">
     <img alt="" src="https://www.baidu.com/img/baidu_jgylogo3.gif" style="display: inline-block;" />
  </span>
</div>

3.4 表格与 `<table>` 标签

HTML 表格的基本结构：
- <table></table> 表格的根标签 ,设置表格基本标签属性。
- <caption></caption> 设置表格的标题，必须直接放在 <table> 标签后。
- <thead></thead> 用于组合表头内容，内部必须包含至少一个 <tr> 标签。
- <tbody></tbody> 表主体。
- <tfoot></tfoot> 表格脚部（页脚）。
- <tr></tr> 行标签。
- <th></th> 表头单元格。
- <td></td> 标准的数据单元格。
语法说明
- <thead>、<tbody>、<tfoot> 元素通常结合使用，规定表格的各个部分。
- <thead>、<tbody>、<tfoot> 默认不会影响表格的布局。可以使用 CSS 来为这些元素定义样式，进而改变表格的外观。
  
  示例：

表格标题
谐波/ 电机型号关节类型	M14B	M25B	M25B
表头1	表头2	表头3加粗	表头4加粗
页脚
横向合并四个单元格，内容居中
竖向合并两个单元格单元格内换行	横向合并三个单元格
竖向合并两个单元格单元格内换行	`表格中的代码块`	2	1

   <!--使用style设置thead、tbody、tfoot的样式-->
   <style type="text/css">
      thead {color:green;}
      tbody {color:blue;}
      tfoot {color:red;}
   </style>
   <!--以下为表格-->
   <table>
      <caption>表格标题</caption> 
   <!--表头-->
      <thead>
         <tr>
            <td style="width:200px;">
               <span style="float:left;margin-top:20px;">谐波/ 电机型号</span>
               <span style="float:right;margin-top:-10px;">关节类型</span>
            </td>
            <td>M14B</td>
            <td>M25B</td>
            <td>M25B</td>
         </tr>
         <tr>
            <td>表头1</td>
            <td>表头2</td>
            <th>表头3加粗</th><!--在typora中 th 标签的格式会覆盖 thead 标签的格式-->
            <th>表头4加粗</th>
         </tr>
      </thead>
      <!--表格脚部，或称页脚等，会自动放置在表格最后一行-->
      <tfoot>
         <tr>
            <td colspan="4">页脚</td>
         </tr>
      </tfoot>
      <!--表格主体-->
      <tbody>
         <tr><!--第一行-->
            <td style="text-align:center" colspan="4">横向合并四个单元格，内容居中</td>
         <!--可以直接使用 th 标签表示表头-->
         </tr>
         <tr><!--第二行-->
            <td style="text-align:center" rowspan="2">竖向合并两个单元格<br/>单元格内换行</td>
            <td colspan="3">横向合并三个单元格</td>
         </tr>
         <tr><!--第三行-->
            <td><code>表格中的代码块</code></td><!--在单元格中使用引用代码样式-->
            <td>2</td>
            <td>1</td>
         </tr>
      </tbody>
   </table>

3.4 锚点与 `<a>` 标签

<a> 标签可以标记超链接，它在文档中创建一个热点，当用户激活或选中这个热点时进行链接。

<a href="">超链接</a>

href 是 <a> 标签的必要属性，用于指定链接的目的地址，可以是本地地址、锚记标记、网络地址或文件等。

3.4.1 本地地址

href 属性值设置为相对地址，实现本地文件之间的跳转：

<a href="./README.md">查看说明</a>

3.4.2 锚点标记

通过元素的 id 或 name 属性来定义标记，然后设置一个超链接标签，单击此超链接标签可以跳转到标记 id 或 name 的位置。

<h1 id="nn">转跳位置</h1>

<a href="#nn">同一文件中的锚记标记</a>

<a href="./README.md #nn">不同文件中的锚记标记</a>

<a href="#">空链接</a>

提示：利用此方法可实现文档内部的段落跳转。

3.4.3 网络地址

href 属性值设置为网络地址，在联网状态下单击超链接可跳转至设置的网址。

<a href="http://www.baidu.com">百度</a>

3.4.4 电子邮箱地址

href 属性值设置为 mailto:电子邮箱地址，可以启动本地的默认邮件软件，将自动在收件人处输入设置的电子邮件地址。

<a href="mailto:XXXX@qq.com">发送邮件</a>

3.4.5 文件链接

href 属性值设置为一个文件的相对地址，单击超链接可以浏览目标文件。

<a href="../other/README.md">查看其他说明</a>

提示：利用此方法可实现文档之间的跳转。

03 Markdown 基本语法

Markdown 基本语法

1 简介

2 Markdown 常见语法

2.1 字体

2.1.1 标题

2.1.2 粗体和斜体

2.1.3 删除线

2.2 段落与换行

2.3 分隔线

2.4 有序列表

2.5 图片

2.6 表格

2.7 链接

2.7.1 文字链接

2.7.2 引用链接

2.7.3 网址链接

2.7.4 锚点

2.8 行内代码与代码块

2.9 引用

2.10 转义

3 HTML 元素

3.1 定制字体样式

3.3.1 下划线

3.1.2 修改字体、字号、字体颜色等

3.2 行内代码

3.3 图片与 `<img>` 标签

3.3.1 图片水平居中

3.3.2 图片垂直居中

3.4 表格与 `<table>` 标签

3.4 锚点与 `<a>` 标签

3.4.1 本地地址

3.4.2 锚点标记

3.4.3 网络地址

3.4.4 电子邮箱地址

3.4.5 文件链接

results matching ""

No results matching ""

Markdown 基本语法

1 简介

2 Markdown 常见语法

2.1 字体

2.1.1 标题

2.1.2 粗体和斜体

2.1.3 删除线

2.2 段落与换行

2.3 分隔线

2.4 有序列表

2.5 图片

2.6 表格

2.7 链接

2.7.1 文字链接

2.7.2 引用链接

2.7.3 网址链接

2.7.4 锚点

2.8 行内代码与代码块

2.9 引用

2.10 转义

3 HTML 元素

3.1 定制字体样式

3.3.1 下划线

3.1.2 修改字体、字号、字体颜色等

3.2 行内代码

3.3 图片与 <img> 标签

3.3.1 图片水平居中

3.3.2 图片垂直居中

3.4 表格与 <table> 标签

3.4 锚点与 <a> 标签

3.4.1 本地地址

3.4.2 锚点标记

3.4.3 网络地址

3.4.4 电子邮箱地址

3.4.5 文件链接

results matching ""

No results matching ""

3.3 图片与 `<img>` 标签

3.4 表格与 `<table>` 标签

3.4 锚点与 `<a>` 标签