# Markdown 简介

Markdown is created by Daring Fireball, the original guideline is here. Its syntax, however, varies between different parsers or editors.

## 哲学

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.

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.

## Markdown 和 HTML

Markdown文档中可以直接插入大多数HTML标签。HTML的区段标签（如：<span><cite><del>等）甚至可以直接插入到Markdown的段落、列表等语法中。同时某些HTML区块标签的插入存在一些限制（如： <div><table><pre><p> 等），必须在前后加上空行与其它内容隔开，还要求它们的开始标签与结尾标签不能用制表符或空格来缩进。

Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.

Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.

Markdown 是一种针对 web 的书写格式，而 HTML 则是针对 web 的发布格式，二者完全不同。Markdown 的设计初衷是，使得编辑、阅读纯文本文档变得简单，而不是要取代 HTML 或者替代 HTML 的部分子集。

Markdown 语法仅仅解决可以通过纯文本来表达的问题。在无法用 Markdown 来进行表达时，允许创作者自由的使用原生的 HTML。既保证了纯文本的简洁性，又结合了 HTML 丰富的表现力。

## 用 Markdown 写 HTML 更方便

HTML 由于给标记和实体字符的冲突，要对内容中出现的 < 和 & 转义处理：In HTML, there are two characters that demand special treatment: <and &. Left angle brackets are used to start tags; ampersands are used to denote HTML entities. If you want to use them as literal characters, you must escape them as entities, e.g. &lt;, and &amp;. 如果没有转义的话，一般会引起 HTML 解析错误。

Markdown 解析器对 < 和 & 的处理，是智能的，可以判断 < 和 & 是 HTML 的语法部分，还是正文中出现的，如果是正文中出现的话，就自动将其替换为 &lt;&amp;，如果是语法部分则保持不变。

This makes it easy to use Markdown to write about HTML code. (As opposed to raw HTML, which is a terrible format for writing about HTML syntax, because every single < and & in your example code needs to be escaped.)

## markdown 转义

markdown 的元字符可以使用 \ 进行转义，这样的话，即使语法规则符合，也不会被 Markdown 引擎解析

# 块元素 Block Elements

## 段落 Paragraphs

Markdown’s email-style blockquoting and multi-paragraph list itemswork best — and look better — when you format them with hard breaks.

Markdown 支持两种风格的标题：一种是在标题内容后面一行用不少于一个 =- 符号来标注，其中 = 表示一级标题，- 表示二级标题；另外一种风格是在行首用 1~6 个 # 来分别表示 6 个级别的标题，如果为了看起来美观可以在标题结尾添加任意数量的 # 字符，此外 # 和标题内容之间可以用空格隔开，也可以不隔开。

## 块引用 Blockquotes

### 引用中可以使用标题语法

• 列表项1
• 列表项2

def test():
pass


## 列表 Lists

悬挂式缩进列表（更美观）
*   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.

*   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.


*   A list item with a blockquote:

> This is a blockquote
> inside a list item.

*   A list item with a code block:

<code goes here>

• 列表项目标记通常放在最左边，但是其实也可以缩进，最多 3 个空格，项目标记后面一定要接着至少一个空格或制表符

• 如果列表项目间用空行分开，则在转换为HTML时项目内容会用<p>标签包起来

• 列表是可以嵌套的

• 嵌套列表项1
• 嵌套列表项2
• 列表项目可以包含多个段落，且段落必须缩进 4 个空格或是 1 个制表符

列表项中的一个段落

列表项中的另一个段落

• 如果要在列表项目内包含引用，那引用标记^就需要缩进4 个空格或是 1 个制表符

包含在列表项目中的引用内容

• 如果要在列表项目内包含代码区块，该区块就需要缩进 8 个空格或是 2 个制表符

  <代码写在这里>


## 代码区块 Code Blocks

Pre-formatted code blocks are used for writing about programming or markup source code. Rather than forming normal paragraphs, the lines of a code block are interpreted literally. Markdown wraps a code block in both <pre> and <code> tags.

程序文档等内容通常会有已经排版好的格式，我们不希望以一般段落格式去展示它们，而是希望以原来看到的排版方式来呈现。



Within a code block, ampersands (&) and angle brackets (< and >) are automatically converted into HTML entities. This makes it very easy to include example HTML source code using Markdown

Regular Markdown syntax is not processed within code blocks. E.g., asterisks are just literal asterisks within a code block. This means it’s also easy to use Markdown to write about Markdown’s own syntax.

# 行内元素 span elements

## 链接

Markdown supports two style of links: inline and reference. In both styles, the link text is delimited by [square brackets].

If you’re referring to a local resource on the same server, you can use relative paths:

See my [About](/about/) page for details.


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


• Square brackets containing the link identifier (optionally indented from the left margin using up to three spaces);
• followed by a colon;
• followed by one or more spaces (or tabs);
• followed by the URL for the link;
• optionally followed by a title attribute for the link, enclosed in double or single quotes, or enclosed in parentheses.

The link URL may, optionally, be surrounded by angle brackets:

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


You can put the title attribute on the next line and use extra spaces or tabs for padding, which tends to look better with longer URLs:

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


The implicit link name shortcut allows you to omit the name of the link, in which case the link text itself is used as the name. Just use an empty set of square brackets — e.g., to link the word “Google” to the google.com web site, you could simply write:

Visit [Daring Fireball][] for more information.


[Daring Fireball]: http://daringfireball.net/


The point of reference-style links is not that they’re easier to write. The point is that with reference-style links, your document source is vastly more readable.

## 强调 Emphasis

Markdown treats asterisks (*) and underscores (_) as indicators of emphasis. Text wrapped with one * or _ will be wrapped with an HTML <em> tag; double *’s or _’s will be wrapped with an HTML<strong> tag.

Emphasis can be used in the middle of a word:

un*frigging*believable



But if you surround an * or _ with spaces, it’ll be treated as a literal asterisk or underscore. 不能和被强调的内容用空白隔开。

single asterisks

single underscores

double asterisks

double underscores

## 行内代码 code span

To indicate a span of code, wrap it with backtick quotes.

To include a literal backtick character within a code span, you can use multiple backticks as the opening and closing delimiters, 为了使得开始和尾部可以包含 backtick quote，允许空白，The backtick delimiters surrounding a code span may include spaces — one after the opening, one before the closing. This allows you to place literal backtick characters at the beginning or end of a code span:

A single backtick in a code span:   

A backtick-delimited string in a code span:  foo 


printf() 是最常见的C语言函数之一

# Misc

Markdown supports a shortcut style for creating “automatic” links for URLs and email addresses: simply surround the URL or email address with angle brackets.

<http://example.com/>

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


## backslash escape

Markdown allows you to use backslash escapes to generate literal characters which would otherwise have special meaning in Markdown’s formatting syntax.

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

##### Xiao Wenbin
###### Natural Language Processing Engineer

My research interests include machine learning, information retrieval and natural language processing.