MarkDown common grammar

Personally like Markdown syntax used to do some notes, following a brief introduction about its syntax.

purpose

Markdown's goal is to achieve "Easy to read and write."

Readability, however, is the most important. A document written using Markdown format should be posted in plain text directly, and does not look like the label or format consists of a number of instructions. Markdown syntax is affected to some extent both text-to-HTML formats, including Setext , ATX , Textile , reStructuredText , Grutatext and EtText , but the biggest source of inspiration is actually a plain text e-mail format.

HTML compatible

Target Markdown syntax is: apply to become a network of written language.

Markdown is not intended to replace HTML, not even close to it and its grammatical category rarely, only a small portion of the corresponding HTML tags. Markdown idea is not to make the document easier to write HTML. In my opinion, HTML is very easy to write. Markdown philosophy is to make the document easier to read, write and random change. HTML is a publishing format, Markdown is a writing format. In this way, Markdown formatting syntax coverage only plain text can be covered.

Tags are not within the scope of Markdown, can be written in HTML directly in the document inside. No additional labeling This is HTML or Markdown; as long as the direct labeling on it.

To restrict only some HTML block elements - such as <div>, <table>, <pre>, , etc. tags must add a blank line with other content area separated before and after, they also require start tag and end labels with tabs or spaces can not be retracted. Markdown generator has sufficient intelligence, not in the HTML tags plus an outer block unnecessary tags.

Examples are as follows, with some HTML tables in Markdown document:

这是一个普通段落。

<table>
    <tr>
        <td>Foo</td>
    </tr>
</table>

这是另一个普通段落。

Please note, Markdown syntax format between HTML block tags will not be processed. For example, you use Markdown-style in the HTML block * emphasize * will have no effect.

HTML section (inline) as tag , <cite>, <del> can Markdown paragraph, the list in the title or disposable. According to personal habits, even without Markdown format, and direct use of HTML tags to format. For example: If you prefer the <a> or HTML <img> tag, you can use these tags directly instead of Markdown link or image tag syntax provided.

And in between HTML tags different blocks, Markdown syntax section between HTML tags are valid.

Special characters automatic conversion

In the HTML file, there are two characters require special treatment: <and &. <Tag start sign for, for marking the symbol & HTML entities, if you want to display just a prototype of these characters, you have to use a physical form, such as & lt; and & amp ;.

In particular, let & Character network documentation writers tortured, if you want to make, "AT & T", you have to write 'AT & amp; T. " The URL of the & character should be converted. For example, you want to link to:

http://images.google.com/images?num=30&q=larry+bird

You have to put URLs into written as:

http://images.google.com/images?num=30&q=larry+bird

In order to put the href attribute in the link tag. Needless to say it is easy to forget, this may also be checked to verify the HTML standard errors, the largest number.

Markdown allows you to write characters naturally, need to convert to deal with it better. If you use the ampersand character is part of an HTML entity, it will stay the same, otherwise it will be converted to & amp ;.

So if you want to insert a copyright symbol © in the document, you can write:

&copy;

Markdown will leave it intact. And if you write:

AT&T

Markdown will turn it:

AT&amp;T

Similar situation also occurs in the <symbol, because Markdown allows HTML compatible, if you are the <symbol to use as a delimiter HTML tags, Markdown that it will not do any conversion, but if you write:

4 < 5

Markdown will convert it to:

4 &lt; 5

But note that, within the scope of code, either inline or block, <and & are two symbols will be converted into HTML entities, this feature allows you to easily use Markdown to write HTML code (HTML and relative For, HTML syntax, you put all the <and & are converted to HTML entities, in order to write HTML code in an HTML file inside.)

Paragraph and line breaks

Markdown is a passage of one or more successive lines of text, the definition (blank lines have one or more blank lines before and after it is displayed on the display looks like blank, blank lines will be considered. For example If a line containing only spaces or tabs, the line is treated as a blank line). With a normal paragraph should be indented spaces or tabs.

This sentence "by one or more consecutive lines of text composition" actually implies Markdown allows the forced line breaks within paragraphs (insert line breaks), this feature and most other text-to-HTML format is not the same (including Movable Type the "Convert Line Breaks" option), other formats will each line breaks are converted to tags.

If you really want to rely Markdown to insert a tag, then press at the insertion into two or more spaces and then press Enter.

Indeed, you need a little extra something (to pay more spaces) to generate , but simply "Every line breaks converted to " approach is not suitable in Markdown, Markdown-style block references in the email and a list of more than a paragraph in the new line to use when publishing, not only easier to use, but also easier to read.

title

Markdown supports two header syntax, classes and class Setext atx form.

Class Setext form is in the form of the bottom line, using a = (highest-order header) and - (second order header), for example:

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

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

Any number of = and - can be effective.

Class Atx form is first inserted line # 1-6, 1-6 correspond to the title order, for example:

# 这是 H1

## 这是 H2

###### 这是 H6

You can selectively "close" atx-style class title, this is purely aesthetic use, if think this looks more comfortable, you can add # end of the line, while the number # end of the line and do not have the same beginning (number of determining the amount of the order of the first line of the title character well):

# 这是 H1 #

## 这是 H2 ##

### 这是 H3 ######

Block quote Blockquotes

Markdown block reference numerals are used with reference similar email> of. If you are familiar introduction in the email letter, you will know how to create a block in Markdown reference file, it will look like yourself first off the line well and then add on top of each row>:

> This is a blockquote with two paragraphs. 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.

Markdown also allows you to just be lazy in front of the first row plus the entire paragraph>:

> This is a blockquote with two paragraphs. 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.

Reference can be nested block (example: references cited therein), as long as according to a different number of levels plus>:

 This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level.

Referenced within the block also can use other Markdown syntax, including headings, lists, and other blocks of code:

> ## 这是一个标题。
> 
> 1.   这是第一行列表项。
> 2.   这是第二行列表项。
> 
> 给出一些例子代码：
> 
>     return shell_exec("echo $input | $markdown_script");

Any decent text editor can easily create email type of reference. For example, in the BBEdit, you can select the text and then select Add referenced class from the menu.

List

Markdown supports ordered list and unordered list.

Unordered list with an asterisk, plus or minus mark as a list:

*   Red
*   Green
*   Blue

Equivalent to:

+   Red
+   Green
+   Blue

Also equivalent to:

-   Red
-   Green
-   Blue

Ordered list using the number followed by a period English:

1.  Bird
2.  McHale
3.  Parish

It is important that you use a digital mark on the list does not affect the output of HTML results, the above list is generated HTML tags:

<ol>
<li>Bird</li>
<li>McHale</li>
<li>Parish</li>
</ol>

If your list tags written:

1.  Bird
1.  McHale
1.  Parish

Or even:

3. Bird
1. McHale
8. Parish

You will get exactly the same HTML output. The point is that you can make a list of numbers and output Markdown files of the same results, or you a little lazy, you can totally do not care about the correctness of figures.

If you use lazy writing, the proposed first project is best to start from 1, because Markdown future might support start an ordered list of attributes.

List item tag is usually placed on the left, but in fact can be indented up to three spaces, the project behind the mark must be followed by at least one space or tab.

Make lists look more beautiful, you can use the contents of a fixed indentation collated:

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

But if you're lazy, that's OK:

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

If separated by a blank line between the list items, when the output HTML Markdown will content item with tags wrap, for example:

*   Bird
*   Magic

It will be converted:

<ul>
<li>Bird</li>
<li>Magic</li>
</ul>

But this:

*   Bird

*   Magic

It will be converted:

<ul>
<li><p>Bird</p></li>
<li><p>Magic</p></li>
</ul>

List item may comprise a plurality of paragraphs, each paragraph under item must be indented four spaces or tabs 1:

1.  This is a list item with two paragraphs. 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.

2.  Suspendisse id sem consectetuer libero luctus adipiscing.

If you have indented each line, will look a lot of good, of course, again, if you're lazy, Markdown also allows:

*   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. Lorem ipsum dolor
sit amet, consectetuer adipiscing elit.

*   Another item in the same list.

If you want to put in the reference list of projects that> you need indent:

*   A list item with a blockquote:

    > This is a blockquote
    > inside a list item.

If you want to put the code block, then the block will need to indent twice, which is 8 spaces or two tabs:

*   一列表项包含一个列表区块：

        <代码写在这>

Of course, the list of items likely to accidentally produce, like this wording below

1986. What a great season.

In other words, is the beginning of a line of digital - period - blank, to avoid such a situation, you can add a backslash period.

1986\. What a great season.

Code blocks

And procedures related to writing or label typesetting language source code generally have been good code blocks, these blocks typically we do not want it to go the way of the general paragraphs file layout, but according to the original look show, Markdown will with <pre> and <code> tag to wrap the code block.

To create a block of code in a very simple Markdown, simply indented four spaces or a tab can be, for example, the following input:

这是一个普通段落：

    这是一个代码区块。

Markdown converted to:

<p>这是一个普通段落：</p>

<pre><code>这是一个代码区块。
</code></pre>

The first order of each row indentation (4 spaces or a tab), will be removed, for example:

Here is an example of AppleScript:

    tell application "Foo"
        beep
    end tell

It will be converted:

<p>Here is an example of AppleScript:</p>

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

A block of code will continue until the line (or the end of the file) is not indented.

In the code block inside, &, <and> will be automatically converted into HTML entities, in such a way so that you are very easy to use Markdown insert with examples of HTML source, just copy and paste, plus indentation on it, the remaining Markdown will help you deal with, such as:

<div class="footer">
  &copy; 2004 Foo Corporation
</div>

It will be converted:

<pre><code>&lt;div class="footer"&gt;
    &amp;copy; 2004 Foo Corporation
&lt;/div&gt;
</code></pre>

The code block, the general Markdown syntax will not be converted, it is just like an asterisk asterisk, which means you can easily write files to Markdown syntax Markdown syntax-related.

Dividing line

You may have more than three asterisks, minus, the bottom line to create a dividing line in line with, can not have anything else in the line. You can also insert a space in the middle of an asterisk or minus sign. Each of the following wording can create separate line:

* * *

***

*****

- - -

---------------------------------------

link

Markdown syntax supports two forms of links: inline and reference type two forms.

Either way, the link text is with [square brackets] to mark.

To create an inline-style links, just behind the square brackets brackets immediately and insert the URL link, if you want to add title text links, as long as the end of the url, the title character in double quotation marks that is wrapped can, for example:

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

[This link](http://example.net/) has no title attribute.

Will produce:

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

<p><a href="http://example.net/">This link</a> has no
title attribute.</p>

If you want to link to resources is the same host, you can use relative paths:

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

With reference to formula in brackets behind the link is followed by another link text square brackets, and the brackets in the second flag to identify the link to be filled in:

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

You can also optionally be in the middle of two square brackets with a space:

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

Then, anywhere in the file, you can link the content of this tag definitions out:

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

In the form of linked content is defined as:

Square brackets (front may selectively add up three spaces to indent), which link text input
Followed by a colon
Followed by one or more spaces or tabs
Then Web address
Next title contents selectively, in single quotes, or double quotes wrapped in parentheses

The following three define the links are the same:

[foo]: http://example.com/  "Optional Title Here"
[foo]: http://example.com/  'Optional Title Here'
[foo]: http://example.com/  (Optional Title Here)

Please note: There is a known issue that Markdown.pl 1.0.1 ignores single quotes to wrap the link title.

Link URL can also be wrapped in square brackets:

[id]: "Optional Title Here"

You can also put the title attribute into the next line, you can also add some indentation, if the URL is too long, then that would be more attractive:

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

URL link is generated only when the definition of use, and does not directly appear in the file.

Links can have labels to identify letters, numbers, blanks and punctuation, but not case-sensitive, so the following two links are the same:

[link text][a]
[link text][A]

Implicit link tagging capabilities allow you to specify the link tag is omitted, in which case, the link will be labeled as equivalent to the link text, use the implicit link tag in the back as long as the link text with an empty square brackets, if you want to let "Google" link to google.com, you may be simplified to:

[Google][]

Then define the link to the content:

[Google]: http://google.com/

Since the link text may contain a blank, so within this simplified type of mark may contain more than one word:

Visit [Daring Fireball][] for more information.

And then define links

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

Link definitions can be placed anywhere in the file, I prefer direct link appears on the back of a paragraph, you can also put it in the final document face, just like notes.

Here is an example of a reference-style links:

I get 10 times more traffic from [Google] [1] than from
[Yahoo] [2] or [MSN] [3].

  [1]: http://google.com/        "Google"
  [2]: http://search.yahoo.com/  "Yahoo Search"
  [3]: http://search.msn.com/    "MSN Search"

If you changed the way to write the name of the link:

I get 10 times more traffic from [Google][] than from
[Yahoo][] or [MSN][].

  [google]: http://google.com/        "Google"
  [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
  [msn]:    http://search.msn.com/    "MSN Search"

Both spelling will have the following HTML.

<p>I get 10 times more traffic from <a href="http://google.com/"
title="Google">Google</a> than from
<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>

Here is a line within the same paragraph written in Markdown document content, provided for comparison purposes:

I get 10 times more traffic from [Google](http://google.com/ "Google")
than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
[MSN](http://search.msn.com/ "MSN Search").

In fact, a link-style focus is not it better to write, but it is better to read, compare the above example, the article itself using a reference type only 81 characters, but with inline form but it will increase to 176 characters if it is pure HTML format to write, there will be 234 characters in HTML format, more than the label text.

Using Markdown's reference-style links, allowing more like a file browser results generated last, so you can put some markers associated meta data to a paragraph of text outside, you can add a link to read the article and not let the feeling of being interrupt.

Emphasize

Markdown asterisk (*) and underscores (_) as a marker emphasis word symbols, words or enclosed _ * will be converted to a tag enclosed by two _ * or wrap, then It will be transformed into , for example:

*single asterisks*

_single underscores_

**double asterisks**

__double underscores__

It will turn into:

<em>single asterisks</em>

<em>single underscores</em>

<strong>double asterisks</strong>

<strong>double underscores</strong>

You may use your favorite style, the only limit is what you sign open label, you must use what symbolic end.

Emphasize also can be directly inserted in the middle of the text:

un*frigging*believable

But if you * and _ blank on both sides, then they will be treated as ordinary symbols.

If you want to insert a normal asterisk or the bottom line directly before and after the text, you can use the backslash:

\*this text is surrounded by literal asterisks\*

Code

To mark the short lines of code, you can use the anti-wrap it in quotation marks ( '), for example:

Use the `printf()` function.

Will produce:

<p>Use the <code>printf()</code> function.</p>

If you want to insert the code section in the back quotes, you can use multiple backticks to open and end code section:

``There is a literal backtick (`) here.``

This syntax produced:

<p><code>There is a literal backtick (`) here.</code></p>

Start and end side code segment can be placed in a blank, a starting end of the back end of a front end, so you can Backticks is inserted at the beginning of the section:

A single backtick in a code span: `` ` ``

A backtick-delimited string in a code span: `` `foo` ``

Will produce:

<p>A single backtick in a code span: <code>`</code></p>

<p>A backtick-delimited string in a code span: <code>`foo`</code></p>

In the code segment, and & brackets will be automatically converted to HTML entities, which makes it into the HTML source becomes easy, the Markdown following this will:

Please don't use any `<blink>` tags.

Switch to:

<p>Please don't use any <code><blink></code> tags.</p>

You can also write:

`&#8212;` is the decimal-encoded equivalent of `&mdash;`.

To produce:

<p><code>&amp;#8212;</code> is the decimal-encoded
equivalent of <code>&amp;mdash;</code>.</p>

image

Obviously, to design a "natural" syntax to insert a picture in a text-only applications, there is a certain degree of difficulty.

Markdown uses a very similar syntax and links to mark the pictures, also allows two styles: inline style and reference type.

In-the-line image syntax looks like:

![Alt text](/path/to/img.jpg)

![Alt text](/path/to/img.jpg "Optional title")

Described in detail as follows:

An exclamation point!
Then a square brackets, which put an alternative text for the image
Then a common bracket, which put the image URL finally be wrapped with quotes and add selective 'title' text.

Reference-style image syntax looks like this then:

![Alt text][id]

"Id" is a reference to the name of the picture, it defines the reference picture and the link reference as:

[id]: url/to/image  "Optional title attribute"

So far, Markdown has no way to specify the width and height of the picture, if you need to, you can use an ordinary <img> tag.

Backslash

Markdown can use the backslash to insert some other meaning in the syntax notation, for example: If you want to add in the way with an asterisk next to the text to make emphasize the effect (but not tag), you can An asterisk in front of a backslash:

\*literal asterisks\*

Markdown support these backslash in front of the following symbols to help insert common symbols:

\   反斜线
`   反引号
*   星号
_   底线
{}  花括号
[]  方括号
()  括弧
#   井字号
+   加号
-   减号
.   英文句点
!   惊叹号

Automatic Link

Markdown supports a relatively short form automatically linked to process URLs and e-mail, as long as the package is in square brackets, Markdown will automatically turn it into a link. General URL link text and link to the same address, for example:

<http://example.com/>

Markdown will turn:

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

Automatic link-mail address is also very similar, except that Markdown will do first a transcoding process, the text characters turn into 16-bit code into HTML entities, such a format can fool some of the bad mail address collecting robot, for example:

<[email protected]>

Markdown will turn into:

<a href="mailto:addre
[email protected]
m">address@exa
mple.com</a>

In the browser, this string (in fact, <a href="mailto:[email protected]"> [email protected] </a>) becomes a clickable "[email protected]" link.

(Although this practice can fool a lot of robots, but can not block all down, but something is better than doing nothing. In any case, open your mail will eventually lead to advertising letters.)