集合(Collections)

并非所有的都会是文章或页面。也许您想要记录您开源项目中涉及的各种解决方案,团队成员,或是某次会议记录。集合(Collection)允许您定义一种新的文档类型,它既可以像页面和文章那样工作,也可以拥有它们特有的属性和命名空间。

使用集合

第一步:让 Jekyll 读取您的集合

将下面的代码加入您的 _config.yml 文件,将 my_collection 替换为您集合的名字。

collections:
- my_collection

您也可以在配置中为你的集合加入具体的元数据:

collections:
  my_collection:
    foo: bar

集合也可以设置默认的属性:

defaults:
  - scope:
      path: ""
      type: my_collection
    values:
      layout: page

第二步:加入您的内容

创建对应的文件夹(如 <source>/_my_collection)并添加文件。若 YAML 头信息存在,他将被作为数据读入,并且其后的任何信息都将被保存在文档的content 属性中。如果没有任何 YAML 头信息存在, Jekyll 将不会在您的集合中生成任何文件。

确保你的文件夹命名正确

文件夹名称必须和你在_config.yml中定义的集合名称完全一致,包括前缀的_字符。

第三步:选择性渲染你的集合文件为独立文件

如果你希望 Jekyll 对每一个你集合中的文件,都创建一个公开的,渲染后的版本,请在_config.yml中,将你集合的元数据中将output键设置为true

collections:
  my_collection:
    output: true

这将会依据每一个在集合中的文档创建一个文件。例如,你有一个_my_collection/some_subdir/some_doc.md文件,它将利用 Liquid 以及你选用的 Markdown 转换器创建一个<dest>/my_collection/some_subdir/some_doc.html文件。

如同设置了 Permalinks 属性的文章,这些文件的URL也可以通过对集合的permalink元数据进行设置来自定义。

collections:
  my_collection:
    output: true
    permalink: /awesome/:path/

例如,你有一个_my_collection/some_subdir/some_doc.md文件,它将写入到<dest>/awesome/some_subdir/some_doc/index.html路径下。

不要忘记添加 YAML 头

没有头信息的文件将被视为静态文件,它们仅会被简单拷贝到目的路径下,而不会被处理。

变量 说明

collection

所包含集合的标签

path

文档相对于集合文件夹的路径

name

文档的基本文件名,任何空格和非字母数字的字符将被替换为连字符

title

文档的小写字母标题(在 头信息中定义),任何空格和非字母数字的字符将被替换为连字符。如果title在头信息中未定义,该值等同于name

output_ext

输出文件的文件扩展名

Liquid 属性

集合

每个集合均可访问 Liquid 的site变量。例如,若你希望获取_albums中的集合albums,请使用site.albums变量。每个集合都具有一个他本身的文档数组(例如,site.albums就是一个文档组成的数组,和site.pagessite.posts类似)。下面会介绍如何获取这些文档的属性。

集合可以通过site.collections获取,其中包含你在_config.yml(如果存在)中定义的元数据和下面的信息:

变量 描述

label

你集合的名称,如my_collection

docs

文档构成的数组。

files

由集合中静态文件构成的数组。

relative_directory

集合中相对于站点路径的源目录的路径。

directory

集合源目录的完整路径。

output

集合中的文件将作为单独的文件输出。

文档

作为文档 YAML 头信息的补充,每一个文档还具有以下属性。

变量 说明

content

文档的内容(未被渲染的)。若不存在 YAML 头信息, Jekyll 将不会在你的集合中生成该文件。若定义 YAML 头,这部分内容将是头信息结尾`---`后面的全部内容。

output

基于文档content的渲染后的输出。

path

文档源文件的完整路径。

relative_path

文档相对于站点源的相对路径。

url

渲染后集合的 URL 。该文件仅在其所属集合名称在站点配置文件中的 render 键中时会被写入到目的地。

collection

文档所属的集合名称。

获取集合的属性

在站点的任何位置,你都可以获取在 YAML 头重的属性。通过上面的示例,配置一个site.albums集合,并在对应的文件的头信息中创建如下结构的数据(需要使用引擎支持的标记语言,且不能以.yaml作为扩展名):

title: "Josquin: Missa De beata virgine and Missa Ave maris stella"
artist: "The Tallis Scholars"
director: "Peter Phillips"
works:
  - title: "Missa De beata virgine"
    composer: "Josquin des Prez"
    tracks:
      - title: "Kyrie"
        duration: "4:25"
      - title: "Gloria"
        duration: "9:53"
      - title: "Credo"
        duration: "9:09"
      - title: "Sanctus & Benedictus"
        duration: "7:47"
      - title: "Agnus Dei I, II & III"
        duration: "6:49"

若要在一个页面中列出集合中的专辑(album),可以使用下面的模板:

{% for album in site.albums %}
  <h2>{{ album.title }}</h2>
  <p>Performed by {{ album.artist }}{% if album.director %}, directed by {{ album.director }}{% endif %}</p>
  {% for work in album.works %}
    <h3>{{ work.title }}</h3>
    <p>Composed by {{ work.composer }}</p>
    <ul>
    {% for track in work.tracks %}
      <li>{{ track.title }} ({{ track.duration }})</li>
    {% endfor %}
    </ul>
  {% endfor %}
{% endfor %}

此网站由 @xcatliu 维护,由 开源爱好者们 共同翻译。若发现错误或想贡献翻译,请访问: xcatliu/jekyllCN