Markdown Guide

Markdown是"文字轉HTML"的語法,利用在文字中加入簡單的符號來告訴系統如何建構HTML。這樣的寫法可以讓使用者在撰寫Plain Text(純文字)文件時,達到"easy-to-read"和"easy-to-write"的好處。您可以到Daring Fireball: Markdown Syntax Documentation找到更多關於Markdown的資訊。

為什麼使用Markdown

Easy-to-write(容易寫):撰寫Markdown比您直接寫HTML簡單、快速又直覺,您不需要學習HTML語法,也可讓您的文章有HTML的版型和CSS樣式。不像傳統網頁樣式編輯器,您要一直使用滑鼠圈選和改變樣式,使用Markdown就算在沒有滑鼠的環境,如手機、平板,也可以快速撰寫文章。

Easy-to-read(容易讀):在一些開發端的環境,如純文字介面,您是沒有辦法開啟Word、PDF或是網頁等格式的檔案。在這種情況Plain Text是唯一能夠使用的檔案格式,因此您無須擔心使否能開起檔案。另外,Markdown的語法會強制您寫出容易讀的檔案,即使您沒有將它轉成漂亮的HTML,您還是可以看得懂。

Consistency(一致性):傳統網頁您可以自由使用網頁編輯器,將文章內容改成您喜歡的樣子,但對於需要多人維護的平台這是很大的麻煩。因為這會讓平台變得雜亂無章,甚至讓使用者誤解。Markdown會讓每個人寫出的格式一致,如此可以讓文章的美工交給專業人士設計,使所有網頁格式一致。如果網頁樣式需要修改,新的樣式也可以很輕易的套用在所有舊文章上。

Markdown語法

Headers

Markdown支援兩種Header的寫法

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

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

任何長度的"="或"-"都可以,但他必須在您的標題之下。

# This is an H1

## This is an H2

###### This is an H6

Bold, Italic, Delete

Markdown當然也支援粗體斜體刪除

**Blod**
*Italic*
***Bold and Italic***
~~Delete~~

Blod

Italic

Bold and Italic

Delete


Lists

Markdown支援數字開頭或符號開頭lists,

您可以使用"*""-""+"加上空白來建立list

* Red
* Green
* Blue

= Red = Green = Blue

您也可使用數字來建立,但是數字本身不會影響list的順序

1. Red  
2. Green  
1. Blue  
  1. Red
  2. Green
  3. Blue

如您希望將元件放入list,您只需要用空白鍵縮排

1. lines  
  Lorem ipsum dolor sit amet, consectetur adipisicing elit
2. number list  
  1. aaaa
  2. bbbb
  3. cccc
3. bulleted list  
  * aaaa
  * bbbb
  * cccc
  1. lines
    Lorem ipsum dolor sit amet, consectetur adipisicing elit
  2. number list
    1. aaaa
    2. bbbb
    3. cccc
  3. bulleted list
    • aaaa
    • bbbb
    • cccc

連結的使用有很多種,這邊指介紹兩種主要方式。基本使用方式為文字,請參考下方實例:

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

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

This is an example inline link.

This link has no title attribute.

如果您的連結要使用很多次,您也可以用參照的方式編寫:

This is [Geego Official][0] reference-style link.  
This is [Geego Blog][1] reference-style link.

[0]: http://www.geego.com.tw/ "Geego Official Site"
[1]: http://blog.geego.com/ "Geego Blog"

This is Geego Official reference-style link 官方網站.
This is Geego Blog reference-style link 部落格.

如果您想了解所有只用方式,請到Daring Fireball: Markdown Syntax Documentation


Images

圖片的插入跟聯結有點像,但須在前面多加"!"

![Geego Logo](http://blog.geego.com/content/images/2015/08/geego_logo.png)  

Geego Logo

當然,您也可以用參照的方式編寫,會得到跟上面一樣的結果。

![Geego Logo][5]  


[5]: http://blog.geego.com/content/images/2015/08/geego_logo.png

Horizontal Rules

您可以用以下方式加入分隔線:

* * *

***

*****

- - -

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

基本上只要三個以上的符號就會轉為水平線了。


Blockquotes

Blockquote常見在email中,引用別封信件的區塊,在網頁中常用作引言的區塊。您可以巢狀的塞入其他Markdown語法包含headers, lists, and code blocks:

> Lorem ipsum dolor sit amet, consectetur adipisicing elit, 
> sed do eiusmod tempor incididunt ut labore et dolore magna
>
> 1. aliqua. Ut enim ad minim veniam, quis nostrud exercitation 
> 2. ullamco laboris nisi ut aliquip ex ea commodo consequat. 
>
> Duis aute irure dolor in reprehenderit in voluptate velit 
> esse cillum dolore eu fugiat nulla pariatur. Excepteur sint
> > occaecat cupidatat non proident, sunt in culpa qui officia 
> > deserunt mollit anim id est laborum.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna

  1. aliqua. Ut enim ad minim veniam, quis nostrud exercitation
  2. ullamco laboris nisi ut aliquip ex ea commodo consequat.

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint

occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.


Code Block

Code Block對電腦工程師來說非常重要,很多重要的文件都會有相關的指令或設定檔。如果只單純使用純文字會相當難以辨識。Markdown提供Code Block語法,讓您輕鬆將程式碼或指令插入文章中,並可另外加入行號及程式語言專屬的色碼。

如果您要將指令插入文字中,請使用"``"包起來。

  
`ifconfig | grep netmask`

ifconfig | grep netmask

如您需要多行的程式區塊,請用"```"包在頭尾。

  
```  
#!/usr/bin/env python

print("Hello World");  
```  
#!/usr/bin/env python

print("Hello World");  

如果使用的平台支援,您可以加入其他參數讓Code Block看起來更專業

  
```python line-numbers  
#!/usr/bin/env python

print("Hello World");  
```  
#!/usr/bin/env python

print("Hello World");  

HTML Tags

Markdown接受HTML格式,如果您知道如何使用HTML Tag,您也可以直接撰寫HTML Tag。

<p>This is HTML tag</p>  

This is HTML tag


結語

Markdown真的是非常好用的文件撰寫語法,本文也是以Markdown的語法撰寫出來的。以上說明希望能讓大家了解Markdown的使用方式。如您覺得不錯,歡迎分享給需要的人,不過需要麻煩您註明出處。如有什麼需要改正的地方,或是您有任何問題,歡迎您給我們建議與指教,您可以在下方留言,或請直接來信,我們會盡力提供更多新鮮的教學文件,非常感謝您!