# Как создать блог на Astro: полная инструкция **Проблема:** нужно быстро поднять быстрый блог или контентный сайт с хорошим SEO, но без сложностей Next.js и без перегруженного JavaScript. **Решение:** Astro — статический генератор (SSG), который рендерит HTML по умолчанию и добавляет интерактивность точечно (islands architecture). В итоге получается лёгкая страница, понятная поисковикам и пользователям. В этой статье — пошаговая настройка блога на Astro: установка, структура проекта, маршруты, **MDX** (Markdown с компонентами) и **Content Collections** со схемой на Zod для валидации контента. --- ## В чём проблема: выбор фреймворка для контентного сайта Если нужен блог, документация или маркетинговый сайт, есть три основных варианта: | Критерий | Astro | Next.js | Gatsby | |----------|-------|---------|--------| | **Модель по умолчанию** | SSG, HTML-first | SSR/SSG, JS-heavy | SSG (React) | | **JS в браузере** | Минимум (islands) | Много (гидрация всего) | Много (React-дерево) | | **Контент из коробки** | MDX, Markdown, Collections | Нужны решения | GraphQL + плагины | | **Скорость контент-сайта** | Очень высокая | Зависит от настроек | Хорошая после билда | | **Кривая обучения** | Низкая (HTML + островки) | Выше (React, App Router) | Выше (GraphQL, плагины) | | **Лучше всего под** | Блог, доки, лендинг, портфолио | SPA, приложения, сложный роутинг | Контент на React + CMS | **Вывод:** для блога, документации или маркетингового сайта Astro часто даёт самый лёгкий результат при минимальном JavaScript. --- ## Рабочее решение: пошаговая настройка ### Шаг 1: Создание проекта Astro ```bash # Официальный способ: интерактивный мастер npm create astro@latest # или pnpm create astro@latest ``` Мастер спросит: - Шаблон (выбери `blog` для блога или `minimal` для чистого старта) - TypeScript (рекомендуется включить — пригодится для Content Collections) - ESLint и форматирование (по желанию) ### Шаг 2: Проверка системных требований ```bash # Проверить Node.js (должно быть >= 18) node -v # Проверить менеджер пакетов npm -v # или pnpm -v / yarn -v ``` **Требования:** - Node.js 18+ (рекомендуется LTS: 20 или 22) - npm, pnpm или yarn - Редактор кода (VS Code + плагин Astro) ### Шаг 3: Запуск dev-сервера ```bash # Перейти в папку проекта cd <имя-проекта> # Запустить dev-сервер npm run dev # или pnpm dev ``` Открой `http://localhost:4321` — должен открыться стартовый сайт. ### Шаг 4: Проверка сборки перед деплоем ```bash # Собрать проект в папку dist/ npm run build # или pnpm build ``` Если сборка прошла без ошибок — проект готов к деплою. --- ## Структура проекта Astro Типичная структура блога на Astro: ```text / ├─ astro.config.mjs # Конфигурация Astro ├─ package.json # Зависимости и скрипты ├─ src/ │ ├─ pages/ # Маршруты (file-based routing) │ │ ├─ index.astro # Главная страница │ │ ├─ about.astro # /about │ │ └─ blog/ │ │ ├─ index.astro # /blog (список статей) │ │ └─ [slug].astro # /blog/:slug (страница статьи) │ ├─ layouts/ # Layouts (общая обвязка) │ │ └─ BaseLayout.astro │ ├─ components/ # UI компоненты │ │ └─ Callout.astro │ ├─ content/ # Контент (Content Collections) │ │ └─ blog/ # Статьи блога │ └─ styles/ # Глобальные стили └─ public/ # Статика (копируется как есть) └─ favicon.svg ``` **Правило маршрутизации:** файл в `src/pages/` = маршрут. - `src/pages/index.astro` → `/` - `src/pages/about.astro` → `/about` - `src/pages/blog/[slug].astro` → `/blog/:slug` --- ## Первый layout: BaseLayout.astro Создай файл `src/layouts/BaseLayout.astro`: ```astro --- // Пропсы приходят со страницы; задаём значения по умолчанию const { title = "Site", description = "Astro site", } = Astro.props; --- {title}

Главная | Блог

``` > `` — это "сюда вставится содержимое страницы". --- ## Первая страница: index.astro Создай файл `src/pages/index.astro`: ```astro --- import BaseLayout from "../layouts/BaseLayout.astro"; ---

Привет, Astro

Если страница открылась — ты уже в деле.

``` Открой `http://localhost:4321` — должна отобразиться главная страница. --- ## Подключаем MDX: Markdown с компонентами ### Установка MDX MDX — это Markdown, который умеет **встраивать компоненты** и JS-выражения. ```bash npx astro add mdx # или pnpm astro add mdx ``` После установки в `astro.config.mjs` появится интеграция `@astrojs/mdx`. ### Первая MDX-страница Создай файл `src/pages/guide.mdx`: ```mdx --- title: "Гайд по Astro" description: "Пробная MDX-страница" --- # MDX в Astro работает ✅ Это обычный Markdown… но с бонусами. - списки - `код` - и компоненты ниже ``` Открой `/guide` — должна отрендериться страница. --- ## Встраиваем компоненты в MDX ### Создаём компонент Callout.astro Создай файл `src/components/Callout.astro`: ```astro --- const { type = "info", title = "Важно" } = Astro.props; const styles = { info: "background: rgba(0, 180, 255, .08); border: 1px solid rgba(0, 180, 255, .35);", warn: "background: rgba(255, 180, 0, .08); border: 1px solid rgba(255, 180, 0, .35);", danger: "background: rgba(255, 80, 80, .08); border: 1px solid rgba(255, 80, 80, .35);", }; ---

{title}

``` ### Используем компонент в MDX Обнови `src/pages/guide.mdx`: ```mdx --- title: "Гайд по Astro" description: "Пробная MDX-страница" --- import Callout from "../components/Callout.astro"; # MDX + компоненты Ты пишешь статью как Markdown, но можешь вставлять "живые" компоненты. Не превращай статью в React-приложение. Это всё ещё контент. ``` --- ## Content Collections: контент с валидацией ### Зачем нужны collections Чтобы: - Описать **схему фронтматтера** (какие поля обязательны) - Ловить ошибки **на этапе билда** (а не в проде) - Получать **типизацию** (особенно приятно в TS) ### Настраиваем `src/content.config.ts` Создай файл `src/content.config.ts`: ```ts // src/content.config.ts import { defineCollection } from "astro:content"; import { z } from "astro/zod"; const blog = defineCollection({ schema: z.object({ title: z.string().min(5), description: z.string().min(20), pubDate: z.date(), updatedDate: z.date().optional(), tags: z.array(z.string()).default([]), category: z.string().default("Frontend"), draft: z.boolean().default(false), cover: z.string().optional(), slug: z.string().min(3), }), }); export const collections = { blog }; ``` > `astro/zod` — это реэкспорт Zod для схем коллекций. --- ## Первая статья в коллекции Создай файл `src/content/blog/astro-part-1.mdx`: ```mdx --- title: "Astro: старт (часть 1)" description: "Статья в content collection, чтобы потом красиво собрать список и страницы." pubDate: 2026-01-05T16:00:00.000Z tags: - astro - mdx - frontend category: Frontend draft: false slug: "astro-part-1" --- import Callout from "../../components/Callout.astro"; # Astro: старт (часть 1) Он лежит в src/content/blog и валидируется схемой. Здесь начинается содержание статьи… ``` --- ## Выводим список статей: /blog Создай файл `src/pages/blog/index.astro`: ```astro --- import BaseLayout from "../../layouts/BaseLayout.astro"; import { getCollection } from "astro:content"; // Загружаем все посты, скрываем черновики, сортируем по дате const posts = (await getCollection("blog")) .filter(p => !p.data.draft) .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf()); ---

Блог

{post.data.title}
{post.data.description}

``` --- ## Страница статьи: /blog/:slug Создай файл `src/pages/blog/[slug].astro`: ```astro --- import BaseLayout from "../../layouts/BaseLayout.astro"; import { getCollection } from "astro:content"; // Для SSG Astro нужен список всех путей export async function getStaticPaths() { const posts = await getCollection("blog"); return posts .filter(p => !p.data.draft) .map((post) => ({ params: { slug: post.data.slug }, props: { post }, })); } const { post } = Astro.props; // У коллекционных MDX/MD есть render() — получаем компонент контента const { Content } = await post.render(); ---

{post.data.title}

{post.data.pubDate.toLocaleDateString("ru-RU")}

``` --- ## Проверка результата ### 1. Проверка списка статей ```bash # Запустить dev-сервер npm run dev # Открыть http://localhost:4321/blog ``` Должен отобразиться список статей из `src/content/blog/`. ### 2. Проверка страницы статьи ```bash # Открыть http://localhost:4321/blog/astro-part-1/ ``` Должна отобразиться страница статьи с содержимым MDX. ### 3. Проверка сборки ```bash # Собрать проект npm run build # Проверить dist/ ls -la dist/ ``` Если сборка прошла без ошибок — все маршруты и коллекции настроены верно. --- ## Типичные ошибки ### ❌ Ошибка: `getCollection("blog")` — коллекция не найдена **Причина:** Нет `src/content.config.ts` или папки `src/content/blog/`. **Решение:** ```bash # Создать конфиг touch src/content.config.ts # Создать папку для статей mkdir -p src/content/blog ``` ### ❌ Ошибка валидации frontmatter при билде **Причина:** Поля не совпадают со схемой (дата, обязательные поля). **Решение:** Проверить `title`, `description`, `pubDate`, `slug` в `.mdx`. Даты в формате ISO: `2026-01-05T16:00:00.000Z`. ### ❌ MDX-страница не открывается / 404 **Причина:** Файл не в `src/pages/` или опечатка в имени. **Решение:** Роут = путь от `pages`: `guide.mdx` → `/guide`. ### ❌ Компонент в MDX не найден **Причина:** Неверный путь импорта (относительно файла MDX). **Решение:** Импорт от корня файла: `../../components/Callout.astro`. ### ❌ `post.render is not a function` **Причина:** Используется сырой объект поста вместо результата `getCollection`. **Решение:** В `[slug].astro` брать `post` из `getStaticPaths` → `props` и вызывать `post.render()`. --- ## Где применять - **Блоги:** контентные сайты с MDX и Collections - **Документация:** техническая документация с компонентами - **Лендинги:** маркетинговые страницы с быстрым SEO - **Портфолио:** сайты-визитки с минимальным JS **Связанные статьи:** - [SEO, sitemap и RSS в Astro](/blog/astro-seo-sitemap-rss-setup) - [Actions, API Routes, SSR и деплой](/blog/astro-2025-2026-part-3-actions-api-ssr-deploy) - [TypeScript: основы и философия](/blog/typescript-basics-philosophy-and-start) **Документация:** - [Astro Documentation](https://docs.astro.build/) - [MDX Guide](https://docs.astro.build/en/guides/markdown-content/) - [Content Collections](https://docs.astro.build/en/guides/content-collections/) ---

Как создать блог на Astro: установка, MDX, Content Collections