All notes



Those must be escaped with "\":

* # / ( ) [ ] < > _

Good reference

Numbered sections

pandoc --number-sections < > out.html

File extension: .md

# Markdown


## The history and why

Markdown comes out originally to make email formatting more convinient.


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:

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):

![alt text]( "Logo Title Text 1")

![alt text][logo]

[logo]: "Logo Title Text 2"

## Reference

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


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

We can take it the easiest way:


Markdown will turn it to:

	<a href=""></a>

If you put on an email address


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]( "Title") inline link.

will produce

	<p>This is <a href="" 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]: "Optional Title Here" 

Other example:


[I'm an inline-style link](

[I'm an inline-style link with title]( "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]:
[link text itself]:

Gitlab link to markdown file

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




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


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"
    end tell

will turn into:

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

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.

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


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


Definition lists

: A Markdown-superset converter

:     Another Markdown-superset converter