Hello Octopress

Posted on Edited on

不可免俗的，Octopress 第一篇文章是 say hello。

在 Windows 上玩 Octopress + Github。

Prepare

要先裝好 Git 跟 Ruby 環境。Git 是用 Git for Windows，Ruby 環境則從從 http://rubyinstaller.org/downloads 下載 RubyInstaller 1.9.3 跟 Development kit 來安裝。

Development kit 下載後先解壓縮，用以下指令安裝：

1
2
3
$ cd <DEVKIT_INSTALL_DIR>
$ ruby dk.rb init
$ ruby dk.rb install

安裝完 Ruby 要在環境變數 PATH 加入 Ruby 的 bin 資料夾路徑，如 C:\Ruby193\bin。

Install Octopress

我直接用 Git Bash 下指令。

1
2
3
4
5
6
$ git clone git://github.com/imathis/octopress.git octopress
$ gem update --system
$ gem install bundler
$ cd octopress
$ bundle install
$ rake install

Configuration

編輯 _config.yml 可修改 blog 的主要設定。

Deploy 到 github

先建名稱為 username.github.com 的 repos。blog 建出來會位於 http://username.github.io 。

1
2
3
$ rake setup_github_pages
$ rake generate
$ rake deploy

第一步需輸入 github repos 的位置，例如：git@github.com:cjwind/cjwind.github.com.git

rake deploy 後會把產生出來的 blog push 到 master branch。

在 git repos 中會有兩個 branch，分別放產生頁面的 master 跟 source file 的 source。

將 source 加入 repos

將 source files 也 push 到 github 上。

1
2
3
$ git add .
$ git commit
$ git push origin source

Write Post

1
$ rake new_post["title"]

用以上指令產生新文章後，到 source/_posts 下用文字編輯器編輯生出來的檔案。

1
2
3
4
5
6
7
---
layout: post
title: "Hello"
date: 2014-03-15 23:11:22 +0800
comments: true
tags:
---

分類的寫法有幾種。一個分類：tags: programming，或多個分類：tags: [programming, tips]。

如果想當作草稿，可以加上 published: false。

上面那段之後就是內文了。如果想加上「閱讀全文」，只要在文章中加入 <!--more--> 即可。

寫好之後可以用 

1
$ rake preview

產生預覽，到 http://127.0.0.1:4000 看結果。

要發布的時候同樣先產生頁面再 deploy 到 github 上：

1
2
$ rake generate
$ rake deploy

Remove post

只要將 source/_posts/ 底下相對應的 .markdown 檔刪掉，之後 generate 時會刪掉對應的頁面。

貼 highlight code

安裝 Python，基於可能會有版本整合上的問題，還是先用 Python 2。裝完要在環境變數 PATH 加入 Python 的安裝路另，如 C:\Python27。如果沒裝 Python 而且文章中有 highlight code 語法，rake generate 不會有 error 但會生出空白頁。

inline 的語法：

1
` code snippet `

block 的語法：

1
[title] [url] [link text] [linenos:false] [start:#] [mark:#,#-#]
1
code snippet

有寫 language 就會 highlight。support 的 language

Write Page

1
$ rake new_page["page_name"]

以上指令會產生 source/page_name/index.markdown，編輯完成、產生頁面後，可從 /page_name 看。

將 Page 列在導覽列上

以 About page 為例，修改 source/_includes/custom/navigation.html，加入

1
<li><a href="{{ root_url }}/about">About</a></li>

加上分類列表

Download https://github.com/tokkonopapa/octopress-tagcloud，這個 plugin 有分類列表跟標籤雲。

將檔案解壓縮到 octopress 對應的資料夾。

修改 _config.yml

1
default_asides: [custom/asides/category_list.html, ...]

產生頁面

1
$ rake generate

Custom Domain

在 source/ 底下新增檔案 CNAME，內容是自訂 domain，例如 www.cjwind.idv.tw。

1
2
3
4
5
6
$ rake generate
$ rake deploy

$ git add .
$ git commit
$ git push origin source

設定 DNS，新增一 CNAME record，將 www.cjwind.idv.tw 指向 cjwind.github.io。如果要用最上層的 domain name，參考 Octopress 官網說明。

Troubleshooting

code highlight

有一次 rake generate 遇到 error：

1
pygments_code.rb:14:in `highlight': undefined method `[]' for nil:NilClass (NoMethodError)

原因不明，測試起來是某段 C code 造成的，可是看起來我寫的語法沒錯，google 之後砍掉 .pygments-cache/ 再重新 generate 就好了。

Ref