顯示具有 markdown 標籤的文章。 顯示所有文章
顯示具有 markdown 標籤的文章。 顯示所有文章
2012年2月10日

Blogging with Markdown

用 Markdown 寫部落格

前陣子比較了一些輕量級標記語言,想作為之後自己撰寫文件的格式依據。其中 reStructuredText 太過複雜,就不考慮了;剩下的 AsciiDoc 與 Markdown 兩者中,剛開始我比較喜歡 AsciiDoc 多一些。因為 AsciiDoc 有支援表格的語法,而 Markdown 則必須透過 Inline HTML 的方式,這麼一來如果文章中想包含表格,免不了還是得塞入一堆礙眼的 HTML 語法。

不過比起 AsciiDoc, Markdown 的應用支援顯然要來得廣泛得多,除了 GitHub 與 BitBucket 等網站外,有相當多的工具或編輯器支援 Markdown 語法,例如 Day One, iA Writer 或是 Byword,這方面壓倒性勝過 AsciiDoc。於是乎 Markdown 便逐漸成為我的首選,至於不能製作表格的問題嘛,反正作表格的機會也不是那麼多,大部分時候也可以用清單方式來呈現資料,所以倒不是太大問題。

決定用 Markdown 作為主要規範後,第一個想到的就是用 Markdown 來寫 blog。不過 blogger 本身沒有支援 Markdown 語法,也沒有外掛或工具支援直接將 Markdown 寫好的文章發佈。大部分用 Markdown 在 blogger 寫文章的方式,都與 Notely: How to use Markdown in Blogspot posts 這篇文章的作業流程大同小異:

  1. 在你的電腦中用文字編輯器撰寫文章並儲存成檔案(原作者 Joel 使用 yyyy-mm-dd post title.txt 的檔案命名方式)
  2. 開啟 Daring Fireball: Markdown Web Dingus 網站,複製貼上文章內容,進行轉換。
  3. 最後,將轉換完成的 HTML 碼貼到 blogspot 的新文章中。

另外,貼上時要注意以下兩點:

  1. 在貼上新文章時,確定文字輸入區上方的模式是在「HTML」下而非「撰寫」。
  2. 開啟右側「文章設定」最下方的選項,
    1. 「撰寫模式」勾選解譯輸入的 HTML
    2. 「換行符號」勾選使用 <br> 標記

我目前也是採用類似的流程。比較特別要提的有以下幾點:

  1. 標題除了作為檔名外,檔案內的第一行也會放上一級標題;最後一行則是列出這篇文章的標籤。所以在轉換為 HTML 時,要去首尾行。
  2. 檔案存放在 dropbox 空間中。這樣可以確保文章有多份備份。
  3. 文章是用 iA Writer 寫的。寫完之後用〈在 OS X 中隨時隨地將 Markdown 轉為 HTML〉這一篇提到的方法轉換為 HTML 碼,這樣就不用再開啟線上轉換的網頁了。

這篇文章就是用上述流程所寫的,你可以到這邊看看原始模樣

在 OS X 中隨時隨地將 Markdown 轉為 HTML

很多人喜歡用 Markdown 寫純文字的文件,包括我。簡單又有規範,而且幾乎所有文書軟體/編輯器都可以開啟(應該沒有不支援純文字的編輯器吧?),也可以轉成 HTML 在網路上發表。

在 Markdown 作者 John Gruber 的網站上有提供了一個 perl 寫的 Markdown 轉換指令稿,可以將 Markdown 轉換成 HTML。不過每次要轉檔都要進終端機下指令也是麻煩,今天剛好看到一篇文章,可以在 OS X 中加入一項服務,透過該服務,任何只要提供文字編輯的應用程式,都可以經由右鍵選單輕鬆將 Markdown 轉換成 HTML。

原始文章:
Installing Markdown as an OS X Services Menu Item Using Automator

懶得看原文的也可以看下面步驟。原文中的作法是將轉好的 HTML 直接取代掉原始 Markdown,因為我的需求不同,所以以下的步驟還會加上將轉好的 HTML 放到剪貼簿中。

先下載 John Gruber 所寫轉換指令稿:Markdown.pl
下載後找個地方存放,我是放在 "/usr/local/bin/" 下面。

然後開啟 Automator,選擇新增一項「服務」

automator service

接著會在視窗中看到如下內容。勾選「輸出會取代所選文字」,如果你只複製到剪貼簿而不需替換掉原本文字,可以不用勾選。

replace selected text

在左側程式庫列表中找到「執行 Shell 工序指令」,拉到右側。然後在文字區域中輸入 "/usr/local/bin/Markdown.pl" (請依照下載時所存放位置作適當修改)

run shell script

type the path

如果只是要產生 HTML 碼,到上個步驟就可以了。若還要把轉換後的 HTML 存到剪貼簿中,一樣在左側程式庫列表中找到「拷貝到剪貼板」,然後拉到右側剛剛的指令下方。

copy to clipboard

存檔,大功告成!

save and finish

接下來實驗看看。打開「文字編輯」或是任何可以編寫純文字的程式,隨便打一段 Markdown 指令。輸入完後全選,叫出右鍵選單,可以看到我們剛才辛苦的結晶:

markdown to html

用力給他按下去--噹啦~全部變成 HTML 了,很方便不是?

markdown to html converted

2011年10月18日

輕量級標記語言 - AsciiDoc, Markdown, reStructuredText

因為最近使用 GitHub 的關係,注意到了 Markdown 這個輕量級標記語言 (Lightweight markup language),跟著查了一下資料才發現原來輕量級標記語言的選項百百款,其中比較常見的有 Markdown, reStructuredText 以及 textile,這三種語法也同時被 BitBucket 和 GitHub 所支援。

稍微看過三者的語法比較後,覺得 textile 的語法太過接近 HTML, 使得文字檔本身無法呈現容易理解的架構。而除了前述三者之外,也另外注意到 AsciiDoc 這一款輕量級標記語言,GitHub 有支援 AsciiDoc。下面就是我對 Markdown, reStructuredText 與 AsciiDoc 的一些比較筆記:

Markdown
使用最為廣泛也最簡單的輕量級標記語言。除了前面提到的 GitHub 與 BitBucket 之外,StackOverflow 的語法基本上也是 Markdown 的強化版,另外 Tumblr 與 Posterous 這兩個輕量級的 blog 也都支援 Markdown 語法。

然而正如前面所提到的,StackOverflow 用的是修改過的 Markdown, 實際上 GitHub 用的也是 Markdown 的修改版本。Markdown 簡單卻又略顯不足,使得許多網站的應用必須增添額外的修改。另外,缺乏表格功能的支援是最大的遺憾。

reStructuredText
以 Python 寫成,主要也使用於 Python 社群中;Python 的文件產生器 Sphinx 就是以 reStructuredText 為基礎。是三者之中功能最為完整的一套,事實上,即便要說是所有輕量級標記語言中功能最為完整的一套也不為過,要拿來寫論文也不成問題。腳注 (footnote) 功能讓人眼睛一亮。不過真的是太複雜了,快要脫離「輕量級」的範圍了。

AsciiDoc
跟 reStructuredText 同樣也是 Python 寫成,不過語法上比較接近 Markdown 的簡單,但也提供了表格的功能。會讓我注意到這一套,最主要原因是因為開源遊戲韋諾之戰 (The Battle for Wesnoth) 的 Manual 就是以 AsciiDoc 所寫成。

線上工具

BitBucket 的 README 支援列表,主要就是以 reStructuredText, Markdown, Textile 這三種為主,README 和 README.txt 這兩個檔名預設為 Plain Text, 不過如果該專案所使用的語言為 Python 的話,上述兩個檔案則會以 reStructuredText 的格式去轉為網頁。

GitHub 支援的格式 比較多種,其中 Markdown 應該是最優先的,從許多專案的 README 都是以 .md 作為檔名後綴不難看出。有趣的是 GitHub 是以 Ruby 開發,然而在 Ruby 社群中比較活躍的輕量標記語言其實是 textile。(順帶一提,BitBucket 是以 Python 開發,Mercurial 也是以 Python 開發的)

10.21 補充:根據 AcsiiDoc 官網上記載,Git User's Manual 也是以 AsciiDoc 所製作。
Related Posts Plugin for WordPress, Blogger...