Памятка по 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
. Если их нужно записать как просто слово, то надо обернуть в кавычки.