@astrojs/mdx

Эта интеграция Astro включает поддержку компонентов MDX и позволяет создавать страницы в виде файлов .mdx.

Почему MDX?

MDX позволяет использовать переменные, JSX-выражения и компоненты прямо внутри Markdown-контента в Astro. Если у вас уже есть контент, написанный в MDX, эта интеграция позволит перенести эти файлы в ваш проект Astro.

Установка

Astro включает команду astro add для автоматической настройки официальных интеграций. Если вы предпочитаете, вы можете установить интеграции вручную.

Запустите одну из следующих команд в новом окне терминала.

npm

npx astro add mdx

pnpm

pnpm astro add mdx

Yarn

yarn astro add mdx

Если у вас возникнут какие-либо проблемы, не стесняйтесь сообщать нам о них на GitHub и попробуйте выполнить шаги ручной установки ниже.

Ручная установка

Сначала установите пакет @astrojs/mdx:

npm

npm install @astrojs/mdx

pnpm

pnpm add @astrojs/mdx

Yarn

yarn add @astrojs/mdx

Затем примените интеграцию к вашему файлу astro.config.*, используя свойство integrations:

astro.config.mjs

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [mdx()],
});

Интеграция с редактором

Для поддержки в VS Code установите официальное расширение MDX.

Для других редакторов используйте MDX language server.

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

Смотрите документацию MDX, чтобы узнать, как использовать стандартные возможности MDX.

MDX в Astro

После установки интеграции MDX вы можете использовать JSX-переменные, выражения и компоненты в Markdown.

Интеграция также добавляет дополнительные возможности к стандартному MDX, включая поддержку frontmatter в стиле Markdown в MDX. Это позволяет использовать большинство встроенных возможностей Markdown в Astro.

Файлы .mdx должны быть написаны в синтаксисе MDX, а не в HTML-подобном синтаксисе Astro.

Использование MDX с коллекциями контента

Чтобы включить MDX-файлы в коллекцию контента, убедитесь, что ваш лоадер коллекции настроен на загрузку контента из файлов .mdx:

src/content.config.ts

import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';
import { z } from 'astro/zod';

const blog = defineCollection({
  loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/blog" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
  })
});

export const collections = { blog };

Использование экспортируемых переменных в MDX

MDX поддерживает export-операторы, которые позволяют добавлять переменные в ваш MDX-контент или экспортировать данные для компонента, который импортирует этот MDX.

Например, вы можете экспортировать поле title из страницы или компонента MDX, чтобы использовать его в заголовке с {JSX expressions}:

/src/blog/posts/post-1.mdx

export const title = 'My first MDX post'

# {title}

Или вы можете использовать этот экспортируемый title на странице через import и import.meta.glob():

src/pages/index.astro

---
const matches = import.meta.glob('./posts/*.mdx', { eager: true });
const posts = Object.values(matches);
---

{posts.map(post => <p>{post.title}</p>)}

Экспортируемые свойства

Следующие свойства доступны в .astro компоненте, когда вы используете import или import.meta.glob():

• file - абсолютный путь к файлу (например /home/user/projects/.../file.mdx).
• url - URL страницы (например /en/guides/markdown-content).
• frontmatter - содержит данные, указанные в YAML/TOML frontmatter файла.
• getHeadings() - асинхронная функция, которая возвращает массив всех заголовков (<h1> - <h6>) в файле с типом: { depth: number; slug: string; text: string }[]. slug каждого заголовка соответствует сгенерированному ID и может использоваться для якорных ссылок.
• <Content /> - компонент, который возвращает полный отрендеренный контент файла.
• (любое значение export) - MDX-файлы также могут экспортировать данные через export.

Использование переменных frontmatter в MDX

Интеграция Astro MDX по умолчанию поддерживает frontmatter в MDX. Добавляйте свойства frontmatter так же, как и в Markdown файлах: переменные будут доступны в шаблоне, а также как именованные свойства при импорте файла.

/src/blog/posts/post-1.mdx

---
title: 'My first MDX post'
author: 'Houston'
---

# {frontmatter.title}

Written by: {frontmatter.author}

Использование компонентов в MDX

После установки интеграции MDX вы можете импортировать и использовать как компоненты Astro, так и компоненты UI-фреймворков в файлах MDX (.mdx) так же, как в любом другом компоненте Astro.

Не забудьте при необходимости добавить client: директиву на компоненты UI-фреймворков!

Смотрите больше примеров использования import/export в документации MDX.

src/blog/post-1.mdx

---
title: My first post
---
import ReactCounter from '../components/ReactCounter.jsx';

I just started my new Astro blog!

Here is my counter component, working in MDX:
<ReactCounter client:load />

Назначение пользовательских компонентов для HTML-элементов

В MDX вы можете сопоставлять синтаксис Markdown с пользовательскими компонентами вместо стандартных HTML-элементов. Это позволяет писать на обычном Markdown, но применять специальное оформление к выбранным элементам.

Например, можно создать компонент Blockquote.astro для стилизации <blockquote>:

src/components/Blockquote.astro

---
const props = Astro.props;
---
<blockquote {...props} class="bg-blue-50 p-4">
  <span class="text-4xl text-blue-600 mb-2">“</span>
  <slot /> <!-- Be sure to add a `<slot/>` for child content! -->
</blockquote>

Импортируйте ваш пользовательский компонент в .mdx файл, затем экспортируйте объект components, который сопоставляет стандартный HTML-элемент вашему компоненту:

src/blog/posts/post-1.mdx

import Blockquote from '../components/Blockquote.astro';
export const components = {blockquote: Blockquote}

> This quote will be a custom Blockquote

Смотрите на сайте MDX полный список HTML-элементов, которые можно переопределять.

Заметка

Пользовательские компоненты, определенные и экспортированные внутри MDX-файла, всегда должны быть импортированы, а затем переданы обратно в компонент <Content /> через проп components.

Передача components в MDX-контент

При рендеринге импортированного MDX-контента через компонент <Content /> пользовательские компоненты можно передать через проп components. Эти компоненты должны быть импортированы, чтобы быть доступными для <Content />.

Объект components сопоставляет имена HTML-элементов (h1, h2, blockquote и т.д.) вашим пользовательским компонентам. Можно также включить все компоненты, экспортируемые самим MDX-файлом, используя spread (...), при этом их нужно импортировать как components.

Если вы импортируете MDX напрямую из одного файла для использования в Astro-компоненте, импортируйте и компонент Content, и экспортируемые компоненты:

src/pages/page.astro

---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---
<!-- Создает пользовательский <h1> для синтаксиса # и применяет любые пользовательские компоненты, определенные в `content.mdx` -->
<Content components={{...components, h1: Heading }} />

Если ваш MDX-файл - запись коллекции контента, используйте функцию render() из astro:content, чтобы получить компонент <Content />.

Следующий пример передает пользовательский заголовок в <Content /> через components, чтобы он использовался вместо всех HTML-элементов <h1>:

src/pages/blog/post-1.astro

---
import { getEntry, render } from 'astro:content';
import CustomHeading from '../../components/CustomHeading.astro';
const entry = await getEntry('blog', 'post-1');
const { Content } = await render(entry);
---
<Content components={{ h1: CustomHeading }} />

Конфигурация

После установки интеграции MDX никакая конфигурация не требуется, чтобы использовать .mdx файлы в проекте Astro.

Вы можете настроить, как рендерится MDX, с помощью следующих опций:

• Опции, наследуемые от конфигурации Markdown
• extendMarkdownConfig
• recmaPlugins
• optimize

Опции, наследуемые от конфигурации Markdown

Все markdown опции конфигурации можно настраивать отдельно в интеграции MDX. Это включает remark и rehype плагины, подсветку синтаксиса и многое другое. По умолчанию опции будут соответствовать вашей конфигурации Markdown (см. опцию extendMarkdownConfig ниже).

astro.config.mjs

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkToc from 'remark-toc';
import rehypePresetMinify from 'rehype-preset-minify';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      syntaxHighlight: 'shiki',
      shikiConfig: { theme: 'dracula' },
      remarkPlugins: [remarkToc],
      rehypePlugins: [rehypePresetMinify],
      remarkRehype: { footnoteLabel: 'Footnotes' },
      gfm: false,
    }),
  ],
});

Осторожно

MDX не поддерживает передачу remark/rehype плагинов строкой. Нужно установить плагин, импортировать его и передать функцию.

Смотрите справочник опций Markdown для полного списка опций.

extendMarkdownConfig

Тип: boolean
По умолчанию: true

Добавлено в: @astrojs/mdx@0.15.0

По умолчанию MDX расширяет существующую конфигурацию Markdown проекта. Чтобы переопределить отдельные опции, вы можете указать их аналоги в конфигурации MDX.

Например, если нужно отключить GitHub-Flavored Markdown и применить другой набор remark плагинов для MDX файлов, вы можете сделать так (при включенном extendMarkdownConfig, который включен по умолчанию):

astro.config.mjs

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  markdown: {
    syntaxHighlight: 'prism',
    remarkPlugins: [remarkPlugin1],
    gfm: true,
  },
  integrations: [
    mdx({
      // `syntaxHighlight` унаследован из Markdown

      // Markdown `remarkPlugins` игнорируются,
      // применяется только `remarkPlugin2`.
      remarkPlugins: [remarkPlugin2],
      // `gfm` переопределяется на `false`
      gfm: false,
    }),
  ],
});

Иногда также нужно отключить наследование конфигурации Markdown в MDX. Для этого установите extendMarkdownConfig в false:

astro.config.mjs

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  markdown: {
    remarkPlugins: [remarkPlugin1],
  },
  integrations: [
    mdx({
      // Конфигурация Markdown теперь игнорируется
      extendMarkdownConfig: false,
      // `remarkPlugins` не применяются
    }),
  ],
});

recmaPlugins

Тип: PluggableList
По умолчанию: []

Добавлено в: @astrojs/mdx@0.11.5

Это плагины, которые модифицируют выходной estree напрямую. Это полезно для изменения или внедрения JavaScript-переменных в ваши MDX-файлы.

Мы рекомендуем AST Explorer для экспериментов с estree, и estree-util-visit для поиска по JavaScript-узлам.

optimize

Тип: boolean | { ignoreElementNames?: string[] }
По умолчанию: false

Добавлено в: @astrojs/mdx@0.19.5

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

По умолчанию отключено. Чтобы включить оптимизацию MDX, добавьте в конфигурацию интеграции MDX следующее:

astro.config.mjs

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: true,
    }),
  ],
});

ignoreElementNames

Тип: string[]

Добавлено в: @astrojs/mdx@3.0.0

Ранее опция называлась customComponentNames.

Опциональное свойство optimize, которое предотвращает обработку некоторых имен элементов оптимизатором, например, пользовательских компонентов, передаваемых в импортированный MDX контент через проп components.

Вам нужно исключать такие компоненты из оптимизации, потому что оптимизатор заранее превращает контент в статическую строку, что ломает компоненты, которые должны рендериться динамически.

Например, ожидаемый вывод MDX для следующего кода - это <Heading>...</Heading> вместо каждого "<h1>...</h1>":

---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---

<Content components={{ ...components, h1: Heading }} />

Чтобы настроить оптимизацию с помощью ignoreElementNames, укажите массив имен HTML-элементов, которые следует трактовать как пользовательские компоненты:

astro.config.mjs

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: {
        // Не обрабатывать `h1` элементы оптимизатором
        ignoreElementNames: ['h1'],
      },
    }),
  ],
});

Обратите внимание: если ваш MDX-файл настраивает пользовательские компоненты через export const components = { ... }, то вручную настраивать эту опцию не нужно - оптимизатор автоматически их обнаружит.

Примеры

• Стартовый шаблон Astro MDX показывает, как использовать MDX файлы в вашем проекте Astro.

Дополнительные интеграции

UI-фреймворки

• 

  @astrojs/alpinejs

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

Адаптеры

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

Другие интеграции

• 

  @astrojs/db

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap