小鲸鱼的梦境
0%

markdown基本语法

发表于 分类于 Valine：
本文字数： 2.3k 阅读时长 ≈ 2 分钟

前言

博客的文章都是使用 markdown 文档进行编写的，所以这里记录下一些基础的语法内容。

其实很久之前有做过一个教程汇总，这里进行整理一下。

[TOC]

参考资料

简介

Markdown 是一种轻量级的标记语言，可用于在纯文本文档中添加格式化元素。Markdown 由 John Gruber 于 2004 年创建，如今已成为世界上最受欢迎的标记语言之一。

Markdown有很多中拓展，在不同平台可能有些平台特有的语法，但基本的语法是有用的。

个人觉得 Markdown 两个强大的地方在于：

  1. 兼容部分 Latex 语法，即输入数学公式非常方便
  2. 兼容部分 Html 语法，即

标题语法

# 表示标题，其数量表示标题级别，根据级别可以自动生成目录，这里就不演示具体效果了

注意 # 与标题文字之间要有一个空格

1
2
3
4
5
6
7
8
9
10
11
# 一级标题

## 二级标题

### 三级标题

#### 四级标题

##### 五级标题

###### 六级标题

一级标题可以使用 yaml 或 json 格式，但更多是将其当成一些文档信息而非标题，例如本文的一级标题就是使用 yaml 格式书写的，这也是 Hexo 博客的固有要求(下面中有些不是 markdown要求的，而是 Hexo 要求的，但添加了一般也不会报错), 关于 yaml 语法可以在我的博客中搜索 yaml 查看另外一篇介绍 yaml 基本语法的文章。

1
2
3
4
5
6
7
8
9
---
title: markdown基本语法
author: MeteorDream
date: 2022-07-07 14:09:32
updated: 2022-07-07 14:09:32
categories:
- [markdown]
tags: [markdown]
---

段落说明

单纯换行并不会换行，欲要换行有两个办法：

  1. 行末尾加两个空格再换行，渲染后就会有换行了(这里有个小坑，有些编辑器例如 Vscode 的个别插件会自动把段落后的空格去掉，这个特性必须关掉)
  2. 空一行，和上一个方法的区别是这其实是换段落了，行间距有区别
  3. 使用 $\quad\quad$ 进行段首缩进(这个其实是Latex的两个占位符)

强调

这里 * 和 _ 是等效的，建议一篇文章只使用一种，不要混搭。我个人的习惯是使用 *, 因为 _ 有时不太看得清数量。

  • **加粗字体, 快捷键 <kbd>ctrl</kbd>+<kbd>B</kbd>**: 加粗字体, 快捷键 ctrl+B
  • *斜体文本, 快捷键 <kbd>ctrl</kbd>+<kbd>i</kbd>*: 斜体文本, 快捷键 ctrl+i
  • *斜体文本*: 斜体文本
  • _斜体文本_: 斜体文本
  • **粗体文本**: 粗体文本
  • __粗体文本__: 粗体文本
  • ***粗斜体文本***: 粗斜体文本
  • ___粗斜体文本___: 粗斜体文本
  • <u>下划线要通过HTML标签实现</u>: 下划线要通过HTML标签实现
  • ~~这是删除线~~: 这是删除线
  • <mark>高亮文本</mark>: 高亮文本

博文不全部显示

这条是 Hexo 博客渲染特有的，并不是 markdown 的语法

1
<!--more-->

事实上, <!-- 注释 --> 是 html 的注释语法。

分割线

一般用 *** 或 --- 在单独一行

无序列表、有序列表、嵌套列表

无序列表一般以 - 或 * 开头，注意后面有个空格是必须的

有序列表以 数字+空格 开头

嵌套做好缩进即可。

同理，建议一篇文章只使用一种方式，个人最常用的是 - 的方式

1
2
3
4
5
6
7
8
9
10
11
12
- 123
  - 嵌套列表
    - 在嵌套
      - 再一次
- 456
  1. 可以嵌套有序列表
  2. 显示的是……
     1. 再一次嵌套优秀列表
        1. 再一级
        2. 第二季
        3. 第三季
- 789
  • 123
    • 嵌套列表
      • 在嵌套
        • 再一次
  • 456
    1. 可以嵌套有序列表
    2. 显示的是……
      1. 再一次嵌套优秀列表
        1. 再一级
        2. 第二季
        3. 第三季
  • 789

To do list(可选项)，注意 [] 内的空格是必须的

1
2
3
- [ ] 待完成  
- [x] 已完成
- [ ] ~~未完成~~

引用

1
2
3
4
5
6
7
> 区块引用
>
> 1. 还能嵌套列表
> 2. 列表第二项
>
> > 嵌套区块
> > > 三级嵌套

区块引用

  1. 还能嵌套列表
  2. 列表第二项

嵌套区块 > 三级嵌套

代码

行内代码用反引号(`, Tab 上面那个键)包裹

`单行代码`

print(Hello)

多行代码块用两组“三反引号”包裹，在开头的三个反引号后面添加上语言标记(关系到语法高亮)

1657179723834

1
print("Hello world!")
1
2
3
int main(){
    cout << "Hello World!" << endl;
}

那么问题来了，要是想要在代码块中使用反引号怎么办呢？那么需要多个引号，例如想要显示 (`), 那么应该写为 `` (`) ``, 以此类推

如果想使用 双反引号，那么要用三反引号对包围，注意包围的反引号对与内容之间要空格，这个空格渲染器会视为分隔不会显示。

折叠代码块(html标签实现)

1
2
3
4
5
6
7
8
<details>
  <summary>展开代码</summary>
  <pre><code>
    int main(){
      cout << "Hello!" << endl;
    }
  </code></pre>
</details>
展开代码 

    int main(){
      cout << "Hello!" << endl;
    }

混合代码块(html标签实现)//暂未研究出如何实现

目录

[TOC]

开头已经演示了

有些渲染器不一定能渲染，看情况，如果上面那个方法出不来目录，只能手动添加了

页内跳转

1、定义锚点 <-- 其实就是标题类型
2、跳转格式： [点击这文本跳转](#前言) 点击这文本跳转 -- 很类似链接啦，无论是什么级别标题都只要一个#哦
点我到锚点跳转

注音文本

1
<ruby>饕餮 <rt>tāo tiè</rt></ruby>

饕餮 tāo tiè

emoji

  • 简短编码：两个冒号包围的单词，例如 :cat: 表现就是 :cat:, :joy: 的表现就是 :joy:, :laughing: 就是 :laughing:。
  • Unicode编码: &#x{unicode};，有些 emoji 没有简短编码，例如 &#x1F923; 是 🤣 ，&#x26A7; 是 ⚧ .

具体的emoji 可以在 https://www.emojiall.com/zh-hans/all-emojis 找到，就不一一罗列了，太多了，看简短代码即可:blush:.

同理该功能也不是所有渲染器都支持的（Hexo 只能渲染 Unicode 编码）。

链接

1
[bilibili](https://www.bilibili.com/)

bilibili

1
<https://www.bilibili.com/>

https://www.bilibili.com/

图片

1
![小兔子](https://ss1.bdstatic.com/70cFvXSh_Q1YnxGkpoWK1HF6hhy/it/u=1189146037,251605608&fm=26&gp=0.jpg "悬浮注释")

小兔子

注意 [] 里面的内容是在图片加载不出来才显示的内容，后面引号内的是鼠标悬停在图片上会显示的内容（有些渲染器会显示为图片下方的图片说明）

表格

格式化表格快捷键: alt+shift+F

1
2
3
4
| 语言  | python |    cpp |   java   |
| :---: | :----- | -----: | :------: |
|   1   | .py    |   .cpp |  .java   |
| 格式  | 左对齐 | 右对齐 | 居中对齐 |
语言 python cpp java
1 .py .cpp .java
格式 左对齐 右对齐 居中对齐

公式

行内公式用 $ 包围 或使用 \[ 及 \] 包围: \(\lim_{x \to \infty}x^{\frac{1}{x}}=1\).

多行公式用 $$ 包围 或使用 \[ 及 \] 包围, 代码块语言标记为 math 也会被识别为公式

\[ \lim_{x \to \infty}x^{\frac{1}{x}}=1 \]

公式的具体语法参考 Latex 语法

脚注

插入标注[1]的语法为 <sup id="fnref:1"><a href="#fn:1" rel="footnote"><span class="hint--top hint--error hint--medium hint--rounded hint--bounce" aria-label="第一个脚注 [^footnote]: The second footnote">[1]</span></a></sup> 当然不一定要求数字，可以是单词[^note]，但不能有空格

在其他位置（一般是文章末尾）添加脚注的具体内容，格式为

1
2
[^1]: 第一个脚注
[^note]: The second footnote

流程图

代码块语言标记为 mermaid, 但有些渲染器不一定支持

方向

  • TB 从上到下
  • BT 从下到上
  • RL 从右到左
  • LR 从左到右
  • TD 同TB
1
2
graph RL
   A --> B

基本图形

1
2
3
4
5
6
graph RL
    id[带文本的矩形]
    id4(带文本的圆角矩形)
    id3>带文本的不对称的矩形]
    id1{带文本的菱形}
    id2((带文本的圆形))

连接

  • A --> B A带箭头指向B
  • A --- B A不带箭头指向B
  • A -.- B A用虚线指向B
  • A -.-> B A用带箭头的虚线指向
  • A ==> B A用加粗的箭头指向
  • A -- 描述 --- B A不带箭头指向B并在中间加上文字描
  • A -- 描述 --> B A带箭头指向B并在中间加上文字描
  • A -. 描述 .-> B A用带箭头的虚线指向B并在中间加上文字描
  • A == 描述 ==> B A用加粗的箭头指向B并在中间加上文字描述
1
2
3
4
5
6
7
8
9
10
graph LR
    A[A] --> B[B] 
    A1[A] --- B1[B] 
    A4[A] -.- B4[B] 
    A5[A] -.-> B5[B] 
    A7[A] ==> B7[B] 
    A2[A] -- 描述1 --- B2[B] 
    A3[A] -- 描述2 --> B3[B] 
    A6[A] -. 描述3 .-> B6[B] 
    A8[A] == 描述4 ==> B8[B]

颜色代码

  • pink 255,192,203, #FFC0CB
  • LightPink 255,182,193, #FFB6C1
  • Purple 160,32,240, #A020F0
  • 紫罗兰 138,43,226, #8A2BE2
  • shizuku蓝 193,22,38, #C1DEEE

Markdown标准

下面是 Markdown 的一份标准，但不是一定要执行, 主要是 vscode 插件 markdownlint 的语法检查规则（有些不喜欢的就关掉了）参数也是插件里面的参数。

MD001 - Heading levels should only increment by one level at a time 标题级数每次只能扩大1, 也就是不能隔级创建标题（从1级到6级的顺序）

MD002 - First heading should be a top level heading 文档的第一个标题必须是最高级的标题（标题等级1级到6级逐渐降低）

参数： "level"：指定最高级标题的级数，默认是1

MD003 - Heading style 整篇文档要采用一致的标题格式

参数： "style"：字符串，指定文档标题的格式，有("consistent", "atx", "atx_closed", "setext", "setext_with_atx", "setext_with_atx_closed")五种，默认是"consistent"，也就是整篇文档一致

标题格式必须统一，一般不能混用，但"setext_with_atx", "setext_with_atx_closed"格式可以在"setext"格式二级标题后接着使用"atx"或"atx_closed"格式的标题

MD004 - Unordered list style 整篇文档定义无序列表的格式要一致

参数： "style"：字符串，指定无序列表的定义格式，有("consistent", "asterisk", "plus", "dash", "sublist")五种，分别表示“定义时符号前后一致”，“用星号定义”，“用加号定义”，“用减号定义”，“定义多重列表时用不同的符号定义”，默认是"consistent"

MD005 - Inconsistent indentation for list items at the same level 同一级的列表缩进必须一致 在有序列表中，前面的数字序号可以左对齐，也可以右对齐

MD006 - Consider starting bulleted lists at the beginning of the line 1级列表不能缩进

MD007 - Unordered list indentation 无序列表嵌套缩进时默认采用两个空格

参数： "ident"：指定无序列表嵌套时缩进的空格数，默认是2

MD009 - Trailing spaces 行尾最多可以添加两个空格，超过会给出警告，两个空格正好可以用于换行

参数： "br_spaces"：指定在行尾可以添加的空格数目，空格数目建议大于等于2，如果小于2，会默认为0，也就是不允许任何行尾的空格 "list_item_empty_lines"：字符串，指定在列表中是否(true or false)用默认的空格数缩进空行，有的解释器会要求列表中的空行要缩进

MD010 - Hard tabs 不能使用tab键缩进，要使用空格

参数： "code_blocks"：指定本条规则在代码块里是否(true or false)生效

MD011 - Reversed link syntax 检查内联形式的链接的创建方式是否错误，中括号和圆括号是否用对

MD012 - Multiple consecutive blank lines 文档中不能有连续的空行，在代码块中此规则不会生效

参数： "maximum"：指定文档中可以连续的最多空行数，默认值是1

MD013 - Line length 默认行的最大长度是80，此规则对代码块、表格、标题也生效

参数： "line_length"：指定行的最大长度，默认是80 "heading_line_length"：指定标题行的最大长度，默认是80 "code_blocks"：指定规则是否(true or false)对代码块生效，默认true "tables"：指定规则是否(true or false)对表格生效，默认true "hesdings"：指定规则是否(true or false)对标题生效，默认true

MD014 - Dollar signs used before commands without showing output 在代码块中，终端命令前不需要有美元符号($) 如果代码块中既有终端命令，也有命令的输出，则终端命令前可以有美元符号($)，如：

$ ls foo bar $ cat foo hello world

MD018 - No space after hash on atx style heading 在"atx"格式的标题中，#号和文字间需用一个空格隔开

MD019 - Multiple spaces after hash on atx style heading 在"atx"格式的标题中，#号和文字间只能用一个空格隔开，不能有多余的空格

MD020 - No space inside hashes on closed atx style heading 在"closed_atx"格式的标题中，文字和前后的#号之间需用一个空格隔开

MD021 - Multiple spaces inside hashes on closed atx style heading 在"closed_atx"格式的标题中，文字和前后的#号之间只能用一个空格隔开，不能有多余的空格

MD022 - Headings should be surrounded by blank lines 标题行的上下行必须都是空行

参数： "lines_above"：指定标题行上方的空行数，默认为1，可以设为更大或0 "lines_below"：指定标题行下方的空行数，默认为1，可以设为更大或0

注意当此处的空行设为比1大的数时，规则MD012的设置也要改

MD023 - Headings must start at the beginning of the line 标题行不能缩进

MD024 - Multiple headings with the same content 文档不能有内容重复的标题

参数： "siblings_only"：默认为false，设为true时，不同标题下的子标题内容可以重复

MD025 - Multiple top level headings in the same document 同一文档只能有一个最高级的标题，默认是只能有一个1级标题

参数： "level"：指定文档最高级的标题，默认是1 "front_matter_title"：字符串，指定在文档开头处的front matter中的标题，这个标题将作为整篇文档的最高级标题，如果文档中再次出现最高级标题，将会给出警告，另外，如果不想在front matter中指定标题，就把本参数的值设置为""

MD026 - Trailing punctuation in heading 标题行末尾不能有以下标点符号：".,;:!?"

参数： "punctuation"：字符串，指定标题行尾不能有的标点符号，默认是".,;:!?"

此规则默认的是英文的标点符号，中文标点符号不在规则之内

MD027 - Multiple spaces after blockquote symbol 创建引用区块时，右尖括号 ( > ) 和文字之间有且只能有一个空格

MD028 - Blank line inside blockquote 两个引用区块间不能仅用一个空行隔开或者同一引用区块中不能有空行，如果一行中没有内容，则这一行要用>开头

MD029 - Ordered list item prefix 有序列表的前缀序号格式必须只用1或者从1开始的加1递增数字("one_or_ordered")

参数： "style"：字符串，指定前缀序号的格式，("one","ordered","one_or_ordered","zero")，分别表示只用1做前缀，用从1开始的加1递增数字做前缀，只用1或者从1开始的加1递增数字做前缀，只用0做前缀，默认值是"one_or_ordered"

本条规则支持在前缀序号中补0，以实现对齐，如：

1
2
3
1.   one
2.   two
3.   three

MD030 - Spaces after list markers 列表（有序、无序）的前缀符号和文字之间用1个空格隔开 在列表嵌套或者同一列表项中有多个段落时，无序列表缩进两个空格，有序列表缩进3个空格

参数： "ul_single","ol_single","ul_multi","ol_multi"：分别规定无序列表单个段落，有序列表单个段落，无序列表多个段落，有序列表多个段落的前缀符号和文字之间的空格数，默认是1

MD031 - Fenced code blocks should be surrounded by blank lines 单独的代码块前后需要用空行隔开（除非是在文档开头或末尾），否则有些解释器不会解释为代码块

MD032 - Lists should be surrounded by blank lines 列表（有序、无序）前后需要用空行隔开，否则有些解释器不会解释为列表 列表的缩进必须一致，否则会警告

MD033 - Inline HTML 文档中不允许使用HTML语句

参数： "allowed_elements"：自定义允许的元素，是一个字符串数组，默认是空(empty)

MD034 - Bare URL used 单纯的链接地址需要用尖括号 (<>) 包裹，否则有些解释器不会解释为链接

MD035 - Horizontal rule style 创建水平线时整篇文档要统一(consistent)，要和文档中第一次创建水平线使用的符号一致

参数： "style"：字符串，指定创建水平线的方式，值有：("consistent","***","---","___")，默认是"consistent"

MD036 - Emphasis used instead of a heading 不能用强调代替标题

参数： "punctuation"：字符串，指定用于结尾的标点符号，以此符号结尾的强调不会被视为以强调代替标题，默认值是".,;:!?"

此规则会检查只包含强调的单行段落，如果这种段落不是以指定的标点符号结尾，则会被视为以强调代替标题，会给出警告

MD037 - Spaces inside emphasis markers 用于创建强调的符号和强调的的文字之间不能有空格

MD038 - Spaces inside code span elements 当用单反引号创建代码段的时候，单反引号和它们之间的代码不能有空格 如果要把单反引号嵌入到代码段的首尾，创建代码段的单反引号和嵌入的单反引号间要有一个空格隔开

MD039 - Spaces inside link text 链接名和包围它的中括号之间不能有空格，但链接名中间可以有空格，如：

百 度

MD040 - Fenced code blocks should have a language specified 单独的代码块（此处是指上下用三个反引号包围的代码块）应该指定代码块的编程语言，这一点有助于解释器对代码进行代码高亮

MD041 - First line in file should be a top level heading 文档的第一个非空行应该是文档最高级的标题，默认是1级标题

参数： "level"：指定文档最高级的标题，默认是1 "front_matter_title"：字符串，指定在文档开头处的front matter中的标题，这个标题将作为整篇文档的最高级标题，另外，如果不想在front matter中指定标题，就把本参数的值设置为""

MD042 - No empty links 链接的地址不能为空

MD043 - Required heading structure 要求标题遵循一定的结构，默认是没有规定的结构("null")

参数： "headings"：字符串数组，指定标题需要遵循的结构，默认是"null"，可以自行指定结构，如；

[ "# head", "## item", "### detail", "*"] 星号(*)表示对应的标题是可选的，没有强制要求，本条具体可以参照MD043

MD044 - Proper names should have the correct capitalization 指定一些名称，会检查它是否有正确的大写

参数： "names"：字符串数组，指定要检查需要大写的名称，默认是空("null") "code_blocks"：指定本规则是否(true or false)对代码块生效，默认是true 一些经常使用的名称可以使用本规则防止其拼写错误，比如JavaScript中字母J和S需要大写，就可以写到参数"names"中，防止写错

MD045 - Images should have alternate text (alt text) 图片链接必须包含描述文本（alt text）

MD046 - Code block style 整篇文档采用一致的代码格式

参数： "style": 字符串，指定代码块定义格式，有（"consistent","fenced","indented"）三种，分别代表：文档上下文一致，使用三个反引号隔开，使用缩进，默认是上下文一致

MD047 - Files should end with a single newline character 文档需用一个空行结尾
  1. 1.第一个脚注 [^footnote]: The second footnote ↩︎
--- ♥ end ♥ ---

欢迎关注我呀~