Мой дэйли дайджест

одно техническое понятие в день

Frontmatter

7 июля 2026 · ~13 мин чтения

формат-данных метаданные markdown yaml веб

Frontmatter

Frontmatter — это блок метаданных (данных о данных) в самом начале текстового
файла, отделённый от основного содержимого специальными разделителями, чаще
всего тремя дефисами ---. Внутри блока — обычно YAML: заголовок, дата, теги
и любые другие поля, которые описывают документ, но не являются его текстом.

История

Термин пришёл не из программирования, а из книгоиздания. В типографике
«front matter» — это всё, что идёт в книге до основного текста: титульный
лист, выходные данные, оглавление, посвящение, предисловие. Страницы front
matter традиционно даже нумеруются отдельно — римскими цифрами, чтобы
подчеркнуть: это ещё не книга, это сведения О книге.

В мир разработки термин притащил Том Престон-Вернер (Tom Preston-Werner),
один из сооснователей GitHub. В 2008 году он написал Jekyll — генератор
статических сайтов (программа, которая превращает папку с текстовыми файлами
в готовый HTML-сайт). Джекиллу нужно было где-то хранить заголовок поста,
дату публикации, шаблон оформления. Престон-Вернер решил не заводить
отдельную базу данных и не придумывать свой формат, а положить метаданные
прямо в начало Markdown-файла, обернув их в YAML и отбив тремя дефисами.
Так родился «YAML front matter» — и название, и синтаксис.

Контекст эпохи важен. В 2008 году блоги жили в основном на WordPress и
подобных CMS (системах управления контентом) с базой данных MySQL. Это
означало хостинг с PHP, обновления безопасности, взломы, бэкапы. Идея
Jekyll была радикально проще: пост — это просто файл в git-репозитории,
метаданные — прямо в файле, сайт — статические HTML-страницы, которые
нечего взламывать. GitHub Pages, запущенный в том же 2008-м, сделал Jekyll
своим движком по умолчанию — и frontmatter мгновенно стал стандартом
де-факто для всей экосистемы статических сайтов.

Ключевые вехи дальше:

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

Что это такое

Идея frontmatter — разделить в одном файле два слоя: что документ
содержит и что документ собой представляет. Тело — для человека,
который будет читать. Шапка — для машины, которая будет обрабатывать.

Выглядит это так:

---
title: Как я перестал бояться и полюбил rsync
date: 2026-07-07
tags: [инструменты, devops]
draft: false
---

Здесь начинается обычный текст статьи...

Парсер (программа-разборщик) видит --- в первой строке, читает всё до
следующего ---, скармливает это YAML-библиотеке и получает словарь:
{title: "...", date: ..., tags: [...], draft: false}. Всё, что после
второго разделителя, — тело документа, оно уходит в Markdown-рендерер.

Полезно понимать, чем frontmatter отличается от соседних решений:

Важная тонкость: строго говоря, файл с frontmatter — невалидный
Markdown. Спецификация Markdown ничего не знает о --- в начале файла
(три дефиса в ней — это горизонтальная линия или подчёркивание заголовка).
Всё держится на договорённости: инструменты, которые «в теме», сначала
отрезают шапку, а уже остаток парсят как Markdown. Инструмент «не в теме»
покажет твои метаданные как обычный текст — отсюда странные таблицы или
линии в начале документа, если открыть файл не тем рендерером.

Аналогии из жизни

Титульный лист книги. Открываешь книгу — и до первой главы идут
страницы с названием, автором, годом, издательством. Это метаданные:
они описывают книгу, но не являются её сюжетом. Frontmatter — ровно это.
Где ломается: титульный лист читатель видит, а frontmatter из
отрендеренной статьи обычно вырезается — читатель блога никогда не видит
сырых полей slug или draft. Метаданные книги — часть продукта,
метаданные файла — часть производства.

Транспортная накладная на коробке. Курьер не вскрывает коробку, чтобы
узнать, куда её везти, — всё написано снаружи: адрес, вес, хрупкость.
Сортировочный центр обрабатывает тысячи коробок, читая только наклейки.
Так и генератор сайта: чтобы построить список статей с датами и тегами,
ему не нужно «понимать» тексты — достаточно прочитать шапки. Где
ломается: накладная существует отдельно от содержимого — её можно
переклеить, потерять, коробку можно переупаковать. Frontmatter же внутри
самого файла: потерять его отдельно от текста невозможно, но и «переклеить»
без вскрытия файла — тоже.

Анкета в регистратуре поликлиники. Прежде чем попасть к врачу, ты
заполняешь бланк: имя, год рождения, аллергии, жалобы. Врач за 10 секунд
сканирует анкету и понимает контекст, не расспрашивая тебя с нуля. Поля
стандартные, поэтому любая медсестра найдёт нужное мгновенно. Где
ломается: анкету заполняет и читает человек, и человек же переспросит,
если поле заполнено криво. YAML-парсер не переспросит — он либо молча
поймёт тебя неправильно, либо упадёт с ошибкой на весь файл. Машина
строже регистратуры.

Как это работает

Разберём по шагам, что происходит, когда генератор сайта встречает файл
с frontmatter. Псевдокод любого парсера выглядит примерно так:

прочитать файл
если первая строка == "---":
    искать следующую строку "---"
    всё между ними → yaml.parse() → словарь метаданных
    всё после → тело документа
иначе:
    метаданные = пустой словарь
    тело = весь файл

Дальше по конвейеру:

  1. Обнаружение. Парсер смотрит на самое начало файла. Разделитель
    должен быть в первой строке — даже пустая строка или невидимый
    BOM (byte order mark, служебные байты кодировки в начале файла) перед
    --- ломают распознавание: парсер решает, что frontmatter нет вообще.

  2. Извлечение. Всё между разделителями вырезается и передаётся
    YAML-парсеру. Здесь живут главные грабли, потому что YAML — формат
    с сюрпризами:
    - Двоеточие в значении. title: Frontmatter: зачем он нужен —
    ошибка парсинга: YAML видит второе двоеточие и не понимает структуру.
    Лечится кавычками: title: "Frontmatter: зачем он нужен".
    - Табы. YAML запрещает табуляцию в отступах — только пробелы.
    - Автомагия типов. version: 1.10 превратится в число 1.1,
    answer: no — в булево false, а дата может стать объектом даты
    со сдвигом часового пояса. Классика: норвежский код страны NO
    в старых YAML-парсерах превращался в false.
    - Регистр и синонимы. Tags и tags — разные ключи; парсер не
    будет догадываться.

  3. Валидация и дефолты. Хороший генератор проверяет обязательные поля
    (нет title — падаем с понятной ошибкой или подставляем имя файла)
    и наполняет необязательные значениями по умолчанию (draft: false,
    layout: post).

  4. Слияние с контекстом. Метаданные файла объединяются с настройками
    уровня папки и сайта. В Jekyll это называется «каскад»: значения из
    _config.yml перекрываются значениями папки, а те — значениями файла.
    Знакомый принцип, правда? Так же работает CSS.

  5. Использование. Поля разлетаются по местам: title — в <title> и
    <h1>, date — в сортировку ленты, tags — в страницы тегов, slug —
    в URL, draft: true — сигнал «не публиковать». Тело файла тем временем
    отдельно проходит через Markdown-рендерер.

Обрати внимание на асимметрию последствий. Ошибка в теле — это криво
отрендеренный абзац, косметика. Ошибка во frontmatter — это упавшая
сборка всего сайта или молча пропавшая из ленты статья. Метаданные —
машиночитаемый контракт, и машина спрашивает с них строже.

Самые частые поломки frontmatter

Двоеточие или # в значении без кавычек, табуляция вместо пробелов, пустая строка перед первым ---, кривая кодировка с BOM. Если сборка упала на «неправильном YAML» — начинай проверку с этих четырёх пунктов, в 90% случаев дело в одном из них.

Где встречается в обычной жизни

Где встречается в IT и бизнесе

Общий класс задач: много однотипных текстовых единиц + необходимость
их машинной сортировки/фильтрации + желание обойтись без базы данных.
Если все три пункта совпали — ты в территории frontmatter.

Кто пользуется

Точных цифр «сколько файлов с frontmatter в мире» не существует — это
соглашение, а не сервис с телеметрией. Но косвенная оценка: только на
GitHub счёт Markdown-файлов с YAML-шапкой идёт на десятки миллионов.

Альтернативы и конкуренты

Когда НЕ стоит использовать

Лакмусовая бумажка

Спроси: «кто и когда меняет это поле?» Если человек и в момент редактирования текста — поле просится во frontmatter. Если машина и в любой момент времени — полю место в базе данных. Смешивать эти два мира в одной шапке — самый частый архитектурный промах с frontmatter.

Связанные понятия

Литература и источники

Где встретилось у меня

Вчера в пайплайне daily-digest сборка HTML споткнулась о битый
YAML-frontmatter одной из старых статей — двоеточие в строковом значении
без кавычек, ровно та грабля из раздела «Как это работает». Плюс сам
генератор статей, выбирая тему дня, отметил frontmatter как один из самых
частых терминов в логах: весь этот блог — Markdown-файлы с YAML-шапками,
из которых build.sh собирает HTML.

Краткое резюме