Markdown有一个根据项目英文文档翻译的中文文档,但我感觉有些问题:1、有些过于啰嗦的内容 2、并没有给运行前后代码 3、并不是全面(比如表格没有)。我这里重新编写,专门解决上面的问题。另外说明,本文档就是基于Markdown写的。

宗旨

Markdown 的目标是实现「易读易写」。

可读性,无论如何,都是最重要的。一份使用 Markdown 格式撰写的文件应该可以直接以纯文本发布,并且看起来不会像是由许多标签或是格式指令所构成。Markdown 语法受到一些既有 text-to-HTML 格式的影响,包括 Setext、atx、Textile、reStructuredText、Grutatext 和 EtText,而最大灵感来源其实是纯文本电子邮件的格式。

兼容 HTML

Markdown 语法的目标是:成为一种适用于网络的书写语言。

Markdown 不是想要取代 HTML,甚至也没有要和它相近,它的语法种类很少,只对应 HTML 标记的一小部分。Markdown 的构想不是要使得 HTML 文档更容易书写。在我看来, HTML 已经很容易写了。Markdown 的理念是,能让文档更容易读、写和随意改。HTML 是一种发布的格式,Markdown 是一种书写的格式。就这样,Markdown 的格式语法只涵盖纯文本可以涵盖的范围。

不在 Markdown 涵盖范围之内的标签,都可以直接在文档里面用 HTML 撰写。不需要额外标注这是 HTML 或是 Markdown;只要直接加标签就可以了。

要制约的只有一些 HTML 区块元素――比如 <div>、<table>、<pre>、<p> 等标签,必须在前后加上空行与其它内容区隔开,还要求它们的开始标签与结尾标签不能用制表符或空格来缩进。Markdown 的生成器有足够智能,不会在 HTML 区块标签外加上不必要的

标签。

例子如下,在 Markdown 文件里加上一段 HTML 表格:

这是一个普通段落。

<table>
<tr>
<td>Foo</td>
</tr>
</table>

这是另一个普通段落。
请注意,在 HTML 区块标签间的 Markdown 格式语法将不会被处理。比如,你在 HTML 区块内使用 Markdown 样式的*强调*会没有效果。

HTML 的区段(行内)标签如 <span>、<cite>、<del> 可以在 Markdown 的段落、列表或是标题里随意使用。依照个人习惯,甚至可以不用 Markdown 格式,而直接采用 HTML 标签来格式化。举例说明:如果比较喜欢 HTML 的 <a> 或 <img> 标签,可以直接使用这些标签,而不用 Markdown 提供的链接或是图像标签语法。

和处在 HTML 区块标签间不同,Markdown 语法在 HTML 区段标签间是有效的。

特殊字符自动转换
在 HTML 文件中,有两个字符需要特殊处理: < 和& 。 < 符号用于起始标签,& 符号则用于标记 HTML 实体,如果你只是想要显示这些字符的原型,你必须要使用实体的形式,像是 &lt; 和 &amp;。
& 字符尤其让网络文档编写者受折磨,如果你要打「AT&T」 ,你必须要写成「AT&amp;T」。

不过需要注意的是,code 范围内,不论是行内还是区块, < 和& 两个符号都一定会被转换成 HTML 实体,这项特性让你可以很容易地用 Markdown 写 HTML code (和 HTML 相对而言, HTML 语法中,你要把所有的 < 和 & 都转换为 HTML 实体,才能在 HTML 文件里面写出 HTML code。)

也可以用实体编号,我们只是想显示<HTML>这个内容,但是如果直接写就会被转换而看不见。

所以,写的形式应该为:

&#60;HTML&#62;

常用转义字符表:

显示结果 描述 实体名称 实体编号
  空格 &nbsp; &#160;
< 小于号 &lt; &#60;
> 大于号 &gt; &#62;
& 与号 &amp; &#38;
" 引号 &quot; &#34;
' 撇号 &apos; &#39;
¥ 元(yen &yen; &#165;
© 版权copyright &copy; &#169;
® 注册商标 &reg; &#174;
商标 &trade; &#8482;
× 乘号 &times; &#215;
÷ 除号 &divide; &#247;

原官方文档写这段太啰嗦,我简化,并补上上面的表格

表格

前面的 《常用转义字符表》代码如下:

显示结果|描述|实体名称|实体编号
:---:|:---:|:---:|:---
&nbsp;|空格|&amp;nbsp;|&amp;#160;
&lt;|小于号|&amp;lt;|&amp;#60;
&gt;|大于号|&amp;gt;|&amp;#62;
&amp;|与号|&amp;amp;|&amp;#38;
&quot;|引号|&amp;quot;|&amp;#34;
&apos;|撇号|&amp;apos;|&amp;#39;
&yen;|元(yen|&amp;yen;|&amp;#165;
&copy;|版权copyright|&amp;copy;|&amp;#169;
&reg;|注册商标|&amp;reg;|&amp;#174;
&trade;|商标|&amp;trade;|&amp;#8482;
&times;|乘号|&amp;times;|&amp;#215;
&divide;|除号|&amp;divide;|&amp;#247;

注:同时 :---代表左对齐,---:代表右对齐,:---:代表居中对齐,-数目至少一个,:没有默认左对齐,第二行必须有,否则不是表格形式。以上格式代表是三行三列的表格。
上面因为要在这些显示,所以用了很多符号,如果难理解,可以简单归为如下:

|文字|文字|文字|

|:-----|-----:|:-----:|

|文字|文字|文字|

|文字|文字|文字|

区块元素

段落和换行

一个 Markdown 段落,前后要有一个以上的空行(空行的定义是显示上看起来像是空的,便会被视为空行。比方说,若某一行只包含空格和制表符,则该行也会被视为空行)。普通段落不该用空格或制表符来缩进。

Markdown 允许段落内的强迫换行(插入换行符),这个特性和其他大部分的 text-to-HTML 格式不一样,其它的格式会把每个换行符都转成 <br /> 标签。

如果你确实想要依赖 Markdown 来插入 <br /> 标签的话,在插入处先按入两个以上的空格然后回车。

的确,需要多费点事(多加空格)来产生<br /> ,但是简单地「每个换行都转换为<br />」的方法在 Markdown 中并不适合, Markdown 中 email 式的 区块引用 和多段落的 列表 在使用换行来排版的时候,不但更好用,还更方便阅读。

字体

加粗:要加粗的文字左右分别用两个*号包起来

斜体:要倾斜的文字左右分别用一个*号包起来

斜体加粗:要倾斜和加粗的文字左右分别用三个*号包起来

删除线:要加删除线的文字左右分别用两个~号包起来
示例:
**这是加粗的文字**
*这是倾斜的文字*
***这是斜体加粗的文字***
~~这是加删除线的文字~~

效果如下:
这是加粗的文字
这是倾斜的文字
这是斜体加粗的文字
这是加删除线的文字

标题

Markdown 支持两种标题的语法,类 Setext 和类 atx 形式。

1、类 Setext 形式是用底线的形式,利用 = (最高阶标题)和 - (第二阶标题),例如:
This is an H1
===========
This is an H2
----------------
任何数量的 = 和 - 都可以有效果。显示效果如下:

This is an H1

This is an H2

2、类 Atx 形式则是在行首插入 1 到 6 个 # ,对应到标题 1 到 6 阶,例如:

# 这是 H1

## 这是 H2

###### 这是 H6
显示效果如下:

这是 H1

这是 H2

这是 H6

为了美观,你就可以在行尾加上 #,而行尾的 # 数量也不用和开头一样(行首的井字符数量决定标题的阶数):

# 这是 H1 #

## 这是 H2 ##

### 这是 H3 ######

显示效果如下:

这是 H1

这是 H2

这是 H3

区块引用

在每行的最前面加上或整个段落的第一行最前面加上> :

> 每个人都会经历这样一个阶段,见到一座山,就想知道山后面是什么。我很想告诉他,可能翻过去,你会发觉没什么特别,再翻过来,可能会觉得这边会更好,但我知道他不会听,以他的性格,自己不走一走,又怎么会甘心呢。

显示效果如下:

每个人都会经历这样一个阶段,见到一座山,就想知道山后面是什么。我很想告诉他,可能翻过去,你会发觉没什么特别,再翻过来,可能会觉得这边会更好,但我知道他不会听,以他的性格,自己不走一走,又怎么会甘心呢。

引用也可以嵌套:

>这是第一个引用.
>> 在引用里面的引用.
>>> 第三个引用.
显示效果如下:

这是第一个引用.

在引用里面的引用.

第三个引用.

引用的区块内也可以使用其他的 Markdown 语法,包括标题、列表、代码区块等:

> ## 这是一个标题。
>
> 1. 这是第一行列表项。
> 2. 这是第二行列表项。
>
> 给出一些例子代码:
>
> return shell_exec("echo $input | $markdown_script");

显示效果如下

这是一个标题。

  1. 这是第一行列表项。
  2. 这是第二行列表项。

给出一些例子代码:

return shell_exec("echo $input | $markdown_script");

列表

Markdown 支持有序列表和无序列表。

1、无序列表使用星号、加号或是减号作为列表标记都可以,一般为使用相同符号:

* Red
+ Green
- Blue
显示效果如下:

  • Red
  • Green
  • Blue

2、有序列表则使用数字接着一个英文句点:

1. Bird
2. McHale
3. Parish
显示效果如下:

  1. Bird
  2. McHale
  3. Parish

很重要的一点是,你在列表标记上使用的数字并不会影响输出的 HTML 结果,上面的列表所产生的 HTML 标记为:
<ol>
<li>Bird</li>
<li>McHale</li>
<li>Parish</li>
</ol>

如果你的列表标记写成:

1. Bird
1. McHale
1. Parish

输出结果

  1. Bird
  2. McHale
  3. Parish

两个输出相同,你可以完全不用在意数字的正确性。

要让列表看起来更漂亮,你可以把内容用固定的缩进整理好:

日照香炉生紫烟,李白来到烤鸭店。口水直流三千尺,一摸口袋没带钱。
李白乘舟不给钱,船夫一脚踢下船。桃花滩水深千尺,不知李白死没死。

但是如果你懒,那也行,在前面加*:

* 北冥有鱼,其名为鲲。鲲之大,不知其几千里也;化而为鸟,其名为鹏。鹏之背,不知其几千里也;怒而飞,其翼若垂天之云。
* 先帝创业未半而中道崩殂,今天下三分,益州疲弊,此诚危急存亡之秋也。然侍卫之臣不懈于内,忠志之士忘身于外者,盖追先帝之殊遇,欲报之于陛下也。

显示为:

  • 北冥有鱼,其名为鲲。鲲之大,不知其几千里也;化而为鸟,其名为鹏。鹏之背,不知其几千里也;怒而飞,其翼若垂天之云。
  • 先帝创业未半而中道崩殂,今天下三分,益州疲弊,此诚危急存亡之秋也。然侍卫之臣不懈于内,忠志之士忘身于外者,盖追先帝之殊遇,欲报之于陛下也。

代码区块

1、Markdown 会用<pre>和 <code> 标签来把代码区块包起来。

2、缩进 4 个空格或是 1 个制表符就可以,例如,下面的输入:
    System.out.println("Hello World!");

Markdown 会转换成:

System.out.println("Hello World!");

这个每行一阶的缩进(4 个空格或是 1 个制表符),都会被移除,,并且会一直持续到没有缩进的那一行(或是文件结尾)。例如:

Here is an example of AppleScript:

    tell application "Foo"
      beep
    end tell
会被转换为:

Here is an example of AppleScript:

tell application "Foo"
    beep
end tell

3、使用三个反引号代码区
三个反引号要单独一行,前后都加。(因为本编译器不好对三个反引号转义,你们明白自己测试时,加上就得)
public void run() {
try {
for (;;) {
System.out.print(word + " ");
sleep(delay); // wait until next time
}
} catch (InterruptedException e) {
return; // end this thread
}
}

加后效果如下:

public void run() {
    try {
        for (;;) {
            System.out.print(word + &quot; &quot;);
            sleep(delay);   // wait until next time
        }
    } catch (InterruptedException e) {
        return;             // end this thread
    }
}

注:为了防止转译,前后三个反引号处加了小括号,实际是没有的。这里只是用来演示,实际中去掉两边小括号即可。

分隔线

你可以在一行中用三个以上的星号、减号、底线来建立一个分隔线,行内不能有其他东西。你也可以在星号或是减号中间插入空格。下面每种写法都可以建立分隔线:

* * *

***

*****

- - -

---------------------------------------
显示结果为:






区段元素

链接
Markdown 支持两种形式的链接语法: 行内式和参考式两种形式。不管是哪一种,链接文字都是用 [方括号] 来标记。

1、行内式的链接
只要在方块括号后面紧接着圆括号并插入网址链接即可,如果你还想要加上链接的 title 文字,只要在网址后面,用双引号把 title 文字包起来即可,例如:

This is [an example](http://itmanclub.com/ "高龄IT男养老院") inline link.
效果如下:
This is an example inline link.
2、参考式的链接
链接文字的括号后面再接上另一个方括号,而在第二个方括号里面要填入用以辨识链接的标记:

This is [an example][id] reference-style link.
你也可以选择性地在两个方括号中间加上一个空格:

This is [an example] [id] reference-style link.
接着,在文件的任意处,你可以把这个标记的链接内容定义出来:

[id]: http://itmanclub.com/ "桂林山水甲天下"
链接内容定义的形式为:

方括号(前面可以选择性地加上至多三个空格来缩进),里面输入链接文字
接着一个冒号
接着一个以上的空格或制表符
接着链接的网址
选择性地接着 title 内容,可以用单引号、双引号或是括弧包着

强调

Markdown 使用星号()和底线(_)作为标记强调字词的符号,被 包围的字词会被转成用 <em> 标签包围,用两个 * 或 包起来的话,则会被转成 <strong>,例如:

*single asterisks*

_single underscores_

**double asterisks**

__double underscores__
显示效果为:

single asterisks

single underscores

double asterisks

double underscores

你可以随便用你喜欢的样式,唯一的限制是,你用什么符号开启标签,就要用什么符号结束。

强调也可以直接插在文字中间:

unfriggingbelievable
但是如果你的 * 和 _ 两边都有空白的话,它们就只会被当成普通的符号。

如果要在文字前后直接插入普通的星号或底线,你可以用反斜线:

*this text is surrounded by literal asterisks*
代码
如果要标记一小段行内代码,你可以用反引号把它包起来(`),例如:

Use the ` printf()` function.
显示结果:

Use the printf() function.


如果要在代码区段内插入反引号,你可以用多个反引号来开启和结束代码区段:

``There is a literal backtick (`) here.``
显示结果:

There is a literal backtick (`) here.

图片

Markdown 使用一种和链接很相似的语法来标记图片,同样也允许两种样式: 行内式和参考式。

1、行内式的图片语法:

![Alt text](/path/to/img.jpg)

![Alt text](/path/to/img.jpg "野外白虎无MA")
详细叙述如下:

一个惊叹号 !
接着一个方括号,里面放上图片的替代文字,接着一个普通括号,里面放上图片的网址,最后还可以用引号包住并加上 选择性的 'title' 文字。

2、参考式的图片语法:

![Alt text][id]
「id」是图片参考的名称,图片参考的定义方式则和连结参考一样:

[id]: /path/to/img.jpg "你想多了"
到目前为止, Markdown 还没有办法指定图片的宽高,如果你需要的话,你可以使用普通的 <img> 标签。

其它

反斜杠

Markdown 可以利用反斜杠来插入一些在语法中有其它意义的符号,例如:如果你想要用星号加在文字旁边的方式来做出强调效果(但不用 <em> 标签),你可以在星号的前面加上反斜杠:

\*literal asterisks\*
效果如下:
*literal asterisks*
Markdown 支持以下这些符号前面加上反斜杠来帮助插入普通的符号:

\ 反斜线
` 反引号
* 星号
_ 底线
{} 花括号
[] 方括号
() 括弧
# 井字号
+ 加号
- 减号
. 英文句点
! 惊叹号

自动链接

Markdown 支持以比较简短的自动链接形式来处理网址和电子邮件信箱,只要是用方括号包起来, Markdown 就会自动把它转成链接。一般网址的链接文字就和链接地址一样,例如:

<http://example.com/>
Markdown 会转为:

<a href="http://example.com/">http://example.com/</a>
邮址的自动链接也很类似,只是 Markdown 会先做一个编码转换的过程,把文字字符转成 16 进位码的 HTML 实体,这样的格式可以糊弄一些不好的邮址收集机器人,例如:

<address@example.com>
Markdown 会转成:

<a href="mailto:addre
ss@example.co
m">address@exa
mple.com</a>

在浏览器里面,这段字串(其实是 address@example.com)会变成一个可以点击的「address@example.com」链接。

(这种作法虽然可以糊弄不少的机器人,但并不能全部挡下来,不过总比什么都不做好些。不管怎样,公开你的信箱终究会引来广告信件的。)

Markdown 免费编辑器

Windows 平台

MarkdownPad
MarkPad

Linux 平台

ReText

Mac 平台

Mou

在线编辑器

Markable.in
Dillinger.io

浏览器插件

MaDe (Chrome)
Sublime Text 2
MarkdownEditing
教程