Коллекции

Не все можно отнести к постам или страницам. Возможно, вам надо документировать различные методы вашего open-source проекта для членов команды или для обсуждения на конференции. Коллекции позволяют определить новый тип документа с поведением похожим на посты или страницы, но с собственными уникальными свойствами и пространством имен.

Использование коллекций

Шаг 1: Сообщите Jekyll о вашей коллекции

Для этого добавьте в _config.yml следующий код, заменив my_collection именем своей коллекции:

collections:
- my_collection

При желании вы можете задать для вашей коллекции метаданные:

collections:
  my_collection:
    foo: bar

Также можно задать для документов коллекции значения по умолчанию:

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

Шаг 2: Добавьте свой контент

Создайте соответствующий каталог (<source>/_my_collection) и добавьте в него документы. Вводные, будут считаны как данные, а все остальное будет в атрибуте content документа. При отсутствии вводной, Jekyll не добавит файл в коллекцию.

Следите за правильным наименованием каталогов

Каталог должен быть назван идентично названию коллекции, заданному в _config.yml с добавлением подчеркивания _ в начале.

Шаг 3: При желании выводите документы коллекции в отдельные файлы

Если вы хотите, чтобы Jekyll отрендеренную версию каждого документа в коллекции, задайте в метаданных коллекции вашего _config.yml значение true ключу output:

collections:
  my_collection:
    output: true

Это создаст файл для каждого документа в коллекции. Например, если у вас есть файл _my_collection/some_subdir/some_doc.md, он будет обработан Liquid и конвертером Markdown в статический HTML-файл — <dest>/my_collection/some_subdir/some_doc.html.

Также как и посты, 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`	Название документа строчными буквами (как определено во вводной), все пробелы и не буквенно-числовые символы заменены дефисами. Если название не определено во вводной, переменная эквивалентна `name`.
`output_ext`	Расширение итогового файла.

Атрибуты Liquid

Коллекции

Любая коллекция доступна через переменную 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`	Определяет, будут ли документы коллекции выводиться в виде отдельных файлов.

Документы

В дополнение к данным из вводной, каждый документ имеет следующие атрибуты:

Переменная	Описание
`content`	Неотрендеренный контент документа. Если в файле не вводной YAML, Jekyll не сгенерирует файл в вашей коллекции. При наличии вводной YAML, контентом является все содержимое файла после закрывающих дефисов `---` вводной.
`output`	Отрендеренный вывод документа на основе `content`.
`path`	Полный путь к исходнику документа.
`relative_path`	Путь к исходнику документа относительно исходников сайта.
`url`	URL отрендеренной коллекции. Файл записывается в каталог назначения, когда имя коллекции, к которой он относится, включено в ключ `render` конфигурации сайта.
`collection`	Название коллекции документов.
`date`	Дата документа.

Доступ к атрибутам коллекции

Атрибуты из вводной YAML могут быть доступны как данные из любого места сайта. Следующий пример использован для конфигурации коллекции site.album, этот код может быть во вводной отдельного файла коллекции (это должен быть полноценный файл в поддерживаемом формате разметки, а не чистые данные с расширением .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 %}