Markdown语法、Jumly语法学习

发表于   |   分类于 ，   |  

概况

本文主要介绍下Markdown的基本语法1，以及如何使用Jumly2（译文）在Markdown中支持流表等

Markdown语法

Markdown概述

宗旨

Markdown 是一种轻量级标记语言，创始人为约翰·格鲁伯（John Gruber）。它允许人们 使用易读易写的纯文本格式编写文档，然后转换成有效的XHTML(或者HTML)文档。

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

总之， Markdown 的语法全由一些符号所组成，这些符号经过精挑细选，其作用一目了然。比如：在文字两旁加上星号，看起来就像强调。Markdown 的列表看起来，嗯，就是列表。Markdown 的区块引用看起来就真的像是引用一段文字，就像你曾在电子邮件中见过的那样。

兼容HTML

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

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

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

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

例子如下，在 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 区段标签间是有效的。

块元素

段落和换行

段落只是被至少一个空行分隔的至少一行文本内容，空行是只有空格或Tabs的一行。正常的段落不应该使用空格或Tabs缩进。

使用Markdown时若想要换行，可以使用2个以上的空格和return来结束该行。

标题

Markdown支持两种标题风格，Setext3和atx4

  1. Setext风格标题

    使用=（第一级别标题）和-（第二级别标题）来描述

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

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

  2. atx风格标题

    使用1~6个#放在行的开头，对应级别1~6的标题

    # This is an H1

## This is an H2

###### This is an H6

块引用

  1. Markdown使用邮件风格的>字符
  2. Markdown允许只在段落的第一行添加>（使用大于号和空格表示）

  3. 块引用可以嵌套，即使用额外的>

    This is the first level of quoting.

    This is nested blockquote.

    Back to the first level.

  4. 块引用可以包含其它的Markdown元素，包括标题、列表和代码块等

    This is a header

    1. This is the first list item.
    2. This is the second list item.

列表

Markdown支持有序和无序列表

  1. 无序列表使用*、+、-（可以互换）作为列表标记
  2. 有序列表使用数字来作为列表标记，注意用于列表标记的具体数字对HTML输出没有影响
  3. 列表标记后必须跟着至少一个空格或Tab
  4. 列表条目可以有多个段落，每个段落要么使用4个空格，要么一个Tab来缩进

  5. 在列表条目中添加块引用时，需要在缩进后添加>

    • A list item with a blockquote

      This is a blockquote
      inside a list item.

  6. 在列表条目中添加代码块，需要缩进2次，即8个空格或2个Tabs

    • A list item with a code block
      1
      2
      3
      4
      public class MyClass {
      	private String name;
      	public void printName() {}
      }

代码块

  • 预格式化代码块用于写程序或标记源代码，代码块的一行在字面上被解释，而不是形成正常的段落。
  • Markdown把代码块封装在<pre>和<code>标签中。

  • 在Markdown中为了生成一个代码块，只是简单缩进每行4个空格或1个Tab即可。

    tell application "Foo"
    beep
end tell

  • 代码块的范围是直到文章末尾或有一行没有缩进

  • 代码块内，&符号和尖括号（<、>）是自动转换为HTML实体，这使得使用Markdown很容易就实现包含HTML代码，只是简单粘贴和缩进。

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

水平线

在一行中使用至少三个-、*、_可以生成一条水平线，当然也可以在-或*使用空格隔开。

跨度元素

链接

Markdown支持inline和reference两种类型链接

  • inline：以中括号标记显示的链接文本，后面紧跟用小括号包围的链接。如果链接有title属性，则在链接中使用空格加”title属性”。

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

  • reference：一般应用于多个不同位置使用相同链接。通常分为两个部分，调用部分为链接文本；定义部分可以出现在文本中的其他位置，格式为 ref: http://some/link/address (可选的标题)。

    1
    2
    3
    This is [an example][id] reference-style link.
    [id]: http://example.com/  "Optional Title Here"

强调

  • Markdown使用*和_来着重强调。使用一个*或_封装的文本可以被带有<em>的HTML标签封装，使用两个*或_封装的文本可以被带有<strong>的HTML标签封装。
  • 还可以对一个单词的部分内容使用强调

代码

  • 使用反引号` 来指示其跨度，不像预格式化的代码块，一段代码的跨度表明在一个段落里。

  • 为了在一个代码跨度里包含反引号，可以使用多个反引号来当作开闭分隔符

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

  • 围绕一个代码跨度的反引号分隔符可能包括空格，开始后一个，关闭前一个

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

图片

图片的使用方法基本上和链接类似，只是在中括号前加叹号。

  • inline

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

  • reference

    1
    2
    3
    ![Alt text][id]
    [id]: url/to/image  "Optional title attribute"

其它

自动链接

Markdown为URLs和邮件地址提供创建自动连接的快捷方式，即使用尖括号来包围URLs或邮件地址。

<http://example.com/>

<address@example.com>

转义

Markdown中的转义字符为\

\\ 反斜杠
\` 反引号
\* 星号
\_ 下划线
\{\} 大括号
\[\] 中括号
\(\) 小括号
\# 井号
\+ 加号
\- 减号
\. 英文句号
\! 感叹号

Jumly语法

概述

Jumly是一个用于UML画图渲染引擎的JavaScript库，工作原理完全在客户端。使用Jumly，可以很容易将时尚的UML图标嵌入到HTML文档中。

指令

Sequence Diagram

@found

开始交互的顶级元素，将参与者与生命线（虚线表示）和发生的事（灰色边界矩形）放在一起

1
@found "He"

可以使用->来显示发生的事的交互，使用缩进（2个空格或1个Tab）并且写如@message的其它指令

@message

两个参与者或自调用之间的交互

1
2
@found "He",  ->
	@message "calls", "Her"

如果第二个参数未提供，则表示自调用

1
2
@found "He",  ->
	@message "thinks",

可以在上述两种情况下将->放在最后一个参数后面，用于嵌套的交互

@create

新建一个交互，参与者的名字即给定的参数名，创建的参与者会向下移动，并且箭头是虚线形式

1
2
@found "He",  ->
	@create "Contact"

可选：将->作为第二个参数；也可以结合其它指令

@reply

显示回调的信息，可以和一个简短说明的参数放在一个@message指令里

1
2
3
@found "Browser", ->
	@message "GET", "Server", ->
		@reply "200"

@alt

一种碎片，通常形成带有一些交互的2个或多个条件部分。@alt的一部分由一对文本和->组成，可以在@alt里存放多对

1
2
3
4
5
6
7
@found "You", ->
	@alt
		"[male]": ->
			@message "pay with a card", "Bar", ->
				@message "auth the card", "Visa"
		"[female]": ->
			@message "wait for his payment"

@loop

一种碎片，显示重复。一个亮灰色的矩形表示一个循环

1
2
3
@found "You", ->
	@loop "[until she answer]", ->
		@message "call", "Her"

@fragment

泛型指令，生成如@alt和@loop的碎片

1
2
3
4
5
@found "Thread-A", ->
	@fragment "critical section": ->
		@message "acquire", "Mutex"
		@message "do something"
		@message "release", "Mutex"

@ref

移动到另一个图表的指令

1
2
@found "MacOX", ->
	@ref "initialize"

@note

存放注意提示的指令

1
2
3
4
5
@found "She", ->
	@note "Eventually"
	@message "meets", "You", ->
		@note "can't do anything then"
	@note "Just say goodbye..."

  1. 1.Markdown: Syntax ↩
  2. 2.Jumly ↩
  3. 3.Structure-enhanced text，文档地址 ↩
  4. 4.atx, the true structured text format，文档地址 ↩