This is my note of learning markdown, also a digest from [this paper][markdown syntex]. [markdown syntex]: http://daringfireball.net/projects/markdown/syntax
INTRODUCTION
Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).
Thus, “Markdown” is two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML. See the Syntax page for details pertaining to Markdown’s formatting syntax.
The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.
The best way to get a feel for Markdown’s formatting syntax is simply to look at a Markdown-formatted document.
###MARKDOWN SYNTEX DETAIL
PHILOSOPYH
Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters — including Setext, atx, Textile, reStructuredText,Grutatext, and EtText — the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.
To this end, Markdown’s syntax is comprised entirely of punctuation characters, which punctuation characters have been carefully chosen so as to look like what they mean. E.g., asterisks around a word actually look like *emphasis*. Markdown lists look like, well, lists. Even blockquotes look like quoted passages of text, assuming you’ve ever used email.
SYNTEX DETAIL
1. headers 标题
the number of opening hashes determines the header level.
using 1-6 hash characters at the start of the line, corresponding to header level 1-6.
This is an H1.
This is an H2.
This is an H3.
This is an H4.
This is an H6.
2. blockquotes 块引用
put a > (right angle brackets) before every line you quoted.
Email-style angle brackets are used for blockquotes.
Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.
blockquotes can be nested by adding additional level of >.
blockquotes can be contain other MARKDOWN elements, including headers,lists,and code blocks.
3. lists 列表
support ordered(numbered) and unordered(bulleded) lists.
(1) unordered list:
adding * or - in front of the line.
- red
- green
- blue
or,
* red
* green
* blue
this have some points for attention.
1) List markers typically start at the left margin, but may be indented by up to three spaces.
2) List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either 4 spaces or one Tab.
一个列表项的第一行要在“－”或“＊”或“数学.”后加空格（至多三个），其后此段落的行可以加空格（与第一行保持一致的缩进）。
此列表项的下一个段落以4空格或1个Tab来缩进。
-
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.
-
Anther item in the same list.
3) Put a blockquote within a list item, the blockquotes’s > delimiters need to be indeeted.
-
A list item with a blockquotes:
This is a blockquote inside a list item.
4) Put a code block within a list item, the code block needs to be indented twice - 8 spaces or two Tabs:
-
A list item with a code block:
return shell_exec("echo $input | $markdown_script");
(2) ordered list:
- red
- Green
- Blue
note:
A number-period-space sequence at the beginning of a line will trigger and ordered list. Sometimes, you can backslash-escape the period.
1986. what a great season.
=> 1986\. what a great season.
4. code blocks 代码段
Simply indent every line of the code blocks by at least 4 spaces or 1 Tab.
A code block continues until it reaches a line that is not indented(or the end of the artile).
This is a normal paragraph:
This is a code block.
5. horizontal rules 分隔线，水平线
place three or more hyphens, asterisks.行中只有”-“或”“，不能有其他字符。行中的”“或”-“之间可以加空格（也可以不加）。
***
-———-
6. links 链接
方法1：inline style:
An [example](http://url.com/ “an optional title”)
方法2：reference style:
An [example][id]……..
…….
[id]: http://example.com/ “an optional title”
有时候链接文字比较短，这时可以省略id.
[Google][]
….
[Google]: http://google.com/
7. emphasis
*single asterisk, italic*
**double aterisk, bold**
8. code span
Unlike a preformatted code block, a code span indicates code within a normal paragraph.
Use the printf() function.
9. images 图片
方法1: inline style:
方法2: reference style:
![alt text][id]
…
[id]: /url/to/img.jpg “optional title”
As of this writing, Markdown has no syntex for specifying the dimensions of an image; if this is important to you, you can simply use regular HTML tags.
10. automatic links
11. backslash escapes 转义字符
Markdown allows you to use backslash escapes to generate literal characters which would otherwise have special meaning in Markdown’s formatting syntax. For example, if you wanted to surround a word with literal asterisks (instead of an HTML tag), you can use backslashes before the asterisks, like this:
\*literal asterisks\*
Markdown provides backslash escapes for the following characters:
\ backslash
` backtick
* asterisk
_ underscore
{} curly braces
[] square brackets
() parentheses
# hash mark
+ plus sign
- minus sign (hyphen)
. dot
! exclamation mark