Jekyll使用教程筆記五

時間 2019-11-16

標籤 jekyll 使用教程筆記简体版

原文原文鏈接

目錄html

合集

並不是全部內容都是文章或頁面。也許你想記錄開源項目中的各類方法、團隊成員、或會議中的會話。合集容許你定義一種相似頁面或文章那樣正常工做的新類型的文檔，但也具備其本身的惟一屬性和名稱空間。git

使用合集

開始使用合集，須要一下三步：github

第一步：告訴Jekyll讀取你的合集
第二步：添加你的內容
第三步：有選擇地將你的合集文檔渲染爲獨立的文件

第一步：告訴Jekyll讀取你的合集

將如下內容添加到你的網站的_config.yml文件中，將my_collection替換爲你的合集的名稱：json

collections:
- my_collection
複製代碼

你能夠在配置中爲你的合集指定元數據：數組

collections:
- my_collection:
 foo: bar
複製代碼

也能夠爲合集設置默認屬性：bash

defaults:
 - scope:
 path: ""
 type: my_collection
 values:
 layout: page
複製代碼

重要：Gather your collections[3.7.0]composer

你可使用collections_dir: my_collections選擇指定一個目錄來將全部合集存儲在同一個位置。post

而後，Jekyll將在my_collections/_books中查找books合集，並在y_collections/_recipes中查找recipes合集。網站

警告：確保將草稿和文章移動到自定義合集目錄中ui

使用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>
複製代碼

有關如何爲你的站點構建強大的導航的信息（特別是若是你有文檔網站或其餘類型的Jekyll站點而且須要組織許多頁面），請參閱導航。