## 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.
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.
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.
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](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 1")
[logo]: https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 2"
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 ```.
We can take it the easiest way:
Markdown will turn it to:
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](http://example.com/ "Title") inline link.
<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"
[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]
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
[link text itself]: http://www.reddit.com
Gitlab link to markdown file
NOTE: only the format "()" is supported. Triangle brackets will not work.
Unordered lists use: '*', '+', '-'
While ordered lists use numbers followed by an english dot.
<!-- _ 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"
will turn into:
<pre><code>tell application "Foo"
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><blink></code> tags.</p>
Starts and ends with 3 ticks. You could specify the language class on the openning line.
s = "Python syntax highlighting"
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