All notes
Markdow

FAQ

Escape

Those must be escaped with "\":

* # / ( ) [ ] < > _

Good reference

Numbered sections


pandoc --number-sections < test.md > out.html

File extension: .md


# Markdown

---

## The history and why

Markdown comes out originally to make email formatting more convinient.

## HTML

The HTML tags are permitted in markdown. But be noted that, the block tags such as `<div>, <table>, <pre>, <p>` should be companied by empty lines before and after.

Like wiki and TeX, markdown sees paragraphs separated by empty lines.

In order to insert `<br>` for mandatory line break, insert 2 or more spaces at the end of line and then press return.

## Comments

The same as HTML, you know that. ;-p

## Generate sections

You can always use 1 to 6 #'s in the begining of a line of make it a section title, such as

	# This is H1

	## This is H2

It is called Atx way. Another is Setext way:

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

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

Personally I prefer the first one, which is also present in wiki writing.


## Blockquotes

This is very much the same as in the forwarded text in email:

	> This is a blockquote.
	>> Embeded blockqoute.

The markdown syntax is on in the blockquote:

	> ## This is H2.
	>> 1. Item 1.
	>> 2. Item 2.

## Separation/horizontal line

Uses 3 or more than 3 '*', '-' or '_'. There shouldn't be anything else except spaces.


## Images

Gitlab only supports this format:
![screenshot](screenshot.png)

Seeing that Markdown doesn't support image width/height, I would suggest to use HTML *img* tag.

Here's our logo (hover to see the title text):

Inline-style: 
![alt text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 1")

Reference-style: 
![alt text][logo]

[logo]: https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 2"

## Reference

The chinese documentation for Markdown. \todo give the link.

Emphasis


Emphasis, aka italics, with *asterisks* or _underscores_.
Strong emphasis, aka bold, with **asterisks** or __underscores__.
Combined emphasis with **asterisks and _underscores_**.
Strikethrough uses two tildes. ~~Scratch this.~~

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

wcfNote: it doesn't work within ``` code snippets ```.

Links


## Links

We can take it the easiest way:

	<http://example.com/> 

Markdown will turn it to:

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

If you put on an email address

	<[email protected]>

Markdown will first encode it into 16bit HTML entities in order to obfuscate web robot to fight against spam. It is always suggested that you don't give out your email address directly on the internet.

It is suggested to use Markdown link instead of direct HTML a tag for the sake of reading. The former is more consice.

The inline version

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

will produce

	<p>This is <a href="http://example.com/" title="Title"> an example</a> inline link.</p>

参考式的链接是在链接文字的括号后面再接上另一个方括号,而在第二个方括号里面要填入用以辨识链接的标记:

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

你也可以选择性地在两个方括号中间加上一个空格:

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

接着,在文件的任意处,你可以把这个标记的链接内容定义出来:

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

Other example:

Ref.

[I'm an inline-style link](https://www.google.com)

[I'm an inline-style link with title](https://www.google.com "Google's Homepage")

[I'm a reference-style link][Arbitrary case-insensitive reference text]

[I'm a relative reference to a repository file](../blob/master/LICENSE)

[You can use numbers for reference-style link definitions][1]

Or leave it empty and use the [link text itself]

Some text to show that the reference links can follow later.

[arbitrary case-insensitive reference text]: https://www.mozilla.org
[1]: http://slashdot.org
[link text itself]: http://www.reddit.com

Gitlab link to markdown file

NOTE: only the format "[]()" is supported. Triangle brackets will not work.


[Intro](intro.md)

Lists

Ref.


## Lists

Unordered lists use: '*', '+', '-'

While ordered lists use numbers followed by an english dot.

1. Bird
2. McHale
3. Parish

<!-- _ means a space. -->

NOTE: pandoc only accept indentation of 4 spaces or a tab!

1. First ordered list item
2. Another item
	* Unordered sub-list. 
1. Actual numbers don't matter, just that it's a number
	1. Ordered sub-list
4. And another item.

	You can have properly indented paragraphs within list items. Notice the blank line above.

	To have a line break without a paragraph, you will need to use two trailing spaces__.
	Note that this line is separate, but within the same paragraph__.
	(This is contrary to the typical GFM line break behaviour, where trailing spaces are not required.)

<!-- To prevent from regarding this as a list item, use backslash: -->
1986\. What a great season.

Codes

Use 1 tab or 4 spaces indentation to generate code blocks. The code blocks will be wrapped into


Here is an example of AppleScript:

    tell application "Foo"
        beep
    end tell

will turn into:

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

Note that it assumes codes to be HTML.



If you need codes inline, use '`'.
	Use the `printf()` function. 
It will translate to
	<p>Use the <code>printf()</code> function.</p> 

如果要在代码区段内插入反引号,你可以用多个反引号来开启和结束代码区段:
	``There is a literal backtick (`) here.``
这段语法会产生:
	<p><code>There is a literal backtick (`) here.</code></p>

在代码区段内,&和<>都会被自动地转成 HTML 实体,这使得插入 HTML 原始码变得很容易,Markdown 会把下面这段:
	Please don't use any `<blink>` tags. 
转为:
	<p>Please don't use any <code>&lt;blink&gt;</code> tags.</p> 

Starts and ends with 3 ticks. You could specify the language class on the openning line.

```javascript
var s = "JavaScript syntax highlighting";
alert(s);
```
 
```python
s = "Python syntax highlighting"
print s
```
 
```
No language indicated, so no syntax highlighting. 
But let's throw in a <b>tag</b>.
```

Tables


Colons can be used to align columns.

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |

The outer pipes (|) are optional, and you don't need to make the raw Markdown line up prettily. You can also use inline Markdown.

Markdown | Less | Pretty
--- | --- | ---
*Still* | `renders` | **nicely**
1 | 2 | 3

kramdown

Definition lists

kramdown.gettalong.org.


kramdown
: A Markdown-superset converter

Maruku
:     Another Markdown-superset converter