Frontmatter в MDX

Frontmatter — это специальный блок метаданных, расположенный в начале MDX-файла, который используется для хранения структурированной информации о документе. Этот блок оформляется в формате YAML и ограничен тройными дефисами ---. Он позволяет задавать свойства, такие как заголовок, автор, дата создания, теги, категории, и другие данные, которые могут быть использованы при генерации документации, статических сайтов или в динамических приложениях на основе MDX.

---
title: "Пример статьи на MDX"
author: "Иван Иванов"
date: "2026-03-23"
tags:
  - javascript
  - mdx
  - frontmatter
draft: false
---

Основные правила и особенности Frontmatter

  1. Расположение: Frontmatter должен находиться строго в начале MDX-файла. Любой текст или компоненты до блока YAML сделают его недействительным.

  2. Формат YAML: Все данные внутри frontmatter должны соответствовать синтаксису YAML. Это означает:

    • Отступы важны. Используются два пробела на уровень вложенности.
    • Строки, содержащие специальные символы, лучше заключать в кавычки.
    • Списки обозначаются через дефис - с пробелом после него.
    • Булевы значения пишутся как true или false без кавычек.

  3. Типы данных: Frontmatter поддерживает различные типы данных:

    • Строки (title: "Заголовок статьи")
    • Числа (version: 1.0)
    • Булевы значения (draft: false)
    • Массивы (tags: [ "mdx", "javascript" ])
    • Объекты (author: { name: "Иван", email: "ivan@example.com" })

  4. Использование в коде: MDX-компоненты и генераторы статических сайтов (например, Next.js с @next/mdx) автоматически извлекают frontmatter. Пример использования в React-компоненте:

import { useMDXComponent } from 'next-contentlayer/hooks';
import { allPosts } from '.contentlayer/data';

export default function Post({ post }) {
  const MDXContent = useMDXComponent(post.body.code);

  return (
    <article>
      <h1>{post.title}</h1>
      <p>Автор: {post.author}</p>
      <MDXContent />
    </article>
  );
}

// Получение frontmatter
const post = allPosts.find(p => p.slug === 'primer-stati');
console.log(post.title); // Пример статьи на MDX
  1. Динамические свойства: Frontmatter можно использовать для фильтрации и сортировки контента. Например, список всех черновиков:
const drafts = allPosts.filter(post => post.draft);
  1. Дополнительные поля: Можно добавлять любые пользовательские поля, например readingTime, summary, categories. Главное — следить за корректным синтаксисом YAML:
---
title: "MDX и Frontmatter"
summary: "Разбор frontmatter в MDX"
readingTime: 5
categories: ["javascript", "mdx"]
---

Особенности интеграции с генераторами сайтов

  • Next.js: Использование next-mdx-remote или Contentlayer позволяет автоматически извлекать frontmatter для генерации страниц и списков постов.
  • Gatsby: Плагин gatsby-plugin-mdx считывает frontmatter, обеспечивая создание GraphQL-узлов для каждой статьи. Это позволяет запрашивать метаданные через GraphQL-запросы.
  • VitePress / VuePress: Frontmatter используется для генерации навигации, заголовков страниц и метаданных для SEO.

Примеры сложных структур frontmatter

  • Вложенные объекты
---
title: "Продвинутое использование MDX"
author:
  name: "Анна Петрова"
  email: "anna@example.com"
categories:
  - frontend
  - mdx
metadata:
  version: 2
  draft: false
---
  • Списки с объектами
---
title: "Сложный frontmatter"
contributors:
  - name: "Иван Иванов"
    role: "Автор"
  - name: "Мария Смирнова"
    role: "Редактор"
---

Такой подход позволяет создавать гибкие и структурированные данные для использования в любом MDX-экосистемном инструменте.

Проверка корректности

  • Frontmatter должен быть валидным YAML, иначе парсер MDX выдаст ошибку.
  • Все ключи должны быть уникальными в пределах одного блока.
  • Тестирование можно проводить через онлайн-валидаторы YAML или встроенные средства сборки MDX.

Frontmatter — это мощный инструмент, который превращает MDX-файл из простого документа в полноценный контентный объект с метаданными, управляемыми на уровне приложения.

Оглавление