Jekyll使用教程笔记五-CSDN博客

合集

并非所有内容都是文章或页面。也许你想记录开源项目中的各种方法、团队成员、或会议中的会话。合集允许你定义一种类似页面或文章那样正常工作的新类型的文档，但也具有其自己的唯一属性和名称空间。

使用合集

开始使用合集，需要一下三步：

第一步：告诉Jekyll读取你的合集
第二步：添加你的内容
第三步：有选择地将你的合集文档渲染为独立的文件

第一步：告诉Jekyll读取你的合集

将以下内容添加到你的网站的_config.yml文件中，将my_collection替换为你的合集的名称：

collections:
- my_collection
复制代码

你可以在配置中为你的合集指定元数据：

collections:
- my_collection:
    foo: bar
复制代码

也可以为合集设置默认属性：

defaults:
  - scope:
      path: ""
      type: my_collection
    values:
      layout: page
复制代码

重要：Gather your collections[3.7.0]

你可以使用collections_dir: my_collections选择指定一个目录来将所有合集存储在同一个位置。

然后，Jekyll将在my_collections/_books中查找books合集，并在y_collections/_recipes中查找recipes合集。

警告：确保将草稿和文章移动到自定义合集目录中

使用collections_dir: my_collections选择指定一个目录来将所有合集存储在同一个位置，则需要将_drafts和_posts目录移至my_collections/_drafts和my_collections/_posts。请注意，你的合集目录的名称不能以下划线（_）开头。

第二步：添加你的内容

创建一个相应的文件夹（例如<source>/_my_collection）并添加文档。如果存在Front Matter，则处理YAML Front Matter，并将Front Matter之后的所有内容都推送到文档的content属性中。如果没有提供YAML Front Matter，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。

如果你希望在访问/my_collection/时显示指定页面，只需将永久链接：/my_collection/index.html添加到页面即可。要列出合集中的项目，在该页面或任何其他项目中，你可以使用：

{% for item in site.my_collection %}
  <h2>{{ item.title }}</h2>
  <p>{{ item.description }}</p>
  <p><a href="{{ item.url }}">{{ item.title }}</a></p>
{% endfor %}
复制代码

注意：不要忘记添加YAML进行处理

合集中的文件没有Front Matter的将被视为静态文件，只是简单地复制到其输出位置而不进行处理。

配置合集的永久链接

如果你希望为合集网页所在的网址指定自定义模式，则可以使用永久链接属性进行设置：

collections:
  my_collection:
    output: true
    permalink: /:collection/:name
复制代码

例子

对于具有以下源文件结构的合集，

_my_collection/
└── some_subdir
    └── some_doc.md
复制代码

以下每个permalink配置中的每一个都会生成下面显示的文档结构。

默认与permalink: /:collection/:path一样。

_site/
├── my_collection
│   └── some_subdir
│       └── some_doc.html
...
复制代码

permalink: pretty 与permalink: /:collection/:path/一样。

_site/
├── my_collection
│   └── some_subdir
│       └── some_doc
│           └── index.html
...
复制代码

permalink: /doc/:path

_site/
├── doc
│   └── some_subdir
│       └── some_doc.html
...
复制代码

permalink: /doc/:name

_site/
├── doc
│   └── some_doc.html
...
复制代码

permalink: /:name

_site/
├── some_doc.html
...
复制代码

模板变量

变量	说明
`:collection`	包含合集的标签。
`:path`	文档相对于合集目录的路径。
`:name`	文档的基本文件名，每个空格和非字母数字字符序列都用连字符替换。
`:title`	如果文档中存在文件，则`:title`模板变量将采用Front Matter中`slug`变量值;如果没有定义那么`:title`将等同于`:name`，也就是通过文件名生成的`slug`。
`:output_ext`	输出文件的扩展名。（默认情况下有扩展名，但通常是不需要的。）

Liquid属性

合集

每个合集都可以作为site变量中的字段来访问。例如，如果你想访问_albums中的albums合集，则可以使用site.albums。

每个合集本身都是一系列文档（例如，site.albums是一组文档，与site.pages和site.posts非常相似）。请参阅下表以了解如何访问这些文档的属性。

这些合集也可以在site.collections下找到，并含有你在_config.yml中指定的元数据（如果存在）以及以下信息：

变量	说明
`label`	你的合集的名称，例如：`my_collection`。
`docs`	文档数组。
`files`	合集中的静态文件数组。
`relative_directory`	合集源目录的路径，相对于站点源。
`directory`	合集的源目录的完整路径。
`output`	该合集的文档是否将作为单个文件输出。

注意：硬编码合集

除了你自己创建的合集外，posts合集还被Jekyll硬编码，不管是否存在_posts目录。在迭代site.collections时，需要注意这点，因为你可能需要将其过滤掉。

你可能希望使用过滤器来查找in的合集：{{ site.collections | where: "label", "myCollection" | first }}。

注意：合集和时间

除了默认硬编码合集posts中的文档外，你创建的合集中的所有文档均可通过Liquid进行访问，而不考虑其指定日期（如果有），因此可以进行渲染。

但是，只有在相关合集元数据output: true时，才会尝试将文档写入磁盘。此外，未来日期的文件只有在site.future也是true的情况下才会写入。

通过在文档的Front Matter设置published: false（默认为true），可以对正在写入磁盘的文档进行更细致的控制。

文档

除文档相应文件中提供的任何YAML Front Matter外，每个文档还具有以下属性：

变量	说明
`content`	文件的（未提及的）内容。如果没有提供YAML Front Matter，则Jekyll将不会在你的合集中生成该文件。如果使用YAML Front Matter，则这是Front Matter的终止符`---`后面的所有内容。
`output`	基于`content`渲染文档的输出。
`path`	文档源文件的完整路径。
`relative_path`	文档源文件相对于网站源的路径。
`url`	渲染的合集的URL。只有当它所属的合集在站点配置中具有`output：true`时，才会将文件写入目标。
`collection`	文档合集的名称。
`date`	文档合集的日期。

访问合集属性

来自YAML Front Matter的属性可以作为数据在网站中任何地方被访问。使用上面的示例将一个合集配置为site.albums，你可能会在单个文件中构建如下的Front Matter（它必须使用支持的标记格式，并且不能使用.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"
复制代码

合集中的每个专辑都可以使用模板在单个页面上列出：

{% 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 %}
复制代码

数据文件

除了Jekyll提供的内置变量之外，你还可以指定自己的自定义数据，这些数据可以通过Liquid模板系统访问。

Jekyll支持从位于_data目录中的YAML，JSON和CSV文件加载数据。请注意，CSV文件必须包含标题行。

这个强大的功能可以避免模板中的重复，并且可以在不更改_config.yml的情况下设置特定于站点的选项。

插件/主题还可以利用数据文件来设置配置变量。

数据文件夹

正如在目录结构页面上所解释的那样，_data文件夹是你可以在其中存储Jekyll生成站点时使用的其他数据的位置。这些文件必须是YAML，JSON或CSV文件（使用.yml，.yaml，.json或.csv扩展名），并且可以通过site.data访问它们。

示例：成员列表

以下是使用数据文件避免在Jekyll模板中复制大量代码的基本示例：

在_data/members.yml中：

- name: Eric Mill
  github: konklone

- name: Parker Moore
  github: parkr

- name: Liu Fengyun
  github: liufengyun
复制代码

或_data/members.csv中：

name,github
Eric Mill,konklone
Parker Moore,parkr
Liu Fengyun,liufengyun
复制代码

这些数据可以通过site.data.members进行访问（请注意，文件名决定变量名称）。

你现在可以在模板中呈现成员列表：

<ul>
{% for member in site.data.members %}
  <li>
    <a href="https://github.com/{{ member.github }}">
      {{ member.name }}
    </a>
  </li>
{% endfor %}
</ul>
复制代码

注意：

如果你的Jekyll站点有很多页面，例如文档网站，请参阅详细示例以了解如何为你的站点构建强大的导航。

示例：组织

数据文件也可以放在_data文件夹的子文件夹中。每个文件夹级别将被添加到变量的命名空间中。下面的示例显示了如何在orgs文件夹下的文件中分别定义GitHub组织：

在_data/orgs/jekyll.yml中：

username: jekyll
name: Jekyll
members:
  - name: Tom Preston-Werner
    github: mojombo

  - name: Parker Moore
    github: parkr
复制代码

在_data/orgs/doeorg.yml中：

username: doeorg
name: Doe Org
members:
  - name: John Doe
    github: jdoe
复制代码

然后可以通过site.data.orgs访问组织，后面接是文件名：

<ul>
{% for org_hash in site.data.orgs %}
{% assign org = org_hash[1] %}
  <li>
    <a href="https://github.com/{{ org.username }}">
      {{ org.name }}
    </a>
    ({{ org.members | size }} members)
  </li>
{% endfor %}
</ul>
复制代码

示例：访问特定的作者

页面和文章也可以访问特定的数据项。以下示例显示了如何访问特定项目：

_data/people.yml：

dave:
    name: David Smith
    twitter: DavidSilvaSmith
复制代码

然后，作者可以被指定为文章Front Matter的页面变量：

---
title: sample post
author: dave
---

{% assign author = site.data.people[page.author] %}
<a rel="author"
  href="https://twitter.com/{{ author.twitter }}"
  title="{{ author.name }}">
    {{ author.name }}
</a>
复制代码