Markdown语法-基础

最新推荐文章于 2024-05-13 07:27:35 发布

weixin_34410662

最新推荐文章于 2024-05-13 07:27:35 发布

阅读量171

点赞数

文章标签： markdown java python

原文链接：https://my.oschina.net/calmsnow/blog/2876096

版权

2019独角兽企业重金招聘Python工程师标准>>>

1. 标题

Markdown支持两种标题标记语法，我个人常用的是 # 井号标记，使用很简单，在文字前添加 1-6个# ，分别代表1-6级标题。

简洁写法

只在标题开头写标签，以换行为标记语法的结束：

  # h1 //井号标记与标题需要一个以上的空格或者一个水平制表符
  ## h2
  ### h3
  #### h4
  ##### h5
  ###### h6

显示的写出闭合的标记

闭合的 # 井号标记数量不一定需要和起始相同，起始的井号数量已经决定了标题的级别，闭合标记可以明确标题结束位置；通常标题几乎都是独立成行，闭合写法实际使用很少:

  # h1 # //井号标记与标题需要一个以上的空格或者一个水平制表符
  ## h2 ##
  ### h3 ###
  #### h4 ####
  ##### h5 #####
  ###### h6 ######

备注：另外还有一种Markdown标题标记语法，有兴趣可以自行查找，语法书写并不方便，很少用，所以我觉得没必要在这里列出。

2. 首行缩进、换行及段落

首行缩进

由于 Markdown 语法是老外发明的，他们主要考虑的语言体是英文，英语是没有严格的首行缩进，字符占位也和汉语不一样，Markdown 对中文的首行缩进并不太友好，常用这两种方法解决这个问题：

把输入法由半角改为全角，两次空格之后就能够有两个汉字的缩进，不过这样做 Markdown 语法转换器有些兼容性并不好；
在段落开头的地方，使用特殊占位符，然后紧跟着输入文本即可，占位符所占空白大小是不一样的，一般汉语用全角，英语用半角：

&ensp;或&#8194; //半角
&emsp;或&#8195; //全角
&nbsp;或&#160; //普通空格

换行

换行直接敲回车，在有些 Markdown 语法转换器里是不会换行的，解决办法是换行后敲至少两个空格后再回车换行；这个方法其实也只是解决大部分 Markdown 语法转换器的问题，我记得在 Gitlab 在某个版本的时候，这种方法就是不行的；如果遇到这个情况，终极解决办法就是在要换行的地方直接指明写上： <br/>

段落

段落就是连续行上的文本, 一个或多个还行划分不同的段落，通常一个换行或两个换行为一个段落。

3. 块引用

Markdown 使用 > 标记表示块引用，以换行结束块引用：

> 这是第一个块引用！

> 这是第二个块引用！和上一个块引用有换行了

块引用可以包含其他 Markdown 标记, 包括标题、列表和代码块等:

> 包含其他 Markdown 标记的块引用
>
> 1. 列表1
> 2. 列表2

块引用可以嵌套,即块引用中包含块引用, 根据层次加上不同数量的>标记即可:

> 一级
> > 二级
> > > 三级

4. 列表

有序列表

使用 "数字 + . 句号标记" 表示有序列表:

1.  列表一 //标记后与列表文本应有一个以上的空格或者一个水平制表符
2.  列表二
3.  列表三
等价于:
3.  列表一
2.  列表二
6.  列表三
等价于：
<ol>
<li>列表一</li>
<li>列表二</li>
<li>列表三</li>
</ol>

备注：如上第二个列表，使用错误的列表序号, 最终生成的列表仍然会以序号1开始；这个特性会导致在实际使用列表中遇上一个场景，在列表与列表之间插入其他的块级元素标记，标签序号上下就对不上号了，下面的列表又重新从1开始，这个问题在某些 Markdown 语法转换器不会出现，但就目前 Markdown 的语法定义来看，这个问题存在是正常的，解决方案见下面的列表使用的注意事项。

无序列表

Markdown 使用 *星号标记, + 加号标记, - 连字符标记,这三个标记都可以表示无序列表:

*   列表x //标记后与列表文本应有一个以上的空格或者一个水平制表符
*   列表y
*   列表z
等价于:
+   列表x
+   列表y
+   列表z
等价于:
-   列表x
-   列表y
-   列表z
等价于:
<ul>
<li>列表x</li>
<li>列表y</li>
<li>列表z</li>
</ul>

列表使用的注意事项

如果有序列表项中包含 > 块引用标记，则块引用需要缩进，否则下一个列表序号和上一个就不衔接了:

1. 这是一个带引用的列表
    > 引用内容
2. 这是一个带引用的列表
    > 引用内容

效果：

这是一个带引用的列表

引用内容
这是一个带引用的列表

引用内容

如果列表项中有代码块, 代码块需要双倍缩进8个空格或者两个水平制表符:

*   这是一个有代码块的列表
        <code>

终极大招，有些有 Markdown 语法转换器，不管怎么小心还是很容易出现有序列表序号上下不衔接的情况，时候我们就干脆自己定义序号，不触动 Markdown 语法有序列表, 可以通过 \ 转意标记将点号转意，如下面这样的代码:

3\. 列表3
2\. 列表2
6\. 列表6

效果：
3. 列表3
2. 列表2
6. 列表6

5. 代码块

作为程序员写 Markdown 文档，引代码到文档是经常会用到的，代码块分为行内代码块和多行代码代码块。

行内代码块

使用 `` 标记表示行内代码块，代码块前后各使用一个标记，如下：

Java打印控制台日志通过代码 `System.out.println("Hello!");` 实现
等价于：
Java打印控制台日志通过代码<code>System.out.println("Hello!");</code>实现

效果： Java打印控制台日志通过代码 System.out.println("Hello!"); 实现

多行代码代码块

在要引入的代码每一行都缩进4个空格或者1个水平制表符，就可以表示代码块，不过我更喜欢用标签显得更美观一些，Markdown 使用``` ``` 标记表示多行代码块，代码块前后各使用三个标记，如下：：

` ` `
public static void main(String[] args) {
    System.out.println("Hello!");
}
、、、
等价于：
<pre><code>
public static void main(String[] args) {
    System.out.println("Hello!");
}
</code><pre>

引入HTML原始码

代码块中， < 和 > 会自动转成HTML实体 < 和 < ，代码块标记可以直接引入HTML原始码，例如想在文档中引入一段html代码：

` ` `
<div class="footer">
   © 2016 ***
</div>
` ` `
等价于：
<pre><code>&lt;div class="footer"&gt;
    &amp;copy; 2004 Foo Corporation
&lt;/div&gt;
</code></pre>

6. 链接

Markdown 链接的标记语法有"内联式"和"引用式"两种形式，还有一种特殊的自动链接，通常我们程序员内联式使用较多，参考式语法一般用在学术论文上面。

内联式语法

[] 里写链接文字，() 里写链接地址, () 中的""中可以为链接指定title属性，title属性可加可不加(title属性的效果是鼠标悬停在链接上会出现指定的title文字),链接地址与链接title前有一个空格，如下：

欢迎点击[calmsnow的博客](https://my.oschina.net/calmsnow/)
欢迎点击[Atom编写Markdown](https://my.oschina.net/calmsnow/blog/2875493 "Atom编写Markdown")
等价于：
欢迎点击<a href="https://my.oschina.net/calmsnow/">calmsnow的博客</a>
欢迎点击<a href="https://my.oschina.net/calmsnow/blog/2875493" title="Atom编写Markdown">Atom编写Markdown</a>

引用式语法

![] 里写链接文字，紧跟着 : 链接标记，一个以上的空白符和水平制表符后是链接地址，链接地址后打一个空格，可以为链接指定title属性，title属性可加可不加(title属性的效果是鼠标悬停在链接上会出现指定的title文字)，如下

我的文章[数据结构概述]:https://my.oschina.net/calmsnow/blog/733059
我的文章[Markdown简介]:https://my.oschina.net/calmsnow/blog/2875124 "Markdown简介"

自动链接

Markdown 支持一种 "自动" 创建 URL 地址链接的简短形式: 只需用 <> 尖括号包围 URL 地址即可：

<http://example.com/>
等价于：
<a href="http://example.com/">http://example.com/</a>

7. 锚点链接

在网页中，锚点就是网页内的链接跳转，Markdown的锚点链接也是一样的效果，实现跳转到本文档内部的某些位置; [] 里写锚点链接文字, (#) 里面写链接跳转到的字符

跳转到[大标题](#标题)

备注：有些Markdown语法转化器只支持在标题后插入锚点，其它地方无效

7. 图片引入

Markdown 图片引入和链接一样，有"内联式"和"引用式"两种形式，通常我们程序员内联式使用较多，参考式语法一般用在学术论文上面。

内联式语法

![] 里写图片的 alt 属性(图片Alt的意思是如果图片因为某些原因不能显示，就用定义的图片Alt文字来代替图片)，() 里写图片地址, () 中的 "" 中可以为图片指定title属性，title属性可加可不加(title属性的效果是鼠标悬停在图片上会出现指定的title文字),图片地址与图片title前有一个空格，如下：

本地图片引入：
![](/path/mk.img)
远程图片引入：
![远程图片](https://oscimg.oschina.net/oscnet/25ab82.jpg "远程图片")

引用式语法

![] 里写图片的 alt 属性(图片Alt的意思是如果图片因为某些原因不能显示，就用定义的图片Alt文字来代替图片)，紧跟着 : 标记，一个以上的空白符和水平制表符后是图片地址，图片地址后打一个空格，可以为图片指定title属性，title属性可加可不加(title属性的效果是鼠标悬停在图片上会出现指定的title文字)，如下

本地图片引入：
![]: /path/mk.img
远程图片引入：
![远程图片]: https://oscimg.oschina.net/oscnet/25ab82.jpg "远程图片"

备注：Markdown 提供了图片引入的语法，但是没有指定图片尺寸的支持，如果需要指定图片尺寸, 可以直接使用 HTML 标签 <img>。

8. 斜体、加粗、删除线、水平线

斜体

Markdown 用星号标记 * 或下划线标记 _ ，代表斜体，相当于用 HTML 标签 <em> 包裹,如下：

*斜体*
等价于：
_斜体_
等价于：
<em>斜体</em>

加粗

Markdown 用两个星号标记 ** 或两个下划线标记 __ ，代表加粗，相当于用 HTML 标签 <strong> 包裹,如下：

**粗体**
等价于：
<strong>double asterisks</strong>
三个星号标记加粗斜体：
***加粗斜体***
等价于：
<strong><em>加粗斜体</em></strong>

删除线

Markdown 用两个波浪号标记 ~~,代表删除线

~~删除线~~

水平线

一行中只有三个以上的号标记 *,或三个以上连字符标记 -,或三个以上下划线标记 _，则会在该位置生成一个水平线，并换行，星号和连字符之间的空格也是允许的，如下都是生成一条水平线:

* * *
***
*****
---
_ _ _

9. 反斜杠转义

Markdown 将很多字符作为标记，那么当在Markdown中想原样输出这些字符，除了用行内代码块的方式以外，还可以使用 \ 反斜杠转义 Markdown 语法标记符号使之成为字面量，比如：

\\
输出：\
\`   backtick
输出：`
\*
输出：*
\!
输出：！
......

10. 表格

Markdown 标记表格，对于简单表格，应该是比较方便的，通常对于用来写服务端接口文档，多层Json嵌套，需要展现出嵌套感的表格，使用 HTML 标签 <table> 会更方便清晰一些；

语法：第一行为表头，列于列之间用|竖线标记，第二行分隔表头和主体部分，列于列之间用-|标记，第三行开始每一行为一个表格行，列于列之间用|竖线标记；表格单元格默认为左对齐，在-右边加上:就右对齐。

简单方式写写法：
学号|姓名|分数
-|-|-
张三|男|99
李小妹|女|60
王五|男|85
等价于：
|学号|姓名|分数|
|-|-|-|
|张三|男|99|
|李小妹|女|60|
|王五|男|85|
为表格第二列指定方向：
帐号|备注
-|-:
calmsnow|超级活跃
平淡|潜水

11. 注脚

说明注脚最佳的例子就是学术论文，在需要添加注脚的文字后加上脚注名字，在文本的任意位置(一般在最后)添加脚注说明；Markdown 使用[^注脚名字]添加脚注：

用 Markdown[^1] 书写文档, 可以转换成 HTML[^2]、 PDF[^pdf]
[^1]:Markdown是一种纯文本标记语言
[^2]:HTML是一种标记语言
[^pdf]:就是pdf，我也不知道怎么描述它

备注：有些Markdown语法转换器注脚内容与注脚之间必须空一行，不然会失效。上面示例效果如下：<br> 用 Markdown^1 书写文档, 可以转换成 HTML^2 、 PDF^pdf

还有一些更复杂有趣的Markdown语法，以后有时间再研究了，很多不太常用，本文就简单的总结归纳常用的Markdown基础语法

转载于:https://my.oschina.net/calmsnow/blog/2876096

weixin_34410662

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
Markdown语法-基础

2019独角兽企业重金招聘Python工程师标准>>> ...
复制链接

扫一扫