What does Markdown mean? How to use Markdown syntax/formatting markup?

MarkdownWhat means?

How to use Markdown syntax/formatting markup?

Outline

Markdown is a lightweight markup language created by John Gruber.

It allows people to "write documents in a plain text format that is easy to read and write, and then convert them into valid XHTML (or HTML) documents".

The language incorporates many of the features of plain text markup already found in e-mail.

John Gruber created the Markdown language in 2004, in collaboration with Aaron Swartz in large part on the syntax.The purpose of the language is to use "a plain text format that is easy to read, easy to write, and optionally converts to valid XHTML (or HTML)".

Service Purposes

The goal of Markdown is to be "easy to read and easy to write".

readability, do it anywayInternet marketing, user experience is very important.

A file written in Markdown should be able to be published directly in plain text, and should not appear to consist of many tags or formatting directives.

Markdown syntax is influenced by some existing text-to-HTML formats, including Setext, atx, Textile, reStructuredText, Grutatext, and EtText, but the biggest source of inspiration is the plain text email format.

In short, the syntax of Markdown is all composed of symbols, which are carefully selected and their functions are clear at a glance.For example: put asterisks around text to make it look like *emphasis*.

Lists in Markdown look like, well, lists. Blockquotes in Markdown really look like quoting a piece of text, like you've seen in emails.

Compatible with HTML

The goal of the Markdown grammar is to be a writing language for the web.

Markdown isn't meant to replace HTML, or even come close to it, it has very few types of syntax and corresponds to only a small subset of HTML markup. Markdown was not conceived to make HTML documents easier to write.

In my opinion, HTML is already easy to write. The idea of ​​Markdown is to make documents easier to read, write, and change at will. HTML is a publishing format, Markdown is aCopywritingwritten format.As such, Markdown's formatting syntax only covers what plain text can.

Tags that are not covered by Markdown can be written in HTML directly in the documentWeb Promotioncopy.There is no need to mark this as HTML or Markdown; just add the markup directly.

Only some HTML block elements to be constrained - such as <div>,<table>,<pre>,<p> and other tags, they must be separated from other content areas with blank lines before and after, and their opening and closing tags cannot be indented with tabs or spaces. The Markdown generator is smart enough not to add unnecessary HTML block tags <p> label.

The example is as follows, adding an HTML table to the Markdown file:

这是一个普通段落。

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

这是另一个普通段落。

Note that Markdown formatting syntax between HTML block tags will not be processed.For example, if you use a Markdown style inside an HTML block*强调*will have no effect.

HTML section (inline) tags such as <span>,<cite>,<del> Can be used freely in Markdown paragraphs, lists or headings.According to personal habits, you can even use HTML tags to format without using Markdown format.Example: If you prefer HTML <a> Or <img> tags, which can be used directly without the link or image tag syntax provided by Markdown.

Unlike between HTML block tags, Markdown syntax is valid between HTML section tags.

Automatic conversion of special characters

In HTML files, there are two characters that require special handling: < 和 & . < symbols are used for start tags,& Symbols are used to mark HTML entities, if you just want to display the prototype of these characters, you have to use the entity form, like < 和 &.

& Characters are especially tormenting for web document writers, if you're going to type "AT&T", you must write "AT&T".while in the URL & Characters are also converted.For example you want to link to:

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

You have to write the URL conversion as:

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

to be placed in the link tag href in properties.Needless to say, this is easy to ignore, and probably the largest number of errors detected by HTML standards validation.

Markdown allows you to write characters naturally, and it takes care of what needs to be converted.if you use & A character is part of an HTML character entity, it is left as is, otherwise it is converted to &;.

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

©

Markdown will leave it untouched.And if you write:

AT&T

Markdown will convert it to:

AT&T

A similar situation also occurs in < notation, since Markdown allows HTML compatibility, if you put < Symbols are used as delimiters for HTML tags, and Markdown won't do any conversions on them, but if you write:

4 < 5

Markdown will convert it to:

4 < 5

However, it should be noted that within the scope of code, whether it is inline or block, < 和 & both symbolsfor sureare converted to HTML entities, a feature that allows you to easily write HTML code in Markdown (as opposed to HTML, where you put all the < 和 & All are converted into HTML entities, in order to write HTML code in the HTML file. )

block element

Paragraphs and line breaks

A Markdown paragraph consists of one or more consecutive lines of text, preceded and followed by more than one blank line (the definition of a blank line is that it appears to be empty on display and is considered to be a blank line. For example, , if a line contains only spaces and tabs, the line will also be treated as a blank line).Normal paragraphs should not be indented with spaces or tabs.

The phrase "consists of one or more consecutive lines of text" actually implies that Markdown allows forced newlines (insertion of newlines) within paragraphs, a feature that is different from most other text-to-HTML formats (including Movable Type "Convert Line Breaks" option), other formats will convert each line break to <br /> label.

If youindeedWant to rely on Markdown to insert <br /> For labels, press two or more spaces at the insertion place and then press Enter.

Indeed, it takes a little more work (additional spaces) to generate <br /> , but simply "each newline is converted to <br />"The method is not suitable in Markdown, em in MarkdownaiL-style blockquotes and multi-paragraph lists are not only more useful but also easier to read when typesetting with line breaks.

标题

Markdown supports two syntaxes for headings, Setext-like and atx-like.

The Settext-like form is the form with the bottom line, using = (highest title) and - (Second order headings), for example:

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

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

any amount = 和 - can be effective.

The Atx-like form inserts 1 to 6 at the beginning of the line # , corresponding to headings 1 to 6, for example:

# 这是 H1

## 这是 H2

###### 这是 H6

You can optionally "close" atx-like headers, this is purely for aesthetics, if you feel comfortable this way, you can add it at the end of the line #, while the line endings # The number does not have to be the same as the beginning (the number of pound characters at the beginning of the line determines the order of the title):

# 这是 H1 #

## 这是 H2 ##

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

Blockquotes Blockquotes

Markdown markup blockquotes are used similar to those used in email > of citations.If you're still familiar with quotes in email letters, you know how to create a block quote in a Markdown file, which would look like you break the lines yourself, then add >  :

> 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 be lazy and add only the first line of 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.

Block references can be nested (eg: references within references) by adding a different number of >  :

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

Other Markdown syntaxes can also be used within quoted blocks, including headings, lists, code blocks, etc.:

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

Any decent text editor can easily create email-style citations.For example in BBEdit you can select text and then choose from the menuincrease citation hierarchy.

List

Markdown supports ordered and unordered lists.

Unordered lists use asterisks, plus signs, or minus signs as list markers:

*   Red
*   Green
*   Blue

Equivalent to:

+   Red
+   Green
+   Blue

Also equivalent to:

-   Red
-   Green
-   Blue

Ordered lists use numbers followed by a period:

1.  Bird
2.  McHale
3.  Parish

It's important to note that the numbers you use on the list tag don't affect the output HTML. The resulting HTML markup for the above list would be:

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

If your list markup is written as:

1.  Bird
1.  McHale
1.  Parish

or even:

3. Bird
1. McHale
8. Parish

You'll both get exactly the same HTML output.The point is, you can make the list numbers in the Markdown file the same as the output results, or if you're lazy, you don't need to care about the correctness of the numbers at all.

If you use lazy writing, it is recommended to start with 1. for the first item, because Markdown may support the start attribute of ordered lists in the future.

The list item tag is usually placed on the far left, but it can be indented, up to 3 spaces, and the item tag must be followed by at least one space or tab.

To make the list look nicer, you can organize the contents with a fixed indent:

*   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 fine too:

*   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 the list items are separated by blank lines, Markdown will use the item content when outputting HTML. <p> Labels are wrapped, for example:

*   Bird
*   Magic

Will be converted to:

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

But this:

*   Bird

*   Magic

Will be converted to:

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

List items can contain multiple paragraphs, and the paragraphs under each item must be indented by 4 spaces or 1 tab:

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.

It looks a lot better if you indent each line, 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 a reference inside a list item, then > It needs to be indented:

*   A list item with a blockquote:

    > This is a blockquote
    > inside a list item.

If you want to put a code block, the block needs to be indentedtwice, which is 8 spaces or 2 tabs:

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

        <代码写在这>

Of course, a list of items could be generated accidentally, something like this:

1986. What a great season.

In other words, it appears at the beginning of the linenumber-period-blank, to avoid this, you can add a backslash before the period.

1986\. What a great season.

code block

Program-related writing or tag language source code usually has already typeset code blocks. Usually, we don’t want these blocks to be typeset in the way of general paragraph files, but display them as they are. Markdown will use <pre> 和 <code> tags to wrap code blocks.

Creating code blocks in Markdown is as simple as indenting 4 spaces or 1 tab. For example, enter the following:

这是一个普通段落：

    这是一个代码区块。

Markdown will convert to:

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

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

This first-order indentation per line (4 spaces or 1 tab) is removed, for example:

Here is an example of AppleScript:

    tell application "Foo"
        beep
    end tell

Will be converted to:

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

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

A block of code continues until the unindented line (or the end of the file).

Inside the code block, & , < 和 > It will be automatically converted into HTML entities. This method makes it very easy for you to use Markdown to insert the HTML source code for the example, just copy and paste it, add indentation, and the rest Markdown will handle it for you, for example:

    <div class="footer">
        © 2004 Foo Corporation
    </div>

Will be converted to:

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

In the code block, the general Markdown syntax will not be converted, such as asterisks are just asterisks, which means that you can easily write Markdown syntax related files in Markdown syntax.

divider

You can use more than three asterisks, minus signs, underscores to create a divider in a line, nothing else in the line.You can also insert spaces between asterisks or minus signs.Separation lines can be created in each of the following ways of writing:

* * *

***

*****

- - -

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

section element

link

Markdown supports two forms of link syntax: Inline和Referencetwo forms.

Either way, link text is marked with [square brackets].

to create aInlineIf you want to add the title text of the link, just wrap the title text with double quotation marks after the URL, 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 are linking to resources on the same host, you can use relative paths:

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

ReferenceThe link is followed by another square bracket after the bracket of the link text, and the mark used to identify the link should be filled in the second square bracket:

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

You can also optionally put a space between the two square brackets:

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

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

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

Link content is defined in the form:

• Square brackets (optionally preceded by up to three spaces for indentation) into which link text is entered
• followed by a colon
• followed by one or more spaces or tabs
• the URL of the next link
• Optionally follow the title content, which can be enclosed in single quotes, double quotes, or parentheses

The definitions of the following three 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 where Markdown.pl 1.0.1 ignores link titles enclosed in single quotes.

Link URLs can also be enclosed in angle brackets:

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

You can also put the title attribute on the next line, or add some indentation, which will look better if the URL is too long:

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

The URL definition is only used when generating the link, and does not appear directly in the file.

Link identification tags may contain letters, numbers, whitespace, and punctuation, but do notNotIt is case sensitive, so the following two links are the same:

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

Implicit link tagfeature allows you to omit specifying a link tag. In this case, the link tag will be treated as equivalent to the link text. To use an implicit link tag, just add an empty square bracket after the link text. If you want "Google" Linking to google.com, you can simplify to:

[Google][]

Then define the link content:

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

Since link text may contain whitespace, this simplified markup may contain multiple words:

Visit [Daring Fireball][] for more information.

Then go on to define the link:

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

The definition of the link can be placed anywhere in the file. I prefer to put it directly after the paragraph where the link appears. You can also put it at the end of the file, just like a comment.

Here is an example of a reference link:

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 change it to use the link name to write:

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"

The above two ways of writing will produce 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>

Below is a Markdown file of the same content written inline, provided for comparison:

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, the point of reference-style links is not that it is easier to write, but that it is easier to read. Compare the above example. The reference-style article itself is only 81 characters, but the inline form will increase to 176 characters. , if it is written in pure HTML format, there will be 234 characters. In HTML format, there are more tags than text.

Using Markdown's reference-style links, you can make the document more like the final result of the browser, allowing you to move some markup-related metadata outside the paragraph text, and you can add links without making the reading feel of the article. interrupt.

Emphasize

Markdown uses asterisks (*) and the bottom line (_) as a symbol to mark an underlined word, is * Or _ Surrounded words are converted to <em> surrounded by labels, with two * Or _If it is wrapped, it will be converted into <strong>,E.g:

*single asterisks*

_single underscores_

**double asterisks**

__double underscores__

will turn into:

<em>single asterisks</em>

<em>single underscores</em>

<strong>double asterisks</strong>

<strong>double underscores</strong>

You can use whatever style you like, the only limitation is that you can open the tag with which symbol you want to end it with.

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

un*frigging*believable

Butif your * 和 _ If there are whitespace on both sides, they are just treated as normal symbols.

To insert normal asterisks or underscores directly before and after text, you can use backslashes:

\*this text is surrounded by literal asterisks\*

代码

If you want to mark a small piece of inline code, you can wrap it in backticks (`),E.g:

Use the `printf()` function.

Will produce:

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

If you want to insert backticks inside a code section, you can start and end the code section with multiple backticks:

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

This syntax produces:

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

You can put a blank at the beginning and end of a code section, one after the beginning and one before the end, so you can insert backticks 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>

Inside the code section,& and angle brackets都will be automatically converted to HTML entities, which makes it easy to insert HTML source code, Markdown will put the following paragraph:

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

to:

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

You can also write this:

`—` is the decimal-encoded equivalent of `—`.

To produce:

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

image

Obviously, it is difficult to design a "natural" syntax for inserting images in a text-only application.

Markdown uses a syntax similar to links to mark up images, and also allows two styles: Inline和Reference.

The inline image syntax looks like:

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

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

Details are as follows:

• an exclamation mark !
• followed by a square bracket with alt text for the image
• This is followed by normal parentheses with the URL of the image, and finally an optional 'title' text enclosed in quotes.

The reference image syntax looks like this:

![Alt text][id]

"id" is the name of the image reference, which is defined in the same way as a link reference:

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

So far, Markdown has no way to specify the width and height of the image, if you need, you can use the normal <img> label.

Other

auto link

Markdown supports processing URLs and email mailboxes in the form of relatively short automatic links. As long as they are enclosed in angle brackets, Markdown will automatically convert it into a link.The link text of the general URL is the same as the link address, for example:

<http://example.com/>

Markdown will be converted to:

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

The automatic linking of email addresses is also similar, except that Markdown will first perform an encoding conversion process, converting text characters into hexadecimal HTML entities. This format can fool some bad email address collection robots, such as:

<[email protected]>

Markdown will turn into:

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

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

(Although this approach can fool a lot of robots, it can't stop them all, but it's better than nothing. In any case, opening your mailbox will eventually attract advertising letters.)

backslash

Markdown can use backslashes to insert symbols that have other meanings in the grammar, for example: if you want to add an asterisk next to the text for emphasis (but not <em> tag), you can precede the asterisk with a backslash:

\*literal asterisks\*

Markdown supports the following symbols preceded by a backslash to help insert common symbols:

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

Markdown free editor

Windows platform

• MarkdownPad
• MarkPad

Mac platform

• Mou

online editor

• MPEditor

Browser plugin

• Markdown here plugin

*** If there is a better free Markdown editor to recommend, please pay attention to feedbackChen Weiliang,Thank you!