remark-frontmatter: извлечение метаданных

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

Подключение remark-frontmatter

Для работы с плагином его нужно установить через npm:

npm install remark remark-frontmatter

После установки его подключают в процесс обработки Markdown:

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

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

Аргумент ['yaml', 'toml'] определяет, какие типы frontmatter обрабатывать. Можно указать один тип или оба сразу.

Структура frontmatter

YAML-frontmatter:

---
title: "Пример статьи"
author: "Иван Иванов"
date: "2026-03-22"
tags:
  - javascript
  - remark
---

TOML-frontmatter:

+++
title = "Пример статьи"
author = "Иван Иванов"
date = "2026-03-22"
tags = ["javascript", "remark"]
+++

После подключения remark-frontmatter, блоки frontmatter становятся отдельными узлами AST (Abstract Syntax Tree) с типом yaml или toml.

Обработка frontmatter

Для извлечения метаданных обычно используется плагин remark-parse в связке с собственным обработчиком узлов:

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

const processor = unified()
  .use(remarkParse)
  .use(remarkFrontmatter, ['yaml'])
  .use(() => (tree) => {
    const metadata = {};
    tree.children.forEach((node) => {
      if (node.type === 'yaml') {
        Object.assign(metadata, yaml.load(node.value));
      }
    });
    console.log(metadata);
  });

processor.processSync(`
---
title: "Пример статьи"
author: "Иван Иванов"
date: "2026-03-22"
tags:
  - javascript
  - remark
---
# Контент
Текст статьи.
`);

Результатом выполнения будет объект:

{
  "title": "Пример статьи",
  "author": "Иван Иванов",
  "date": "2026-03-22",
  "tags": ["javascript", "remark"]
}

Совмещение с Rehype

После извлечения frontmatter часто требуется преобразовать Markdown в HTML с помощью Rehype. Для этого используется плагин remark-rehype, который конвертирует AST Remark в AST Rehype.

Пример цепочки:

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

let metadata = {};

const processor = unified()
  .use(remarkParse)
  .use(remarkFrontmatter, ['yaml'])
  .use(() => (tree) => {
    tree.children.forEach((node) => {
      if (node.type === 'yaml') {
        metadata = yaml.load(node.value);
      }
    });
  })
  .use(remarkRehype)
  .use(rehypeStringify);

const file = `
---
title: "Пример статьи"
author: "Иван Иванов"
date: "2026-03-22"
---
# Заголовок
Текст документа.
`;

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

В результате получаем HTML:

<h1>Заголовок</h1>
<p>Текст документа.</p>

и объект metadata с информацией из frontmatter.

Практические советы

  • Для сайтов на Next.js или Astro frontmatter удобно использовать для генерации маршрутов и SEO-метаданных.
  • Если файл содержит несколько блоков YAML/TOML, remark-frontmatter создаёт отдельный узел для каждого блока, поэтому обработка должна учитывать возможные дубликаты.
  • Поддержка TOML ограничена синтаксическим разбором — для преобразования в объект можно использовать библиотеку toml:
import toml from 'toml';

if (node.type === 'toml') {
  metadata = toml.parse(node.value);
}
  • Использование TypeScript позволяет строго типизировать метаданные и уменьшить ошибки при доступе к ключам frontmatter.

Расширение функциональности

remark-frontmatter можно сочетать с другими плагинами:

  • remark-mdx — для MDX-файлов, где frontmatter смешан с JSX.
  • remark-slug — для генерации идентификаторов заголовков на основе frontmatter.
  • remark-toc — создание оглавления, учитывающего заголовки внутри Markdown и метаданные документа.

Эта схема позволяет:

  1. Чётко отделить метаданные документа от контента.
  2. Создавать динамические свойства страниц.
  3. Легко интегрировать Markdown в HTML-пайплайн с помощью Rehype.

Объединение remark-frontmatter + remark-rehype + rehype-stringify обеспечивает полный контроль над метаданными и HTML-рендерингом Markdown-документов.

Оглавление