生命之氢

Hailong Hao's Laboratory

Octopress 精益修改 (4)

| 评论

1. CodeRay Block 代码块插件

用 Octopress 写博客的很多朋友需要在博客内容当中添加代码块，毕竟这是一个「为黑客而生的博客框架」。Octopress 除了可以使用 Markdown 语言默认的代码块实现方式之外，本身也集成了很强大的代码块 (Code Block) 插件，按照官方的说明调用即可，比如：

节选自比特币 Python API 
1
2
3
4
5

rv = conn.validateaddress(foo)
if rv.isvalid:
    print "The address that you provided is valid"
else:
    print "The address that you provided is invalid, please correct"

官方的 Code Block 插件支持语法高亮，本身的显示效果也非常不错，可以与博客大背景的深色形成呼应。但如果你的文章中出现大量的代码块，黑色背景看起来可能不那么舒服。这时，你可能想要使用浅色系的代码块，比如：

节选自比特币 Python API 
rv = conn.validateaddress(foo)
if rv.isvalid:
    print "The address that you provided is valid"
else:
    print "The address that you provided is invalid, please correct"

最早看到这种风格的显示是在 Kat Hagan 的博客，她在文章中介绍了一种新的语法高亮工具——CodeRay，使用这种工具即可实现上面浅色圆角的代码块。作者同时也是一位极具分享精神的 Web 开发者，为了方便大家使用 CodeRay，她还专门制作了一个可直接安装的 Octopress 插件。

但是她这个插件取消了 CodeRay 自带的行号功能，在当你需要指出某一行代码时，就非常不方便。为了解决这个问题，Jan Stevens 在 Kat 的插件基础上，开发了可以添加行号的 CodeRay 插件，但为了适应他自己博客的风格，同时也写了新的样式表。

由于 Kat 用的是 Octopress 默认主题，从总体风格上而言，Kat 的插件样式更适合我们的博客，于是我尝试着用 Kat 的样式表配合 Jan 的插件使用，在代码块没有标题框 (Caption) 的情况下表现完美。但一旦加上标题框，问题就出现了：代码块主体部分与标题框的连接处出现了不必要的圆角，显得非常难看。为了解决这一问题，我在他们的基础上修改了 Coderay Block 插件，如果你需要，在这里：Octopress CodeRay Block.

具体安装和使用方法如下：

1.1 安装 kramdown, CodeRay

首先你需要在你的博客程序中安装 kramdown 和 CodeRay（如果你已经安装过，则可以跳过此步）：

在 Gemfile 中添加如下两行代码：

gem 'kramdown'
gem 'coderay'

在终端执行如下命令：

bundle install

然后修改 _config.yml 文件中相关内容如下：

_config.yml 
markdown: kramdown
kramdown:
    use_coderay: true
    coderay:
        coderay_line_numbers: table
        coderay_css: class

其中 coderay_line_numbers: table 表示激活 CodeRay 的行号功能。

1.2 修改样式表

把 /sass/custom/_coderay.scss 文件复制到你自己的 /sass/custom/ 文件夹下。

把 /sass/custom/_styles.scss 文件中的代码添加到你自己的 /sass/custom/_styles.scss文件夹中。

安装完成。

1.3 使用方法

{ % coderay [lang:lang] [linenos:true|false(default)] [title] [url] [link text] % }
代码片段
{ % endcoderay % }

你可以看到这个使用方法与官方的 CodeBlock 插件非常像，其中：lang: 定义了代码的语言，linenos: 定义了是否显示行号（默认不显示），title 是代码框标题，url 是链接，link text 是链接文本。

2. 给图片添加说明 (Caption)

在我们发布文章的时候，难免会插入图片。你可以把你想插入的图片（比如 dream.jpg）放到 source/images/ 文件夹下。重新生成部署站点之后，图片的地址为 {{ root_url }}/source/images/dream.jpg，当然你也可以给 images 文件夹下再添加其他文件夹，只要你加到图片最终的路径上即可。

具体使用图片时，官方自带了图片插件 (Image Tag)，使用非常方便，具体方法可以参考官方说明。但有时候，我们需要给图片添加说明 (Caption)，比如在我的文章「为什么「Enter 键」要被翻译为「回车键」？」中的第二张图。这时官方的插件就显得不够用了，参照 Image Captions for Octopress , 我们可以按如下步骤实现想要的功能：

2.1 制作并添加插件

首先新建一个文本文件，复制如下代码，另存为 image_caption_tag.rb 文件，注意要使用 .rb 后缀。然后再把这个文件放到 plugins 目录下。

plugins/image_caption_tag.rb 
# Title: Image tag with caption for Jekyll
# Description: Easily output images with captions

module Jekyll

  class CaptionImageTag < Liquid::Tag
    @img = nil
    @title = nil
    @class = ''
    @width = ''
    @height = ''

    def initialize(tag_name, markup, tokens)
      if markup =~ /(\S.*\s+)?(https?:\/\/|\/)(\S+)(\s+\d+\s+\d+)?(\s+.+)?/i
        @class = $1 || ''
        @img = $2 + $3
        if $5
          @title = $5.strip
        end
        if $4 =~ /\s*(\d+)\s+(\d+)/
          @width = $1
          @height = $2
        end
      end
      super
    end

    def render(context)
      output = super
      if @img
        "<span class='#{('caption-wrapper ' + @class).rstrip}'>" +
          "<img class='caption' src='#{@img}' width='#{@width}' height='#{@height}' title='#{@title}'>" +
          "<span class='caption-text'>#{@title}</span>" +
        "</span>"
      else
        "Error processing input, expected syntax: <img class="[class name(s)]" src="/url/to/image" title="[width height] [title text]" >"
      end
    end
  end
end

Liquid::Template.register_tag('imgcap', Jekyll::CaptionImageTag

2.2 修改样式表

在 sass/base/_utilities.scss 文件中添加如下几行代码：

sass/base/_utilities.scss 
@mixin reset-shadow-box() {
  @include shadow-box(0px, 0px, 0px);
}

最后，打开 sass/partials/_blog.scss 文件，作如下修改，其中减号表示删掉该行，加号表示新添该行：

sass/partials/_blog.scss 
   article {
     font-size: 2.0em; font-style: italic;
     line-height: 1.3em;
   }
-  img, video, .flash-video {
+  img, video, .flash-video, .caption-wrapper {
     @extend .flex-content;
     @extend .basic-alignment;
     @include shadow-box;
+    &.caption {
+      @include reset-shadow-box;
+    }
+  }
+  .caption-wrapper {
+    display: inline-block;
+    margin-bottom: 10px;
+    .caption-text {
+      background: #fff;
+      text-align: center;
+      font-size: .8em;
+      color: #666;
+      display: block;
+    }
   }
   video, .flash-video { margin: 0 auto 1.5em; }
   video { display: block; width: 100%; }

2.3 使用方法

按照如下代码将图片插入文中：

<span class='caption-wrapper'><img class='caption' src='/right]' width='' height='' title='[url] [caption] [width] [height] [title text] [alt text]'><span class='caption-text'>[url] [caption] [width] [height] [title text] [alt text]</span></span>

其中，[left/right] 是表示图片显示在页面上的位置，[url] 是图片完整链接，[caption] 是图片说明，[width] 和 [height] 分别是图片的宽度和高度，[title] 是图片标题，[alt text] 是图片替代文字。

有必要区别一下 [caption], [title], 和 [alt text] 三个图片属性。[caption] 指显示在图片下方的说明文字，[title] 指鼠标悬停在图片上时显示出来的文字，[alt text] 指图片无法加载时，该图片的位置所显示的文字。

3. 使用 FontAwesome

装饰网站和撰写文章，不可避免的要使用到一些 Logo 和图标，对于一个非设计专业人士来说，该如何轻松获取图标呢？这里有一个巨大的图标库 Font Awesome，事实上，我博客导航栏和侧边栏使用的 Logo 就来自 Font Awesome.

要使用 Font Awesome，你只需要简单地在 source/_includes/custom/head.html 中添加如下一行代码：

source/_includes/custom/head.htmllink
<link href="//netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet">

安装工作就完成了。然后你看中哪个 Logo，直接输入官方的 Logo 代码，就可以让 Logo 出现在页面相应位置。比如你想显示照相机的 Logo：

你只需要输入如下代码：

<i class="fa fa-camera-retro fa-5x"></i>

有时候 Font Awesome 可能会出现与 kramdown 解析器相冲突的情况，导致全局样式发生变化，这是你只需要在 Logo 的代码前后分别添加 {::nomarkdown} 和 {:/nomarkdown}强制 kramdown 不去解析这段语句即可，比如上面的代码可以改为：

{::nomarkdown}
<i class="fa fa-camera-retro fa-5x"></i>
{:/nomarkdown}

本文评论