Памятка по YAML

YAML это удобный текстовый формат для хранения структур данных. При создании сайтов мы в студии часто используем его (совместно с markdown) чтобы содержать текстовый контент отдельно от вёрстки. Это нужно для мультиязычных сайтов, а также для CMS или если требуется часто редактировать контент.

Основные возможности формата

В начале файла принято писать 3 дефиса --- (но в большинстве случаев это не обязательно), а если ямл встроен в другой формат (например .html или .md), то его блок начинается и заканчивается тремя дефисами.

Файлы ямл содержат пары ключ и значение (ассоциативные массивы). Ключ — это такая ссылка-переменная, которая ставится в том месте в вёрстке, где должен находиться текст. А значение — это и есть сам текст, единица контента.

---
ключ: Значение
title: Заголовок статьи
description: Описание статьи.
date: 2023-08-14

Для создания структуры вложенности используются отступы в 2 пробела перед ключом (табы использовать нельзя). Кроме обычных ключей может выводиться список (массив) из нескольких элементов, каждый айтем списка начинается с дефиса -.

blog:
  title: Все статьи блога
  list:
    - title: Название статьи №1
      text: Описание статьи №1
    - title: Название статьи №2
      text: Описание статьи №2

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

Комментарии начинаются с символа «решётки» # комментарий, могут начинаться в любом месте строки и продолжаются до конца строки.

Кавычки и экранирование символов

Значения можно не оборачивать в кавычки, но часто это придётся сделать чтобы экранировать некоторые символы: кавычки "", '', «», двоеточие :… Практичнее всего оборачивать значения в одинарные кавычки, но возникнут проблемы если такие кавычки используются в самом тексте. Например в англоязычных словах с апострофом I'm, в этом случае можно поменять в тексте все такие кавычки на другой вариант апострофа I’m.

Можно использовать экранированные символы в C-стиле, начинающиеся с обратной косой черты \, только текст должен быть обёрнут в кавычки.

Дополнительные редко используемые возможности

Отдельные ключи и списки ключей можно также записывать в стиле формата JSON:

men: [John Smith, Bill Jones]
- {name: John Smith, age: 33}

Явное задание типа оформляется путём ‘!![указание типа]’. Пример, !! str 100 после разбора выдаст строковое значение «100» вместо целого числа 100.

значения типа Дата/Время задаются в формате YYYY-MM-DD или YYYY-MM-DD HH: MM: SS. Если необходимо задать дату как строку, нужно заключать её в кавычки («2012-12-21»)

Внутри ямла есть свои переменные — якоря (начинаются с &) и псевдонимы (начинаются с *).

# Тут добавляем в переменные весь config1 и значение ключа format:
config1: &conf1
  format: &format HTML

# Тут вставляем значение ключа format (HTML):
config2:
  format: *format

# Тут вставляем всю структуру ключа config1:
config3: *conf1

Добавление большого текста с переносом строк

Это можно сделать, обернув текст в кавычки и в местах переноса добавить /n. Ещё можно перед блоком с текстом добавить символ |. При этом в самом тексте должны быть проставлены разрывы строк, а перед началом каждой такой строки стоять отступ в 2 пробела. Если между выводимыми строками нужно добавить отступ, то к черте добавить плюс |+, а если нужно убрать перенос — минус |-. Также если хочется оформить контент на нескольких строках, то на выходе не нужен перенос строк, то можно поставить знак > или >-.

list: |
  1. Шаг первый
  2. Шаг второй
list2: |+
  1. Шаг первый
  2. Шаг второй
list3: >
  1. Шаг первый
  2. Шаг второй

Булевые значения можно записать различными способами: true, True, yes, 1 и false, False, no, 0. Если их нужно записать как просто слово, то надо обернуть в кавычки.