Markdown介绍,语法及与wordpress的集成

花了一天时间研究了一下Markdown。Markdown让书写html变得更加容易,更加易于阅读,语法也很简单。省去了书写各种html标签的麻烦。

wordpress缺省带所见即所得的编辑器,也有html编辑器。既然都学习了markdown,正好找到一个markdown插件 – WP-Markdown

启用插件后,到“设置” – “撰写”里面,配置Markdown在post页面生效,comment还是暂时算了,否则用户可不会Markdown语法,最明显的是Markdown不会把回车键当做换行。然后在新建或者编辑post里面,就会默认用到Markdown编辑器,也有所见即所得的窗口,很方便。

翻译了一下Markdown的语法,我会逐步用Markdown把它补充到下面。可能有不完善的地方,见谅。


Markdown语法

概述 Overview

理念

Markdown的设计初衷就是尽可能的易于阅读,易于书写。易读性高于一切。

Markdown编写的文档要像纯文本格式文件那样看起来简单,而不是它实际代表的由许多标签和格式组成的html文件。

inline html

markdown的语法只有一个目的:作为一个书写web的格式。

markdown不是html的替代物,或者跟他类似的东东。他的语法很小,只相当于html标签的一个很小子集。创造它的目的不是为了更容易的插入html标签。在我看来,html标签已经很容易的书写编辑了。创造markdown的目的是为了更加舒服的读、写和编辑简单的文本。html是发布格式,markdown是书写格式。所以markdown只解决可以被转换成文本格式的问题。

对于不被markdown涵盖的其他修饰功能,还是可以直接用html语法。你不需要事先描述或者单独申明一下你开始用html标签了,直接用就好了。

唯一的限制是块级别的html元素,比如<div><table><pre><p>等等,必须和他上下内容用空白行隔离开来。块的起始和结束标签不能带有空格。比如:

This is a regular paragraph.

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

This is another regular paragraph.

注意:markdown不会处理块里面的任何元素。

span级别的html标签,比如<span><cite><del>可以用在markdown的任何段落、列表和头里。你甚至可以用html标签代替markdown格式。
跟块级别标签不一样,markdown语法会处理span级别标签里面的元素。

自动escape特殊字符

在html里,有2个字符需要特殊对待:<和&。前者用于标签开始,后者用于指示html实体。如果却是要用到他们作为一般字符,你必须用html实体表示他们。比如<和&。

&尤其讨厌,如果你要写”AT&T”,你必须语法用AT&amp;T。你甚至需要在url里面escape它,比如:

http://images.google.com/images?num=30&q=larry+bird

你就必须在锚标记的href属性里面写成:

http://images.google.com/images?num=30&amp;q=larry+bird

不用多说,很容易遗忘这些,也是最常见的html代码错误。

而markdown允许你很自然地使用这些字符,为你自动处理必要的escape。如果你是在一个html实体里面使用&,ok,他就属于一个html实体,否则他就会替你翻译成&amp;

所以如果你要在文章里包含了一个copyright符号,你可以

&copy;

markdown会把它当做一个html实体。如果你写

AT&T

markdown会把它翻译为AT&amp;T

类似的由于markdown支持inline html,所以你可以照常使用<>作为html标签分隔符。但是如果你是:

4 < 5

markdown会翻译为:

4 &lt; 5

然后,inside markdown code spans and blocks, <和&都会自动编码,这样就很容易用markdown写html代码了。而不用像html那样,每一个单独的<或者&都需要单独被escape一下。

块元素 Block Elements

段落和换行

段落就是一个或者多个连续的文字行,段落有一个或者多个空白行分开(空白行就是不带任何内容的行,包括空格和缩进)。一般的段落都不会有缩进。

一个或多个连续的文字行意味着,markdown支持“hard-wrapped”硬换行文字段落,这一点大大不同于其他把每一个换行字符翻译为<br />标签的编辑器。
如果你确是需要用markdown插入一个<br />换行标签,你在行尾加入2个或者多个空格,然后输入回车。

这一点的确多花了点功夫,但是简单的“每一个换行都是一个<br />”的规则对markdown不适用。markdown有更好的换行处理方式:email形式的blockquoting和多段落的list items。

markdown支持两种形式的头,setext和atx。

setext用等于号和破折号组成的下划线标示,等于号和破折号多少数量无所谓,等于号标示一级头,破折号标示二级头。比如:

This is an H1
=============

This is an H2
-------------

atx头用1-6个#字符至于行首,标示1-6级头。比如:

# This is an H1

## This is an H2

###### This is an H6

当然如果你为了更好看,你也可以在行尾也摆上#,但是数量可以任意。行首的#字符数量决定了头的级别。比如:

# This is an H1 #

## This is an H2 ##

### This is an H3 ######

blockquotes引用

markdown使用email形式的>作为引用标记。如果你在某个硬换行的行首都放一个>,会显得更加美观。比如:

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
> 
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
> id sem consectetuer libero luctus adipiscing.

markdown允许你偷懒一下,只在每个硬换行段落的行首放一个>即可。比如:

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
id sem consectetuer libero luctus adipiscing.

引用还可以嵌套,比如:

> This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level.

引用还可以包含其他markdown元素,比如header,list,代码块。比如:

> ## This is a header.
> 
> 1.   This is the first list item.
> 2.   This is the second list item.
> 
> Here's some example code:
> 
>     return shell_exec("echo $input | $markdown_script");

list列表

markdown支持有序的和无序的列表。

无序列表使用星号、加号或者连字符-作为列表标记,三者等同。

有序列表使用数字带句号。

1.  Bird
2.  McHale
3.  Parish

注意,你用来标记列表的具体数字在生成的html代码里没有实际意义。

列表标记典型的从左边开始,但也可以最大缩进3个空格。列表标记后面必须跟一个或者多个空格。

为了使列表看起来更好,可以使用悬挂式缩进硬分行。比如:

*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
    Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
    viverra nec, fringilla in, laoreet vitae, risus.
*   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
    Suspendisse id sem consectetuer libero luctus adipiscing.

如果列表项目被空白行隔开,那么markdown会用p标签包围列表项目。比如:

*   Bird
*   Magic

会被翻译成:

<ul>
<li>Bird</li>
<li>Magic</li>
</ul>

如果加了空白行

*   Bird

*   Magic

则会被翻译成:

<ul>
<li><p>Bird</p></li>
<li><p>Magic</p></li>
</ul>

列表项目可以包含多个段落,一个列表项目中的随后段落必须缩进4个空格。比如:

1.  This is a list item with two paragraphs. Lorem ipsum dolor
    sit amet, consectetuer adipiscing elit. Aliquam hendrerit
    mi posuere lectus.

    Vestibulum enim wisi, viverra nec, fringilla in, laoreet
    vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
    sit amet velit.

2.  Suspendisse id sem consectetuer libero luctus adipiscing.

否则3个空格正好是独立段落的最大空格限度,列表项目段落就成了新的独立段落了。

像上面每个换行都缩进,会更好看。当然为了偷懒,你不必在列表项目的新段落里每行都缩进。比如:

*   This is a list item with two paragraphs.

    This is the second paragraph in the list item. You're
only required to indent the first line. Lorem ipsum dolor
sit amet, consectetuer adipiscing elit.

*   Another item in the same list.

如果要在列表项目里面加入引用,分隔符>必须缩进。比如:

*   A list item with a blockquote:

    > This is a blockquote
    > inside a list item.

如果要在列表项里面加入代码块,那么代码块必须缩进2倍 – 8个空格。比如:

*   A list item with a code block:

        <code goes here>

另外注意避免错误的触发一个有序列表,比如为了表达这句话:

1986. What a great season.

可以用backslash来escape句号:

1986\. What a great season.

代码块

不同于一般的段落,代码段的行数是按照字面解释的,markdown用<pre><code>标签包围代码块。

生成一个代码块只需要缩进4个空格即可,翻译成html的时候会从代码块的每行去掉4个空格。比如

Here is an example of AppleScript:

    tell application "Foo"
        beep
    end tell

会翻译成:

<p>Here is an example of AppleScript:</p>

<pre><code>tell application "Foo"
    beep
end tell
</code></pre>

代码块生效到缩进结束或者到代码末尾。

在代码块里,&和<>会自动转换成html实体。所以用markdown非常容易加入样本html源代码。比如:

 <div class="footer">
        &copy; 2004 Foo Corporation
    </div>

会翻译为:

 <pre><code>&lt;div class="footer"&gt;
    &amp;copy; 2004 Foo Corporation
&lt;/div&gt;
</code></pre>

普通的markdown语法在代码块里面不会被处理。所以也很容易用markdown书写markdown自己的语法。

水平线规则

可以在一行用3个或更多的星号,连字符或者下划线来生成一个水平线标签(<hr />)。如果你想,在符号中间可以插入空格。下面的效果都一样:

* * *

***

*****

- - -

---------------------------------------

SPAN元素

链接

markdown支持2种类型的link:inline和reference。

两种类型的链接文字都放在[]里面。

inline link,只需要在[]后面紧跟一个(),括号里面放链接地址,后面可以跟一个可选的title,title用””引起来。比如:

This is [an example](http://example.com/ "Title") inline link.

[This link](http://example.net/) has no title attribute.

链接地址可以用相对路径,如果是指向本地资源的话。

reference链接,使用2个[],第二个[]放入指定link的标签名字。在[]之间可以不需要空格,可以插入一个空格。比如:

This is [an example] [id] reference-style link.

然后在文档的任何地方,用一行来定义link标签。

[id]: http://example.com/  "Optional Title Here"

其中:

  • []内放入link标识符,可以缩进最多3个空格;
  • 后面紧跟冒号:
  • 后面紧跟一个或者多个空格
  • 然后是url地址
  • 最后可以可选跟link的标题属性,放在单引号或者双引号或者括号里面。

以下3个link定义都是相同的:

[foo]: http://example.com/  "Optional Title Here"
[foo]: http://example.com/  'Optional Title Here'
[foo]: http://example.com/  (Optional Title Here)

注意:markdown.pl 1.0.1有个bug,不允许使用单引号用于title定义。

另外,url也可以用<>包起来。比如:

[id]: <http://example.com/>  "Optional Title Here"

可以把title属性放在第二行,可以使用额外的空格。比如:

[id]: http://example.com/longish/path/to/resource/here
    "Optional Title Here"

link id定义只是用来创建link,不会作为hmtl输出。

link的名字标示符可以是字母,数字,空格和标点符号。不区分大小写。

甚至可以用一个空的[]来定义link标示符,然后使用link text本身作为标示符名字。比如:

[Google][]
[Google]: http://google.com/

由于link name支持空格,这种捷径甚至可以用多字符的link text。比如:

Visit [Daring Fireball][] for more information.
[Daring Fireball]: http://daringfireball.net/

link标示符可以放在文档的任何地方,一般可以link被用到的段落末尾,当然也可以文档末尾。比如:

I get 10 times more traffic from [Google] [1] than from
[Yahoo] [2] or [MSN] [3].

  [1]: http://google.com/        "Google"
  [2]: http://search.yahoo.com/  "Yahoo Search"
  [3]: http://search.msn.com/    "MSN Search"

或者

I get 10 times more traffic from [Google][] than from
[Yahoo][] or [MSN][].

  [google]: http://google.com/        "Google"
  [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
  [msn]:    http://search.msn.com/    "MSN Search"

上面两个都会被翻译为:

<p>I get 10 times more traffic from <a href="http://google.com/"
title="Google">Google</a> than from
<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>

比较一下markdown的inline link:

I get 10 times more traffic from [Google](http://google.com/ "Google")
than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
[MSN](http://search.msn.com/ "MSN Search").

使用reference link的目的不是为了好写,而是为了更容易阅读。另外,字符数reference也用的最少。而且也最接近浏览器渲染出来的最终结果。

emphasis加重

markdown用或者_作为加重的标示。一个或者_被翻译为<em>,两个被翻译为<strong>。比如:

*single asterisks*

_single underscores_

**double asterisks**

__double underscores__

会产生:

<em>single asterisks</em>

<em>single underscores</em>

<strong>double asterisks</strong>

<strong>double underscores</strong>

4个格式可以任选一个,唯一的限制是开始和终止必须用同样的字符。

加重可以用在单词的中间,比如:

un*frigging*believable

但是如果或者_边上有一个或者多个空格,那么会被当成普通的或者_。

另外,可以使用backslash来escape加重效果。比如:

\*this text is surrounded by literal asterisks\*

Code

用“(不是单引号哦)来标记code span,code span加标记的code可以加入到普通的段落内。比如:

Use the `printf()` function.

如果code里面要包含`字符,可以用””来包围整个code。比如:

"There is a literal backtick (`) here."

会被翻译为:

<p><code>There is a literal backtick (`) here.</code></p>

包围code span的””内可以包含空格,一个在opening后面,一个在closing前面。这样的话,就可以在code span的开头或者结尾放置一个字面意义的`符号。比如:

A single backtick in a code span: `` ` ``

A backtick-delimited string in a code span: `` `foo` ``

会被翻译为:

<p>A single backtick in a code span: <code>`</code></p>

<p>A backtick-delimited string in a code span: <code>`foo`</code></p>

在code span内,&或者<>会被编译为html实体,所以markdown很容易书写html标签实例。比如:

Please don't use any `<blink>` tags.

或者:

`&#8212;` is the decimal-encoded equivalent of `&mdash;`.

图片

公认的,用文本文档格式书写插入图片的代码比较困难。markdown用类似于link的语法来完成这个操作,也包含inline和reference两种类型。

inline image语法为:

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

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

其中:

  • !感叹号标记;
  • []包括alt属性;
  • ()里面包括图片url和路径,可选的在”或者””里面标记title属性。

reference image语法为:

![Alt text][id]

其中“id”是图片reference的名字,reference的语法为:

[id]: url/to/image  "Optional title attribute"

到目前为止,markdown还没有语法来制定图片的尺寸。如果这很重要,可以使用普通的html img标签。

其他

自动link

markdown支持url或者email地址的自动link模式,只需要用<>包围具体的url或者mail地址。比如:

<http://example.com/>

会被翻译为:

<a href="http://example.com/">http://example.com/</a>

email同理。只不过markdown会在翻译成html的时候做一些十进制和十六进制编码来避免垃圾邮件机器。但是这种处理方法并不能总是凑效,所以最好还是不要这样发布email地址。

backslash escape

之前已经提到过,可以用\来escape markdown有意义的标记,还原它字面字符。这些标记字符包括:

\

*

_

{}

[]

()

#

+

.

!

.完.

发表回复