Форматы frontmatter: YAML, TOML, JSON

Frontmatter — это специальный блок метаданных, размещаемый в начале Markdown-файла, который описывает свойства документа: заголовок, дату, категории, теги и другие параметры. Remark и Rehype предоставляют возможность обрабатывать frontmatter, извлекать данные и интегрировать их с различными плагинами. Основные форматы frontmatter включают YAML, TOML и JSON.

YAML

YAML (YAML Ain’t Markup Language) — наиболее распространённый формат frontmatter в экосистеме Markdown. Он прост для чтения человеком и легко парсится в JavaScript.

Пример синтаксиса YAML frontmatter:

---
title: "Пример документа"
date: 2026-03-22
tags:
  - javascript
  - remark
draft: false
---

Особенности YAML:

  • Начало и конец блока обозначаются тремя дефисами ---.
  • Поддерживает вложенные структуры через отступы.
  • Можно использовать массивы и словари.
  • Числовые, булевы и строковые значения парсятся автоматически.
  • Чувствителен к отступам, что требует аккуратного форматирования.

Использование в Remark:

Для парсинга YAML используют плагин remark-frontmatter совместно с remark-parse-yaml:

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkFrontmatter from 'remark-frontmatter';
import remarkParseYaml from 'remark-parse-yaml';

const processor = unified()
  .use(remarkParse)
  .use(remarkFrontmatter, ['yaml'])
  .use(remarkParseYaml);

const file = `
---
title: "Документ"
date: "2026-03-22"
---
`;

const result = processor.processSync(file);
console.log(result.data); // { title: "Документ", date: "2026-03-22" }

TOML

TOML (Tom’s Obvious, Minimal Language) — формат, ориентированный на простоту парсинга и строгую структуру данных. Чаще используется в системах, где требуется явное разделение типов.

Пример синтаксиса TOML frontmatter:

+++
title = "Документ в TOML"
date = 2026-03-22
tags = ["javascript", "remark"]
draft = false
+++

Особенности TOML:

  • Начало и конец блока обозначаются тройными плюсовыми знаками +++.
  • Поддерживает строки, числа, булевы значения, массивы и даты.
  • Вложенные структуры оформляются через таблицы [section].
  • Строгий синтаксис требует явного указания кавычек для строк с пробелами или специальными символами.

Использование в Remark:

TOML также можно парсить через remark-frontmatter и отдельный парсер TOML, например @iarna/toml:

import toml from '@iarna/toml';
import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkFrontmatter from 'remark-frontmatter';

const processor = unified()
  .use(remarkParse)
  .use(remarkFrontmatter, ['toml']);

const file = `
+++
title = "Документ"
date = 2026-03-22
+++
`;

const ast = processor.parse(file);
const tomlNode = ast.children.find(node => node.type === 'toml');
const data = toml.parse(tomlNode.value);
console.log(data); // { title: "Документ", date: 2026-03-22 }

JSON

JSON (JavaScript Object Notation) — наименее популярный для frontmatter формат, но удобен для интеграции с JavaScript и API.

Пример синтаксиса JSON frontmatter:

;;;
{
  "title": "Документ JSON",
  "date": "2026-03-22",
  "tags": ["javascript", "remark"],
  "draft": false
}
;;;

Особенности JSON:

  • Блок обозначается тройными точками с запятой ;;;.
  • Строгая структура: все строки в кавычках, двоеточие разделяет ключ и значение, запятая отделяет элементы.
  • Легко парсится стандартным методом JSON.parse.
  • Не поддерживает комментарии внутри данных.

Использование в Remark:

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkFrontmatter from 'remark-frontmatter';

const file = `
;;;
{
  "title": "Документ JSON",
  "date": "2026-03-22"
}
;;;
`;

const processor = unified()
  .use(remarkParse)
  .use(remarkFrontmatter, ['json']);

const ast = processor.parse(file);
const jsonNode = ast.children.find(node => node.type === 'json');
const data = JSON.parse(jsonNode.value);
console.log(data); // { title: "Документ JSON", date: "2026-03-22" }

Сравнение форматов

Формат Читаемость Строгость Поддержка типов Применение
YAML Высокая Средняя Автоматическая Большинство статических сайтов, Markdown
TOML Средняя Высокая Явное указание Конфигурационные файлы, строгие frontmatter
JSON Низкая Очень высокая Явная, стандартная API, JavaScript-ориентированные проекты

Интеграция с Rehype

Хотя Rehype работает с HTML, а не Markdown напрямую, frontmatter можно передавать в обработку как метаданные. Например, Remark может извлекать frontmatter, а затем через remark-rehype передавать AST в Rehype для генерации HTML с учетом метаданных:

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkFrontmatter from 'remark-frontmatter';
import remarkParseYaml from 'remark-parse-yaml';
import remarkRehype from 'remark-rehype';
import rehypeStringify from 'rehype-stringify';

const processor = unified()
  .use(remarkParse)
  .use(remarkFrontmatter, ['yaml'])
  .use(remarkParseYaml)
  .use(remarkRehype)
  .use(rehypeStringify);

const file = `
---
title: "Документ"
---
# Заголовок
`;

const html = processor.processSync(file).toString();
console.log(html);

Метаданные frontmatter могут быть использованы для формирования динамических заголовков, метатегов, классов или других атрибутов HTML.

Рекомендации по выбору формата

  • YAML подходит для большинства случаев, особенно для блога и документации.
  • TOML полезен там, где важна строгая структура и явное разделение типов.
  • JSON удобен при тесной интеграции с JavaScript, если требуется прямой парсинг без сторонних библиотек.

Правильное использование frontmatter позволяет организовать структуру проекта, унифицировать метаданные и облегчить автоматическую обработку Markdown-документов с помощью Remark и Rehype.

Оглавление