аркдауним YAML для Jekyll

Пока я всё никак не допишу какой-либо из длинных постов, попробую выложить несколько мелких заметок. Начну с небольшого трюка для Jekyll.

Для настройки метаданных (заголовок, лейаут, дата, всё такое) в Jekyll используется «YAML front matter» — описание всех этих данных в специально оформленном коде, который обязательно должен идти в начале файла. Jekyll в принципе «видит» только те страницы, у которых этот заголовок есть, поэтому YAML front matter — довольно важная часть.

Обычно такой заголовок выглядит примерно так:

---
layout: docs
title: Resources
prev_section: sites
---

Казалось бы, всё ок. Но! Раз я использую Jekyll на Гитхабе, мой перфекционизм требует, чтобы исходник страницы с таким заголовком выглядел идеально. А Гитхаб по умолчанию показывает не исходный код .md-файлов, а сразу рендерит их. Вот, например, как выглядит код выше, отрендеренный в маркдауне:

Плохой код

Не очень читаемо, правда? И последняя строчка, внезапно, становится заголовком (если знать синтаксис маркдауна, то, конечно, не внезапно) — это вряд ли то, чего мы хотели.

Всё это дело легко исправить: достаточно изменить стиль написания YAML-заголовков. Нужно просто добавить воды, то есть пустых строк. Вот так:

---

layout: docs

title: Resources

prev_section: sites

---

Такой YAML-заголовок будет уже выглядеть приемлемо:

Хороший код

Вместо заголовка мы получаем хорошо отделённый от основного контента поста YAML-заголовок, каждая строка которого превращается в параграф.

Так как в постах чаще всего бывает не так много метаданных, лишние строки не особо раздувают код. На мой взгляд, подобный стиль написания YAML-заголовков гораздо читабельнее, так что я не вижу причин почему бы не использовать его постоянно.

Я лишь жалею, что синтаксис YAML слишком строг, и нельзя добавить в начало каждой строки или отступов, чтобы весь этот блок выглядел как кусок кода, или дефисов, чтобы он выглядел как список. И, если кто придумает как ещё можно улучшить читаемость кода YAML-заголовков, не стесняйтесь, пишите issues.

Вы можете прокомментировать эту статью в Мастодоне.

Опубликовано с метками: #Blog #Meta #Jekyll