Astro 6.4: руководство
Sätteri, подключаемый API Markdown и Cloudflare

Введение

28 мая 2026 года вышел Astro 6.4 — один из самых значительных технических релизов в жизненном цикле Astro 6. Если Astro 6.0 представил переработанный dev-сервер и экспериментальный Rust-компилятор, то 6.4 предлагает три функции, которые фундаментально меняют то, как Astro обрабатывает контент и деплой:

• Подключаемый API процессора Markdown (markdown.processor) — замена всего пайплайна unified одной опцией конфигурации
• Sätteri (@astrojs/markdown-satteri) — Rust-процессор Markdown/MDX, сокращающий время сборки на ~1 минуту
• Хелпер Cloudflare cf() — настройка экспериментальной расширенной маршрутизации с SESSION KV, ASSETS binding и другими возможностями

Это руководство подробно рассматривает каждое изменение с практическими примерами кода, стратегиями миграции со старого remark/rehype пайплайна на Sätteri, сравнением случаев использования процессоров и паттернами деплоя Cloudflare с кастомными fetch-обработчиками и Hono middleware.

1. Подключаемый API процессора Markdown

Пайплайн Markdown в Astro всегда строился на unified — той же экосистеме, которая обеспечивает работу remark, rehype и сотен плагинов для обработки Markdown. Эта экосистема мощная, но не всем подходит. Некоторые разработчики хотят более быструю сборку, другую обработку синтаксиса или процессоры на других языках.

Astro 6.4 добавляет новую опцию конфигурации markdown.processor, которая позволяет полностью заменить пайплайн. Стандартный процессор — unified(), поэтому существующие проекты продолжают работать без изменений.

Настройка процессора unified()

С новым API плагины remark и rehype настраиваются непосредственно в функции процессора, а не в корневой конфигурации markdown:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import remarkToc from 'remark-toc';
import rehypePrism from 'rehype-prism-plus';

export default defineConfig({
  markdown: {
    processor: unified({
      remarkPlugins: [remarkToc],
      rehypePlugins: [rehypePrism],
    }),
  },
});

Устаревшие корневые опции

Существующие корневые опции markdown.remarkPlugins, markdown.rehypePlugins, markdown.remarkRehype, markdown.gfm и markdown.smartypants всё ещё работают в Astro 6.4, но они помечены как устаревшие и будут удалены в Astro 8.0. Переносите их в форму unified({...}) при обновлении.

2. Sätteri — Rust-процессор Markdown/MDX

Главная функция в области производительности Astro 6.4 — Sätteri, конвейер обработки Markdown и MDX, написанный целиком на Rust и распространяемый как @astrojs/markdown-satteri. В тестах команды Astro переключение документации Astro и Cloudflare на Sätteri сократило время сборки более чем на минуту — огромное улучшение для сайтов с большим количеством контента.

Установка и настройка

Установка Sätteri состоит из двух шагов. Сначала установите пакет:

npm install @astrojs/markdown-satteri

Затем настройте его как процессор в astro.config.mjs:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import { satteri } from '@astrojs/markdown-satteri';

export default defineConfig({
  markdown: {
    processor: satteri({
      features: {
        directive: true,  // Включить контейнерные директивы (:::)
        gfm: true,        // GitHub Flavored Markdown
        math: false,      // LaTeX математика
      },
    }),
  },
});

Сравнение производительности

Разница в производительности между unified (JavaScript) и Sätteri (Rust) впечатляет для сайтов с большим объёмом контента. Вот что сообщила команда Astro:

Встроенные возможности

Sätteri реализует многие функции Markdown нативно, без необходимости в отдельных remark или rehype плагинах:

• GitHub Flavored Markdown (GFM) — таблицы, списки задач, зачёркивание, автоссылки
• Контейнерные директивы (блоки :::) — информационные, предупреждающие и кастомные блоки
• Парсинг Frontmatter — встроенное извлечение YAML-метаданных
• Подсветка синтаксиса — нативная интеграция с Shiki
• LaTeX математика — опциональное отображение формул через $...$ и $$...$$
• Emoji-шорткоды — :smile: → 😄

Поскольку эти функции реализованы на Rust, они выполняются значительно быстрее своих JavaScript-аналогов. Для многих проектов переход на Sätteri означает возможность удалить несколько remark и rehype плагинов.

Ограничения: отсутствие поддержки remark/rehype плагинов

Важное предупреждение: Sätteri не запускает remark или rehype плагины. Если ваш проект зависит от плагинов экосистемы unified (remark-toc, rehype-prism, rehype-autolink-headings и т.д.), у вас два варианта:

• Остаться на unified() — существующая конфигурация продолжает работать
• Портировать в MDAST/HAST плагины Sätteri — система плагинов Sätteri работает с MDAST и HAST деревьями

Система плагинов Sätteri использует ту же структуру AST, что и unified (MDAST для Markdown, HAST для HTML), поэтому портирование многих remark-плагинов концептуально несложно — нужно адаптировать плагин для работы с нативной манипуляцией деревом на Rust.

3. Хелпер Cloudflare cf() для расширенной маршрутизации

Astro 6.3 представил экспериментальную расширенную маршрутизацию, дающую разработчикам тонкий контроль над обработкой запросов на edge. Astro 6.4 расширяет эту возможность хелпером cf() из @astrojs/cloudflare, который автоматически настраивает всё необходимое для Cloudflare.

Что делает cf()

Хелпер cf() — это удобная функция, которая настраивает:

• SESSION KV binding — хранение данных сессии через Cloudflare KV
• Обслуживание статических файлов через ASSETS binding
• locals.cfContext — доступ к raw-объекту Cloudflare cf (геолокация, ASN и т.д.)
• IP клиента из заголовка cf-connecting-ip
• waitUntil — для фоновых задач, не блокирующих ответ
• Предварительно отрисованные страницы ошибок — кастомные 404/500 из статической выдачи

Паттерн с кастомным fetch-обработчиком

С кастомным fetch-обработчиком используйте cf() из @astrojs/cloudflare/fetch:

// src/app.ts
import { astro, FetchState } from 'astro/fetch';
import { cf } from '@astrojs/cloudflare/fetch';

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    const state = new FetchState(request);
    const asset = await cf(state, env, ctx);
    if (asset) return asset;
    return astro(state);
  },
};

Паттерн с Hono middleware

Если вы используете Hono, применяйте cf() из @astrojs/cloudflare/hono как middleware:

// src/app.ts
import { Hono } from 'hono';
import { actions, middleware, pages, i18n } from 'astro/hono';
import { cf } from '@astrojs/cloudflare/hono';

const app = new Hono<{ Bindings: Env }>();

app.use(cf());
app.use(actions());
app.use(middleware());
app.use(pages());
app.use(i18n());

export default app;

4. Миграция: с unified на Sätteri

Миграция со стандартного пайплайна unified на Sätteri требует аудита ваших remark/rehype плагинов. Вот пошаговый подход:

Шаг 1: Аудит плагинов

Составьте список всех remark и rehype плагинов в astro.config.mjs и распределите их по категориям:

• Нативно поддерживаются Sätteri — GFM, директивы, подсветка синтаксиса, frontmatter
• Легко заменяются — автоссылки на заголовки, emoji, оглавление (можно через MDAST плагины или пост-обработку HTML)
• Нетривиальные — кастомные трансформации, кастомные rehype-компоненты, сложные манипуляции AST

Шаг 2: Тест без плагинов

Установите @astrojs/markdown-satteri и настройте его только с теми функциями, которые Sätteri поддерживает нативно. Запустите astro build и проверьте результат.

Шаг 3: Портирование оставшихся плагинов

Для плагинов, которые Sätteri не поддерживает нативно, портируйте их в формат MDAST/HAST плагинов Sätteri. API плагинов похож на unified — вы трансформируете дерево, но выигрыш в производительности достигается за счёт выполнения трансформаций на Rust.

Шаг 4: Бенчмарк

Сравните время сборки до и после миграции. Используйте astro build --verbose для просмотра времени по этапам. Сайты с сотнями Markdown-страниц получают наибольший прирост производительности.

5. Sätteri vs unified: руководство по выбору

6. Другие улучшения в Astro 6.4

Помимо трёх главных функций, Astro 6.4 включает ряд небольших улучшений и исправлений. Полный список изменений охватывает десятки патчей — вот самые заметные:

• Улучшенные сообщения об ошибках в dev-сервере — более понятные stack trace и оверлеи с указанием компонента
• Улучшенная гидратация островков — более надёжный порядок гидратации для сложных деревьев компонентов
• Производительность Content Collections — оптимизированное кэширование вызовов getCollection()
• Оптимизация изображений — улучшенная обработка отсутствующих или повреждённых изображений
• Поддержка TypeScript 5.8 — обновлённые определения типов и улучшенный автокомплит в IDE

Заключение

Astro 6.4 — значительный шаг вперёд для фреймворка. Подключаемый API процессора Markdown даёт разработчикам свободу выбора контент-пайплайна, Sätteri предлагает убедительный прирост производительности для сайтов с большим объёмом контента, а хелпер Cloudflare cf() упрощает один из самых мощных, но и самых сложных целевых окружений для деплоя.

Если вы поддерживаете Astro-сайт — особенно документацию, блог или маркетинговый сайт с сотнями Markdown-страниц — экономия в 10-30 секунд на сборке от Sätteri накапливается с каждым CI-запуском, каждой предварительной сборкой и каждым продакшен-деплоем. Для команд, выполняющих десятки сборок в день, это часы сэкономленного времени разработчиков каждый месяц.

Я — full-stack разработчик, специализирующийся на Astro, React и современных веб-фреймворках. Живу в Минске и работаю по всему миру. Обсудим ваш проект.

Хотите сайт на Astro? Смотрите мои услуги по разработке сайтов

FAQ

Готовы работать с Astro 6.4?

Astro 6.4 — этапный релиз, открывающий новые возможности для контентных сайтов. Rust-процессор Sätteri меняет правила игры для команд, управляющих крупными порталами документации или контентными маркетинговыми сайтами — более быстрая сборка означает более быстрый CI, более быстрые превью и более довольных разработчиков.

Если вам нужна помощь с миграцией сайта на Astro 6.4, внедрением Sätteri или настройкой расширенной маршрутизации Cloudflare — я предоставляю услуги разработки и консалтинга для проектов любого размера на Astro.

Я — full-stack разработчик с фокусом на Astro, React и современные веб-фреймворки. Живу в Минске, работаю удалённо по всему миру. Свяжитесь со мной для обсуждения вашего проекта.