【markdown】markdown自学笔记（进阶篇）

riskmoumou

已于 2024-01-07 20:40:30 修改

阅读量924

点赞数 18

文章标签： vscode 笔记

于 2024-01-07 20:26:46 首次发布

本文链接：https://blog.csdn.net/riskmoumou/article/details/135444112

版权

【markdown】markdown语法（进阶篇）

前言

markdown基础语法的学习过后,我以为总要学一下进阶的语法,但被反复 踢皮球 后失去了耐心.
于是我决意自己写一篇来使用,正好通过输出的方式巩固所学.后续会试图更新此篇,进一步完善它.
本篇内容涉及markdown的基础语法与规范的建议(这有助于你对自己文档的修改,或者使用支持markdown的多人在线编辑文档),以及后续的进阶语法(扩展语法主要基于Markdown Preview Enhanced).

使用环境

Visual Studio Codevscode的官方网站:https://code.visualstudio.com/(假如你被搜索引擎困扰的话,你也许需要它?)相关扩展安装(打勾的为必需)

Markdown Preview Enhanced
Office Viewer(Markdown Editor)
Markdown All in One
learn-markdown
markdownlint
Markdown Emoji --(如果你需要使用emoji的话,似乎是必需的)
:emojisense: --(我单纯喜欢它能快速提供emoji选择)

基础语法说明与建议

事实上,对于基础语法的规范建议,大都可以通过vscode扩展中的markdownlint插件解决
(也许你需要一些 简单? 的个性化配置来忽略跟某些规则的冲突,因为有的规则你可能不需要,以及你可能需要根据个人需要修改某个规则的相应参数).
扩展语法上,则可以参考CommonMark(一种普遍接受的扩展语法标准).
不过出于需求的差异,没有一种语法可以让所有人满意,因此markdown没有完全标准化,
默认需要看此篇内容的读者已经掌握了markdown基础语法,因而,在本部分
除却部分较复杂(我个人以为)的内容我会给出具体代码语法,更多的则是给出针对的建议.
本部分参考了Markdown 风格指南完成.

标题

在#后加一个空格是一个好习惯，避免造成阅读困难.(~~个人修改自己的第一篇markdown文档时已经想鼠~~)
使用#标记标题，而不是==（一级标题）或者–（二级标题），后者通常是难以阅读以及维护的(这一点通常是显而易见的)。
标题应该用空行包围（除非标题在文档开头）.
标题简短可以方便你的后续引用，特别是生成目录时。假如原拟的标题是一个长句，比起使用长句,你可以将标题作为长句子的摘要，而将长句写在标题下的第一段。
通常,你可能需要在标题内容的末尾加一个分隔线,表示该标题下的内容到此为止.

部分示例如下:

# 我是一级标题

## 我是二级标题

猜猜我是几级标题
--

猜猜我是几级标题
==

使用markdown写文档的推荐结构(Google Style)

文档标题：第一个标题应为一级标题，并且理想情况下，应与文件名相同或几乎相同。
作者：可选。如果需要请在标题下添加自己。然而在修订历史里添加通常就足够了。
简短介绍:1-3 句话介绍本文的内容。想象自己是一个完全的新手，他需要知道你认为理所当然的最基本假设。
目录：如果你使用的主机支持目录,例如Gitiles,将其放在简短的介绍之后。(~~事实上,你也能自己写目录~~)详情请参阅 TOC 文档。
标题:其余标题应从第2级开始。
相关链接：将杂项链接放在底部，供想要的用户使用了解更多或没有找到的他所需要的东西。

示例代码如下:


# 文档标题

简短介绍

目录

## 标题

内容

## 相关链接

description:<https://link-to-more-info>

粗体

建议使用 *包裹,因其可读性比 _更强

段落与换行

段落的分隔使用空行实现
段内换行需要在上一行末尾加入2个及以上的空格,然后按回车键,也推荐使用 <br/>进行换行,
(假如你需要你的markdown文档是"纯文字"的,那么你需要采取前面的方法,即尾随空格¹的方式)
markdown语句支持部分HTML语法.

换行通常建议:

超过80个字符后换行
在一句话结束后换行
URL较长时换行
在URL前加一个换行符
通过引用链接来进行优化

示例代码如下:

[GitHub Flavored Markdown](https://github.github.com/gfm/)

[GitHub Flavored Markdown]

[GitHub Flavored Markdown]:https://github.github.com/gfm/

列表

建议统一使用 -来标记无序列表,或者使用 *与 +,-固定格式组合的形式(比如整个文档无序一级用 *,二级用 +,三级用 -)来标记多级无序列表.
倘若列表每个内容适合单个段落,使用1个空格缩进.否则对无序列表使用3个空格缩进,有序列表使用2个空格缩进.(这样方便你后续对所有同类的列表进行修改)
列表内部的内容和其他列表项的缩进级别应当与第一个列表项相同

分割线

分割线须使用至少3个及以上一样的 *,-,_
可以在标记符中间加入空格

图片

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

图片无论是使用本地的绝对路径或相对路径,还是使用网络图片的地址,都是支持的
图片替代文字在图片无法正常显示时显示

链接

语法:
[链接文字][链接标记]–正文直接引用
[链接标记]:链接地址–文档定义(通常在文档底部或者在你试图引用它的段落的周围)后引用
<URL或邮箱地址>

建议:

链接的文字应当具有实际意义(你也不希望你看到的链接文字信息不告诉你对应的链接是什么吧?)
使用<>将链接括起来,因为不是所有markdown编辑器都支持将URL自动转换为链接的

行内代码与代码块

行内代码:

可执行文件,例如:
```
    `gcc` is the best compiler available.
```
区分工具和相关项目的名称。例如：vs GCC。gcc
文件路径
版本号
缩写的大写解释：

xinetd stands for eXtended Internet daemon
您不想添加到字典中的与计算机相关的其他术语

代码块:

除非你要在同一代码块上显示命令输出,否则不要在shell代码前面加上 $
(shell命令我们通常希望直接复制粘贴就可以运行)
如果目标是澄清语言是什么，请在上一段中进行。

不要标记为代码:

项目名称。例如：GCC
库的名称。例如：libc、glibc

引用

建议在引用的标记符号 >加一个空格以增加可读性
多行引用时,建议每一行引用使用 >(即使那一行什么内容都没有,只是要引用的部分中的空行)

转义

\ 可以转义的字符如下表所示

Character	Name
\	反斜线
`	勾号
*	星号
_	下划线
{}	花括号
[]	括号
()	圆括号
#	井号
+	加号
-	减号（连字号）
.	句号
!	感叹号

扩展语法

部分内容因为在markdown基础语法的扩展语法中有涉及,故不提供示例,只提供说明.(默认都掌握了markdown基本语法)
因为网上材料踢皮球以及大散篇的现状,我参考了Gitiles中关于markdown语法的内容,我会进行实验已确定其是否能正常应用于Markdown Preview Enhanced.

删除线

语法:将要添加删除线的部分前后用 ~~框起来就完了

表情符号

语法:用两个 :将emoji表情对应的Shortcode括起来就可以了,具体操作如下所示
(我也不知道为啥似乎很多emoji的短代码复制下来不支持,但是也可以直接复制表情粘贴😇)

首先进入官网https://www.webfx.com/tools/emoji-cheat-sheet/

在这里插入图片描述

随后将鼠标移到emoji上,会显示出这个emoji表情的unicode和shortcode

在这里插入图片描述

最后点击旁栏,切换我们需要复制的内容为shortcode,然后点击emoji表情,就可以获取它的shortcode了

在这里插入图片描述

示例代码:
:smile:

演示效果:
😄

自动链接

在markdown基础语法中有提到过,有的扩展语法支持URL地址在不使用 <>的情况下自动转换为超链接,GFM正是其中一种.代码示例如下:

http://example.com
<http://example.com>

演示效果如下:

http://example.com
http://example.com

假如两者都能点击跳转,就说明当前编辑器支持.

为了更好的移植性,个人建议使用 <>将链接括起来是好的(也没费啥事,偷这个懒干嘛😄)

表格

表格的使用,一般不建议使用过于大的表格,这样表格会很难写或者难以修改,即使你使用Tables Generator.

让我们来复习下吧:

基础知识

Markdown 制作表格使用 | 来分隔不同的单元格，使用 - 来分隔表头和其他行。

| 表头   | 表头   |
| ------ | ------ |
| 单元格 | 单元格 |
| 单元格 | 单元格 |

对齐

水平向左 :---
水平居中 :---:
水平向右 ---:

注意:这里的 -数量其实没有影响,用1个也没有影响,个人习惯,就用了三个😄

示例代码如下:

| 语法       |    描述    |        测试文本 |
| :--------- | :--------: | --------------: |
| ---页眉--- | ---标题--- | --Here's this-- |
| ---段落--- | ---文本--- |    --And more-- |

演示效果:

语法	描述	测试文本
—页眉—	—标题—	–Here’s this–
—段落—	—文本—	–And more–

表格前后空一行(很眼熟的要求,因为这让这些部分更显眼,利于你后续来修改调整)
每一行的 |对不对齐没有什么影响.

在表格规模小的时候一下就看出来了,对齐耗费的时间反而更多
表格规模大?不是说了不要用过大的表格吗🤣
~~除非你是强迫症~~不然个人建议没必要,真的.
假如你确切有这样的需求,你可以通过Alt+Shift+F(windows)来格式化
(通过Markdown All in One扩展可以帮你快速解决掉这个困扰)

任务列表

- [ ] 表示任务列表,在 []内用空格占位表示未选中
- [x] 表示任务列表,在 []内用 x 占位表示选中

- [x] Write the press release
- [ ] Update the website
- [ ] Contact the media

演示效果:

Write the press release
Update the website
Contact the media

围栏代码块

使用 ````或者~~~`将代码框起来即可,你还可以在其后标明这段代码使用的语言,以此显示对应的语法高亮.

锚点

锚点(直接翻译过来应该叫命名锚,但习惯了锚点的说法)(Named anchors),可以分为:
显式锚和隐式锚,让我们来一步步了解它吧

隐式锚点怎么产生

对应英文:

Anchor generation

letters and digits, after removing accents (á → a)
spaces are replaced with hyphens (-)
other characters are replaced with underscores (_)
runs of hyphens and underscores are collapsed

对应译文:

锚点生成

移除了重音后的字母和数字 (á → a)
空格被连字符 - 替换
将其他字符替换为下划线 _
连字符和下划线将被折叠

显式锚点怎么设置

方法一:<a name="tag"></a>

方法二:在标题后面加 {#你想要起的锚点名}

vscode上的markdown

vscode配置和快捷键

授人以鱼不如授人以渔,vscode官方文档拿去(什么英文有困难?~~不是有浏览器自带的翻译吗~~)

vscode的快捷键:https://code.visualstudio.com/shortcuts/keyboard-shortcuts-windows.pdf

vscode的用户指南:https://code.visualstudio.com/docs/editor/codebasics

vscode关于markdown的指南:https://code.visualstudio.com/docs/languages/markdown

啥,找不到文档在哪里?

在这里插入图片描述

下面是常见的可能用得到的操作:
打开预览方式:

右键单击编辑器选项卡并选择“打开预览”
(Ctrl+Shift+V)
(使用命令面板 (Ctrl+Shift+P) 运行“Markdown：在侧面打开预览”命令(Ctrl+K V))

markdown关于快捷键的扩展
Markdown Shortcuts

如果你希望你的图标更好看,你可以使用Material Icon Theme扩展(扩展搜索icon,第一个就是它了)

vscode编辑markdown

在使用环境中,我们有提到过,我们需要安装Markdown Preview Enhanced(此后简称为MPE), 接下来让我们开始使用它吧.

插入目录

关于如何插入目录,在TOC中有提到过,根据Markdown Preview Enhanced中关于TOC部分的文档显示, 它在被空行包围的情况下,会使用你的的H1,H2,H3标题提取生成对应的目录
(不过这样生成的目录,只会在预览中显示,而不会修改你的markdown文件)

示例代码:

---

@[toc]
---

值得一提的是,按照Gitiles的对应文档所述,假如只存在一个一级标题,那么目录中将省略H1标题.这允许我们将H1用作文档的标题.
(但实验过后,我发现MPE似乎不直接支持这么做?但我们可以通过一些参数的设置实现它)
至于具体怎么提取,感兴趣的读者可以再看看锚点的内容

一般我们使用的是这种方式完成目录,因为一方面,这很省事,不用自己一个个手搓创造目录~~(那真的很折磨)~~,另一方面,后续再做任何更改,在你保存之后,目录是会自动更改的.

但是我们可能会因某些原因,想要修改TOC自动生成的目录,那么我们需要怎么做呢?

参照MPE的语法的官方文档链接,你可以这样来设置

方法一:假如我们在生成目录时想要忽略某个标题,那么就可以在那个标题同行后面加上 {ignore=true}.

示例图如下所示:

在这里插入图片描述

方法二:我们可以通过ctrl+shift+p的快捷键调出命令面板,然后选择Markdown Preview Enhanced: Create Toc来创建你的TOC(这会修改你的markdown文章)

示例图如下所示:

在这里插入图片描述

关于参数的介绍如下:

orderedList 是否使用有序列表。
depthFrom, depthTo [1~6] 包含的。
ignoreLink 如果设置为 true，那么 TOC 将不会被超链接。(就是目录点击后不能跳转了)

其中depthFrom决定你的TOC目录从第几级标题开始生成, depthTO则决定你的TOC目录生成到第几级标题

示例图如下所示:

在这里插入图片描述

可以看到,TOC生成的目录只包括了1-4级标题,正如我们参数所设置的那样

导入文件

参照MPE的语法的官方文档链接,语法如下:

@import "你的文件"

或者

又或者

- image like syntax
  ![](file/path/to/your_file)

- wikilink like syntax
  ![[ file/path/to/your_file ]]
  ![[ my_file ]]

支持的文件类型:

.jpeg(.jpg), .gif, .png, .apng, .svg, .bmp 文件将会直接被当作 markdown 图片被引用。
.csv 文件将会被转换成 markdown 表格。
.mermaid 将会被 mermaid 渲染。
.dot 文件将会被 viz.js (graphviz) 渲染。
.plantuml(.puml) 文件将会被 PlantUML 渲染。
.html 将会直接被引入。
.js 将会被引用为 <script src="你的 js 文件"></script>。
.less 和 .css 将会被引用为 style。目前 less 只支持本地文件。.css 文件将会被引用为 <link rel="stylesheet" href="你的 css 文件">。
.pdf 文件将会被 pdf2svg 转换为 svg 然后被引用。
markdown 将会被分析处理然后被引用。
其他所有的文件都将被视为代码块。

此处的具体操作就看MPE的语法的官方文档链接,个人不再赘述.

幻灯片制作(个人目前没有需求,故偷懒放个链接完事)

MPE幻灯片制作

文件导出(同理偷懒)

MEP导出PDF(更多格式的导出你可以在左边旁栏下的 “文档导出” 找到)

用户代码片段

vscode支持自定义用户代码片段,允许你通过触发智能感知(IntelliSense)来快速插入你设置的相应语言的模版,你可以设置全局的,局部的,某个语言的,都可以,更多详情见vscode官方文档,这里我只提供简单的应用.

用户代码片段在哪里?示图如下:

在这里插入图片描述

选择你需要的语言,示图如下:

在这里插入图片描述

然后根据里面的示例开始吧,示图如下:

在这里插入图片描述

这显示的是vscode提供给你的示例和说明,其大意如下:

将你的代码片段放置在这里。每个代码段都在一个代码段名称下定义，并具有前缀、主体和描述。前缀是用来触发代码片段的，代码体将被展开和插入。可能的变量有:$1，$2用于制表位，$0用于最终光标位置，$(1:label)， $(2:another)用于占位符。具有相同id的占位符被连接。

具体操作步骤如图所示:

step1:仿照示例写一个代码片段

在这里插入图片描述