Runge Zhai's Blog

I Came, I Coded, I Crashed | 苟不记之笔墨, 未免有辜彼苍之厚

Octopress Q&A

关于Octopress的配置在这个博客中有详细的教程, 这里我只是做一些很必要的配置或者开发中遇到的各种问题的总结. 会一直持续更新.

文章在首页显示摘要

一般情况下我们想让文章在主页只显示摘要, 而不是全部显示, 这种情况下, 我们只需要在文章开头的摘要后面空行加入<!--more-->.

Markdown文件拓展名修改

默认的MarkDown文件名是.markdown. 我们想把它改成.md, 这样更简洁. 方法是修改 rakefile 文件, 将下面两行

1
2
new_post_ext    = "markdown"  # default new post file extension when using the new_post task
new_page_ext    = "markdown"  # default new page file extension when using the new_page task

替换成

1
2
new_post_ext    = "md"  # 默认新日志文件后缀
new_page_ext    = "md"  # 默认新页面文件后缀

修改默认Markdown解释器

默认的Markdown解释器是rdiscount, 可以把它改成GitHub推荐的kramdown. 打开Gemfile, 在最后新增下面一行

1
gem 'kramdown'

然后在Terminal执行bundle install安装这个依赖项(很可能已经安装过了).

再打开_config.yml, 找到markdown: rdiscount, 将其中的rdiscout改成kramdown. 并将下面的删除或注释掉(yml文件的行注释是前面加#).

1
2
3
4
5
rdiscount:
  extensions:
    - autolink
    - footnotes
    - smart

在主页侧边栏显示文章分类

  • plugins目录下新建category_list_tag.rb文件, 内容如下:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
module Jekyll 
  class CategoryListTag < Liquid::Tag 
    def render(context) 
      html = "" 
      categories = context.registers[:site].categories.keys 
      categories.sort.each do |category| 
        posts_in_category = context.registers[:site].categories[category].size 
        category_dir = context.registers[:site].config['category_dir'] 
        category_url = File.join(category_dir, category.gsub(/_|\P{Word}/, '-').gsub(/-{2,}/, '-').downcase) 
        html << "<li class='category'><a href='/#{category_url}/'>#{category} (#{posts_in_category})</a></li>\n" 
      end 
      html 
    end 
  end 
end
	
Liquid::Template.register_tag('category_list', Jekyll::CategoryListTag)
  • source/include/custom/asides目录下新建category_list.html文件, 内容如下:
1
2
3
4
5
6
<section>
  <h1>Categories</h1>
  <ul id="categories">
    {% category_list %}
  </ul>
</section>
  • 修改_config.yml文件

    找到以default_asides:开头的一行, 添加custom/asides/category_list.html. 到了这里, 重新生成部署已经可以看到结果了, 但仔细看会发现, 分类的名字中的大写字母都被变成了小写, 如果想改成本来的大小写, 参考下一步.

  • 修改Jekyll, 取消自动小写分类名称

    找到Jekyll的源代码目录, 我这里是/Users/liuge/.rvm/gems/ruby-1.9.3-p551/gems/jekyll-2.5.3/lib/jekyll 修改目录下的post.rb文件, 找到如下内容, 删除其中的downcase.

1
self.categories = self.data.pluralized_array('category', 'categories').map {|c| c.to_s.downcase}

如果遇到Error: Pygments can't parse unknown language: </p>这种问题, 一般是文章中包含HTML代码等非常规文字, 修改plugins/pygments_code.rb文件, 将raise "Pygments can't parse unknown language: #{lang}."替换成raise "Pygments can't parse unknown language: #{lang}#{code}." 然后再执行 rake generate 就可以看到产生问题的位置. 实际使用中, 我发现产生问题的位置都是在文章中贴的HTML代码块或者其他非常规文字的位置, 解决方法是代码块结束的```1(triple-backtick)前后都需要留一个空行. 顺便说一句, Pygments是语法高亮插件.

在文章中显示特殊字符

有一些字符是Octopress的保留字符, 比如{{, ^ ...等. 若在文章中直接输入这些字符, 文章生成可能会报错或者显示一些意想不到的内容.

若要在文中显示这些字符, 需要将包含这些字符的文字放在{% raw %}{% endraw %}之间.

已有Octopress在新机器上的配置 / 多终端并行写作

如果已经有了自己的 Octopress, 如何在一台新机器上将文章同步到本地并配置环境. 就算只有一个人来维护Blog, 有时候也难免会遇到换电脑什么的情况, 怎么办.

首先, 科普, Blog 的 Repository有两个分支, mastersource, master 是存储的 Blog 网站本身, 而source是Blog的源文件. master的内容存储在根目录下的_deploy目录下, 当我们执行rake deploy, 其中就包含 push 到 master 操作, 当我们随后 push source 分支时, _deploy目录会被忽略, 详细内容可以查看source分支的.gitignore文件.

  • 将 Blog clone 到本地

将 source 分支 clone 到本地目录 (下面是octopress)

1
git clone -b source git@github.com:username/username.github.com.git octopress 

将 master 分支 clone 到 上面 octopress目录下的 _deploy 目录下

1
2
cd octopress  
git clone git@github.com:username/username.github.com.git _deploy  
  • 配置环境

包括安装ruby和各种依赖项, 参考这里, 不再需要执行rake install安装主题.

  • 更新

如果在其他地方更新过文章, 那么在本地需要 pull 一下最新的提交. 由于 master 是 Octopress自动更新的, 所以我们只需要更新 source 分支.

1
git pull origin source  # update the local source branch

站内文章链接

如果想在文章中引用自己的其他文章, 可以使用下面的格式, 其中2010-07-21-name-of-post是要引用的markdown或者html文件的文件名:

1
[Some Link]({% post_url 2010-07-21-name-of-post %})

导航栏新增About

Octopress有两种类型的文章, 一种叫post, 一种叫page, 概念和WordPress差不多. 如果想在导航栏新增”关于”页, 这是一个page, 不是我们平时发表的post. post源文件存放在source/_posts目录下, 每个page默认对应一个目录, 直接存放在source目录下, Octopress应该是自动查找page目录下的index.md或者index.html.

  • 新建页面
1
rake new_page["about"]

执行完以后会在source下默认新建一个名为about的目录, 目录下有一个名为index.md的文件. 和post一样, 可以输入自己想写的内容.

  • 导航栏新建链接指向该page

编辑source/_includes/custom/navigation.html文件, 默认的内容是

1
2
3
4
<ul class="main-navigation"> 
  <li><a href="{{ root_url }}/">Blog</a></li> 
  <li><a href="{{ root_url }}/blog/archives">Archives</a></li> 
</ul>

我们添加一行

1
2
3
4
5
<ul class="main-navigation">
  <li><a href="{{ root_url }}/">Blog</a></li>
  <li><a href="{{ root_url }}/blog/archives">Archives</a></li>
  <li><a href="{{ root_url }}/about">About</a></li>
</ul>
  • 修改字体大小和颜色

字体的样式在sass/base/_typography.scss中设置, 但不建议直接修改该文件. 如果想做修改的话, 修改sass/custom/_styles.scss文件.



Reference

improve-octopress-advanced-tweaks-tips

Octopress CDN Config

Markdown Syntax

Kramdown Syntax

  1. 关于markdown如何显示```等特殊字符, 以及如何添加脚注(footnotes), 参考这里

Comments