個人Markdown學習之旅

認識 Markdown

Markdown 是一種輕量級的「標記語言」，它的優勢不少，目前也被愈來愈多的寫做愛好者，撰稿者普遍使用。看到這裏請不要被「標記」、「語言」所迷惑，Markdown 的語法十分簡單。經常使用的標記符號也不超過十個，這種相對於更爲複雜的 HTML 標記語言來講，Markdown 可謂是十分輕量的，學習成本也不須要太多，且一旦熟悉這種語法規則，會有一勞永逸的效果。

使用 Markdown 的優勢

• 專一你的文字內容而不是排版樣式，安心寫做。
• 輕鬆的導出 HTML、PDF 和自己的 .md 文件。
• 純文本內容，兼容全部的文本編輯器與字處理軟件。
• 隨時修改你的文章版本，沒必要像字處理軟件生成若干文件版本致使混亂。
• 可讀、直觀、學習成本低。

1、區塊元素

1. 段落

先後要有一個以上的空行,普通段落不應用空格或製表符來縮進。

2. 標題

Markdown 支持兩種標題的語法，類 Setext 和類 atx 形式

• 類 Setext 形式

  是用底線的形式，利用 = （最高階標題）和 - （第二階標題），例如：

  This is an H1 
  =============
  
  This is an H1
  =
  
  This is an H2
  --------------

任何數量的 = 和 - 均可以有效果。

• 類 Atx 形式

  是在行首插入 1 到 6 個 # ，對應到標題 1 到 6 階，例如：

  # 這是 H1
  
  ## 這是 H2
  
  ###### 這是 H6

3. 區塊引用

• 在每行的最前面加上 > ：

> 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 也容許只在整個段落的第一行最前面加上 >：

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

區塊引用能夠嵌套：

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

引用的區塊內也可使用其餘的 Markdown 語法，包括標題、列表、代碼區塊等：

> ## 這是一個標題。
> 
> 1.   這是第一行列表項。
> 2.   這是第二行列表項。
> 
> 給出一些例子代碼：
> 
>     return shell_exec("echo $input | $markdown_script");

4. 列表

Markdown 支持有序列表和無序列表。

• 無序列表

使用星號( * )、加號( + )或是減號( - )做爲列表標記：

*   Red
*   Green
*   Blue

等同於：

+   Red
+   Green
+   Blue

也等同於：

-   Red
-   Green
-   Blue

• 有序列表

數字 + 一個英文句點 + 空格：

1.  Bird
2.  McHale
3.  Parish

列表標記上使用的數字並不會影響輸出的 HTML 結果*

若是你的列表標記寫成：

1.  Bird
1.  McHale
1.  Parish

或甚至是：

3. Bird
1. McHale
8. Parish

都會獲得徹底相同的 HTML 輸出

建議第一個項目最好仍是從 1. 開始，由於 Markdown 將來可能會支持有序列表的 start 屬性。*

列表項目標記一般是放在最左邊，可是其實也能夠縮進，最多 3 個空格，項目標記後面則必定要接着至少一個空格或製表符。

要讓列表看起來更漂亮，你能夠把內容用固定的縮進整理好：

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

可是若是你懶，那也行：

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

列表項目能夠包含多個段落，每一個項目下的段落都必須縮進 4 個空格或是 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.

若是你每行都有縮進，看起來會看好不少，固然，Markdown 也容許僅僅段落第一行縮進：

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

若是要在列表項目內放進引用，那 > 就須要縮進：

*   A list item with a blockquote:

    > This is a blockquote
    > inside a list item.

若是要放代碼區塊的話，該區塊就須要縮進兩次，也就是 8 個空格或是 2 個製表符：

*   一列表項包含一個列表區塊：

        <代碼寫在這>

固然，項目列表極可能會不當心產生，像是下面這樣的寫法：

1986. What a great season.

換句話說，也就是在行首出現數字-句點-空白，要避免這樣的情況，你能夠在句點前面加上反斜槓。

1986\. What a great season.

5. 代碼框

• 行內代碼(inline code)：`<code>`

  inline <code>

• 塊代碼(block code)的寫法：簡單地縮進 4 個空格或是 1 個製表符
• Fenced Code Block 寫法是：第一行和最後一行都是3個 " ` "，中間的行是代碼，

  加上語言類型，代碼塊有高亮顯示

``` js
<code>
```

6. 分隔線

在一行中用三個以上的星號、減號、底線來創建一個分隔線，行內不能有其餘東西。也能夠在星號或是減號中間插入空格。下面每種寫法均可以創建分隔線：

* * *

***

*****

- - -

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

7. 表格

表格是我以爲 Markdown 比較累人的地方，例子以下：

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

這種語法生成的表格以下：

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

兩邊有冒號是居中，Cool 右邊有冒號是靠右對齊

2、區段元素

1. 連接

Markdown 支持兩種形式的連接語法： 行內式和參考式(連接標記、隱士連接標記)。
不論是哪種，連接文字都是用 [方括號] 來標記。

• 行內式

[連接文字](插入網址連接 "Title")

連接的 title 文字能夠不加：

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

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

若是連接到一樣主機的資源，你可使用相對路徑：

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

• 參考式

[連接文字][連接的標記]

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

能夠選擇性地在兩個方括號中間加上一個空格：

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

接着，在文件的任意處，你能夠把這個標記的連接內容定義出來：

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

連接內容定義的形式爲：

1. 方括號（前面能夠選擇性地加上至多三個空格來縮進），裏面輸入連接文字
2. 接着一個冒號
   
3. 接着一個以上的空格或製表符
   
4. 接着連接的網址
5. 選擇性地接着 title 內容，能夠用單引號、雙引號或是括弧包着

下面這三種連接的定義都是相同：

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

請注意：有一個已知的問題是 Markdown.pl 1.0.1 會忽略單引號包起來的連接 title。*

連接網址也能夠用方括號包起來：

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

你也能夠把 title 屬性放到下一行，也能夠加一些縮進，若網址太長的話，這樣會比較好看：

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

網址定義不會直接出如今文件之中。

連接標記能夠有字母、數字、空白和標點符號，可是並不區分大小寫，所以下面兩個連接是同樣的：

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

隱式連接標記

能夠省略指定連接標記，這種情形下，連接標記等同於連接文字，在連接文字後面加上一個空的方括號，若是要讓 "Google" 連接到 google.com，你能夠簡化成：

[Google][]

而後定義連接內容：

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

因爲連接文字可能包含空白，因此這種簡化型的標記內也許包含多個單詞：

Visit [Daring Fireball][] for more information.

而後接着定義連接：

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

連接的定義能夠放在文件中的任何一個地方,直接放在連接出現段落的後面，你也能夠把它放在文件最後面，就像是註解同樣。

下面是三種寫法的例子，提供做爲比較之用：

• 參考式連接的範例：

  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"

• 若是改爲用連接名稱的方式寫：

  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"

• 下面是用行內式寫

  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").

2. 強調

Markdown 使用星號（）和底線（_）做爲標記強調字詞的符號，被 或 包圍的字詞會被轉成用 <em> 標籤包圍，用兩個 * 或 包起來的話，則會被轉成 <strong>，例如：

*single asterisks*

_single underscores_

**double asterisks**

__double underscores__

會轉成：

<em>single asterisks</em>

<em>single underscores</em>

<strong>double asterisks</strong>

<strong>double underscores</strong>

強調也能夠直接插在文字中間：

un*frigging*believable

可是若是你的 * 和 _ 兩邊都有空白的話，它們就只會被當成普通的符號。

若是要在文字先後直接插入普通的星號或底線，你能夠用反斜線：

\*this text is surrounded by literal asterisks\*

3. 圖片

Markdown 使用一種和連接很類似的語法來標記圖片，一樣也容許兩種樣式： 行內式和參考式。

• 行內式

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

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

詳細敘述以下：

1. 一個驚歎號 !
2. 接着一個方括號，裏面放上圖片的替代文字
3. 接着一個普通括號，裏面放上圖片的網址，最後還能夠用引號包住並加上 選擇性的 'title' 文字。

• 參考式的圖片語法則長得像這樣：

![Alt text][id]

「id」是圖片參考的名稱，圖片參考的定義方式則和連結參考同樣：

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

到目前爲止， Markdown 尚未辦法指定圖片的寬高，若是你須要的話，你可使用普通的 <img> 標籤。

4. 其它

• 反斜槓

Markdown 能夠利用反斜槓來插入一些在語法中有其它意義的符號，例如：若是你想要用星號加在文字旁邊的方式來作出強調效果（但不用 <em> 標籤），你能夠在星號的前面加上反斜槓：

\*literal asterisks\*

Markdown 支持如下這些符號前面加上反斜槓來幫助插入普通的符號：

\   反斜線
`   反引號
*   星號
_   底線
{}  花括號
[]  方括號
()  括弧
#   井字號
+   加號
-   減號
.   英文句點
!   驚歎號

3、兼容 HTML

不在 Markdown 涵蓋範圍以內的標籤，均可以直接在文檔裏面用 HTML 撰寫。

只有一些 HTML 區塊元素――好比 <div>、<table>、<pre>、<p> 等標籤，必須在先後加上空行與其它內容區隔開，還要求它們的開始標籤與結尾標籤不能縮進。

Markdown 的生成器有足夠智能，不會在 HTML 區塊標籤外加上沒必要要的 <p> 標籤。

例子以下，在 Markdown 文件里加上一段 HTML 表格：

這是一個普通段落。

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

這是另外一個普通段落。

在 HTML 區塊標籤間的 Markdown 格式語法將不會被處理。好比，你在 HTML 區塊內使用 Markdown 樣式的 強調 會沒有效果。

HTML 的區段（行內）標籤如 <span>、<cite>、<del> 能夠在 Markdown 的段落、列表或是標題裏隨意使用。

依照我的習慣，甚至能夠不用 Markdown 格式，而直接採用 HTML 標籤來格式化。舉例說明：若是比較喜歡 HTML 的 <a> 或 <img> 標籤，能夠直接使用這些標籤，而不用 Markdown 提供的連接或是圖像標籤語法。

和處在 HTML 區塊標籤間不一樣，Markdown 語法在 HTML 區段標籤間是有效的。

例如：

<html>
<!--在這裏插入內容-->
<a href="http://www.baidu.com">百度一下</a>
</html>

<font face="黑體">我是黑體字</font>
<font face="微軟雅黑">我是微軟雅黑</font>
<font face="STCAIYUN">我是華文彩雲</font>
<font color=#0099ff size=12 face="黑體">黑體</font>
<font color=#00ffff size=3>null</font>
<font color=gray size=5>gray</font>

例如：怎樣用MarkDown寫一個npmjs裏面的README.md文檔？？？

README 應該是介紹code source 的一個概覽.其實這個靜態文件是有約定成俗的規範：

• 環境依賴
• 項目介紹
• 代碼實現了什麼功能?
• 特性
• 如何使用?
• 代碼組織架構是什麼樣的?
• 版本更新重要摘要

DEMO
===========================

###########環境依賴
node v0.10.28+
~

###########部署步驟
1. npm install  //安裝node運行環境

2. npm start  //使用

3. npm run build //前端編譯


###########目錄結構描述
├── Readme.md                   // help
├── config                         
├── src                      
│   ├── apps
│   ├── assets                
│   ├── common         
│   ├── components                
│   ├── routes                     
│   └── utils       
├── doc                         
├── .gitignore
├── .npmignore
├── .editorconfig
├── .gitattributes          
├── .stylelintrc.json
├── package.json
├── tsconfig.json              
├── tslint.json             
└── yarn.lock



###########V1.0.0 版本內容更新
1. 新功能     aaaaaaaaa
2. 新功能     bbbbbbbbb
3. 新功能     ccccccccc
4. 新功能     ddddddddd