原文来自:Jekyll Bootstrap API

 本文结构:
    Jekyll Bootstrap API
      |– 工作原理
      |– 创建新方法
      |– 调用方法
      |– 注意事项
      |– 贡献
    Jekyll Bootstrap 方法
      |– JB/analytics
      |– JB/categories_list
      |– JB/comments
      |– JB/pages_list
      |– JB/posts_collate
      |– JB/setup
      |– JB/sharing
      |– JB/tags_list
    Jekyll Bootstrap 组件覆盖
      |– 使用方法

Jekyll Bootstrap API

工作原理

Bootstrap API 通过 Jekyll 来包含其他的文件。这允许我们打包复杂的 Liquid 代码到可复用模块中,这些模块可以在模板、列表页和文章页中调用。

如果你熟悉 ruby-on-rails,此模式与 在 view 帮助模块中定义方法 和 在 views 中调用它们是一样的。

创建新方法

Jekyll-Bootstrap 使用可加载文件来仿真 ruby 方法。首先封装 Liquid 逻辑代码在 Jekyll 的 _includes 文件夹中。

  |-JB
    |-tags_list
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{ % if site.JB.tags_list.provider == "custom" % }
  { % include custom/tags_list % }
{ % else % }
  { % if tags_list.first[0] == null % }
    { % for tag in tags_list % } 
      <li><a href="{ { BASE_PATH } }{ { site.JB.tags_path } }#{ { tag } }-ref">{ { tag } } <span>{ { site.tags[tag].size } }</span></a></li>
    { % endfor % }
  { % else % }
    { % for tag in tags_list % }
      <li><a href="{ { BASE_PATH } }{ { site.JB.tags_path } }#{ { tag[0] } }-ref">{ { tag[0] } } <span>{ { tag[1].size } }</span></a></li>
    { % endfor % }
  { % endif % }
{ % endif % }
{ % assign tags_list = null % }

正确写法:在 ‘{ {’、‘} }’、‘{ %’、‘% }’ 之间是不存在空格的。

以上是 JB/tags_list 样例,可以列举出所有标签和每个标签的文章总数。

为了模拟调用方法时的参数传递,应尽量使用局部变量。在引入文件前我们可以通过局部变量传递参数。

调用方法

1
2
3
4
<ul>
  { % assign tags_list = site.tags % }
  { % include JB/tags_list % }
</ul>

正确写法:在 ‘{ {’、‘} }’、‘{ %’、‘% }’ 之间是不存在空格的。

你可以尽可能的定义所需要的参数,但在文件引入后将其赋值为空以保护其他模块。

注意事项

在 Liquid 中,变量不能内连到任何地方,甚至字符串都不可以。这就意味着不可以传递数组或哈希表等。然而如上所示,你可以通过引用,赋值局部变量为已经存在的变量。

如果需要传递数据结构,你需要在 YAML 前缀或者 _config.yml 中进行申明,然后再引用它们。

贡献

如果你有一个很好的功能模块,请按照以上的样式进行书写,并推送至Jekyll-Bootstrap,我们将会包含它。

Jekyll Bootstrap 方法

JB/analytics

在你的站点里包含分析追踪代码

1
{ % include JB/analytics % }

正确写法:在 ‘{ {’、‘} }’、‘{ %’、‘% }’ 之间是不存在空格的。

默认情况下,在本机调试时并没有启用分析机制。只用当 site.safe 设置为 true 时分析机制才正式启用。GitHub 将此时的模式为生产模式。

此方法应该应用于主题的 default.html 文件中,关于此方法的配置详情见:Jekyll Configuration System

JB/categories_list

这里提供了非常便利的方式来列举所有类别。

####列举整站点类别

通过使用 site.categories 变量列举整个站点的类别。

1
2
3
4
<ul>
  { % assign categories_list = site.categories % }
  { % include JB/categories_list % }
</ul>

正确写法:在 ‘{ {’、‘} }’、‘{ %’、‘% }’ 之间是不存在空格的。

####列举特定页面类别

通过 page.categories 可以列举特定页面的类别。

1
2
3
4
<ul>
  { % assign categories_list = page.categories % }
  { % include JB/categories_list % }
</ul>

正确写法:在 ‘{ {’、‘} }’、‘{ %’、‘% }’ 之间是不存在空格的。

####迭代列举每篇文章的类别

1
2
3
4
5
6
7
{ % for post in site.posts % }
  <h3>Categories for: { { post.title } }</h3>
  <ul>
    { % assign categories_list = post.categories % }  
    { % include JB/categories_list % }
  </ul>
{ % endfor % }

正确写法:在 ‘{ {’、‘} }’、‘{ %’、‘% }’ 之间是不存在空格的。

####源码

1
./_includes/JB/categories_list

JB/comments

在博客中引入一个评价回复系统。

1
{ % include JB/comments % }

正确写法:在 ‘{ {’、‘} }’、‘{ %’、‘% }’ 之间是不存在空格的。

评价回复系统在本机调试时不一定可用,这取决于采用哪种评价回复系统。

此方法通常使用在主题的 post.html 文件中,关于此方法的配置详情见:Jekyll Configuration System

JB/pages_list

####列举所有页面

1
2
3
4
<ul>
  { % assign pages_list = site.pages % }
  { % include JB/pages_list % }
</ul>

正确写法:在 ‘{ {’、‘} }’、‘{ %’、‘% }’ 之间是不存在空格的。

####列举小组内容的页面

pages页不支持分类,但支持类似的分组功能。我们可以在 YAML 前缀中进行声明。

1
2
3
4
5
---
layout: default
title: A Nice Title
group: project
---

可以通过一下代码来列举小组内的所有页面

1
2
3
4
5
<ul>
  { % assign pages_list = site.pages % }
  { % assign group = 'project' % }
  { % include JB/pages_list % }
</ul>

正确写法:在 ‘{ {’、‘} }’、‘{ %’、‘% }’ 之间是不存在空格的。

####源码

1
./_includes/JB/pages_list

JB/posts_collate

按照年、月列举所有的文章。

####以时间倒序整理文章

默认情况下所有文章是以时间倒序进行排列的。

1
2
3
4
<ul>
  { % assign posts_collate = site.posts % }
  { % include JB/posts_collate % }
</ul>

正确写法:在 ‘{ {’、‘} }’、‘{ %’、‘% }’ 之间是不存在空格的。

####整理一个子集的文章

以下列举了标签为 Jekyll 的所有文章。

1
2
3
4
<ul>
  { % assign posts_collate = site.tags.jekyll % }
  { % include JB/posts_collate % }
</ul>

正确写法:在 ‘{ {’、‘} }’、‘{ %’、‘% }’ 之间是不存在空格的。

####源码

1
./_includes/JB/posts_collate

JB/setup

提供了所有 layouts, posts, 和 pages 的 Liquid 全局变量。

1
2
3
<ul>
  { % include JB/setup % }
</ul>

正确写法:在 ‘{ {’、‘} }’、‘{ %’、‘% }’ 之间是不存在空格的。

最相关的变量是: BASE_PATH 将指定所有的 post 和 page 的连接, ASSET_PATH 将指定某主题的所有资源。

这些路径信息在本机调试和生产模式时会自动进行切换,便于开发。

JB/sharing

这个目前还未完成。在文章页上引入分享的插件。

1
2
3
<ul>
  { % include JB/sharing % }
</ul>

正确写法:在 ‘{ {’、‘} }’、‘{ %’、‘% }’ 之间是不存在空格的。

此方法通常使用在主题的 post.html 文件中,关于此方法的配置详情见:Jekyll Configuration System

JB/tags_list

提供所有的标签以及文章总数

####列举整站点标签

我们可以使用 site.tags 来列举整站点标签

1
2
3
4
<ul>
  { % assign tags_list = site.tags % }
  { % include JB/tags_list % }
</ul>

正确写法:在 ‘{ {’、‘} }’、‘{ %’、‘% }’ 之间是不存在空格的。

####列举特定页面的标签

可以通过 page.tags 来列举特定页面的标签

1
2
3
4
<ul>
  { % assign tags_list = page.tags % }
  { % include JB/tags_list % }
</ul>

正确写法:在 ‘{ {’、‘} }’、‘{ %’、‘% }’ 之间是不存在空格的。

####迭代列举每篇文章的标签

1
2
3
4
5
6
7
{ % for post in site.posts % }
  <h3>Tags for: { {post.title} }</h3>  
  <ul>
    { % assign tags_list = post.tags % }  
    { % include JB/tags_list % }
  </ul>
{ % endfor % }

正确写法:在 ‘{ {’、‘} }’、‘{ %’、‘% }’ 之间是不存在空格的。

####源码

1
./_includes/JB/tags_list

Jekyll Bootstrap 组件覆盖

以上所有的 Jekyll-Bootstrap 方法都可以通过自定义实现覆盖。不建议直接在 Jekyll-Bootstrap 源文件中进行修改,因为这样的话在升级到新版本时将带来许多问题。

相反,你可以自定义文件在 custom 文件夹中。你可以重写标签或者页面的输出形式等,也可以重写评价回复系统等。

使用方法

####1. 配置文件

_config.yml 文件中说明你需要重写方法。

1
2
3
JB :
  tags_list :
    provider : "custom"

以上是告诉 Jekyll-Bootstrap 你需要自定义 tags_list

####2. 新增自定义文件

以下是自定义文件的路径

1
./_includes/custom/tags_list

此文件的名称就是 Jekyll-Bootstrap 中源文件的名称。你还可以复制一份源文件放在 custom 目录下然后进行修改。

遵循以上规则,你还可以自定义更多所需的方法。