Коллекции

Коллекции — это отличный способ группировать связанный контент, например, членов команды или докладов на конференции.

Настройка

Чтобы использовать коллекцию, сначала необходимо определить её в вашем _config.yml. Например, вот коллекция сотрудников:

collections:
  - staff_members

В данном случае collections определяется как последовательность (т.е. массив) без дополнительных метаданных для каждой коллекции. Вы можете необязательно указать метаданные для вашей коллекции, определив collections как отображение (т.е. хэш-таблицу) вместо последовательности, а затем определив дополнительные поля в ней:

collections:
  staff_members:
    people: true

При определении коллекции как последовательности её страницы по умолчанию не будут рендериться. Чтобы включить это, необходимо указать output: true в метаданных коллекции, что требует определения коллекции как отображения. Для получения дополнительной информации см. раздел Вывод.

Соберите ваши коллекции3.7.0

Вы можете необязательно указать каталог для хранения всех ваших коллекций в одном месте с помощью collections_dir: my_collections.

Затем Jekyll будет искать my_collections/_books для коллекции books, и в my_collections/_recipes для коллекции recipes.

Убедитесь, что черновики и записи перенесены в каталог пользовательских коллекций

Если вы укажете каталог для хранения всех ваших коллекций в одном месте с помощью collections_dir: my_collections, вам необходимо переместить ваш каталог _drafts и _posts в my_collections/_drafts и my_collections/_posts. Обратите внимание, что имя вашего каталога коллекций не может начинаться с подчёркивания (`_`).

Добавление контента

Создайте соответствующую папку (например, <source>/_staff_members) и добавьте документы. Фронтовая информация обрабатывается, если она существует, а всё после фронтовой информации добавляется в атрибут документа content. Если фронтовая информация не предоставлена, Jekyll посчитает её статическим файлом статическим файлом, и содержимое не будет подвергаться дальнейшей обработке. Если фронтовая информация предоставлена, Jekyll обработает содержимое файла в ожидаемый результат.

Независимо от того, существует ли фронтовая информация или нет, Jekyll будет записывать в целевой каталог (например, _site) только если output: true установлено в метаданных коллекции.

Например, вот как вы бы добавили сотрудника в вышеуказанную коллекцию. Имя файла — ./_staff_members/jane.md со следующим содержимым:

---
name: Jane Doe
position: Developer
---
Jane has worked on Jekyll for the past *five years*.

Обратите внимание, что, несмотря на то, что внутренне он рассматривается как коллекция, вышесказанное не относится к статьям. Статьи с допустимым форматом имени файла будут помечены для обработки, даже если они не содержат фронтовой информации.

Убедитесь, что вы правильно назвали свои каталоги

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

Вывод

Теперь вы можете итерироваться по site.staff_members на странице и выводить контент для каждого сотрудника. Аналогично статьям, тело документа доступно через переменную content:

{% for staff_member in site.staff_members %}
  <h2>{{ staff_member.name }} - {{ staff_member.position }}</h2>
  <p>{{ staff_member.content | markdownify }}</p>
{% endfor %}

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

collections:
  staff_members:
    output: true

Вы можете связаться со сгенерированной страницей, используя атрибут url:

{% for staff_member in site.staff_members %}
  <h2>
    <a href="{{ staff_member.url }}">
      {{ staff_member.name }} - {{ staff_member.position }}
    </a>
  </h2>
  <p>{{ staff_member.content | markdownify }}</p>
{% endfor %}

Пермалинки

Существуют специальные переменные пермалинков для коллекций, чтобы помочь вам контролировать выходной URL для всей коллекции.

Настройка сортировки документов4.0

По умолчанию два документа в коллекции сортируются по их атрибуту date, когда оба содержат ключ date в своей фронтовой информации. Однако, если у одного или обоих документов отсутствует ключ date в их фронтовой информации, они сортируются по соответствующим путям.

Вы можете контролировать эту сортировку через метаданные коллекции.

Сортировка по ключу фронтовой информации

Документы можно сортировать по ключу фронтовой информации, установив метаданные sort_by со строкой ключа фронтовой информации. Например, чтобы отсортировать коллекцию учебников по ключу lesson, конфигурация будет следующей:

collections:
  tutorials:
    sort_by: lesson

Документы упорядочиваются в порядке возрастания значения ключа. Если у документа нет определенного ключа фронтовой информации, то он размещается сразу после отсортированных документов. Если несколько документов не имеют определенного ключа фронтовой информации, эти документы сортируются по датам или путям и затем размещаются сразу после отсортированных документов.

Ручная сортировка документов

Вы также можете вручную отсортировать документы, установив метаданные order со списком файлов в желаемом порядке. Например, коллекция учебников будет настроена так:

collections:
  tutorials:
    order:
      - hello-world.md
      - introduction.md
      - basic-concepts.md
      - advanced-concepts.md

Любые документы с именами файлов, не совпадающими с записями в списке, размещаются просто после переупорядоченных документов. Если документ вложен в подкаталоги, включайте их в записи тоже:

collections:
  tutorials:
    order:
      - hello-world.md
      - introduction.md
      - concepts/basics.md
      - concepts/advanced.md

Если оба ключа метаданных установлены корректно, список order имеет приоритет.

Атрибуты Liquid

Коллекции

Коллекции также доступны в site.collections, с метаданными, которые вы указали в вашем _config.yml (если они присутствуют), и следующей информацией:

Жёстко закодированная коллекция

В дополнение к любым коллекциям, которые вы создаёте сами, коллекция posts жёстко закодирована в Jekyll. Она существует вне зависимости от того, есть ли у вас каталог _posts или нет. Это нужно учитывать при итерации по site.collections, так как вам может потребоваться его отфильтровать.

Возможно, вам стоит использовать фильтры для поиска вашей коллекции: {{ site.collections | where: "label", "myCollection" | first }}

Коллекции и время

За исключением документов в жёстко закодированной коллекции по умолчанию posts, все документы в созданных вами коллекциях доступны через Liquid независимо от назначенной даты, если она есть, и поэтому могут быть рендерены.

Документы пытаются быть записанными на диск только если соответствующие метаданные коллекции содержат output: true. Кроме того, документы с будущей датой записываются только если site.future также истина.

Более детальный контроль над записью документов на диск можно осуществить, установив published: false (true по умолчанию) в фронтовой информации документа.

Документы

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