搜尋此網誌

2013-02-08

將靜態網頁上傳到 Github Pages

由於 project 可以設定自己的頁面,因此有些開放授權的書便把原始檔 host 在 github,順便開一個頁面,其中最有名的是創用 CC 授權的 Pro Git,書的原始碼在這邊

以 root 權限安裝 git。
apt-get install git
選擇要 clone 的 project,譬如︰https://github.com/user/repo.git。
git clone https://github.com/progit/progit.git
切入該目錄後,製作一分支 gh-pages(這是 Github Pages 預設的網頁分支名稱)。
git checkout --orphan gh-pages
如果 gh-pages 本來就存在,需要先把 github 上的檔案跟目錄同步。
git pull origin gh-pages
清除所有內容。
git rm -rf .
將相關的檔案放進來。
cp /from/files/directory /to/current/directory
將加進來的檔案與資料夾加入 git。
git add *
接著 commit 這些變動。
git commit -a -m "First pages commit"
最後是上傳到 github。
git push origin gh-pages
這時需要等候的幾分鐘,然後靜態網頁就完成了。由於可以使用 javascript,所以也不完全是靜態,而且沒有廣告,速度又快,想要分流給其他人改版也方便,算是目前放置開放授權創作最好的解決方案。

Reference:
Creating Project Pages manually
Generating SSH Keys

2013-02-06

markdown 的轉檔神器 - pandoc

pandoc

Haskell 寫的,所以邏輯性易讀性高於其他 imperative 的程式語言,同時在速度與可靠性上加分。

直接從 repositories 以 root 權限安裝。
apt-get install pandoc
把 source.md 轉為不含定義的 html 格式。
pandoc source.md -f markdown -t html -o output.html
把 source.md 轉為含定義的 html 格式,可以通過 W3C 的檢驗。
pandoc source.md -f markdown -s -t html -o output.html
把 source.md 轉為含定義的 html5 格式,可以通過 W3C 的檢驗。
pandoc source.md -f markdown -s -t html5 -o output.html
也可指定內嵌程式碼的配色主題,個人偏好暗色系背景,如 espresso 與 zenburn。
pandoc source.md -f markdown -s -t html5 --highlight-style espresso -o output.html
使用 mathjax 方案解決網頁的 LaTex 顯示問題。
pandoc source.md -f markdown -s -t html5 --mathjax -o output.html
使用 mathml 方案解決網頁的 LaTex 顯示問題,browser 相容性看這邊
pandoc source.md -f markdown -s -t html5 --mathml -o output.html
把 source.md 轉為 tex。
pandoc source.md -s -o output.tex
把 source.md 轉為 pdf。
pandoc source.md -o output.pdf
轉中文的 pdf 有點麻煩,直接轉的話會有斷行判斷錯誤的問題,我的解決方式是修改 default.latex,加入以下兩行。
\XeTeXlinebreaklocale "zh"
\XeTeXlinebreakskip = 0pt plus 1pt
如果要強迫 section 跟 subsection 要用 \LARGE 大小且置中,加入以下三行。
\usepackage{titlesec}
\titleformat{\section}{\LARGE\filcenter}{}{1em}{}
\titleformat{\subsection}{\Large\filcenter}{}{1em}{}
如果要在 LaTex 使用表格,加入這一行,然後在轉檔時加入 --toc;還有個小問題,到 LaTex 中將 pos = H 改為 pos = h。
\usepackage{ctable}
將 source.md 轉為 source.tex。
pandoc source.md -o source.tex --latex-engine=xelatex -V mainfont="WenQuanYi Micro Hei" -V fontsize=12pt --template=default.latex
接著修改 tex 檔的問題,目前已知的是 {enumerate}[1.] 需要改為 {enumerate}。然後轉檔為 pdf。
xelatex source.tex
其他格式與用法可以參考官方的範例

通用的文件轉換格式 - markdown

英文版
中文版

由於在製作文件時,我們想要盡量維持一致的稿件,但是可以輸出為多種格式,雖然 tex 文件製成的 pdf 檔也可以用 calibre 轉為其他電子書格式,但是轉出的檔案定義不夠明確,也不能生成 html 等網頁較喜歡的格式,因此在文件的撰寫上,採用 markdown 似乎是理所當然的。

至於學術用途的 tex 檔,也可以由 markdown 來轉,所以看來問題不大,可能會成為文件撰寫的主流,尤其是需要開放公眾授權的文件。