首页
学习
活动
专区
圈层
工具
发布
首页
学习
活动
专区
圈层
工具
MCP广场
社区首页 >专栏 >一份简明的 Markdown 笔记与教程

一份简明的 Markdown 笔记与教程

作者头像
mzlogin
发布于 2020-04-16 10:20:40
发布于 2020-04-16 10:20:40
1.1K00
代码可运行
举报
文章被收录于专栏:闷骚的程序员闷骚的程序员
运行总次数:0
代码可运行

为部门内知识分享准备的素材,记录了 Markdown 的优点、应用场景和编辑工具,介绍了标准语法与扩展语法,以及一些应用 Markdown 的奇技淫巧。个人使用 Markdown 的经验持续补充中,最新完整版请参见

https://github.com/mzlogin/markdown-intro


自从 2014 年左右接触到 Markdown 以来,对它的使用就一发而不可收拾。从最开始使用它在 GitHub Pages 里写博客,到用它编辑项目的 README 文件,再到撰写开发文档,编辑微信公众号文章和邮件内容等等,这期间也见证了它在各类平台和网站上的普及和被原生支持,可以说,Markdown 如今已经渗透了我在技术和网络活动的方方面面,成为了我撰写文本文档的首选。

那么首先我们一起来看一下它的「定义」:

Markdown 是一种轻量级标记语言,创始人为 John Gruber。它允许人们「使用易读易写的纯文本格式编写文档,然后转换成有效的 XHTML(或者 HTML)文档」。——维基百科

本文档的目的不在于面面俱到地介绍 Markdown,只是作为我对其理解的笔记整理,希望能同时帮助一些对 Markdown 感兴趣的人快速上手,或是作为一个工具,供对其已经有所了解的人在需要时参考。

接下来请随我一起深入了解这门并不神秘的实用标记语言。

目录

背景

优点

  1. 专注于文字内容;
  2. 纯文本,易读易写,可以方便地纳入版本控制;
  3. 语法简单,没有什么学习成本,能轻松在码字的同时做出美观大方的排版。

使用场景

  • 各类代码托管平台 主流的代码托管平台,如 GitHub、GitLab、BitBucket、Coding、Gitee 等等,都支持 Markdown 语法,很多开源项目的 README、开发文档、帮助文档、Wiki 等都用 Markdown 写作。
  • 技术社区和写作平台 StackOverflow、CSDN、掘金、简书、GitBook、有道云笔记
  • 论坛 V2EX、光谷社区

个人感觉比较遗憾的一点是各平台可能采用不同语言实现的 Markdown 解析引擎,或采用同一解析引擎的不同版本,而且可能有不同程度的定制与扩展,这导致在不同平台上使用 Markdown 写作时体验并不完全一致。不过幸好对于大家公认的一些标准语法,各家都是支持的。

编辑工具

理论上任何一款文本编辑器都能用于编辑 Markdown 文档,它们分别提供了不同程度的语法高亮、预览等功能,以下只是列举其中一部分,选择自己称手的即可。

  • 现代编辑器 VSCode / Atom
  • 传统编辑器 Vim / Emacs / Sublime Text / Notepad++
  • IDE 自带编辑器 IntelliJ IDEA / Android Studio / WebStorm
  • 专用编辑器 Ulysses / Mou / Typora / Markpad
  • 在线编辑器 各种支持 Markdown 的网站都提供了在线编辑器

语法

标题

Markdown:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
# atx-style 一级标题

## 二级标题

###### 六级标题

Setext-style 一级标题
===

二级标题
---

预览效果:

atx-style 一级标题 二级标题 六级标题 Setext-style 一级标题 二级标题

对应 HTML:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
<h1>atx-style 一级标题</h1>

<h2>二级标题</h2>

<h6>六级标题</h6>

<h1>Setext-style 一级标题</h1>

<h2>二级标题</h2>

段落

中间没有空行的连续不断的几行文字被视为一个段落。

Markdown:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
白日依山尽,

黄河入海流。
(句号后面没空格)

欲穷千里目,

更上一层楼。  
(句号后面有俩空格)

预览效果:

白日依山尽,

黄河入海流。 (句号后面没空格)

欲穷千里目,

更上一层楼。

(句号后面有俩空格)

对应 HTML:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
<p>白日依山尽,</p>

<p>黄河入海流。
(句号后面没有空格)</p>

<p>欲穷千里目,</p>

<p>
  更上一层楼。
  <br>
  (句号后面有俩空格)
</p>

行内格式

对段落或者部分文本的强调效果。

Markdown:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
后面俩字**加黑**

后面俩字*斜体*

预览效果:

后面俩字加黑

后面俩字斜体

对应 HTML:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
<p>
  后面俩字
  <strong>加黑</strong>
</p>
<p>
  后面俩字
  <em>斜体</em>
</p>

引用块

Markdown:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
> 引用块段落一。
>
> 引用块段落二。
>> 内嵌引用块段落一。
>
> ### 引用块内的标题

预览效果:

引用块段落一。 引用块段落二。 内嵌引用块段落一。 引用块内的标题

对应 HTML:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
<blockquote>
  <p>引用块段落一。</p>
  <p>引用块段落二。</p>
  <blockquote>
    <p>内嵌引用块段落一。</p>
  </blockquote>
  <h3 id="引用块内的标题">引用块内的标题</h3>
</blockquote>

超链接

Markdown 支持行内式链接和引用式链接。

Markdown:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
行内式 [博客](https://mazhuang.org "我的个人博客") 链接,带 title。

行内式 [GitHub](https://github.com/mzlogin) 链接。

引用式 [博客][1] 链接。

引用式 [GitHub][2] 链接,带 title。

[1]: https://mazhuang.org
[2]: https://github.com/mzlogin "我的 GitHub 主页"

预览效果:

行内式 博客 链接,带 title。

行内式 GitHub 链接。

引用式 博客 链接。

引用式 GitHub 链接,带 title。

对应 HTML:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
<p>行内式 <a href="https://mazhuang.org" title="我的个人博客">博客</a> 链接,带 title。</p>

<p>行内式 <a href="https://github.com/mzlogin">GitHub</a> 链接。</p>

<p>引用式 <a href="https://mazhuang.org">博客</a> 链接。</p>

<p>引用式 <a href="https://github.com/mzlogin" title="我的 GitHub 主页">GitHub</a> 链接,带 title。</p>

图片

在超链接的写法前加一个 !,就是引用图片的方法。

Markdown:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
![Alt text](https://mazhuang.org/favicon.ico "favicon")

预览效果:

对应 HTML:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
<img src="https://mazhuang.org/favicon.ico" alt="Alt text" title="favicon">

列表

包括有序列表和无序列表。

Markdown:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
- 苹果
- 葡萄
- 榴莲

1. 苹果
2. 葡萄
3. 榴莲

预览效果:

  • 苹果
  • 葡萄
  • 榴莲
  • 苹果
  • 葡萄
  • 榴莲

对应 HTML:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
<ul>
  <li>苹果</li>
  <li>葡萄</li>
  <li>榴莲</li>
</ul>
<ol>
  <li>苹果</li>
  <li>葡萄</li>
  <li>榴莲</li>
</ol>

其中无序列表的标记可以使用 +-*,有序列表前的数字可以是乱序的。

代码块

支持行内代码和代码块。

Markdown:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
Android 里使用 `TextUtils` 类的 `isEmpty` 方法来判断字符串是否为空。

```java

if (TextUtils.isEmpty(text)) {

代码语言:txt
AI代码解释
复制
return null;

}

代码语言:txt
复制

预览效果:

Android 里使用 TextUtils 类的 isEmpty 方法来判断字符串是否为空。

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
if (TextUtils.isEmpty(text)) {
    return null;
}

对应 HTML:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
<p>Android 里使用 <code>TextUtils</code> 类的 <code>isEmpty</code> 方法来判断字符串是否为空。</p>

<div class="highlight highlight-source-java"><pre><span class="pl-k">if</span> (<span class="pl-smi">TextUtils</span><span class="pl-k">.</span>isEmpty(text)) {
    <span class="pl-k">return</span> <span class="pl-c1">null</span>;
}</pre></div>

上例中的语言标记 java 可选填,可用于在编辑器和渲染后的效果里添加语法高亮。

块式代码也可以对整个代码段缩进四个空格,或一个 Tab 来实现。

水平分割线

使用一个单独行里的三个或以上 *- 来生产一条水平分割线,它们之间可以有空格。

Markdown:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
***

-----

- - -

预览效果:




对应 HTML:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
<hr />

<hr />

<hr />

嵌入 HTML

Markdown 标记语言的目的不是替代 HTML,也不是发明一种更便捷的插入 HTML 标签的方式。它对应的只是 HTML 标签的一个很小的子集。

对于那些没有办法用 Markdown 语法来对应的 HTML 标签,直接使用 HTML 来写就好了。

扩展语法

本节的内容是介绍一些受到广泛支持的 Markdown 扩展语法。

表格

Markdown:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
| 编号  | 姓名(左) | 年龄(右) | 性别(中) |
| ----- | :--------  | ---------: | :------:   |
| 0     | 张三       | 28         ||
| 1     | 李四       | 29         ||

预览效果:

编号

姓名(左)

年龄(右)

性别(中)

0

张三

28

1

李四

29

对应 HTML:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
<table>
  <thead>
    <tr>
      <th>编号</th>
      <th align="left">姓名(左)</th>
      <th align="right">年龄(右)</th>
      <th align="center">性别(中)</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>0</td>
      <td align="left">张三</td>
      <td align="right">28</td>
      <td align="center"></td>
    </tr>
    <tr>
      <td>1</td>
      <td align="left">李四</td>
      <td align="right">29</td>
      <td align="center"></td>
    </tr>
  </tbody>
</table>

任务列表

在 GitHub / GitLab 里有较好的支持。

Markdown:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
- [x] 洗碗
- [ ] 清洗油烟机
- [ ] 拖地

预览效果:

  • 洗碗
  • 清洗油烟机
  • 拖地

对应 HTML:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
<ul class="contains-task-list">
  <li class="task-list-item"><input type="checkbox" id="" disabled="" class="task-list-item-checkbox" checked=""> 洗碗</li>
  <li class="task-list-item"><input type="checkbox" id="" disabled="" class="task-list-item-checkbox"> 清洗油烟机</li>
  <li class="task-list-item"><input type="checkbox" id="" disabled="" class="task-list-item-checkbox"> 拖地</li>
</ul>

如果是在 GitHub / GitLab 的 Issue 里,会附赠任务完成比例提示效果:

还可以直接在网页上拖动调整顺序,勾选和取消勾选。

删除线

Markdown:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
后面三个字打上~~删除线~~

预览效果:

后面三个字打上删除线

对应 HTML:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
<p>后面三个字打上<del>删除线</del></p>

自动链接

自动链接扩展,即:当识别到 URL,或用 <> 包括的 URL 时,会自动为其生成 a 标签。

Markdown:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
https://github.com

<example@gmail.com>

预览效果:

https://github.com

example@gmail.com

对应 HTML:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
<p><a href="https://github.com">https://github.com</a></p>

<p><a href="mailto:example@gmail.com">example@gmail.com</a></p>

emoji

以 GitHub Pages 为例。

Markdown:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
:camel: :blush: :smile:

预览效果:

对应 HTML:

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
<p>
  <img class="emoji" title=":camel:" alt=":camel:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f42b.png" height="20" width="20">
  <img class="emoji" title=":blush:" alt=":blush:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f60a.png" height="20" width="20">
  <img class="emoji" title=":smile:" alt=":smile:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f604.png" height="20" width="20">
</p>

奇技淫巧

脑洞清奇的工程师们还发掘了很多使用 Markdown 的方法,大部分都是引入第三方 JavaScript 插件来实现。对这部分我只做简述,对其中的部分功能比如作图等,还是推荐用专门的可视化工具去做。

画流程图和时序图

有部分网站和编辑器实现了对 Markdown 里流程图和时序图的支持,比如我们使用的项目管理工具 TAPD 的在线编辑器,还有 VSCode + 插件 Markdown Preview Enhanced 等。

以我们使用的项目管理工具 TAPD 的在线编辑器为例:

插入数学公式

仍然以 TAPD 为例:

应该是利用 JavaScript 支持了 LaTeX 公式语法。

用 Markdown 做 PPT

有专门的工具 Marp,另外使用 VSCode + 插件 Markdown Preview Enhanced 也可以实现。

用 Markdown 写微信公众号

可以将公众号素材用 Markdown 编辑好后,贴到在线排版工具以后,复制到公众号编辑器里即可。有多种页面主题和代码主题可选择。

我维护的工具地址:https://md.mazhuang.org

更多

想象力丰富的工程师们还扩展了很多基于 Markdown 的玩法,包括但不限于:

  • 自动生成 / 更新 Table of Contents
  • 流程图 / 时序图
  • 制作幻灯片
  • 集成 PlantUML / GraphViz 的能力
  • 导出 HTML / PDF / 电子书

以上功能基本都可以用 VSCode + 插件 Markdown Preview Enhanced 实现。

另外可以参考我以前的一篇博客 关于 Markdown 的一些奇技淫巧

参考

----欢迎关注我的微信公众号,接收 markdown-intro 最新动态。

本文参与 腾讯云自媒体同步曝光计划,分享自作者个人站点/博客。
原始发表:2018/09/06,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 作者个人站点/博客 前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体同步曝光计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
暂无评论
推荐阅读
编辑精选文章
换一批
Markdown使用教程
Markdown 是一种轻量级标记语言,它允许人们使用易读易写的纯文本格式编写文档。
张小驰出没
2021/12/06
6.6K0
Markdown使用教程
Markdown高级教程
作为程序员,如果你不清楚 Markdown 估计没人敢相信,毫不夸张地说,Markdown 是目前世界上最受欢迎的标记语言之一,所以今天我就带领大家初步了解一下 Markdown 的魅力,带你快速上手 Markdown
小城故事
2022/11/30
1.9K0
Markdown高级教程
Markdown 语法笔记
Markdown 是一种轻量级的标记语言,可用于在纯文本文档中添加格式化元素。Markdown 由 John Gruber 于 2004 年创建。它使用易读易写的纯文本格式编写文档,可与HTML混编,可导出 HTML、PDF 以及本身的 .md 格式的文件。因简洁、高效、易读、易写,Markdown被大量使用。
h-t-m
2022/11/24
4.5K0
Markdown 语法笔记
微信公众号 Markdown 编辑器
微信公众号文章 Markdown 在线编辑器,使用 markdown 语法创建一篇简介美观大方的微信公众号图文。由于发版本麻烦,和一些功能无法扩展停滞开发了,未来不再开发 Chrome 的工具(暂存在 chrome 分支),通过 web 版本定制更丰富的功能。 Github:https://github.com/jaywcjlove/wxmp 编辑器:https://jaywcjlove.github.io/wxmp
小弟调调
2022/11/08
1.3K0
微信公众号 Markdown 编辑器
Markdown基础教程
Markdown 换行挺讲究,会发现在编写的时候直接回车换行发现不生效,那怎么办呢?
小城故事
2022/11/30
6.5K0
Markdown语法图文全面详解(10分钟学会)
博客:https://www.jianshu.com/u/f408bdadacce
陈宇明
2020/12/15
22.7K1
Markdown语法图文全面详解(10分钟学会)
十五分钟让你快速学习Markdown语法到精通排版实践
描述: Markdown 是一种轻量级标记语言于2004年推出,创始人为约翰·格鲁伯(John Gruber)。 它允许人们使用易读易写的纯文本格式编写文档,然后转换成有效的 XHTML(或者HTML)文档。
全栈工程师修炼指南
2022/09/29
2.7K0
文字编码 - Markdown 简明教程
语法:* 内容*或_内容_标记为倾斜; ** 内容** 或__内容__标记为加粗;*** 内容** 或___内容___标记为加粗倾斜。
为为为什么
2022/08/04
4.4K0
文字编码 - Markdown 简明教程
Markdown
alt 和 title 即对应 HTML 中 img 元素的 alt 和 title 属性(都可省略):
硬件开源小站
2023/04/07
7640
Typora Markdown 语法
当前许多网站都广泛使用 Markdown 来撰写帮助文档或是用于论坛上发表消息。例如:GitHub、简书、reddit、Diaspora、Stack Exchange、OpenStreetMap 、SourceForge等。
框架师
2021/03/08
2.9K0
Typora Markdown 语法
掌握Markdown技巧,轻松应对写作需求
本文 Markdown 语法使用 VSCode 编辑并使用其插件 Markdown Preview Enhanced 预览。
M.Talen
2024/05/22
2700
掌握Markdown技巧,轻松应对写作需求
Markdown 语法说明(简体中文版)
NOTE: This is Simplelified Chinese Edition Document of Markdown Syntax. If you are seeking for English Edition Document. Please refer to Markdown: Syntax. 声明: 这份文档派生(fork)于繁体中文版,在此基础上进行了繁体转简体工作,并进行了适当的润色。此文档用 Markdown 语法编写,你可以到这里查看它的源文件。「繁体中文版的原始文件可以查看这里
_gongluck
2018/03/08
2.4K0
开发工具总结(5)之Markdown语法图文全面详解及其工具介绍
版权声明:本文为博主原创文章(少量文字参考他人博文,已加上引用说明),未经博主允许不得转载。https://www.jianshu.com/p/c0a2897ad4eb
AWeiLoveAndroid
2018/09/03
2.7K0
开发工具总结(5)之Markdown语法图文全面详解及其工具介绍
Hexo中Markdown语法(GFM)使用
提起Markdown,对我来说是毕设、是项目、是不可多得的助手。 Markdown 是一种轻量级的”标记语言”,优点在于 (1)可以更加专注文章内容而不是排版样式。 (2)轻松的导出 HTML 和本身的 .md 文件。 (3)纯文本内容,兼容所有的文本编辑器与字处理软件。 (4)可读,直观。适合所有人的写作语言。 查资料了解到,Hexo下使用的MarkDown为Github的 GFM ,风格很漂亮,简洁美观大方。但是GFM 的MarkDown语法和标准的MarkDown稍有不同,使用过程中需要注意一些,在下面的介绍中我会进行说明的请放心。
零式的天空
2022/03/27
3K0
Hexo中Markdown语法(GFM)使用
关于 Markdown 的一些奇技淫巧
自从几年前开始在 GitHub 玩耍,接触到 Markdown 之后,就一发不可收拾,在各种文档编辑上,有条件用 Markdown 的尽量用,不能用的创造条件也要用——README、博客、公众号、接口文档等等全都是,比如当前这篇文章就是用 Markdown 编辑而成。
零式的天空
2022/03/28
1.1K0
关于 Markdown 的一些奇技淫巧
Markdown - 让网络书写变得简单
可读性,无论如何,都是最重要的。一份使用 Markdown 格式撰写的文件应该可以直接以纯文本发布,并且看起来不会像是由许多标签或是格式指令所构成。Markdown 语法受到一些既有 text-to-HTML 格式的影响,包括 Setext、atx、Textile、reStructuredText、Grutatext 和 EtText,而最大灵感来源其实是纯文本电子邮件的格式。
laixiangran
2018/07/25
1.4K0
关于 Markdown 的一些奇技淫巧
自从几年前开始在 GitHub 玩耍,接触到 Markdown 之后,就一发不可收拾,在各种文档编辑上,有条件用 Markdown 的尽量用,不能用的创造条件也要用——README、博客、公众号、接口文档等等全都是,比如当前这篇文章就是用 Markdown 编辑而成。
mzlogin
2020/04/16
1.9K0
关于 Markdown 的一些奇技淫巧
Markdown基本语法
参考式超链接一般用在学术论文上面,或者另一种情况,如果某一个链接在文章中多处使用,那么使用引用 的方式创建链接将非常好,它可以让你对链接进行统一的管理。
爱学习的小超人
2022/11/14
2.9K0
Markdown基本语法
MarkDown 常用语法
最为常用的格式,只需要在文本前面加上 # 即可,同理、你还可以增加二级标题、三级标题、四级标题、五级标题和六级标题,总共六级,只需要增加 # 即可,标题字号相应降低
GoodTime
2024/03/05
2820
MarkDown 常用语法
Markdown:解放排版,简洁高效的文字创作神器!
Markdown 是一种轻量级的标记语言,它允许人们使用易读易写的纯文本格式编写文档,借助可实现快速排版且转换成格式丰富的 HTML 页面。目前被越来越多的写作爱好者及工作者使用。它在写作、博客、文档等领域得到了广泛应用,因其简洁、易读、易写的特点而备受欢迎,一旦掌握这种标记语言,将极大提高效率。但是若需要复杂排版如左右对齐缩进等,还是选择 word 等专业软件。
南山竹
2024/06/13
6900
Markdown:解放排版,简洁高效的文字创作神器!
相关推荐
Markdown使用教程
更多 >
交个朋友
加入云开发企业交流群
企业云开发实战交流 探讨技术架构优化
领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档