×

Octopress安装和配置

96
holaOla
2015.10.04 21:34* 字数 4255

安装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源文件,是博客的原始数据,以及一些模板文件。因此很有必要备份。用上述命令提交到github,这样就用git管理起来了,再也不用担心数据丢失了。

1.Ruby等依赖安装

Ruby 需要1.9.3版本的,同时由于Jekyll和octopress都是ruby写的,会有诸多ruby依赖,建议切换ruby源为国内源。对于git版本没有太大要求。

查看ruby版本

ruby --version  

如果版本符合要求则进入下一步,否则请参照官方手册安装ruby或者使用RVM来安装。

  • 安装bundler
    bundle可以自动解决依赖,安装方法如下:
gem install bundler  

建议国内用户切换gem源为国内源,方法如下:

gem source -r https://rubygems.org/ #删除官方源  
gem source -a http://ruby.taobao.org/  #添加淘宝源  
gem source -l #查看当前源  
  • 安装git
    如果已经安装git,执行命令返回值为具体版本,否则请自行安装git
git --version
#git version 1.9.1  

2.clone网站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的内容,添加到github账户中

然后clone网站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"  

然后执行命令bundle install就会自动安装所有octopress及其所有依赖。
注意: 如果上面的命令执行失败,提示下面的错误:

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)  

请执行下面的命令安装ruby1.9.1-dev

sudo apt-get install ruby1.9.1-dev  
  • 安装octopress默认主题
rake install  

在octopress根目录下的Rakefile定义了如何将octopress跟Jekyll连接起来,rake打包了一些常见的如发布博客主题、生成博客数据、发布博客等一系列命令来简化博主的操作。直接使用Jekyll每一个任务都需要不少命令和文件编辑。

  • tips:保持Jekyll最新
    由于Jekyll更新比较频繁,为了确保你在本地调试的时候看到的网站效果跟GitHub Pages上的一致,务必时常更新Jekyll,推荐使用bundle更新,命令如下:
bundle update  

4.部署到github

github pages支持托管,地址为https://pages.github.com/, 在这个页面你只需要大概了解一下什么是github page,如何申请就行了。

新建一个仓库,这里以your_user_name.github.io为例(当然也可以是project,这个方法有点不一样)。
在octopress根目录执行

rake setup_github_pages

按照要求输入仓库地址等,这个命令会在跟目录下新建_deploy目录,这个会push到仓库的master分支,也就是访问博客的文件。
生成博客, rake generate 这个会按照既定规则生成静态文件的博客。
发布博客,rake deploy 将前一步生成的文件拷贝到_deploy目录并push到github

  • 注意:第一次执行 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 

这样再次执行就不会报错了。

  • 博客本地预览
    如果在部署到仓库之前,需要先预览一下博客,可以在终端输入rake preview命令,然后就能在浏览器中进行本地预览访问了:127.0.0.1:4000localhost:4000,效果跟仓库中的一样。

  • 提交源码用于备份
    前面提到的deploy只是部署博客代码到github上面,整个octopress并没有提交,为了保证在任何地方随时发布博客,而无需再次详细配置以保证跟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已经预定义了脚本rake new_post[“title”]方便我们操作,因为Jekyll有一套固定的文档路径以及命名规范,需要按照它的规定来实现才能成功生成博文。博文必须存储在source/_posts目录下,并且需要按照Jekyll的命名规范对文章进行命名:YYYY-MM-DD-post-title.markdown。文章的名字会被当做url的一部分,而其中的日期用于对博文的区分和排序。

new_post执行后会自动新建博文,并在相应的markdown文件中写入yaml元数据。

---
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表明当前博文是草稿暂时不发布。

  • 发布博文完整流程:
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地址也会根据页面路径自动生成 ,如果要添加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

像发布博文一样,默认后缀依然是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。

  • 内容
    页面和博文会调用markup 引擎渲染,默认引擎是再配置文件中;此外,你可以使用任何Jekyll docs中所介绍的模板特性。

默认首页是显示全文,要想仅仅显示摘要,请在合适的地方插入下面的代码

<!-- more -->  

这个会生成一个Continue → 链接来指向完整博文,这个跟wordpress的一样。

7.用alfred命令创建新的Octopress post

在alfred的workflows里点+号,添加Templates-essentials-keyword to script,language选zsh,escaping里不要勾选space,在脚本里输入内容:

#!/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内容后,发布:

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[...]

原因是诸如"["、"]"之类的不是正确的命令字符。当然,我们也可以使用转义符来解决这一问题。但每次都需要敲入转义符,实在是太麻烦了。解决方案是在~/.zshrc文件下,加入这样一行内容:

alias rake="noglob rake"  
  • 解决中文乱码问题
    Octopress要创建一篇博客,可以直接运行rake new_post[“title”],它会在source/_post下创建一个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环境的问题,可以修改ruby环境下的setup_environment.bat文件,在文件最后加入2行:

set LC_ALL=en_US.UTF-8  
set LANG=en_US.UTF-8  
  • 中文博客名称的问题
    前面已经提到,rake new_post[“”]命令会将双引号引起来的标题作为blog链接的一部分。这就必然导致一个问题,就是我们无法在new_post[“”]命令中直接使用中文作为博客的标题。带来的问题是,我们每次都需要在创建了博客之后,再打开markdown文件,去修改文件前方的title内容为中文。这无疑增加了工作量。解决的办法很简单,因为new_post就是一个rake任务而已,我们可以参照该任务,创建一个自己的任务,添加一个新的参数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任务接收两个参数,第一个参数与之前的new_post任务需要的参数完全相同,第二个参数alias就可以设置到markdown文件的title:中。例如我们要建立一个博客,标题为“如何建立Octopress博客”,则可以输入命令:

rake post["How to create octopress blog","如何建立Octopress博客"]       

注意,除了第二个参数引号内的内容可以用中文外,其他字符包括双引号、逗号和中括号都应该是Utf-8字符。此外,Title和Alias之间用“,”隔开,“,”后不能加空格。

  • 图片问题

加入图片在Octopress中,支持的Markdown语法为:

{% img [position] [url] [width] [height] %}

position可以设置为left,right或center。url可以是网上的图片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 %}  
  • 摘要问题

如果希望在首页只显示一部分内容,例如摘要,也非常简单。只需要在你希望首页显示的内容最后,输入:

<!--more-->  

9.octopress配置

实际上octopress已经很好的隐藏了Jekyll的诸多配置,我们只需要简单操作几个文件。octopress就会自动生成相应的Jekyll配置。这里我们仅仅讲解一下_config.yml文件的部分配置项,具体请看官网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.

注释说明已经很详细了,有一点需要强调的是,如果你想启用自己的域名来访问,这里的url务必修改为你自己的域名,否则即便你添加了CNAME文件,使用rake部署的时候也不会部署该CNAME文件。

建议

最好把里面的twitter相关的信息全部删掉,否则由于GFW的原因,将会造成页面load很慢。涉及到的文件比较多,小心删除,如果以发表博客,_deploy目录下无需手动删除,重新生成博客后会自动删除。
同理,修改定制文件/source/_includes/custom/head.html 把google的自定义字体去掉。

  • 添加about me边栏

编辑 source_includes\custom\asides\about.html,内容如下:

<section>
 <h1>About Me</h1>
 <p>一句话自我介绍.</p>
 <p>新浪微博: <a href="http://weibo.com/soulmachine">@soulmachine</a><br/>
    Twitter: <a href="https://twitter.com/#!/soulmachine">@soulmachine</a><br/>
    Other: <a href="https://github.com/soulmachine">Github</a>, <a href="https://plus.google.com/103519507226474510310">Google+</a>, <a href="http://www.linkedin.com/in/soulmachine">LinkedIn</a>, <a href="http://www.quora.com/Jason-Day-2">Quora</a></p>
 </p>
</section> 

在 _config.yml 的 default_asides 里添加 custom/asides/about.html。

  • 添加about页面
rake new_page[about]  

会生成 source/about/index.markdown 文件。

编辑该文件的内容。

然后在头部导航菜单中添加页面的超链接。具体做法是编辑 /source/_includes/custom/navigation.html 文件。

  • 社会化分享

使用addthis.com的分享按钮,在网站上获取代码,粘贴到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="//s7.addthis.com/js/300/addthis_widget.js#pubid=undefined"></script>
 <!-- AddThis Button END -->

在_config.yml 中,将twitter, google+ 和facebook like的按钮设置为false,取消显示,因为 AddThis 已经集成了这三者。

  • 社会化评论

启用Disqus,填入 short name即可。 Disqus在国外流行,在国内的加载速度太慢,而且只有twitter, facebook, g+,没有照顾到国内的用户习惯,因此替换成国内的多说,如下:

```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       # 侧边栏评论显示条目数
duoshuo_asides_avatars: 1   # 侧边栏评论是否显示头像
duoshuo_asides_time: 1      # 侧边栏评论是否显示时间
duoshuo_asides_title: 1     # 侧边栏评论是否显示标题
duoshuo_asides_admin: 0     # 侧边栏评论是否显示作者评论
duoshuo_asides_length: 32   # 侧边栏评论截取的长度
  • 设置固定链接
    在 _config.yml 里,找到 permalink,设置如下:
permalink: /blog/:year:month:day/

效果就是 www.example.com/blog/20130403/ 。模仿的是豆瓣的URL格式。

参考官方文档 jekyll Permalinks。

  • 侧边栏显示分类目录
    使用第三方插件 octopress-tagcloud。

  • 友情链接
    在 source_includes\custom\asides 目录下添加一个blogroll.html文件,模仿about.html,添加一些友情链接,例如:

<section>
 <h1>友情链接</h1>
 <ul>
   <li>
     <a href="http://coolshell.cn/">酷壳CoolShell</a>
   </li>
   <li>
     <a href="http://mindhacks.cn/">刘未鹏MIND HACKS</a>
   </li>
   <li>
     <a href="http://blog.codingnow.com/">云风</a>
   </li>
   <li>
     <a href="http://www.cnblogs.com/Solstice/">陈硕</a>
   </li>
 </ul>
</section>

然后在 _config.yml 文件中,在 default_asides 的数组中添加custom/asides/blogroll.html

  • 修改字体
    Octopresss默认使用的是 google webfonts,见source/_includes/custom/head.html 里的两行代码。Google Webfonts是个好东西,但遗憾的是它没有中文字体。所以你用 粗体 ,发现并没有变粗,就是这个原因。

首先,将head.html中的两行代码注释掉,省去了加载字体,加快网页加载速度。

<!--Fonts from Google"s Web font directory at http://google.com/webfonts -->
<!-- <link href="http://fonts.googleapis.com/css?family=PT+Serif:regular,italic,bold,bolditalic" rel="stylesheet" type="text/css"> -->
<!-- <link href="http://fonts.googleapis.com/css?family=PT+Sans:regular,italic,bold,bolditalic" 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;

刷新网页,可以看见中文的粗体变黑了。

  • 一些汉化工作

在 _config.yml中,把Read on改为“继续阅读”。在source/_includes/custom/asides目录下,将”Recent Comments”改为“最新评论”,”Categories”改为“分类目录”,将source/_includes/asides/recent_posts.html 中”Recent Posts”改为“最新文章”。

  • 添加统计代码

在_config.yml填入 Google Analytics Tracking ID,例如 UA-7583537-4。

  • 第三方主题和插件

主题: 3rd Party Octopress Themes
插件: 3rd party plugins

  • 在一台新电脑上恢复

如果换了一台电脑,怎样迅速恢复环境呢?参考 Clone Your Octopress to Blog From Two Places。

注意,在windows上,要首先安装python,否则,虽然所有操作可以成功,不报错误,但是你发现打开后首页一篇空白,我当时百思不得其解,因为没有任何错误信息,最后去看生成的文件,所有index.html都是0字节,就猜测应该是编译出了问题。安装python就好了,linux默认是有Python的,就没有这个问题,windows真是坑爹!以后只在windows下做编辑类的工作,编译和运行都放到Linux下。

  • 嵌入代码块

见官方文档 Sharing Code Snippets。

Octopress是一款为hacker量身定制的博客系统,当然内置了代码高亮的功能!它的代码高亮功能是通过Pygments实现的,配色方案用的是Solarized,堪称完美。

Octopress支持多种方式嵌入代码,可以直接嵌入代码,也可以引用github上的gist。

开头用三个反引号空格加bash,结尾三个反引号,直接嵌入代码,比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 大部分支持,某些细节处理的不好,举个例子,它会在动把公式中的 ^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。

Mac
Web note ad 1