博客基础

Octopress提供一些创建文章和页面的rake任务，而这些文章和页面会根据jekyll的命名规则和元数据预先装载。它也会为你的文章生成基于feed的分类和全局(你能在atom.xml以及blog/categories/<category>/atom.xml发现他们)。

博客文章

博客文章必须被保存在source/_posts文件夹，而且必须按照jekyll的命名规则来命名：YYYY-MM-DD-post-title.markdown。这个文件的名字将被解析做为url的级数，（译者注：例如文件名字是2014-10-10-test.markdown，url将是：/blog/2014/10/10/test,其实这个url解析设置是可以修改的），文章名称中间的时间帮助文件区别和决定对文章排序顺序。

Octopress 提供一个rake任务，这个任务使用一个正确的命名约定以及合理的yaml元数据来创建新的文章。

语法

new_post

rake new_post["title"]

new_post当创建一个文件名时，需要一个自然的文件名，同时会剥离不良的url字符。新文章的默认文件扩展名是markdown，但是你能在Rakefile里配置它。

例子

new_post

rake new_post["Zombie Ninjas Attack: A survivor's retrospective"]
# 创建 source/_posts/2011-07-03-zombie-ninjas-attack-a-survivors-retrospective.markdown

文件名决定你的访问url。使用默认的永久链接设置，访问地址会像如下：http://site.com/blog/2011/07/03/zombie-ninjas-attack-a-survivors-retrospective/index.html。

在一个文本编辑器里打开一篇文章，你会在文章最前面看到一块yaml头信息，这块代码告诉Jekyll如何处理文章和页面。

yaml头信息

layout: post
title: "Zombie Ninjas Attack: A survivor's retrospective"
date: 2011-07-03 5:59
comments: true
external-url:
categories:

在这里，你可以给你的文章关掉评论或者分类。假如你的文章有多个作者，你可以加author: Your Name到头信息的元数据。假如你正在做草稿，你能加published: false到头信息，预防在生成博客的时候，也将草稿生成文章。假如你想发布一个linklog形式的文章(博客条目指向外部链接)，只需简单的加一个external-url到你的文章。

你能加一个或者多个分类：

yaml头信息

# One category
categories: Sass

# Multiple categories example 1
categories: [CSS3, Sass, Media Queries]

# Multiple categories example 2
categories:
- CSS3
- Sass
- Media Queries

新页面

你能在你博客源目录的任何地方加一个新页面，它们都会被jekyll解析。URL将正确的指向文件路径，所以about.markdown将变成site.com/about.html。假如你喜欢你的url是site.com/about/，那么你要创建的页面为about/index.markdown。也有一个很简单的rake任务来生成页面。

new_page

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文件里配置它。一个刚生成的页面可能是这样子的：

new_page

layout: page
title: "Super Awesome"
date: 2011-07-03 5:59
comments: true
sharing: true
footer: true

标题是从文件名衍生出来的，所以你可能想改变它。这根生成一个新文章是一样的，除了不包含分类，你可以切换分享以及评论或者干脆移除底部。假如你不想在页面显示时间，你从yaml移除它就是了。

内容

网页和文章将被你网站配置文件指定的markup引擎渲染。此外你能使用在 Jekyll 文章里描述的任何 liquid模板功能。

插入一个<!-- more -->标签到你的文章，将会预防这篇文章这个标签底下的部分显示在你的博客首页。一个Continue →的按钮链接到整篇文章。

生成和预览

生成和预览

rake generate   # Generates posts and pages into the public directory
rake watch      # Watches source/ and sass/ for changes and regenerates
rake preview    # Watches, and mounts a webserver at http://localhost:4000

假如你不想发布这篇文章，而又想生成博客。你可以加published: false，到你文章的YAML头。你可以通过rake preview在你本地服务器预览这篇文章，但是不会被发布，通过rake generate这个命令。

使用rake preview命令是很棒的，因为可以预览。但是假如你有一个POW服务，你能像下面这样设置Octopress：

POW设置Octopress

cd ~/.pow
ln -s /path/to/octopress octopress
cd -

现在你安装好POW，你只要运行rake watch和装载http://octopress.dev就可以了，代替使用rake preview命令。

也可以看分享代码片段和博客插件。

Octopress配置

我尝试着让octopress的配置尽量简单，你很可能只需要修改rakefile以及_config.yml。底下是octopress配置文件的列表：

octopress配置文件列表

    _config.yml       # 主要配置文件 (Jekyll的设置)
    Rakefile          # 部署配置
    config.rb         # Compass配置
    config.ru         # Rack config

Rakefile文件里面的配置关联的几乎都是部署，你甚至都不需要接触他们，除非你使用rsync。

博客配置

在_config.yml有三个部分是用于配置你的octopress博客。注意：你必须改变url,你很可能改变title,subtitle以及使用第三方服务。

octopress配置文件

    url:                # 为RSS重新url, 等等。
    title:              # 在页的头和标题标签使用
    subtitle:           # 在头里面的描述
    author:             # 为RSS的作者, Copyright, Metadata
    simple_search:      # 简单的搜索引擎
    description:        # 为你的站点默认的描述
    date_format:        # 使用ruby的时间格式化
    subscribe_rss:      # 你的博客源订阅url，默认是到/atom.xml
    subscribe_email:    # 邮件订阅email
    category_feeds:     # 使用每一个类别rss源订阅
    email:              # Email address for the RSS feed if you want it.

注意：假如你的站点是多作者，你也许想要设置配置文件里面的author为你们项目或者公司的名称，然后加作者元数据到文章或者页面，为这些工作添加合适的属性。

Jekyll & Plugins

这些配置被 Jekyll以及插件使用。假如你不熟悉Jekyll，你也许需要看一下配置文档，这个文档列出了这儿没有覆盖的更多属性。

octopress配置文件

    root:               # Mapping for relative urls (default: /)
    permalink:          # Permalink structure for blog posts
    source:             # Directory for site source files
    destination:        # Directory for generated site files
    plugins:            # Directory for Jekyll plugins
    code_dir:           # Directory for code snippets (for include_code plugin)
    category_dir:       # Directory for generated blog category pages

    pygments:           # Toggle python pygments syntax highlighting
    paginate:           # Posts per page on the blog index
    pagination_dir:     # Directory base for pagination URLs eg. /blog/page/2/
    recent_posts:       # Number of recent posts to appear in the sidebar

    default_asides:     # Configure what shows up in the sidebar and in what order
    blog_index_asides:  # Optional sidebar config for blog index page
    post_asides:        # Optional sidebar config for post layout
    page_asides:        # Optional sidebar config for page layout

假如你想改变为你的博客文章所设置的永久链接方式，请看Jekyll的永久链接文档。

注意：Jekyll有一个baseurl配置，这个配置通过加一个重定向到Jekyll的WEBrick服务提供模拟子目录发布支持。请不要使用这个。假如你想要发布你的站点到二级目录，请看部署octopress到子目录。

第三方服务设置

这里已经为你设置了第三方集成。简单的填写配置，就会在你的博客展现效果。

• Github - 在侧边栏列出你的github库
• Twitter - 在文章或者页面加一个分享到Twitter的按钮
• Google Plus One - 为google+社交网络加分享按钮
• Pinboard - 在侧边栏分享你最近的Pinboard记录
• Delicious - 在侧边栏分享你最近的Delicious记录
• Disqus Comments - 加你的Disqus短名使你可以使用评论
• Google Analytic - 加你的谷歌记录id，开启谷歌分析追踪。
• Facebook - 加一个facebook喜欢按钮。

octopress布局将读取这些配置，以及仅仅为可以使用的第三方服务加载需要的js和html。

部署

这里有一些很漂亮和简单的方法部署你的octopress博客。

GitHub Pages

使用github’s Pages服务建立你的博客是免费且允许你自定义你的域名。部署只需要将你的库推送到gitHub。这是一种你建立自己的博客的伟大的方法，或者甚至是一个多作者博客，可以通过拉请求和控制权限处理每个人的贡献。

部署到GitHub Pages »

Heroku

像GitHub Pages, Heroku也是免费的，也允许自定义域名。也使用基于git部署工作流。Heroku使用起来很简单，且你的库仍然保持私有。

部署到Heroku »

Rsync

假如你有web主机服务，你能很简单的使用rsync部署，rsync通过SSH同步文件以及修改文件是不可思议的快。假如你的主机不提供SSH服务，你可以寻找一个替代它，试试DreamHost，我从2005年一来就一直使用它。

部署到子目录

假如你部署一个子目录到你的网站，你可以使用github的项目页，确信你正确配置好了你的urls。你几乎可以自动化实现：

配置urls

rake set_root_dir[your/path]

# To go back to publishing to the document root
rake set_root_dir[/]

然后如下更新你的_config.xml以及Rakefile:

_config.xml

# _config.yml
url: http://yoursite.com/your/path

# Rakefile (if deploying with rsync)
document_root = "~/yoursite.com/your/path"

要手动配置部署到子目录，你将改变_config.yml，config.rb 以及Rakefile。底下是一个部署站点到/awesome子目录的例子：

_config.xml，config.rb，Rakefile

# _config.yml
destination: public/awesome
url: http://example.com/awesome
subscribe_rss: /awesome/atom.xml
root: /awesome

# config.rb - for Compass & Sass
http_path = "/awesome"
http_images_path = "/awesome/images"
http_fonts_path = "/awesome/fonts"
css_dir = "public/awesome/stylesheets"

# Rakefile
public_dir = "public/awesome"
# If deploying with rsync, update your Rakefile path
document_root = "~/yoursite.com/awesome"

部署到Rsync

通过SSH部署rsync

将你的服务器配置加到Rsync部署配置目录的rakefile文件下。部署到rsync，确认你的公钥在文件~/.ssh/authorized_keys文件里列出来了。

authorized_keys

ssh_user       = "user@domain.com"
document_root  = "~/website.com/"
rsync_delete   = true
deploy_default = "rsync"

下一步运行

rake generate   # If you haven't generated your blog yet
rake deploy     # Syncs your blog via ssh

在你的终端，你的public目录将被同步到你服务器帐号的根目录。

关于rsync删除

假如在同步中选择删除，rsync将创建一个1:1的比对。文件将被添加，修改以及删除从你部署目录到你的本地复制镜像。

假如没有选择删除：

• 你能存储文件在你的网站部署目录，而这个部署目录还没有被本地版本发现。
• 你本地网站删除的文件必须手动移除服务器端的文件。

从同步中排除文件

假如你想保持octopress文件同步，但是同时你也想很方便的排除一些文件或者目录不跟服务器同步，你可以在rsync中排除他们。

当同步的时候，rsync可以排除服务器或者本地的文件或者目录。简单的加一个rsync-exclude文件，到你项目的根目录，像这样：

rsync-exclude

some-file.txt
some-directory/
*.mp4

注意：使用排除将防止rsync上传本地文件，或者假如你指定了删除选项，它将防止rsync从服务器删除排除列表里面的文件。

版本控制

你想要在远程git库同步你的博客源。所以设置一个github库或者建立一个你自己的主机，然后运行如下命令：

配置远程点

# Since you cloned Octopress, you'll need to change the origin remote
git remote rename origin octopress
git remote add origin (your repository url)
# set your new origin as the default branch
git config branch.master.remote origin

建立你自己的远程仓库

假如你想设置在你自己服务器的私人git仓库，底下是怎么做。你需要ssh维持访问。

git ssh

ssh user@host.com
mkdir -p git/octopress.git
cd git/octopress.git
git init --bare
pwd  # print the working directory, you'll need it below.
logout

你远程访问库的url是：ssh://user@host.com/(output of pwd above)。

部署到子目录

假如你想要建立一个博客在http://yoursite.com/blog/,你将需要为部署到子目录配置octopress。

部署到Heroku

部署到Heroku

假如你还没有heroku帐号，创建一个，它是免费的。然后安装the Heroku gem。

基本的Octopress安装

第一步确定你安装好了the Heroku gem。

安装heroku gem

gem install heroku

下一步为你的部署创建应用。假如你是第一次使用heroku,底下的命令将询问你的帐号密码，并自动上传你的ssh的公钥。假如你还没有一个公钥，请点击：github的向导并创建一个。

heroku create

heroku create

这个命令将为你的部署创建一个heroku应用，然后创建一个名字叫做“heroku”的git远程点。

git远程点

# Set heroku to be the default remote for push/fetch
git config branch.master.remote heroku

编辑库根目录下的.gitignore文件，并移除public。这个让你将生成后的内容部署到Heroku。

部署

rake generate
git add .
git commit -m 'site updated'
git push heroku master

这样你就会部署到HeroKu。假如你想配置自己的域名，请看HeroKu的文档。

部署到Github Pages

• 使用github的用户或者组织页
• 使用github项目页（gh-pages）
• 自定义域名

使用github的用户或者组织页

假如你想要从http://username.github.io拥有一个博客(虽然你也有自己的域名)，就使用这个方法。在过去github使用http://username.github.com作为域名,但是正在使用io扩展代替Pages。

创建一个新的github库，将这个库的名字命名为这种格式的：username.github.io，username是你的github用户名或者组织名。

Github Pages为用户以及组织使用主分支就像web服务器使用公共目录，在你的http://username.github.io网页提供文件。但是你想要在source分支下工作，例如编辑博客文章，然后提交生成后的博客内容到主分支。Octopress有一个帮助你这样设置好的配置命令。

github pages配置

rake setup_github_pages

这个rake命令将询问你的github库url。复制来自于你新创建好的库的ssl或者https的url(例如：git@github.com:username/username.github.io.git)，然后作为回应粘贴到里面。

这个命令将会做如下动作：

1. 询问以及存储你的github pages的库url。
2. 将imathis/octopress远程点的名称’origin’修改为’octopress’。
3. 加入你的github pages库作为默认的origin远程点。
4. 切换活动分支从主分支到源分支。
5. 根据你的库url配置你的博客url。
6. 在_deploy文件夹设置一个主分支用于部署。

下一步运行：

github rake deploy

rake generate
rake deploy

这个将生成你的博客，复制生成好的文件到_deploy/,然后将他们加入到git，提交以及推送他们到github的主分支。在之后几秒钟之内，你会收到一封来自与github的email，告诉你你的提交已经被接收以及将被部署到你的站点。

不要忘记将你的博客开发代码提交到源分支。

github 提交到源分支

git add .
git commit -m 'your message'
git push origin source

注意：使用新库，github会设置基于你第一次推送的分支作为你的默认的分支，然后它将存放你生成的内容。假如你使用github部署你的博客出现问题，点击你库的管理面板，然后确认主分支是默认的分支。

更多关于你第一篇文章的信息，请阅读博客基本设置。

使用github项目页（gh-pages）

github项目页服务允许你为你的开源项目形成一个站点。github将寻找你库里面的gh-pages分支，然后确定在url（例如：http://username.github.io/project）的内容是可用的。

底下能设置octopress站点到gh-pages库：

github pages配置

rake setup_github_pages

有如下几个步骤：

1. 询问你项目库的url。
2. 将imathis/octopress远程点的名称’origin’修改为’octopress’。
3. 在_deploy文件夹设置一个gh-pages分支用于部署。

下一步运行：

github rake deploy

rake generate
rake deploy

这个将生成你的博客，复制生成好的文件到_deploy/,然后将他们加入到git，提交以及推送他们到github的主分支。在之后几秒钟之内，你会收到一封来自与github的email，告诉你你的提交已经被接收以及将被部署到你的站点。

现在你已经有一个地方用于提交生成好的内容，但是你也应该设置一个库用于存储博客的源代码。在你为博客源代码设置好一个库之后，把如下加到origin的远程点。

添加origin远程点

git remote add origin (your repo url)
# set your new origin as the default branch
git config branch.master.remote origin

目前位置你可以推送你所有的改变了。

自定义域名

第一步在你的博客源代码路径新建一个名为cname的文件。

新建cname

echo 'your-domain.com' >> source/CNAME
# OR
echo 'www.your-domain.com' >> source/CNAME

下一步你需要访问你的域名注册商或者DNS主机，然后在你的域名字加一条记录。

• 创建一个子域名，例如：www.example.com,你应该很简单的创建一个cname记录点到charlie.github.io.。
• 假如你使用顶级域名，例如：example.com，你必须使用一个A记录到192.30.252.153或者192.30.252.154。

不要使用顶级域名创建一条CNAME记录！！它也许在其他服务例如邮件有不良的副作用。许多DNS服务允许你在TLD上创建CNAME,虽然你不会。记住dns的改变也许需要一整天才会生效，所以需要耐心。

源：github pages向导

ctopress安装

Octopress安装

首先我想要强调Octopress是一个为骇客准备的博客框架。你应该很自然的运用shell命令以及很熟悉git的基本知识。假如那听起来让人为难的，可能octopress不适合你。

在你开始之前

1. 安装git
2. 安装ruby 1.9.3或者很熟练的使用rbenv或者RVM。

假如ruby --version没有告诉你正在使用ruby至少1.9.3版本，重新审视你安装rbenv或者RVM的过程。

安装Octopress

安装octopress

git clone git://github.com/imathis/octopress.git octopress
cd octopress

下一步安装依赖

安装依赖

gem install bundler
rbenv rehash    # If you use rbenv, rehash to be able to run the bundle command
bundle install

安装octopress默认主题

安装默认主题

rake install

目录结构

一、缘起

总感觉还得写一篇进阶版，将octopress的原理说一说、与jekyll的关系说一说。我觉得应该先说明jekyll是什么，毕竟octopress的精髓是jekyll。

二、jekyll

其实一直是想要搭建一个博客，但是碍于最流行的wordperss实在是太过复杂，我只是想要发布我的内容而已，为什么还要干这么多事？要安装php、要安装mysql，还有各种配置，为啥？后来不了了知。
其实还是创造力不够？遇到困难是退缩，而不是迎难而上。如果迎难而上，应该想市面上既然没有这么简单的博客系统，那为什么你不做一个，自己开发一个？
但是github的创始人之一 Tom Preston-Werner 创建了jekyll静态博客生成系统。它的特点是基于内容的博客发布系统而不是数据库。所以安装简单、部署简单、发布简单。所以我一接触到这个系统就对它着迷，立马浮上心头要创建一个自己的博客网站的想法。

2.1、jekyll描述

jekyll是Tom Preston-Werner使用ruby写的开放源码的程序，Tom Preston-Werner是GitHub网站的创始人。GitHub是Git仓库网络托管服务，提供所有的分布式版本控制和源代码管理（SCM）功能。Jekyll 是一个简单的博客形态的静态站点生产机器，生成的静态站点可以用于个人、项目、或者组织的网站。它是基于文件的内容管理系统而不是数据库，它有一个模版目录，其中包含原始文本格式的文档，通过 Markdown （或者 Textile） 以及 Liquid 转化成一个完整的可发布的静态网站，你可以发布在任何你喜爱的web服务器上，例如apache、Nginx。Jekyll 也可以运行在 GitHub Page 上，也就是说，你可以使用 GitHub 的服务来搭建你的项目页面、博客或者网站，而且是完全免费的。

2.2、jekyll目录结构

Jekyll的核心其实是一个文本转换引擎。它的概念其实就是：你用你最喜欢的标记语言来写文章，可以是 Markdown, 也可以是 Textile, 或者就是简单的 HTML, 然后 Jekyll 就会帮你套入一个或一系列的布局中。在整个过程中你可以设置 URL 路径，你的文本在布局中的显示样式等等。这些都可以通过纯文本编辑来实现，最终生成的静态页面就是你的成品了。

一个基本的 Jekyll 网站的目录结构一般是像这样的：

Jekyll网站的目录结构

.
├── _config.yml
├── _drafts
|   ├── begin-with-the-crazy-ideas.textile
|   └── on-simplicity-in-technology.markdown
├── _includes
|   ├── footer.html
|   └── header.html
├── _layouts
|   ├── default.html
|   └── post.html
├── _posts
|   ├── 2007-10-29-why-every-programmer-should-play-nethack.textile
|   └── 2009-04-26-barcamp-boston-4-roundup.textile
├── _site
└── index.html

1. _config.yml:保存配置数据。很多配置选项都可以直接在命令行中进行设置，但是如果你把那些配置写在这儿，你就不用非要去记住那些命令了。
2. _drafts :drafts 是未发布的文章。这些文件的格式中都没有 title.MARKUP 数据。
3. _includes :你可以加载这些包含部分到你的布局或者文章中以方便重用。可以用这个标签 {% include file.ext %} 来把文件includes/file.ext 包含进来。本身Jekyll会带博客的头文件和尾部文件。
4. _layouts :layouts 是包裹在文章外部的模板。布局可以在 YAML 头信息中根据不同文章进行选择。 这将在下一个部分进行介绍。标签 {{ content }} 可以将content插入页面中。
5. _posts :这里放的就是你的文章了。文件格式很重要，必须要符合: YEAR-MONTH-DAY-title.MARKUP。 The permalinks 可以在文章中自己定制，但是数据和标记语言都是根据文件名来确定的。
6. _site :一旦 Jekyll 完成转换，就会将生成的页面放在这里（默认）。最好将这个目录放进你的 .gitignore 文件中。
7. index.html :如果这些文件中包含 YAML 头信息 部分，Jekyll 就会自动将它们进行转换。当然，其他的如 .html, .markdown, .md, 或者 .textile 等在你的站点根目录下或者不是以上提到的目录中的文件也会被转换。
8. Other Files/Folders :其他一些未被提及的目录和文件如 css 还有 images 文件夹， favicon.ico 等文件都将被完全拷贝到生成的 site 中。

2.3、配置

Jekyll允许你很轻松的设计你的网站，这很大程度上归功于灵活强大的配置功能。既可以配置在网站根目录下的 _config.yml 文件，也可以作为命令行的标记来配置。

默认配置

yaml头信息

source:      .                         #Jekyll 读取文件的路径
destination: ./_site                   #Jekyll 写入文件的路径
plugins:     ./_plugins
layouts:     ./_layouts
include:     ['.htaccess']             #转换时强制包含某些文件、文件夹。.htaccess 是个典型的例子，因为默认排除 . 开头的文件。
exclude:     []
keep_files:  ['.git','.svn']
timezone:    nil
encoding:    nil

future:      true
show_drafts: nil
limit_posts: 0
pygments:    true

relative_permalinks: true

permalink:     date
paginate_path: 'page:num'

markdown:      maruku
markdown_ext:  markdown,mkd,mkdn,md
textile_ext:   textile

excerpt_separator: "\n\n"

safe:        false
watch:       false    # deprecated
server:      false    # deprecated
host:        0.0.0.0                           #监听所给的主机名
port:        4000                              #监听所给的端口
baseurl:     /                                 #网站的根路径
url:         http://localhost:4000
lsi:         false

maruku:
  use_tex:    false
  use_divs:   false
  png_engine: blahtex
  png_dir:    images/latex
  png_url:    /images/latex

rdiscount:
  extensions: []

redcarpet:
  extensions: []

kramdown:
  auto_ids: true
  footnote_nr: 1
  entity_output: as_char
  toc_levels: 1..6
  smart_quotes: lsquo,rsquo,ldquo,rdquo
  use_coderay: false

  coderay:
    coderay_wrap: div
    coderay_line_numbers: inline
    coderay_line_numbers_start: 1
    coderay_tab_width: 4
    coderay_bold_every: 10
    coderay_css: style

redcloth:
  hard_breaks: true

2.4、头信息

正是头信息开始让 Jekyll 变的很酷。任何只要包含 YAML 头信息的文件在 Jekyll 中都能被当做一个特殊的文件来处理。头信息必须在文件的开始部分，并且需要按照 YAML 的格式写在两行三虚线之间。下面是一个基本的例子：

yaml头信息

layout: post
title: "Octopress知识进阶"
date: 2014-09-21 00:28:13 +0800
comments: true
categories: [octopress]
description: "Octopress知识进阶"
keywords: octopress

在这两行的三虚线之间，你可以设置一些预定义的变量（下面这个例子可以作为参考）或者甚至创建一个你自己定义的变量。这样在接下来的文件和任意模板中或者在包含这些页面或博客的模板中都可以通过使用 Liquid 标签来访问这些变量。

三、octopress

现在知道有这么一个静态网站生成器叫jekyll，但是这个还是有点复杂，因为你在写博客之前，你需要先设计你博客的样式，例如头显示什么，尾巴显示什么，边框是什么样子，然后用什么技术，写大量的js大量的css。我们还是要过多关注于博客的样子，博客的目录，而不是内容。所以我想有没有一个托管程序，可以先都帮我们设置好了，安装样式也很简单，不需要过多设置，我拿过来直接写文章就可以。所以网上搜，还真有，而且挺多，最终选择使用octopress。

3.1、octopress描述

octopress是Brandon Mathis为jekyll而设计的一个框架。使用jekyll你不得不写你自己的html模板，css,js,设置好自己的配置，但是octopress托管所有，简单的安装依赖软件，然后你就可以开始写文章了。

3.2、octopress目录结构

octopress目录结构

octopress
├── .themes
|    └──classic
|        ├── sass  
|        └── source     
├── _deploy
├── assets
├── blog
├── images
├── javascripts
├── plugins
|   ├── blockquote.rb
|   ├── config_tag.rb
|   ├── haml.rb
|   ├── .....
|   └── video_tag.rb
├── public
├── sass
|   ├── base
|   ├── custom
|   ├── partials
|   ├── parts
|   ├── plugins
|   ├── _base.scss
|   ├── _partials.scss
|   ├── _parts.scss
|   ├── _plugins.scss
|   └── screen.scss
├── source
|   ├── about
|   |   └── index.markdown
|   ├── _includes
|   |   ├── asides
|   |   ├── custom
|   |   |    ├── asides
|   |   |    |    └── aboutme.html
|   |   |    ├── footer.html
|   |   |    ├── head.html
|   |   |    ├── navigation.html
|   |   |    └── header.html
|   |   ├── post
|   |   |   ├── date.html  
|   |   |   ├── categories.html
|   |   |   └── duoshuo.html
|   |   ├── after_footer.html
|   |   ├── archive_post.html
|   |   ├── article.html
|   |   ├── footer.html
|   |   ├── google_analytics.html
|   |   ├── head.html
|   |   ├── header.html
|   |   └── navigation.html
|   ├── _layouts
|   |   ├── category_index.html
|   |   ├── default.html
|   |   ├── post.html
|   |   └── page.html
|   ├── _posts
|   |   ├── 2007-10-29-why-every-programmer-should-play-nethack.textile
|   |   └── 2009-04-26-barcamp-boston-4-roundup.textile
|   ├── images
|   ├── javascripts
|   ├── stylesheets
|   └── index.html   
├── _config.yml
├── config.rb
├── Gemfile
└── Rakefile

对比jekyll的目录结构，发现是将jekyll的目录结构包含与octopress的目录结构中，并增加了布局、包含、js、css文件。
以下是octopress目录结构的一些总结：

1. jekyll中的_config.yml文件移到octopress的根目录下，且增加了新内容。在Octopress 的_config.yml中有三个部分的配置。我自己博客的配置如下(只展示我修改过的地方)：

_config.yml

#第一部分主要配置
url: twalksong.com
title: 寧靜致遠
subtitle: 焚膏油以繼晷，恆兀兀以窮年。
author: songyj
simple_search: http://www.baidu.com/
description: 这是知识积累与生命哲思一同迸发的地方。
email: picnic106@163.com

#第二部分插件
markdown: kramdown
kramdown:
# toc_levels: 1..3
  use_coderay: true
  coderay:
    coderay_line_numbers: table
    coderay_css: class

excerpt_link: "阅读全文 →"  # "Continue reading" link text at the bottom of excerpted articles

#第三部分社交帐号配置，例如Github ，Twitter ，Facebook 等
github_user: picnic106
github_repo_count: 1
github_show_profile_link: true
github_skip_forks: true
google_analytics_tracking_id:
duoshuo_comments: true
duoshuo_short_name:

1. .themes文件夹用于放置从github库下载下来的octopress的皮肤。这个文件夹下具体的作用还没有做详细的调查，这里暂且不说。
2. _deploy文件夹放置部署到github或者其他托管网站的源文件。即使用·rake deploy·命令之后，会同步更新此文件夹。
3. plugins文件夹放置ruby插件
4. public文件夹放置本地预览所用的源代码。即用·rake preview·命令之后，会在此文件夹生成源代码。
5. sass文件夹用于放置样式表，目前对这个文件夹没有研究，暂且不说，只知道当安装.themes中的皮肤时会覆盖此文件夹相关文档。
6. source文件夹放置如同jekyll的目录。平常撰写博客，基本上在source文件夹下的_post文件夹下写，即运行·rake new_post·命令会在source/_post文件夹下生成文件。
7. Rakefile文件用于编写Ruby的make命令。基本上cotopress有如下命令：install、generate、preview、new_post、new_page、isolate、update_style、update_source、deploy、rsync、push、set_root_dir、setup_github_pages。

个性化设置

一、缘起

虽然octopress博客架起来了，但是一些个人设置或者自己不满意的地方还需要修改呢，例如中文设置、时间设置、性能优化等等。我博客主题为“Greyshade”。

二、性能优化

最近打开个人网站觉得太慢了，使用浏览器的f12，发现打开谷歌的js很慢，所以想办法来替换这些js。在网上搜到这篇博客:“解决Octopress博客访问慢的问题”，很感谢这篇博客，文章详细写了如何替换google的js。

1，解决fonts.googleapis.com访问慢

首先使用f12发现有一段获取fonts.googleapis.com的字体js,是因为greyshade主题使用了谷歌的字体的api，谷歌字体（Google Font）初探这篇文章对谷歌字体的作用有大体介绍。大家都知道googleappis在内地的访问不是很稳定，很慢。将这些链接修改成国内的360网站卫士常用前端公共库CDN服务(http://libs.useso.com/)以提高访问性能。经过查找这段代码在/source/_includes/head.html:

修改谷歌提供的字体服务

<!--<link href='http://fonts.googleapis.com/css?family=Nunito:400,300,700' rel='stylesheet' type='text/css'>-->
<link href="http://fonts.useso.com/css?family=Nunito:400,300,700" rel="stylesheet" type="text/css">

2，解决ajax.googleapis.com访问慢

使用f12也发现有一段代码访问了谷歌服务的jquery库,360网站也提供jquery库cdn服务。经过查找这段代码也在/source/_includes/head.html:

修改谷歌提供的jquery库

<!--<link href='http://fonts.googleapis.com/css?family=Nunito:400,300,700' rel='stylesheet' type='text/css'>-->
<!--<script>!window.jQuery && document.write(unescape('%3Cscript src="./javascripts/libs/jquery.min.js"%3E%3C/script%3E'))</script>-->
<script src="http://ajax.useso.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>

至于为啥要用谷歌的jquery库，“为什么推荐使用谷歌加载jquery库文件”这个网址里有说明。

3，解决Google Analytics访问慢

如果octoperss开启了谷歌的访问数据统计服务，在网站会加载谷歌的ga.js。大家肯定知道谷歌在中国被墙。所以可以修改成放在国内提供的cdn服务器的ga.js。这里我使用的是droidyue博主存放在七牛CDN上的js：http://droidyue-tools.qiniudn.com/ga.js已验证，完全可以正常收集数据。经过查找加载ga.js的代码source/_includes/google_analytics.html:

(google_analytics.html)download

{% if site.google_analytics_tracking_id %}
    <script type="text/javascript">
        var _gaq = _gaq || [];
        _gaq.push(['_setAccount', '{{ site.google_analytics_tracking_id }}']);
        _gaq.push(['_trackPageview']);

        (function() {
            var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
            //ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
            ga.src='http://droidyue-tools.qiniudn.com/ga.js';
            var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
        })();
    </script>
{% endif %}

三、更换主题

如果在网上找到一个比较好的主题，可以先找个这个主题的库地址，然后安装。例如我这个greyshade主题，使用如下脚本安装主题：

安装greyshade主题windos脚本

git clone git@github.com:shashankmehta/greyshade.git .themes/greyshade
rake "install[greyshade]"
rake generate

四、修改个人网站中文

greyshade主题都是英文的，例如标题啊，侧边栏。

1,侧边栏中文

如图红圈里的”博客、关于我、存档”，之前都是英文，如果要修改成中文，文件路径在/source/_includes/navigation.html：

navigation.htm

<ul class="main">
    <li><a href="/">博客</a></li>
    <li><a href="/about/">关于我</a></li>
    <li><a href="/blog/archives">存档</a></li>
</ul>

2,”Comments”中文

2.1,查看评论：

如图红圈里的是“查看评论”，在安装主题完是英文的，如果要修改成中文，文件路径在\source\_includes\article.html:

article.html

<!--<span class="comments"><a href="#disqus_thread">Comments</a></span>-->
<span class="comments"><a href="{% if index %}{{ root_url }}{{ post.url }}{% endif %}#comments">查看评论</a></span>

2.2,评论:

如图红圈里的是“评论”，在安装主题完是英文的，如果要修改成中文，文件路径在\source\_layouts\post.html

post.html

<!--<section>
    <h1>Comments</h1>
   ......
</section>-->
<section>
    <h1>评论</h1>
    ......
</section>

3,”read on”中文

如下图：

如上图，“阅读全文”在没汉化之前是“Continue reading”，文件路径在/_config.yml：

将Continue reading修改为中文

#excerpt_link: "Continue reading →"  # "Continue reading" link text at the bottom of excerpted articles
excerpt_link: "阅读全文 →"

五、博客不显示时间

刚安装的主题居然不显示时间，如下图： 
红圈的地方刚开始时间是不显示的，后来发现是没有包含日期插件，但是去网上下日期插件也不行，后来自己想了办法，修改了octopress代码，直接在代码里格式化，代码路径在\source\_includes\post\date.html，将date_format，修改为date| date: "%Y-%m-%d %H:%M:%S"。

六、安装国内多说插件

本来想安装国外的disqus，但是，去disqus官网注册之后，放到博客，怎么也不显示，转而安装国内的多说评论插件。

1,首先注册多说帐号

首先去多说官网注册帐号且创建站点。但是坑爹的多说，我怎么找都没有找到创造站点的地方，后来在一个非常隐秘的界面找到是在这里，多说也没有一个帮助文档吗，或许是我没找到吧。
注册站点之后记住二级域名，如下图：

2,配置octopress

配置/_config.yml文件，在文件最后加代码如下：

_config.yml

# Duoshuo Comments
duoshuo_comments: true
duoshuo_short_name: twalksong

twalksong为我的多说二级域名。

3,加多说代码

在路径\source\_includes\post，新增文件duoshuo.html，并将以下代码写到此文件：

duoshuo.html

<!-- 多说评论框 start -->
    <div class="ds-thread" data-title="{% if site.titlecase %}{{ page.title | titlecase }}{% else %}
    {{ page.title }}{% endif %}"></div>
<!-- 多说评论框 end -->
<!-- 多说公共JS代码 start (一个网页只需插入一次) -->
<script type="text/javascript">
var duoshuoQuery = {short_name:"{{ site.duoshuo_short_name }}"};
    (function() {
        var ds = document.createElement('script');
        ds.type = 'text/javascript';ds.async = true;
        ds.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') + '//static.duoshuo.com/embed.js';
        ds.charset = 'UTF-8';
        (document.getElementsByTagName('head')[0]
         || document.getElementsByTagName('body')[0]).appendChild(ds);
    })();
    </script>
<!-- 多说公共JS代码 end -->

4,修改原来文章评论代码

修改\source\_layouts\post.html文件，在最后加如下代码:

post.html

{% if site.duoshuo_short_name and site.duoshuo_comments == true and page.comments == true%}
  <section>
    <h1>评论</h1>
    <div id="comments" aria-live="polite">{% include post/duoshuo.html %}</div>
  </section>
{% endif %}

5,修改“查看评论代码”

修改\source\_includes\article.html文件，在以前的disqus代码下加如下代码:

article.html

{% if site.duoshuo_short_name and page.comments != false and post.comments != false and site.duoshuo_comments == true %}
          <span class="comments"><a href="{% if index %}{{ root_url }}{{ post.url }}{% endif %}#comments">查看评论</a></span>
         {% endif %}

6,至此完结，如果还有什么地方发现需要评论，按照上面的思路修改就ok。

七、增加自动生成目录功能(TOC)

摘抄Octopress易筋经，目录表ToC:

维护长博客的时候，如果加上一个目录表 (Table of Contents)，会令读者对文章结构有一个清晰的把握。基于Octopress的博客系统，有两种常见的创建目录表的方式：基于 kramdown1 的实现，以及基于 jQuery 插件的实现。前者基本上不需要配置，仅要求把默认的 Markdown parser 改为 kramdown 即可。后者则需要对系统进行相对较多的修改。

我这里使用第一种kramdown方法实现，所以这里着重介绍第一种方法，第二种方法没有试验。

方式一：利用kramdown内嵌的ToC功能

kramdown是一款由Ruby实现的Markdown解析器。它扩展的标准Markdown语言，添加了很多语法，其中一个就是内置了ToC的实现。这让在基于Jekyll/Octopress的博客系统中插入ToC变得简单而灵活，但是不幸的是，它的目录结构和层次需要在_config.yml中指定，也就是说，这些设定是全站的，你无法在某一篇Blog中使用不同于全站的ToC结构。
实现这种方式的配置很简单，仅需要在你的_config.yml文件中，将默认的 Markdown parser 改为 kramdown，也即，markdown: kramdown，在kramdown中，默认的目录树层次是从h1到h6，你可以用下的设定将这个层次改为从h1到h3，

将octopress的解析器修改为kramdown

markdown: kramdown
kramdown:
  toc_levels: 1..3 #将默认的目录树层次修改为从h1到h3

如果没有还没有安装kramdown，需要安装kramdown解析器：
1，修改/Gemfile，在文件最后增加一行：gem 'kramdown', '~> 0.14'。
2，然后打开windows命令行工具，定位到octopress目录，执行如下命令bundle install，kramdown会自动安装。

然后修改toc的样式，样式目录位于\sass\custom\_styles.scss，在文件最后一行增加如下代码：

toc样式

#markdown-toc:before {
  content: "目录";
  font-weight: bold;
}
ul#markdown-toc {
  list-style: none;
  background-color: white;
}
.blog-index #markdown-toc {
  display: none;
}

插入ToC也很简单，几乎在你的文章任何地方，加入下面的代码，在相应的部分kramdown就会帮你生成并插入一个ToC，

插入toc代码

    * Put anything here
    {:toc}

注：关于阅读全文的问题：
这里有一个问题就是如果在文章中加了<!-- more -->，因此在博客首页只会显示文章的一部分，那么在<!-- more -->之下的目录就不会起作用，所以在博客首页的时候就不显示目录，点击文章进去再显示目录。
网上有解决办法，但是试验不成功，后来经过本人测试，可以如下解决，在目录\source\_includes\article.html,修改如下代码：

toc解决办法

<div class="entry-content blog-index" itemprop="articleBody">
                {{ content | excerpt }}
                {% capture excerpted %}{{ content | has_excerpt }}{% endcapture %}
                {% if excerpted == 'true' %}<a href="{{ root_url }}{{ post.url }}" class="more-link">{{ site.excerpt_link }}</a>{% endif %}
</div>

主要变化是增加了css类blog-index，这个类的作用就是隐藏目录。为什么会是在article.html文件呢，因为如果是博客首页，在这个页面会有一个判断{% if index %}，index就是博客首页的变量，所以这样，就可以在博客首页的时候隐藏目录，然后点击文章才展示目录。以下是article.html全部代码。

(article.html)download

{% if index %}
    <div class="meta">
        <div class="date">{% include post/date.html %}{{ time }}</div>
        <div class="tags">{% include post/categories.html %}</div>
        {% if site.disqus_short_name and site.disqus_show_comment_count == true %}
            <span class="comments"><a href="{{ root_url }}{{ post.url }}#disqus_thread">Comments</a></span>
        {% endif %}
         {% if site.duoshuo_short_name and page.comments != false and post.comments != false and site.duoshuo_comments == true %}
           <span class="comments"><a href="{% if index %}{{ root_url }}{{ post.url }}{% endif %}#comments">查看评论</a></span>
         {% endif %}
    </div>
    <h1 class="title" itemprop="name"><a href="{{ root_url }}{{ post.url }}" itemprop="url">{% if site.titlecase %}{{ post.title | titlecase }}{% else %}{{ post.title }}{% endif %}</a></h1>
    <div class="entry-content blog-index" itemprop="articleBody">
        {{ content | excerpt }}
        {% capture excerpted %}{{ content | has_excerpt }}{% endcapture %}
        {% if excerpted == 'true' %}<a href="{{ root_url }}{{ post.url }}" class="more-link">{{ site.excerpt_link }}</a>{% endif %}
    </div>
{% else %}
<div class="meta">
<div class="date">{% include post/date.html %}{{ time }}</div>
<div class="tags">{% include post/categories.html %}</div>
{% if site.duoshuo_short_name and page.comments != false and post.comments != false and site.duoshuo_comments == true %}
           <span class="comments"><a href="{% if index %}{{ root_url }}{{ post.url }}{% endif %}#comments">查看评论</a></span>
         {% endif %}
</div>
    <h1 class="title" itemprop="name">{% if site.titlecase %}{{ page.title | titlecase }}{% else %}{{ page.title }}{% endif %}</h1>

    <div class="entry-content" itemprop="articleBody">{{ content }}</div>
{% endif %}

方式二：利用jQuery的ToC插件

这种方式实现起来稍微复杂一些，好处是可以根据需要调整ToC的层次结构。当然，它也有局限性，例如，就我的实现而言，ToC的位置是固定浮动与整篇正文之上的，也就是说它会出现在文章的最开头处。这里应用的方法主要参照的是Brian Clapper的博客
* jQuery插件支持
按照jQuery网站的提示配置你的系统，并且下载Table of Contents jQuery Plugin，将相应的JS文件放到source/javascripts目录。在source/_includes/custom/after_footer.html中添加

after_footer.html

// !!! Load jQuery before this
<script type="text/javascript">
    jQuery.noConflict();
</script>
<script src="/javascripts/jquery.scrollTo.min.js" type="text/javascript"></script>
<script src="/javascripts/jquery.tableofcontents.min.js" type="text/javascript"></script>

• 创建JavaScript文件，例如，tocgenerator.js，使其包含下面的代码，

tocgenerator.js

function generateTOC(insertBefore, heading, startLv) {
    var container = jQuery("<div id='tocBlock'></div>");
    var div = jQuery("<ul id='toc'></ul>");
    var content = jQuery(insertBefore).first();

    if (heading !== undefined && heading !== null) {
        container.append('<span class="tocHeading">' + heading + '</span>');
    }

    if (startLv === undefined) { startLv = 1; }

    div.tableOfContents(content, { startLevel: startLv });
    container.append(div);
    container.insertBefore(insertBefore);
}

• 载入创建的JS文件（source/_includes/custom/after_footer.html）

• 创建ToC模块，依然在source/_includes/custom/after_footer.html中，添加，

after_footer.html

{% if page.toc == true %}
  {% if page.tocstartlv %}
    <script type="text/javascript">
    jQuery(document).ready(function() {
      // Put a TOC right before the entry content.
      generateTOC('.entry-content', 'Contents', );
    });
    </script>
  {% else %}
    <script type="text/javascript">
    jQuery(document).ready(function() {
      // Put a TOC right before the entry content.
      generateTOC('.entry-content', 'Contents');
    });
    </script>
  {% endif %}
  {% endif %}

• 插入ToC
  与方式一不同，第二种方法插入ToC需要在文章的开始的Liquid标签出用两个新标签toc和tocstartlv来控制是否显示ToC以及ToC starting level。例如，本文采用了如下设定，

插入toc代码

    toc: true
    tocstartlv: 2

*注：第二种方法还没有经过测试，但是网上有测试成功的，所以我贴出来供大家参考。*

八、修改链接为打开窗口方式

Octopress无法将外链在新窗口中打开，在网上找到一段代码，网址是让Octopress在新标签页中打开外链,代码如下：

open-in-blank.js

function addBlankTargetForLinks () {
  $('a[href^="http"]').each(function(){
        $(this).attr('target', '_blank');
    });
}

$(document).bind('DOMNodeInserted', function(event) {
    addBlankTargetForLinks();
});

用法很简单：

1.将上面的代码下载下来或者复制其内容；
2.保存到octopress目录的source/javascripts/子目录中,另存为open-in-blank.js；
3.修改source/_includes/custom/header.html，在下面插入如下代码即可：

<script type="text/javascript" src="/javascripts/open-in-blank.js"></script>

九、加“关于我”界面

刚安装的主题是没有关于我网页的，这个需要自己创建，代码如下：

rake new_page['about']

会生成source\about\index.markdown文件，修改这个文件，然后生成、预览、部署就行。

使用Octopress和github搭建个人博客

一、缘起

一直想搭建一个自己的博客，用于技术积累的记录。例如有些技术问题会一而再、再而三的出现，但是还是每次要上网查找或者花时间回忆解决办法；例如在项目管理中出现的一些感悟，可能是一闪而过，如果不记录下来下次很难再想起来。虽然目前自己有一个技术积累库，记录在word文档里，有两个缺点，一是查找不方便，第二个是不能用于其他码农的相互借鉴：我的解决办法是不是最优解决办法？我的想法是不是有偏差？

所以花时间搭建了这么一个octopress的博客系统。之前看过wordpress的搭建方法，安装文件越来越大，里面自带的东西也越来越多，php、apache、mysql学习成本也很大。最主要的是需要自己去购买空间安装这些组件。但是我只是需要一个写博客记录并发布给其他志同道合的朋友看而已，为何要这么庞大？所以就一直搁浅。如果我能有一个很方便写博客，且又不需要自己购买空间的方法该有多好！或者是自己太贪心了些。

正好最近对github感兴趣，听说github是一个在线版本控制平台，许多开源项目都托管在上面，对传统版本控制存有疑虑的人来说，github应该是一个极好的版本控制工具。虽然目前自己也还没有弄明白git的使用方法和规范。某次搜索又看到一篇博文说可以利用github为每个用户以及开源项目创建主页的特性，来创建自己的博客，且不用购买空间来部署，因为github提供jekyll的静态网站生成器。静态网站的一个优势是，不需要用到数据库，文章存储在一个标准的静态网页文件里，随意占用空间小部署简单。我们只需要编写jekyll能解析的轻量级的标签语言(Markdown、Liquid等)书写博客，就可以将博客托管给github。

但是出于安全问题有些jekyll插件，github不提供解析服务，例如评论、分享功能，但是github提供静态页面解析服务。所以我们可以自己下载jekyll，将轻量级的标签语言转化为静态页面之后，再上传到github，就可以使用博客的一般功能。但是直接使用jekyll可能会带来一些学习成本，所以我找了octopress，这是一个jekyll的博客发布框架，无缝集成git。

下面具体介绍如何使用这些工具搭建一个轻量级的静态网页博客。

二、需要了解的技术点

1.git:
是一个开源的项目版本管理工具，如同cvs、svn。由linux的发明者Linus Torvalds编写，用作Linux内核代码的管理。

• git主页。
• git维基百科链接。

2.github:
利用服务器端部署git技术，提供在线的开源项目版本管理平台，也是一个项目托管平台。提供付费和无偿服务。例如java的很多开源组件都托管在github上。

• github主页。
• github维基百科链接。

3.jekyll:
是一个使用ruby写的，博客形态的静态站点生成器。Jekyll 是一个简单的博客形态的静态站点生产机器。它有一个模版目录，其中包含原始文本格式的文档，通过 Markdown （或者 Textile） 以及 Liquid 转化成一个完整的可发布的静态网站，你可以发布在任何你喜爱的服务器上。

• jekyll中国主页。
• jekyll维基百科链接。

4.Liquid:
Liquid是一模板引擎语言，从电子商务系统Shopify提取而来。

• Liquid语法。

5.Markdown:
Markdown 是一种轻量级的标记语言，Markdown 的目标是实现「易读易写」。

• Markdown语法。

6.Octopress:
是一个为jekyll而设计的框架。单独使用jekyll，你需要写你自己的html模板，css,js,以及设置好配置文件，但是用Octopress，这一切都被托管，你关注的只是写博客。

• Octopress主页。
• Octopress官方安装文档。

7.Ruby:
因为jekyll是ruby写的,当然需要按装ruby。Ruby 是一种面向对象、命令式、函数式、动态的通用编程语言。在20世纪90年代中期由日本人松本行弘设计并开发。

• Ruby主页。
• ruby维基百科链接。

8.rubygems:
是一种ruby包管理组件,提供一种分发ruby程序和库的标准格式。

• Rubygems主页。
• Rubygems维基百科链接。

9.DevKit:
是一个很方便的编译和使用本地c/c++扩展的工具套件，例如windows上的本地ruby扩展。在windows上使用ruby的一个挑战是如何很容易的使用来自于社区的rubygems。因为有些ruby扩展源代码使用了例如make、gcc、sh类似于unix的命令。所以devkit就发明了，为了能在windows上使用类unix命令。

• github-DevKit。

10.python:
是一种面向对象、直译式电脑编程语言，具有近二十年的发展历史，成熟且稳定。它的语法简捷和清晰，尽量使用无异义的英语单词，与其它大多数程序设计语言使用大括号不一样，它使用缩进来定义语句块。

• python主页。
• python维基百科链接。

三、博客搭建

搭建环境：win7 sp1。
  主体思路是，既然Octopress是使用jekyll来实现的框架，而jekyll是使用ruby写的，那么必然得安装ruby，ruby扩展需要用到Devkit。而博客空间又需要github实现托管，自然需要下载git工具。另外一个博客代码加亮模块需要python的支持。所以需要安装的软件为：ruby、Devkit、octopress、git、python。
  为了使ruby使用中文utf-8编码，需要给操作系统加两个环境变量，

LANG=zh_CN.UTF-8
LC_ALL=zh_CN.UTF-8

或者在windows命令窗口执行

set LANG=zh_CN.UTF-8
set LC_ALL=zh_CN.UTF-8

这样有一个缺点，一旦命令窗口关掉，又需要重新设置这两个变量。

1.git安装

git的windows版下载地址。
  安装没有什么特别之处，按照流程一步一步来就ok。也可参照git官方网站安装介绍：安装 Git。

2.ruby安装

ruby的windows版下载地址。 
  Octopress官方文档介绍，最新的Octopress最低依赖于ruby1.9.3。这里如果使用git clone的方式获取的octopress一定要安装大于ruby1.9.3的版本。之前我就是因为clone的是最新版的Octopress，而安装的是ruby1.9.2在之后的操作中出现问题。
  ruby安装非常简单，需要注意的是，要选中”Add Ruby executables to your PATH”。安装完之后打开windows命令窗口，执行ruby -v，如果执行成功，显示ruby版本号，则表示ruby安装成功。
  更新gem的更新源，ruby的官网经常被拦截，换成国内的更新源。命令如下：

 gem sources -a http://ruby.taobao.org/
 gem sources -r http://rubygems.org/
 gem sources -l

3.Devkit安装

DevKit的下载地址跟ruby的下载地址在一个网页上。选择ruby1.9.3使用的版本。 如果网址打不开，打开这个网址下载devkit。 安装过程中会要求解压，解压目录最好选择不带中文名和空格的目录。我第一次选择的是带中文的，导致执行之后的命令一直报错。
安装完之后，使用cmd命令打开windows命令窗口，执行如下命令：

windows的Devkit安装脚本

d:
cd devkit#我的devkit安装在d盘根目录下
ruby dk.rb init#生成config.yml，这里会检查将要添加DevKit支持的Ruby列表，只支持通过RubyInstaller安装的Ruby。
ruby dk.rb install

4.python安装

python的windows版下载地址，这里下载2.7.8版本。
  python没有什么特别之处，按照流程来安装就ok。安装成功后，执行easy_install pygments，安装博客高亮模块。我执行命令的时候报错，报”不存在的命令”，后来发现是环境变量的问题，python自己加的path环境变量中包含D:\Python27\Pythons没有后面的斜杠，正确应该是D:\Python27\Pythons\。

5.octopress安装

5.1，用命令行下载octopress源码：

用命令行下载octopress源码

d:
git clone git://github.com/imathis/octopress.git  octopress

5.2，更新octopress的更新源：

进入d:/octopress目录，用文本编辑器打开gemfile文件，将source “http://rubygems.org/”，修改为source “http://ruby.taobao.org/”。

5.3，安装octopress依赖项：

安装octopress依赖项

d:
cd octopress
gem install bundler
bundle install

6.登录github，新建主页库(Repositories)。

github分为用户主页和项目主页，用户主页就可以作为个人博客，用户主页输入username.github.com就可以进入。用户主页需要登录github用户，建立一个名字为username.github.com的库。例如twitter的GitHub主页是：http://twitter.github.com/。 
  没有github的用户，先注册一个github用户。注册之后，登录Github，新建一个库，名字为username.github.com,username为你的注册用户名。
  

说明1：最好不要勾选init this repo with a readme，因为octopress会自动为我们设置一个readme.md，如果服务器也有一个readme.md,在之后的操作可能会出现不同步的问题。
说明2：需要配置ssh,具体配置请看底下的注意问题1。

7.部署octopress静态站点到github。

7.1，进行github_pages设置：

打开windows命令窗口，输入

github_pages设置

d:
cd octopress
rake setup_github_pages

这个rake命令会问你的用户库，按照提示输入新建的用户库地址：

git@github.com:username/username.github.com.git
或
git@github.com:username/username.github.com

不要按照提示来输入git@github.com:username/username.github.io，要不然在之后的操作会报错，说找不到库。

说明1：rake是ruby make，ruby开发的一个项目构建工具。
说明2：

Github Pages使用master分支，就像web服务器上的公共目录，为我们的站点提供服务。但是在另外一个方面，我们又想要使用source分支，来版本控制项目源代码。rake setup_github_pages这个命令就可以全部帮我们设置好。
这个命令会执行如下操作： 
询问你主页库地址 
重新命名远程点从'origin'到'octopress' 
加上我们输入的主页库作为默认的origin remote 
转换活动分支从master到source 
根据你的库配置博客地址 
在_deploy目录设置一个master分支，用于部署。

7.2，将静态站点发布到github：

打开windows命令窗口，输入

将静态站点发布到github

rake install  
rake generate  
rake deploy

这个会安装默认博客主题，并生成博客站点，复制博客站点到_deploy文件夹，并将它加入到git,提交发布到github的master分支。几秒之后，在浏览器输入username.github.com，应该就可以进入你的博客站点了。

说明：如果想在本地预览博客效果，可以在rake generate命令执行之后，执行rake preview命令，执行成功，不要关掉命令窗口，在浏览器输入http://localhost:4000就可以预览你自己的博客了。

7.3，别忘了将从github克隆下来的octopress源代码提交到github的source分支：

源代码提交

git add .  
git commit -m 'your message'  
git push origin source

四、站点配置

站点配置介绍。

Jekyll允许你很轻松的设计你的网站，这很大程度上归功于灵活强大的配置功能。既可以配置在网站根目录下的 _config.yml 文件，也可以作为命令行的标记来配置。

一个_config.yml例子如下：

_config.yml例子

    url: http://picnic106.github.io
    title: 寧靜致遠
    subtitle: 焚膏油以繼晷，恆兀兀以窮年。
    author: songyj
    simple_search: https://www.google.com/search
    dePythonion:

你可以修改你博客的url，博客标题，博客的说明，博客作者等。详细站点配置请点击站点配置。

五、使用博客

octopress官方使用文档，以下基本是对官方文档的翻译：

Octopress提供一些rake命令，根据Jekyll的命名规则来创建文章和根据元数据预装载网页。

1，博客文章

博客文章必须被写在source/_posts文件夹下，而且命名规则必须依照Jekyll的命名规则：YYYY-MM-DD-post-title.markdown。这个文件名字将被用于url解析，时间将被用于定位文件以及文章排序。
  Octopress提供一些rake命令使用正确的命名规则以及正确的yaml元素来创建新的文章：rake new_post["title"]。

new_post命令要求一个自然的书写标题，以及剥离了创建文件时的不良url字符。默认新文章文章扩展名是markdown，但是在Rakefile文件中可以配置。例如：

new_post命令

rake new_post["我的第一篇博客"]#将创建source/_posts/2014-08-14-我的第一篇博客.markdown文件

这个文件名决定你的url。根据永久链接设置，新的博客文章访问url将是如下：http://username.github.com/blog/2014/08/14/我的第一篇博客/index.html。永久链接的规则是可以设置的，也可以不按照这个规则来，详细规则请看永久链接设置官方文档。

使用一个文本编辑器(例如win7下使用的是notepad++)打开新文章（source/_posts）。看到一块yaml头信息设置。

正是头信息开始让Jekyll变的很酷。任何只要包含YAML头信息的文件在Jekyll 中都能被当做一个特殊的文件来处理。头信息必须在文件的开始部分，并且需要按照 YAML 的格式写在两行三虚线之间。告诉Jekyll如何处理文章和网页。

YAML头信息

    ---
    layout: post
    title: "我的第一篇博客"
    date: 2014-08-14 5:59
    comments: true
    external-url:
    categories:
    ---

在这两行的三虚线之间，你可以设置一些预定义的变量或者甚至创建一个你自己定义的变量。这样在接下来的文章和任意模板中或者在包含这些页面或博客的模板中都可以通过使用 Liquid 标签来访问这些变量。
  这里你还可以把意见（comments）关掉，或者是给你的文章加一个类别。假如这篇文章是几个人同时写的话，还可以加上author: 你的名字。如果你的文章只是一个草稿，你还可以加上published: false，防止发布到正式博客上。
你还能加一个简单的类别或者多个类别，例如：

YAML头信息categories配置

    # One category
    categories: Sass

    # Multiple categories example 1
    categories: [CSS3, Sass, Media Queries]

    # Multiple categories example 2
    categories:
    - CSS3
    - Sass
    - Media Queries

2，博客网页

你可以加一个页面在你博客源目录的任何地方，他们会被Jekyll解析。这个url将直接指定到目录，所以about.markdown变成了site.com/about.html。Octopress 有一个新建网页的rake命令：

新建网页的rake命令

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中配置。一个新生成的页面大概是这样：

YAML头信息

    ---
    layout: page
    title: "Super Awesome"
    date: 2011-07-03 5:59
    comments: true
    sharing: true
    footer: true
    ---

3，博客内容

在yaml头信息设置后，你可以添加你的博客内容。博客内容可以使用你在站点配置文件中配置的标签语法，（例如Markdown标签语法，第二节有介绍）。这个文章或者网页的内容将被你在站点配置文件设置的标签引擎所渲染。在文章中，你另外你还可以使用liquid模板语法。插入<!-- more -->到你的文章将防止低于此标记的后的内容被显示在首页，一个“Continue →”按钮将显示全文。

4，生成和预览

生成和预览

rake generate   # 生成文章或者网页到对外访问的文件夹
rake watch      # Watches source/ and sass/ for changes and regenerates
rake preview    # 查看和启动一个服务，url是http://localhost:4000进行预览。

5，部署到github

部署到github

rake deploy   #将博客内容发布到github，过几秒，在浏览器网址输入你博客网址(username.github.com)访问你的个人站点。

六、注意问题

1，配置ssh

在本地安装完git,在github服务器注册完帐号，新建库之后，需要配置ssh密钥。新建库之后需要配置github的ssh密钥,要不然在rake deploy部署命令的时候会报错：

Permission denied (publicb.com/key).  
fatal: Could not read from remote repository.

ssh密钥:是一种用来识别受信任计算机的一种方法，而不涉及到密码。下面的步骤将带你产生一个ssh密钥，并将公钥加入到github帐户。

步骤1：

检查ssh密钥：检查计算机上是否存在ssh密钥,进入windows用户目录，例如我机器上的用户目录是：C:\Users\username。检查这个目录下是否有.ssh文件夹，如果有检查.ssh文件夹下是否有id_rsa.pub或者id_dsa.pub文件。如果没有进入第二步，如果已经存在了，进入第三步。

步骤2：

生成一个ssh密钥：生成一个密钥，需要执行以下命令，确保git/bin目录存在环境变量PATH里，your_email@example.com修改为你github的注册邮箱：

生成ssh密钥

ssh-keygen -t rsa -C "your_email@example.com"
#这个命令生成一对ssh公钥/私钥，输入一个目录保存ssh密钥，保存到用户目录的.ssh文件夹下。

然后会要求输入密码，不想输入，直接回车，但是官方建议是一定要输入密码。

步骤3：

配置github帐号的ssh公钥：使用文本文件打开id_rsa.pub文件，复制里面的内容，然后把内容加到github帐号。
  1，点击github帐号设置：

  2，在左边设置点击“ssh keys”： 

  3，在右边输入ssh密钥描述，然后粘贴你复制的ssh公钥,点击保存：

  4，测试sshkey是否配置正确，打开本地命令窗口，输入：

测试sshkey

ssh -T git@github.com

如果提示：

Hi picnic106! You've successfully authenticated, but GitHub does not provide shell access.

表示配置成功。

2，注意rake setup_github_pages命令的库路径

不要按照提示来输入git@github.com:username/username.github.io，要不然在之后的操作会报错，说找不到库。

那么如果输错了的解决办法是修改octopress/_deploy/.git/config下和你本身站点相关的username.github.io全修改成username.github.com，之后使用rake deploy重新部署。例如：

[remote "origin"]
url = git@github.com:username/username.github.io.git

修改成

 [remote "origin"]
 url = git@github.com:username/username.github.com.git

3，文件格式问题

所有文件格式必须是UTF-8的无BOM编码格式，可以使用文本编辑软件进行转换格式，例如notepad++转换格式在菜单：format->转为utf-8无bom编码格式。
至于什么是bom，且为什么要这样，goole吧，本人也了解不多。如果不这么设置，在有一些命令会报错。

4，部署到github，报版本不一致问题

有时候运行rake deploy会报错non-fast-forward errors,出现这个问题是因为本地文件跟github服务器文件版本不一致，例如上面谈到的，在新建库的时候建立了readme.md文件但是本地进行rake generate的时候也生成了readme.md文件，那么就会造成版本不一致问题。
解决办法：

解决报版本不一致脚本

git config branch.master.remote origin  
git config branch.master.merge refs/heads/master  
git pull#将远程文件拉到本地，并进行合并merge
rake deploy#就不会出现问题了

Octopress 2.0 介绍

Octopress是Brandon Mathis为jekyll设计的一个框架，jekyll是Github Pages服务可以支持的博客形态的静态网站生成器。

使用jekyll来写博客，你不得不自己写html模板，css，js以及自己处理各种配置。但是octopress框架托管一切。简单的clone或者fork octopress开源框架，安装依赖软件和主题，你就可以开始写博客了。

2.0有什么新特性？

简短的回答是：一切。基于mojombo/jekyll开发的Octopress已经使用满山的好特性从底层被完全重写。

Octopress有如下特性：

• 一个html5的语义模板
• 第一个移动端响应布局（旋转或者调整您的浏览器观看）
• 内置很多第三方支持，例如：Twitter、Google Plus One、Disqus Comments、Pinboard、Delicious以及Google Analytics
• 使用Github pages或者Rsync，具有很简单的部署策略
• 内置POW或者Rack服务
• 很容易的使用Compass和Sass来构建主题
• 很漂亮的Solarized语法高亮

一定要查看文档获取完整的信息(原文是the full scoop，scoop是勺子，不知这样翻译对不对?)。

插件仓库

大部分插件都创建好了，但是小部分来自于Jekyll社区的插件，一直在改进和更新。

• html5的视频标签 - 轻松发布mp4的html5播放器，使用flash player fallback
• 代码块 - 很方便的内联代码共享
• 包含代码 - 从你的文件系统中嵌入代码
• Gist标签 - 自动下载和嵌入gist要点
• 图片标签 - 很方便的发布图片使用类名字和标题
• 渲染部分 - 插入任何文件到另外的文章或者界面
• 引用块 - 生成漂亮的语义快引用
• Pullquote - 生成只拉引用的css样式 - 没有重复数据，没有js
• 类别生成器 - 为每一个博客类别生成归档页面

更多插件请查看插件列表。

准备好开始了吗？

Octopress是真的很容易设置和不是，点击这里开始。

现在就是这样了。查看文档，查看github的octopress库，发布问题，发给我支持请求，以及告诉你所有朋友。

Octopress文档

Octopress是为了Jekyll(一个Github Pages支持的静态博客引擎)而设计的框架。假如你遇到困难，看一下文档，我很高兴帮助你。假如你发现错误在文档里，发布一个错误，或者fork，然后发送一个拉的请求到主支。

开始吧

这节将帮助你设置以及解释怎样为你的站点配置octopress。注意：假如你已经有一个其他博客，查看博客迁移界面，帮助你为了形成octopress博客而获取当前博客的设置。

• 初始化设置-获取源代码以及安装依赖
• 基本配置-能使用第三方服务以及自定义你自己的博客

使用octopress

你的博客应该极好的，让人羡慕的，底下能帮助到你变成这样：

• 博客基础 - 怎样创建文章和页面
• 部署octopress - 部署到Rsync和Github界面服务的简单介绍
• 分享代码片段 - 简单分享代码片段
• 博客插件 - 博客插件概览
• 主题和定制化 - 改变主题的指南
• 更新octopress - 更新到最新octopress的指南

octopress插件 - 使用和例子

Octopress整个套件有如下插件。许多是专门为octopress而写的，但是有一些是从jekelly社区选择的，而且有很多的更新和改进。

• html5视频标签 - 嵌入mp4编码格式的html5视频
• 简单代码块 - 简单轻量级的代码分享
• 代码块 - 带有标题和代码链接的代码块分享
• 包含代码 - 使用一个可下载的链接从你的文件系统嵌入代码
• gist标签 - 自动下载和嵌入 Github gists
• jsFiddle - 从jsFiddle下载内嵌代码
• 图片标签 - 很容易的发布图片使用类名和标题
• 渲染部分 - 插入任何文件到另外的文章和页面
• 引用块 - 生成漂亮的语义引用块
• 拉引用 - 仅仅拉引用生成css,没有重复数据，没有js
• 类别生成器 - 为每一个博客类别生成归档页面
• 包含多个页面 - 包含一系列的界面在config.yml配置
• 提出 - 将Liquid的日志提出到终端(为了主题和插件开发者)

底下的过滤器被octopress使用，并作为不要的记录在他们的源里面。

Octopress过滤器 - 只是octopress建立liquid过滤器 
网站地图生成器 - 生成一个seo友好的sitemap.xml
Haml转换 - 允许.haml的界面被jekelly解析 代码高亮 - 将代码片段来突出显示并缓存来加快jekelly的处理 Titlecase - 被许多插件需要的自动生成合适的标题

Octopress插件源