学习Markdown

参考B站视频：Markdown 语法及应用

文档：https://slides.tonycrane.cc/PracticalSkillsTutorial/lec3/

什么是 Markdown

  • 是一种轻量级文本标记语言（markup language）

  • 可以通过纯文本来表示带有格式的文档，同时保证易读性

  • 语法简单，易于学习，易于使用，

  • 可以轻松转换为 HTML（映射到 HTML 的子集）

  • Markdown 的本质是一种标记语言，是对 HTML 的一种简化

语法规范

  • ohn Gruber 所规定的语法过于简单，具体实现都没有明确规定

  • 因此诞生了很多不同的标准，甚至各个软件、解析器都会有自己的实现

常见的规范都有什么？

书写软件

  • 裸的markdown 解析器（如果你熟悉 HTML 语法）

    • markdown-it：完美支持 CommonMark 的解析器

    • markdown-it-py：Python 版本，带有命令行工具

    • python-markdown：更传统的 Python 版本解析器（标准不清晰）

    • pandoc：支持多种格式的转换器，但有自己的一套标准

  • 所见即所得的markdown 编辑器

今天以CommonMark 标准进行讲解# 学习Markdown

标题

# 文字，前面几个#就是几级标题！

#加上空格再加文字是一级标题

##加上空格在加上标题名，就是二级标题，以此类推

  • 可以跳过中间标题，一般一篇文章写一个一级标题

  • 还支持Setext样式标题，文本后一行加多个===是一级标题，加多个—是二级标题

一级标题

=======

段落

直接书写就是段落！

换行的话，代码层面直接回车还是一行，需要在文本后面加两个空格或者<br/>才行，两行和同一段落的行间距不一样！

多个空格用&nbsp;或者&emsp;

引言

> 内容

这是一个引言

>空格再加内容，需要一个空行来退出引言！软件里直接enter回车键退出引言！

支持层层嵌套，还可以套用标题的语法，如果是多行引言，每行前都要加上>

这又是一个引言，前面还加了###

这是第二层引言，前面有两层>

无序列表

- + * 内容，减号、加号、或者星号加空格，后面再加内容！

  • 这就可以写层列表了！

  • 这就是列表

注意：符号要统一，可以层层嵌套，使用缩进，用Tab键或者四个空格

  • 123

    • 这使用了Tab缩进

如果要包含段落等内容，需要换一行，再加Tab键

有序列表

1. 内容``——数字空格再加内容，或者数字)空格再加内容！

  1. 这有序列表

  2. 这是有序

数字空格再加内容，或者数字)空格再加内容！处了第一个数字，其它数字不重要！

有序和无序列表可以嵌套!

分割线

--- ***

任意一个字符重复三次以上就可以，生成分割线！

注意，和上层文字最好留一空行，不然被识别成一级或二级标题！

代码块

  • 缩进形式：

    空行加上缩进，创建代码块，内部代码原样展示，但是代码不会高亮！

    console.log(‘学习Markdown，真开心！’)；

  • 篱笆形式：

使用三个```，或者三个~~~

console.log('学习Markdown，真开心！')
console.log('学习Markdown，真开心！')；

加语言就高亮，不加或者加text就不会高亮

行内标记

*或_等效

*斜体*
**粗体**
**_斜粗体_**   ***斜粗体***
`行内代码`
--删除线--
<u>下划线</u>

斜体
粗体
斜粗体
行内代码
–删除线–
下划线

行内标记可以相互嵌套，下划线没有，使用HTML语法！最好标记左右加上空格！

文本中使用符号*，最好使用转义字符！

插入图片

![图片描述](图片位置)

可以是绝对路径，也可以是相对路径，图片描述可以省略！

注意，这是引用，图片并不会真存在于在文档内，不像word文档，嵌入图片！

如果想要调整图片大小，使用HTML语法插入图片！<img scr="图片地址" alt="" width="30%"/>

<img scr="https://yuepan.oss-cn-chengdu.aliyuncs.com/img/tpyoraCom/spongebob.jpg" alt="" width="30%"/>

插入链接

[描述文字](链接地址)或者一对尖括号

[这是一张图片](https://yuepan.oss-cn-chengdu.aliyuncs.com/img/tpyoraCom/spongebob.jpg)

[这是一个网站](yue18.top)

<https://yue18.com>

这是一张图片

这是一个网站

https://yue18.com

描述文字可以嵌套行内标记！

内联HTML语法

解析器会原封不动的保留HTML内容和CSS样式！

常用扩展语法

表格

|符号去分割

|abc|bcd|cde|
|:--|:--:|--:|
|靠左|中间|靠右|
|123|345|567|
|123|345|567|
abc bcd cde
靠左 中间 靠右
123 345 567
123 345 567

第一行是表头，第二行规定对齐方式，其它是单元格，第二行可以没有，其它行可以缺！

  • |--|或者|:--| 是左对齐

  • |--:| 是右对齐

  • |--:| 是中间对齐

脚注

[^脚注名] [^脚注名]:脚注内容

这个内容跟有一个脚注[^1]

[^1]:这是脚注的内容

这个内容跟有一个脚注^1

脚注名可以是其它任意文本，保持一致即刻！最终序号是由出现顺序决定！

任务列表

- [ ] ，插入未完成，注意中间和后面要加个空格！

-[x] ，插入已完成

  • 学习javascript

    • 可以嵌套，使用缩进！

  • 学习Markdown

公式

严格来说，并不是markdown语法的一部分，用一对美元号标记，然后由JS库去处理！

$ $行内公式，直接写内容

$$ $$公式块，两个美元号，再回车！

$E=MC^2$

$$
E=MC^2
$$

流程图/时序图/甘特图…

也是扩展，不是markdown语法的一部分，一般使用mermaid.js来处理制图！

后续慢慢了解这些扩展！

  • 目前很多编辑器都自带 mermaid 支持，详见官方文档集成部分
  • markdown 在这里做的只是将其转为 ”mermaid“ 语言的代码块，然后交给 mermaid.js 来识别并处理
  • 详细语法见 mermaid.js 官方文档，用法非常丰富

支持 Markdown 的实用工具

  • 文档编写类
    • 💡 利用 HTML+CSS 灵活的样式来进行排版
    • 🏆 个人首推 vscode + markdown preview enhanced 插件
    • 所见即所得的开源编辑器：Mark Text
    • 较好支持 markdown 的笔记软件：obsidian
  • 网站搭建类
    • 💡 利用 markdown 来大大减小编写 HTML 网页的工作量
    • 🏆 笔记类网站制作：mkdocs、docsify、…
    • 🏆 博客类网站制作：hexo、hugo、…
    • 🏆 在线 slides 制作：reveal-md（reveal.js）、Slidev、…
    • 书籍类网站制作：mdBook、d2lbook、…
    • “老式” Python 项目文档生成：Sphinx（一般使用 reST 语法）

工具推荐

  • vscode 插件：Markdown Preview Enhanced

    • 说明文档：Markdown Preview Enhanced

    • 特性：

      • 源码 <=> 预览 同步
      • 导出 HTML、PDF、PNG、…，多种导出方式，自定义主题
        • 基于 mpe 的主题自定义指南将在后续课程中介绍
      • 支持数学公式、多种图表（mermaid、wavedrom、flow charts、…）
      • TOC 目录、文件导入、admonition、CriticMarkup 等扩展语法
      • 代码块执行（Code Chunk）
      • 自定义 markdown parser 扩展等高级功能

  • mkdocs

      • 基于 python 的静态网站生成器，适合笔记本 / 文档类网站
      • 官网：www.mkdocs.org；唯一推荐主题：mkdocs-material（文档）
      • 使用 python-markdown，可方便配置具体扩展，material 插件也有语法扩展
      • 优点：简便灵活，主题自带功能丰富，插件多
      • 实现逻辑：
        • 一切都在 mkdocs.yml 中进行配置，通过 nav 规定网站导航，从中读取 md 源文件，解析后嵌入主题的 HTML 框架中
      $ pip install mkdocs # 安装
      $ mkdocs new <name>  # 新建
      $ mkdocs serve       # 实时预览
      $ mkdocs build       # 构建
      $ mkdocs gh-deploy   # 部署
      test/
       ├── docs/       # 存放文档源码
       │     └── index.md
       └── mkdocs.yml  # 配置文件

  • hexo

      • 基于 nodejs 的博客站点生成工具
      • 官网 / 文档：hexo.io
      • 有多种渲染器（markdown 解析器）可以选择
      • 优点：插件众多，主题众多，生态良好
      $ npm install -g hexo-cli # 安装
      $ hexo init blog # 初始化
      $ npm install    # 初始化安装
      $ hexo s         # 实时预览
      $ hexo g         # 构建生成
      $ hexo d         # 部署
      ├── _config.yml   # 配置文件
      ├── package.json  # 应用信息
      ├── scaffolds/    # 模板文件夹
      ├── source/       # 源文件夹
      │     └── _posts/   # 稿件文件夹
      └── themes/       # 主题文件夹