安裝Octopress步驟
git config --global user.name "name"
git config --global user.email "emailaddress"
cd ~
mkdir git
cd git
git clone git@github.com:name/name.github.io.git
cd ~/git
git clone git://github.com/imathis/octopress.git octopress
cd octopress
#修改Gemfile中源地址為ruby.taobao.org
bundle install
rake install
rake setup_github_pages
#輸入github.io.git地址
rake generate
rake preview #在http://localhost:4000
cd source/_deploy
git pull origin master #先同步一次，否則deploy可能報錯
cd ..
rake deploy #該命令首先清空_deploy目錄，然后將public目錄整個拷貝過來，然后commit到github。_deploy 目錄對應著master分支。
#備份source到github
git add .
git commit -m 'your message'
git push origin source #source 目錄下保存了所有的markdown源文件，是博客的原始數(shù)據(jù)，以及一些模板文件。因此很有必要備份。用上述命令提交到github，這樣就用git管理起來了，再也不用擔心數(shù)據(jù)丟失了。
1.Ruby等依賴安裝
Ruby 需要1.9.3版本的，同時由于Jekyll和octopress都是ruby寫的，會有諸多ruby依賴，建議切換ruby源為國內(nèi)源。對于git版本沒有太大要求。
查看ruby版本
ruby --version
如果版本符合要求則進入下一步，否則請參照官方手冊安裝ruby或者使用RVM來安裝。
- 安裝bundler
bundle可以自動解決依賴，安裝方法如下：
gem install bundler
建議國內(nèi)用戶切換gem源為國內(nèi)源，方法如下：
gem source -r https://rubygems.org/ #刪除官方源
gem source -a http://ruby.taobao.org/ #添加淘寶源
gem source -l #查看當前源
- 安裝git
如果已經(jīng)安裝git，執(zhí)行命令返回值為具體版本，否則請自行安裝git
git --version
#git version 1.9.1
2.clone網(wǎng)站repo
先設置git
git config --global user.name "name"
git config --global user.email "emailaddress"
然后生成ssh key
$ ssh-keygen -t rsa -C "emailaddress"
按3個回車，密碼為空。
復制~/.ssh/id_rsa.pub的內(nèi)容，添加到github賬戶中
然后clone網(wǎng)站repo
cd ~
mkdir git
cd git
git clone git@github.com:name/name.github.io.git
3.octopress安裝
octopress的安裝也比較簡單，下載源碼后會有Gemfile文件來指示所有依賴，使用bundle即可。
- 下載源碼
cd ~
cd git
git clone git://github.com/imathis/octopress.git octopress
cd octopress
- 安裝octopress
使用bundle自動安裝，先修改Gemfile中的源地址
source "http://ruby.taobao.org"
然后執(zhí)行命令bundle install就會自動安裝所有octopress及其所有依賴。
注意： 如果上面的命令執(zhí)行失敗，提示下面的錯誤：
Gem::Installer::ExtensionBuildError: ERROR: Failed to build gem native extension.
/usr/bin/ruby1.9.1 extconf.rb
/usr/lib/ruby/1.9.1/rubygems/custom_require.rb:36:in 'require': cannot load such file -- mkmf (LoadError)
請執(zhí)行下面的命令安裝ruby1.9.1-dev
sudo apt-get install ruby1.9.1-dev
- 安裝octopress默認主題
rake install
在octopress根目錄下的Rakefile定義了如何將octopress跟Jekyll連接起來，rake打包了一些常見的如發(fā)布博客主題、生成博客數(shù)據(jù)、發(fā)布博客等一系列命令來簡化博主的操作。直接使用Jekyll每一個任務都需要不少命令和文件編輯。
- tips：保持Jekyll最新
由于Jekyll更新比較頻繁，為了確保你在本地調(diào)試的時候看到的網(wǎng)站效果跟GitHub Pages上的一致，務必時常更新Jekyll，推薦使用bundle更新，命令如下：
bundle update
4.部署到github
github pages支持托管，地址為https://pages.github.com/, 在這個頁面你只需要大概了解一下什么是github page，如何申請就行了。
新建一個倉庫，這里以your_user_name.github.io為例(當然也可以是project，這個方法有點不一樣)。
在octopress根目錄執(zhí)行
rake setup_github_pages
按照要求輸入倉庫地址等，這個命令會在跟目錄下新建_deploy目錄，這個會push到倉庫的master分支，也就是訪問博客的文件。
生成博客， rake generate 這個會按照既定規(guī)則生成靜態(tài)文件的博客。
發(fā)布博客，rake deploy 將前一步生成的文件拷貝到_deploy目錄并push到github
- 注意：第一次執(zhí)行 rake deploy 的時候會報錯如下：
! [rejected] master -> master (non-fast-forward)
error: failed to push some refs to 'https://github.com/yeesterbunny/yeesterbunny.github.com.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Merge the remote changes (e.g. 'git pull')
hint: before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.
解決方法是手動進入_deploy目錄手動強制push一次。
cd octopress/_deploy
git pull origin master
cd ..
rake deploy
這樣再次執(zhí)行就不會報錯了。
博客本地預覽
如果在部署到倉庫之前，需要先預覽一下博客，可以在終端輸入rake preview命令，然后就能在瀏覽器中進行本地預覽訪問了：127.0.0.1:4000或localhost:4000，效果跟倉庫中的一樣。提交源碼用于備份
前面提到的deploy只是部署博客代碼到github上面，整個octopress并沒有提交，為了保證在任何地方隨時發(fā)布博客，而無需再次詳細配置以保證跟github上的最新代碼一致，可以將當前octopress的源碼存放到github的source分支下：
git add .
git commit -m 'Initial source commit'
git push origin source
5.安裝主題
cd ~/git
git clone git://github.com/bkutil/bootstrap-theme.git bootstrap-theme
rake install['bootstrap']
#rake install[bootstrap]/noglob rake install['bootstrap'] ,using zsh
rake generate
rake preview
6.新建博文
新建博文也非常簡單，octopress已經(jīng)預定義了腳本rake new_post[“title”]方便我們操作，因為Jekyll有一套固定的文檔路徑以及命名規(guī)范，需要按照它的規(guī)定來實現(xiàn)才能成功生成博文。博文必須存儲在source/_posts目錄下，并且需要按照Jekyll的命名規(guī)范對文章進行命名：YYYY-MM-DD-post-title.markdown。文章的名字會被當做url的一部分，而其中的日期用于對博文的區(qū)分和排序。
new_post執(zhí)行后會自動新建博文，并在相應的markdown文件中寫入yaml元數(shù)據(jù)。
---
layout: post
title: "title"
date: 2013-08-03 16:36
comments: true
categories:
---
這里的categories是自定義的分類名，支持的定義方式如下：
# One category
categories: Sass
# Multiple categories example 1
categories: [CSS3, Sass, Media Queries]
# Multiple categories example 2
categories:
- CSS3
- Sass
- Media Queries
除此之外，還支持author: Your Name來指明作者，支持 published: false表明當前博文是草稿暫時不發(fā)布。
- 發(fā)布博文完整流程：
rake new_post["New Post"]
#edit the file source/_posts/{DATETIME}-New-Post.markdown
rake generate
git add .
git commit -am "Some comment here."
git push origin source
rake deploy
- 新建頁面
你可以在博客源目錄下任意地方添加頁面，Jekyll會自動拼接，對應的url地址也會根據(jù)頁面路徑自動生成 ，如果要添加about.markdown ，那么就會生成 site.com/about.html ，如果你想要的url地址是 site.com/about/ ,你需要新建的頁面應該是 about/index.markdown .同樣的，octopress也有腳本完成這個操作。
rake new_page[super-awesome] # creates /source/super-awesome/index.markdown
rake new_page[super-awesome/page.html] # creates /source/super-awesome/page.html
像發(fā)布博文一樣，默認后綴依然是markdown，但是你可以再Rakefile中修改這個默認配置；一個干凈的頁面文件如下：
---
layout: page
title: "Super Awesome"
date: 2011-07-03 5:59
comments: true
sharing: true
footer: true
---
這里的title來自于文件名。你也可以手動修改。跟博文的一樣，除了不包含分類 categories，對于 sharing 和 comments 你可以關閉，對于 footer 你可以刪除，這樣就不會添加默認的footer信息到該頁面；如果你不像要再頁面中顯示日期，可以刪除這里的 date。
- 內(nèi)容
頁面和博文會調(diào)用markup 引擎渲染，默認引擎是再配置文件中；此外，你可以使用任何Jekyll docs中所介紹的模板特性。
默認首頁是顯示全文，要想僅僅顯示摘要，請在合適的地方插入下面的代碼
<!-- more -->
這個會生成一個Continue → 鏈接來指向完整博文，這個跟wordpress的一樣。
7.用alfred命令創(chuàng)建新的Octopress post
在alfred的workflows里點+號，添加Templates-essentials-keyword to script，language選zsh，escaping里不要勾選space，在腳本里輸入內(nèi)容：
#!/bin/bash
#Path for your octopress installation
octopath=/Users/sia/git/octopress
#Editor to open the post in. (Exact name of the .app bundle in your Applications folder)
editorapp=MacDown
if [[ -s "$HOME/.rvm/scripts/rvm" ]] ; then
source "$HOME/.rvm/scripts/rvm"
fi
cd $octopath
rvm use 1.9.3@octopress
octopost=$(noglob rake new_post["{query}"]| grep -o 'source/_posts/.*')
open -a "$editorapp" $octopath/$octopost
這里打開方式用了MacDown，由于zsh不支持中括號，rake new_post命令需要用noglob rake new_post。
編輯完成markdown內(nèi)容后，發(fā)布：
rake generate
git add .
git commit -am "Some comment here."
git push origin source
rake deploy
8.Octopress的一些常見問題
- 不能在ZSH中輸入命令的問題
Octopress提供了許多Rake任務，可以方便地完成一些操作。常用的命令是rake new_post[“title”]。但是在ZSH下，輸入這樣的命令，會提示錯誤：
zsh: no matches found: new_post[...]
原因是諸如"["、"]"之類的不是正確的命令字符。當然，我們也可以使用轉(zhuǎn)義符來解決這一問題。但每次都需要敲入轉(zhuǎn)義符，實在是太麻煩了。解決方案是在~/.zshrc文件下，加入這樣一行內(nèi)容：
alias rake="noglob rake"
- 解決中文亂碼問題
Octopress要創(chuàng)建一篇博客，可以直接運行rake new_post[“title”]，它會在source/_post下創(chuàng)建一個markdown文件。同時，它會將你輸入的title作為blog的鏈接URL。我們可以通過一些工具，例如EMacs或者MouApp（在Mac OS下）打開該文件進行編輯。但是，當我將markdown文件打開，修改title為中文，且輸入中文博客時，再運行rake generate生成博客頁面時，會報告編碼錯誤。
gems/ruby-1.9.2-p290/gems/jekyll-0.11.0/lib/jekyll/convertible.rb:32:in 'read_yaml': invalid byte sequence in US-ASCII (ArgumentError)
這是因為jekyll代碼沒有很好地支持多種編碼的緣故。解決辦法是找到提示信息中的convertible.rb文件，將第29行的如下代碼：
self.content = File.read(File.join(base, name))
修改為：
self.content = File.read(File.join(base, name), :encoding => "utf-8")
如果遇到ruby環(huán)境的問題，可以修改ruby環(huán)境下的setup_environment.bat文件，在文件最后加入2行：
set LC_ALL=en_US.UTF-8
set LANG=en_US.UTF-8
- 中文博客名稱的問題
前面已經(jīng)提到，rake new_post[“”]命令會將雙引號引起來的標題作為blog鏈接的一部分。這就必然導致一個問題，就是我們無法在new_post[“”]命令中直接使用中文作為博客的標題。帶來的問題是，我們每次都需要在創(chuàng)建了博客之后，再打開markdown文件，去修改文件前方的title內(nèi)容為中文。這無疑增加了工作量。解決的辦法很簡單，因為new_post就是一個rake任務而已，我們可以參照該任務，創(chuàng)建一個自己的任務，添加一個新的參數(shù)alias，將它作為我們需要的中文標題。
打開在octopress根目錄下的Rakefile文件，在文件末尾增加如下代碼
desc "Begin a new post in #{source_dir}/#{posts_dir} with Alias"
task :post, :title, :title_alias do |t, args|
raise "### You haven't set anything up yet. First run rake install to set up an Octopress theme." unless File.directory?(source_dir)
mkdir_p "#{source_dir}/#{posts_dir}"
args.with_defaults(:title => 'new-post')
title = args.title
title_alias = args.title_alias
filename = "#{source_dir}/#{posts_dir}/#{Time.now.strftime('%Y-%m-%d')}-#{title.to_url}.#{new_post_ext}"
if File.exist?(filename)
abort("rake aborted!") if ask("#{filename} already exists. Do you want to overwrite?", ['y', 'n']) == 'n'
end
puts "Creating new post: #{filename}"
open(filename, 'w') do |post|
post.puts "---"
post.puts "layout: post"
post.puts "title: \"#{title_alias}\""
post.puts "date: #{Time.now.strftime('%Y-%m-%d %H:%M')}"
post.puts "comments: true"
post.puts "categories: "
post.puts "---"
end
end
新的post任務接收兩個參數(shù)，第一個參數(shù)與之前的new_post任務需要的參數(shù)完全相同，第二個參數(shù)alias就可以設置到markdown文件的title:中。例如我們要建立一個博客，標題為“如何建立Octopress博客”，則可以輸入命令：
rake post["How to create octopress blog","如何建立Octopress博客"]
注意，除了第二個參數(shù)引號內(nèi)的內(nèi)容可以用中文外，其他字符包括雙引號、逗號和中括號都應該是Utf-8字符。此外，Title和Alias之間用“,”隔開，“,”后不能加空格。
- 圖片問題
加入圖片在Octopress中，支持的Markdown語法為：
{% img [position] [url] [width] [height] %}
position可以設置為left，right或center。url可以是網(wǎng)上的圖片url。如果是自己博客的圖片，通常建議放在source/images目錄下。為了將來更好地維護，建議按照年和月建立兩層目錄，如2012/12。因為rake generate命令會自動生成博客，放在source/images目錄下的圖片也會被復制過去。因而在markdown的img語法中，圖片的url應該是/images/2012/12/picture.jpg。
- 代碼問題
Octopress支持的代碼高亮有很多。我個人還是比較喜歡直接用codeblock標簽。雖然每次敲入這個codeblock不太方便，但它勝在靈活見解。例如，粘貼的代碼為ruby語言，就可以在代碼片段前后分別加上：
{% codeblock lang:ruby %}
# Here is ruby source code
{% endcodeblock %}
- 摘要問題
如果希望在首頁只顯示一部分內(nèi)容，例如摘要，也非常簡單。只需要在你希望首頁顯示的內(nèi)容最后，輸入：
<!--more-->
9.octopress配置
實際上octopress已經(jīng)很好的隱藏了Jekyll的諸多配置，我們只需要簡單操作幾個文件。octopress就會自動生成相應的Jekyll配置。這里我們僅僅講解一下_config.yml文件的部分配置項，具體請看官網(wǎng)Configuring Octopress。
該文件的配置分為三大部分:Main config、Jekyll&Plugin、3rd Party Settings。
Main config
url: # For rewriting urls for RSS, etc
title: # Used in the header and title tags
subtitle: # A description used in the header
author: # Your name, for RSS, Copyright, Metadata
simple_search: # Search engine for simple site search
description: # A default meta description for your site
date_format: # Format dates using Ruby's date strftime syntax
subscribe_rss: # Url for your blog's feed, defauts to /atom.xml
subscribe_email: # Url to subscribe by email (service required)
category_feeds: # Enable per category RSS feeds (defaults to false in 2.1)
email: # Email address for the RSS feed if you want it.
注釋說明已經(jīng)很詳細了，有一點需要強調(diào)的是，如果你想啟用自己的域名來訪問，這里的url務必修改為你自己的域名，否則即便你添加了CNAME文件，使用rake部署的時候也不會部署該CNAME文件。
建議：
最好把里面的twitter相關的信息全部刪掉，否則由于GFW的原因，將會造成頁面load很慢。涉及到的文件比較多，小心刪除，如果以發(fā)表博客，_deploy目錄下無需手動刪除，重新生成博客后會自動刪除。
同理，修改定制文件/source/_includes/custom/head.html 把google的自定義字體去掉。
- 添加about me邊欄
編輯 source_includes\custom\asides\about.html，內(nèi)容如下：
<section>
<h1>About Me</h1>
<p>一句話自我介紹.</p>
<p>新浪微博: <a >@soulmachine</a><br/>
Twitter: <a >@soulmachine</a><br/>
Other: <a >Github</a>, <a >Google+</a>, <a >LinkedIn</a>, <a >Quora</a></p>
</p>
</section>
在 _config.yml 的 default_asides 里添加 custom/asides/about.html。
- 添加about頁面
rake new_page[about]
會生成 source/about/index.markdown 文件。
編輯該文件的內(nèi)容。
然后在頭部導航菜單中添加頁面的超鏈接。具體做法是編輯 /source/_includes/custom/navigation.html 文件。
- 社會化分享
使用addthis.com的分享按鈕，在網(wǎng)站上獲取代碼，粘貼到source/_includes/post/sharing.html 中，例如我的代碼如下：
<div class="sharing">
<!-- AddThis Button BEGIN -->
<div class="addthis_toolbox addthis_default_style addthis_32x32_style">
<a class="addthis_button_sinaweibo"></a>
<a class="addthis_button_facebook"></a>
<a class="addthis_button_twitter"></a>
<a class="addthis_button_google_plusone_share"></a>
<a class="addthis_button_delicious"></a>
<a class="addthis_button_digg"></a>
<a class="addthis_button_reddit"></a>
<a class="addthis_button_compact"></a><a class="addthis_counter addthis_bubble_style"></a>
</div>
<script type="text/javascript" src="http://s7.addthis.com/js/300/addthis_widget.js#pubid=undefined"></script>
<!-- AddThis Button END -->
在_config.yml 中，將twitter, google+ 和facebook like的按鈕設置為false，取消顯示，因為 AddThis 已經(jīng)集成了這三者。
- 社會化評論
啟用Disqus，填入 short name即可。 Disqus在國外流行，在國內(nèi)的加載速度太慢，而且只有twitter, facebook, g+，沒有照顧到國內(nèi)的用戶習慣，因此替換成國內(nèi)的多說,如下：
```bash
<div class="ds-thread" data-title="我的Octopress配置"></div>
<script type="text/javascript">
var duoshuoQuery = {short_name:"yanjiuyanjiu"};
(function() {
var ds = document.createElement('script');
ds.type = 'text/javascript';ds.async = true;
ds.src = 'http://static.duoshuo.com/embed.js';
ds.charset = 'UTF-8';
(document.getElementsByTagName('head')[0]
|| document.getElementsByTagName('body')[0]).appendChild(ds);
})();
</script>
_config.yml 中的配置也略有不同：
```bash
duoshuo_comments: true
duoshuo_short_name: yanjiuyanjiu
duoshuo_asides_num: 5 # 側(cè)邊欄評論顯示條目數(shù)
duoshuo_asides_avatars: 1 # 側(cè)邊欄評論是否顯示頭像
duoshuo_asides_time: 1 # 側(cè)邊欄評論是否顯示時間
duoshuo_asides_title: 1 # 側(cè)邊欄評論是否顯示標題
duoshuo_asides_admin: 0 # 側(cè)邊欄評論是否顯示作者評論
duoshuo_asides_length: 32 # 側(cè)邊欄評論截取的長度
- 設置固定鏈接
在 _config.yml 里，找到 permalink，設置如下：
permalink: /blog/:year:month:day/
效果就是 www.example.com/blog/20130403/ 。模仿的是豆瓣的URL格式。
參考官方文檔 jekyll Permalinks。
側(cè)邊欄顯示分類目錄
使用第三方插件 octopress-tagcloud。友情鏈接
在 source_includes\custom\asides 目錄下添加一個blogroll.html文件，模仿about.html，添加一些友情鏈接，例如：
<section>
<h1>友情鏈接</h1>
<ul>
<li>
<a >酷殼CoolShell</a>
</li>
<li>
<a >劉未鵬MIND HACKS</a>
</li>
<li>
<a >云風</a>
</li>
<li>
<a >陳碩</a>
</li>
</ul>
</section>
然后在 _config.yml 文件中，在 default_asides 的數(shù)組中添加custom/asides/blogroll.html
- 修改字體
Octopresss默認使用的是 google webfonts，見source/_includes/custom/head.html 里的兩行代碼。Google Webfonts是個好東西，但遺憾的是它沒有中文字體。所以你用 粗體 ，發(fā)現(xiàn)并沒有變粗，就是這個原因。
首先，將head.html中的兩行代碼注釋掉，省去了加載字體，加快網(wǎng)頁加載速度。
<!--Fonts from Google"s Web font directory at http://google.com/webfonts -->
<!-- <link rel="stylesheet" type="text/css"> -->
<!-- <link rel="stylesheet" type="text/css"> -->
參考 這篇博客 最佳 Web 中文默認字體 ，在 sass/custom/_fonts.scss 中添加如下三行代碼：
$heading-font-family: arial, sans-serif;
$header-title-font-family: arial, sans-serif;
$header-subtitle-font-family: arial, sans-serif;
刷新網(wǎng)頁，可以看見中文的粗體變黑了。
- 一些漢化工作
在 _config.yml中，把Read on改為“繼續(xù)閱讀”。在source/_includes/custom/asides目錄下，將”Recent Comments”改為“最新評論”，”Categories”改為“分類目錄”，將source/_includes/asides/recent_posts.html 中”Recent Posts”改為“最新文章”。
- 添加統(tǒng)計代碼
在_config.yml填入 Google Analytics Tracking ID，例如 UA-7583537-4。
- 第三方主題和插件
主題： 3rd Party Octopress Themes
插件： 3rd party plugins
- 在一臺新電腦上恢復
如果換了一臺電腦，怎樣迅速恢復環(huán)境呢？參考 Clone Your Octopress to Blog From Two Places。
注意，在windows上，要首先安裝python，否則，雖然所有操作可以成功，不報錯誤，但是你發(fā)現(xiàn)打開后首頁一篇空白，我當時百思不得其解，因為沒有任何錯誤信息，最后去看生成的文件，所有index.html都是0字節(jié)，就猜測應該是編譯出了問題。安裝python就好了，linux默認是有Python的，就沒有這個問題，windows真是坑爹！以后只在windows下做編輯類的工作，編譯和運行都放到Linux下。
- 嵌入代碼塊
見官方文檔 Sharing Code Snippets。
Octopress是一款為hacker量身定制的博客系統(tǒng)，當然內(nèi)置了代碼高亮的功能！它的代碼高亮功能是通過Pygments實現(xiàn)的，配色方案用的是Solarized，堪稱完美。
Octopress支持多種方式嵌入代碼，可以直接嵌入代碼，也可以引用github上的gist。
開頭用三個反引號空格加bash，結(jié)尾三個反引號，直接嵌入代碼，比codeblock要簡潔。
- 啟用MathJax
在 source/_includes/custom/footer.html 的第一行加入如下代碼：
<!-- mathjax config similar to math.stackexchange -->
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
jax: ["input/TeX", "output/HTML-CSS"],
tex2jax: {
inlineMath: [ ['$', '$'] ],
displayMath: [ ['$$', '$$']],
processEscapes: true,
skipTags: ['script', 'noscript', 'style', 'textarea', 'pre', 'code']
},
messageStyle: "none",
"HTML-CSS": { preferredFont: "TeX", availableFonts: ["STIX","TeX"] }
});
</script>
<script src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML"
這樣就引入了MathJax的JS包，可以直接在markdown文件里直接寫公式了，例如 $\dfrac {\pi}{2}$。
上面的代碼也可以在 source/_includes/custom/header.html 里添加，不過這樣會使得頁面的加載速度變慢。還可以在 source/_layouts/default.html里添加。
有一個問題，rdiscount這個解析器，對 mathjax 大部分支持，某些細節(jié)處理的不好，舉個例子，它會在動把公式中的 ^n 轉(zhuǎn)換成 n ，例如 $2^n$ 會解析成 $2n$ ，這樣就破壞了整個公式，導致公式無法解析。參考這里一段話：
> as discount for example automatically replaces x^2 withx2 which interrupts the MathJax rendering.
因此要換一個解析器， Maruku 和 Kramdown 都可以，由于Maruku主頁PR=4，Kramdown的主頁PR=5，因此選擇Kramdown。
