Gatsby и MDX

Gatsby — это современный фреймворк для генерации статических сайтов на основе React. MDX расширяет возможности Markdown, позволяя включать компоненты React прямо в текстовые документы. Такая интеграция делает Gatsby идеальной платформой для создания документации, блогов и сложных контентных сайтов с динамическими элементами.

Установка необходимых пакетов Для начала работы с MDX в Gatsby потребуется установить следующие пакеты:

npm install gatsby-plugin-mdx @mdx-js/react @mdx-js/mdx
  • gatsby-plugin-mdx — основной плагин для интеграции MDX с Gatsby.
  • @mdx-js/react — позволяет рендерить MDX-документы как React-компоненты.
  • @mdx-js/mdx — ядро библиотеки MDX, необходимое для компиляции файлов.

Подключение плагина в gatsby-config.js После установки пакетов необходимо подключить плагин в конфигурации Gatsby:

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-mdx',
      options: {
        extensions: ['.mdx', '.md'],
        gatsbyRemarkPlugins: [
          {
            resolve: 'gatsby-remark-images',
            options: {
              maxWidth: 1200,
            },
          },
        ],
      },
    },
  ],
};

Здесь extensions указывает на расширения файлов, которые Gatsby будет обрабатывать как MDX, а gatsbyRemarkPlugins позволяет использовать плагины Remark для обработки изображений, кода и других элементов.

Структура MDX-файла

MDX сочетает возможности Markdown и JSX. Основные элементы:

  • Заголовки и параграфы: обычный Markdown-синтаксис.
  • Встраиваемые компоненты React:
import CustomButton from './components/CustomButton'

# Заголовок

Текст параграфа с кнопкой:

<CustomButton label="Нажми меня" />
  • Секции с пропсами: компоненты можно настраивать через атрибуты, что делает контент интерактивным.
  • Использование JavaScript внутри MDX:
{[1, 2, 3].map(num => <li key={num}>{num}</li>)}

Это позволяет динамически генерировать контент прямо в документах.

Преимущества использования MDX в Gatsby

  1. Интерактивность контента: возможность вставки React-компонентов делает документы более гибкими.
  2. Консистентность стиля: одинаковые компоненты можно использовать в разных страницах, обеспечивая единый визуальный стиль.
  3. Гибкая маршрутизация: благодаря Gatsby можно автоматически создавать страницы из MDX-файлов через GraphQL-запросы.

Пример GraphQL-запроса для страниц из MDX:

{
  allMdx {
    nodes {
      id
      frontmatter {
        title
        date
      }
      body
    }
  }
}

frontmatter используется для метаданных (заголовки, даты, категории), а body содержит скомпилированный контент MDX.

Создание шаблона страницы

MDX-документы рендерятся через шаблонные компоненты React. Пример:

import React from 'react';
import { graphql } from 'gatsby';
import { MDXRenderer } from 'gatsby-plugin-mdx';

export default function BlogPost({ data }) {
  const { body, frontmatter } = data.mdx;
  return (
    <article>
      <h1>{frontmatter.title}</h1>
      <p>{frontmatter.date}</p>
      <MDXRenderer>{body}</MDXRenderer>
    </article>
  );
}

export const query = graphql`
  query($id: String) {
    mdx(id: { eq: $id }) {
      body
      frontmatter {
        title
        date(formatString: "DD.MM.YYYY")
      }
    }
  }
`;

MDXRenderer преобразует MDX-контент в React-компоненты, сохраняя все возможности динамики и встраивания компонентов.

Расширение функциональности через плагины

Gatsby позволяет интегрировать плагины Remark для обработки кода, таблиц, ссылок и изображений:

  • gatsby-remark-prismjs — подсветка синтаксиса кода.
  • gatsby-remark-autolink-headers — автоматические якоря для заголовков.
  • gatsby-remark-images — оптимизация и lazy-load изображений.

Пример подключения:

gatsbyRemarkPlugins: [
  { resolve: 'gatsby-remark-prismjs' },
  { resolve: 'gatsby-remark-images', options: { maxWidth: 800 } },
]

Эти плагины позволяют создавать высококачественный, оптимизированный и интерактивный контент на базе MDX.

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

  • Использовать MDXProvider для глобального определения компонентов, которые могут использоваться в MDX-файлах:
import { MDXProvider } from '@mdx-js/react';
import CustomButton from './components/CustomButton';

const components = { CustomButton };

export default function Layout({ children }) {
  return <MDXProvider components={components}>{children}</MDXProvider>;
}
  • Разделять контент на мелкие MDX-файлы для улучшения управляемости проекта.
  • Для сложных сайтов использовать GraphQL-фильтры по категориям и тегам из frontmatter.
  • Оптимизировать изображения и код через Remark-плагины, чтобы не перегружать страницу.

Итоговый подход к разработке

Gatsby + MDX сочетает простоту Markdown с мощью React-компонентов. Такой подход обеспечивает:

  • создание динамичного контента без потери преимуществ статической генерации;
  • возможность повторного использования компонентов и стилей;
  • интеграцию с экосистемой плагинов Gatsby для оптимизации и расширения функциональности.

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

Оглавление