自從使用了markdown，做文件工作就很順手。我幾乎將工作中所有的文件工作都用markdown來完成。最近有了一些新的體驗，也發現了一些新的問題。

在Linux系統中，編輯markdown可以用retext工具：

# Debian/Ubuntu
sudo apt-get install retext
retext Release-Notes.md

要將markdown檔案轉換成html檔案，可以用discount或python-markdown軟體包提供的markdown：

# Debian/Ubuntu
sudo apt-get install discount

或：

# Debian/Ubuntu
 

sudo apt-get install python-markdown

轉換工作很簡單：

# 用discount提供的markdown工具
markdown -o Release-Notes.html Release-Notes.md
# 用python-markdown提供的markdown_py工具
markdown_py -o html4 Release-Notest.md > Release-Notes.html

如果要生成PDF，也很簡單，可以用python-pisa提供的xhtml2pdf：

# Debian/Ubuntu
sudo apt-get install python-pisa

# 將html轉換成PDF
 

xhtml2pdf --html Release-Notes.html Release-Notes.pdf

所以，你可以在文件目錄下放置這樣一個Makefile來自動這個過程：

# Makefile

MD = markdown
MDFLAGS = -T
H2P = xhtml2pdf
H2PFLAGS = --html
SOURCES := $(wildcard *.md)
OBJECTS := $(patsubst %.md, %.html, $(wildcard *.md))
OBJECTS_PDF := $(patsubst %.md, %.pdf, $(wildcard *.
 
md))

all: build

build: html pdf

pdf: $(OBJECTS_PDF)

html: $(OBJECTS)

$(OBJECTS_PDF): %.pdf: %.html
    $(H2P) $(H2PFLAGS) $< > [email protected] 

$(OBJECTS): %.html: %.md
    $(MD) $(MDFLAGS) -o [email protected] $<
clean:
    rm -f $(OBJECTS)

這樣你就可以通過簡單的一個命令生成當前目錄下所有md檔案的pdf或html輸出了：

# html 輸出
make html

# pdf輸出
make pdf

這裡有個問題是如果markdown的內容是中文，那麼轉換出來的html在瀏覽器中開啟就無法自動識別編碼，pdf更慘，直接是一堆亂碼。這時我們可以藉助markdown對html標記的支援來在markdown檔案中加入編碼資訊。例如我們要將markdown轉換為html4檔案，可以在檔案的開頭加上meta標記，指明編碼格式：

sed -i '1i\<meta http-equiv="content-type" content="text/html; charset=UTF-8">' *.md

這樣就可以了。另外，最近使用圖靈社群的編輯系統時，markdown會時不時將下劃線（_）當作斜體的標記，結果函式名就成了這樣的：

# 實際上是ssl_use_cabundle
sslusecabundle

我建議斜體字標記採用單個星號（），加粗字型採用兩個星號（），這樣使用起來就方便多了。當然，這個問題本身在於markdown說用星號或下劃線都可以。但實際上，兩個都支援反倒會造成一些問題。比如有的地方用下劃線（粗體 -> 粗體），有的地方用星號（粗體* -> 粗體），看起來反倒混亂不堪（選星號*的另一個理由是下劃線在內容中出現的概率比星號高很多）。

建議圖靈社群的線上編輯系統指定其中一種，然後在例子中和線上編輯器裡都採用統一的一種，這樣大多數人一看就明白該用哪種了。