MarkdownSyntax - aJiea/OMOOC2py GitHub Wiki

Markdown 简明语法参考

Markdown 概述

博文正文一般使用 Markdown 语法写作. 当然,用 txt 格式也可以,但查看起来会很丑很丑...

Markdown 语法是对纯文本格式的强化,能使文本显示得更清晰,有条理. 但它依旧算是简单的文本,很容易修改和扩展,常用于快速写作之中.

Markdown 格式的简洁特性,兼容性好,使之能快速转换为各种互联网上的常用格式,比如 HTML,Word,PDF 等,所以目前越来越常用.

Markdown 编辑器

常见及常用的 Markdown 编辑器很多,比如:

此外还有(收费为主):

以及支持 Markdown 的优质在线编辑器:

入门编辑器推荐第一序列的 MacDown,其它编辑器可以等熟悉 Markdown 之后再自行探索.

Markdown 语法

关于 Markdown 的基本语法,这里将逐一说明. 对于一些写作中一般不算常用(不好用)的表格及代码展示,不多说明.

基本所有以下涉及的标点都以在英文输入状态下的为准. 不然会导致语法失效.

先看一个包含了蛮多基本语法的范例.

Markdown

关于语法,让我们先从在文中起到分清区块,梳理逻辑关系的标题说起:

各级标题:

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题

显示效果如下:

这是一级标题

俺,二级标题

我是三级标题

人家只是个四级标题...

更小的我,五级标题 XD
Github 支持的最小的可以我(哪里冒出来的)

换行

Markdown 语法下,换行的方式有:

  1. 隔行换行. 连续敲击两下'Return'键,再开始写下一段;
  2. 在行末添加两个空格符,而后'Return'(为了显示清晰),开始写下一段.

强调标记

*斜体* 斜体
_斜体_

**加粗** 加粗
__粗体_

对于强调符号,需要注意的就是,以什么开始,以什么结尾,数量也保持一致,相应的语法才能生效.

显示效果如下:

这是 斜体

这是 强调

分割线

*** 加分割线
* * * 加分割线
***** 或者这样?
--- 还有另外的方式
___ 其实,还可以这样

以下就是一条分割线:

列表

列表分无序列表合有序列表两类,前者以'*','-'开头,后者以数字'1'开头.

三个注意点:

  1. 在输入字符前,应先空一行;
  2. 符号与内容之间,须空一个空格符,列表才能生效;
  3. 第一行内容输入完成,换行会自动补全下一行的开头符号(有序列表数字递增,无序列表符号不变),接下去只需继续输下一行内容,以此类推.

无序列表:

Unordered List:

* English
* Japanese
* Chinese
* ... 

Unordered List:

- English
- Japanese
- Chinese
- ...

显示效果均如下:

Country List:

  • English
  • Japanese
  • Chinese
  • ...

有序列表:

Ordered List:

1. Orange
2. Apple
3. Banana

My Favorite Fruit List:

  1. Orange
  2. Apple
  3. Banana

引言

也即,引用. 使用'>',添加在每行的开头.

两个注意点:

  1. '>'的上一行,必须为空行;
  2. '>'与其后紧跟的第一个字之间有无空格符不影响效果(不过建议加一个).

显示效果如下:

詹姆斯·馬奇"馬奇論管理":

堂吉诃德提醒我们,如果我們只在不被辜負時去信任,只在有所回報時去愛,只在學有所用時去學習,那麼我們就放棄了為人的特征---願意在自我理念的名義下行動,不管結果如何.

或者,你想要引用一首诗,一首歌:

> 五月天"天使"

> 像孩子依赖着肩膀 
> 像眼泪依赖着脸庞 
> 你就像天使一样 
> 给我依赖 给我力量

这儿也需要注意换行:每一行最后换行,添加两个空格符,不然内容会挤压在一块,变成一行. 或者行与行之间,空一行. 以下例子中,歌词部分输入时虽然都分列开,而实际显示时歌词都连成一句了.

五月天"天使"

像孩子依赖着肩膀 像眼泪依赖着脸庞 你就像天使一样 给我依赖 给我力量

每句歌词的行尾空两格之后,效果是这样的:

五月天"天使"

像孩子依赖着肩膀
像眼泪依赖着脸庞
你就像天使一样
给我依赖 给我力量

如果是想嵌套引用,像这样:

浙江

杭州

西湖

湖心亭

博客默认的 Markdown 工具有点问题,效果如下图:

嵌套引用

语法如下,每行多添加一个'>'符号,再输入文字内容即可(每行行尾记得添两个空格符):

> 浙江
>> 杭州
>>> 西湖
>>>> 湖心亭

代码区

也就是 Blockquotes.

如果行尾不空格呢有没其它解决方法呢?如果是这样---

风吹柳絮

"麦兜当当伴我心"插曲

风吹柳絮 茫茫难聚  
随着风吹 飘来飘去  
我若能够携你随风去  

我愿像一块扣肉  
我愿像一块扣肉  
我愿像一块扣肉  
扣住你梅菜扣住你手  

我愿像一块扣肉  
我愿像一块扣肉  
我是你一块扣肉  
你是那梅菜扣住你手

这里的方法是首行开头缩进四个空格符,或敲一下 tab 键(制表符键).

还有一个方法. 连续三个反引号'`'组成的前后两行,将内容包裹起来.

显示效果如下:

这又是一个代码区块

在代码区块中,Markdown 语法一般都不会被转换,这也是为什么前面的很多例子都是先用代码区展示的缘故. 不然这样一篇以 Markdown 语法解释 Markdown 语法的说明也无从谈起了.

嗯...嗯?

反引号的输入:英文输入模式下,点击键盘左上角的'~'键.

标记

标记小段代码(文字)

显示效果如下:

  1. Use the printf() function.
  2. 这是加深背景色框的字符.

这个例子中,为着重强调的代码段(或文字)添加了深色背景框. 方法是用前后各一个反引号'`'将代码段或文字夹在中间.

网址链接

[Link Name](Link)

这是网址链接的基本格式.

  • 一个方括号,添加图片的描述文字
  • 一个括号,添加图片网址

以下为一个在 md 中添加网址的栗子:

[Welcome to my blog](http://azeril.me)

显示效果如下:

Welcome to my blog

第二个方式,利用脚注,将具体链接附加在脚注中,并用脚注将文字段落和网址联结起来.

[Click Google Search][Tags]

[Tags]: http://www.google.com "Google"

显示效果如下:

Click Google Search

或者,也可以使用'<','>'这样的尖角符号来将一些短链接用 Markdown 语法实现类似的可点击链接效果.

<http://www.google.com>

显示效果如下:

http://www.google.com

添加图片

插入图片的语法:

![Pic name](Pic link)  
![Instagram Pic](http://i.imgur.com/UKhrRrK.jpg)
  • 一个英文输入下的惊叹号'!';
  • 一个方括号,添加图片的描述文字;
  • 一个括号,添加图片网址.

相比插入网址链接,多了一个开头的惊叹号.

显示效果如下:

Instagram Pic

添加图片(进阶版)

Pic_Sample

想要在页面中并排插入多张图片(两张或三张并排显示)或想要将插入的图片居中显示,或者是类似固定显示图片的宽度与高度,目前依靠 Markdown 语法还无法实现. 这时,借助 HTML 语言就可以搞定.

以下,可以仅看添加图床图片的,减少认知负荷.

图片与图床

图床是第三方服务托管个人上传图片,并提供图片外链,让我们在写博客文章时使用的方式.

常用图床:

图床在上传图片后会提供一个图片的外链. 我们可以利用外链把图片添加到自己的博文中. 图片也可以存储在 Github 自己的博客项目里,不过图片蛮占用空间(Github 项目空间为200 M). 因而最好是选图床托管图片.

如果是单纯插入来自图床的图片外链:

单张居中显示:

<center>
<img src="http://dreamofbook.qiniudn.com/Zero.png">

OR

<figure>
    <img src="http://xxx.jpg">
</figure>

效果如下:

两张并排显示:

<figure class="half">
    <img src="http://xxx.jpg">
    <img src="http://yyy.jpg">
</figure>

三张并排显示:

<figure class="third">
    <img src="http://xxx.jpg">
    <img src="http://yyy.jpg">
    <img src="http://zzz.jpg">
</figure>

使用时复制相应的代码粘贴,然后替换 ""(英文输入下的引号) 里的链接,也就是例子中的'http://xxx.jpg'链接为自己上传图片(一般只有在图床上传的图才有这样的链接)的外链.

Tips: 关于 jpg/png 都是常用文件格式,jpg 格式压缩效率高,相对文件质量小一点,占用网络空间少,在页面里显示时加载会快一些. png 格式的图片更清晰.

添加 Github 图片

如果是利用在 Github 项目文件夹里的图片,基本的语法不变,只是将前面提到 "" 里的图片外链(网址)替换为:

'自定义的域名 + 图片在 Github 项目的位置'

{{ site.url }}/images/xxx.jpg

引用的代码自动变形了. 博文中两个花括号及'site.url'构成的代码块会自动补全为我的个人域名,所以这篇博文代码区中的演示也受到了影响(上一段的引用就受到影响了. 后边的文中引用的例子也一样). 如果复制了刚才的代码块,需要将' azeril.me//'修改成下图中的样子(两个花括号,中间加 site.url ). 即:

code

使用时复制和修改相应的代码,并替换'/images/xxx.jpg'这样的链接为自己放置图片的路径.

如果 Github 项目下有 images 文件夹,直接在里面放图,就是如上的代码替换. 如果是 images 目录下的文件夹,如 Instagram,则路径为:'images/Instagram/ xxx.jpg'. 依此类推.

附加浏览窗口的模式

更复杂一点,点击图片可以跳出一个预览窗口,可以看大图和切换图片.

效果如下:

PreviewPic

两张并排显示的代码(单张和三张代码和前述的类似):

<figure class="half">
    <a href="{{ site.url }}/images/xxx.jpg"><img src="{{ site.url }}/images/ xxx.jpg"></a>
    <a href="{{ site.url }}/images/yyy.jpg"><img src="{{ site.url }}/images/ yyy.jpg"></a>
</figure>

添加图片代码分享

因博客显示时引用的部分 HTML 代码有问题,所以另外发一份 md 版本的文档供参考.

下载地址:

百度云 - Dl from BaiduYun
box.com - Dl from Box.com
dropbox - Dl from Dropbox

愉快.

Markdown 语法扩展阅读

  1. 献给写作者的 Markdown 新手指南_简书
  2. Markdown 语法说明_WowUbuntu
  3. Markdown语法说明(详解版)_图灵社区
  4. Mastering Markdown · GitHub Guides

公约索引

好书:: Remote^...

GitHub:: Desktop/G.F.M.^Markdown Basics^Writing on GitHub^Mastering Markdown

⚠️ **GitHub.com Fallback** ⚠️