Переход с Docusaurus на собственную платформу

> Когда готовые решения перестают устраивать — пора писать своё.

---

Предыстория

Почти два года мой блог и вики жили на Docusaurus. Это отличный инструмент — быстрый старт, MDX из коробки, удобная структура документации. Я даже писал о нём пост.

Но со временем стали копиться ограничения: хотелось больше контроля над навигацией, кастомных компонентов, нормальной авторизации, комментариев и SEO — всего того, что в Docusaurus приходилось обходить хаками или плагинами.

Старый блог на Docusaurus по-прежнему доступен в репозитории: github.com/BazZziliuS/docusaurus.

---

Почему не Docusaurus

Docusaurus — отличный инструмент, но мне хотелось большего:

* Полная кастомизация — хотелось держать всё в своих руках: от навигации и layout-ов до логики рендеринга. В Docusaurus любое отклонение от стандарта упирается в swizzling и ограничения фреймворка * Поддержка современных библиотек — Docusaurus построен на React, но его архитектура не всегда дружит с актуальными версиями библиотек. На своей платформе я могу свободно использовать любые пакеты без конфликтов и костылей * Контроль над проектом — когда платформа твоя, ты не зависишь от релизного цикла чужого фреймворка. Нужна новая фича — берёшь и делаешь, а не ждёшь PR или ищешь обходные пути

---

Что такое Cloudea Blog

Cloudea Blog — моя собственная платформа для блогов и документации, построенная на:

* Next.js (App Router) — серверные компоненты, ISR, API routes * MDX — контент пишется в тех же .mdx файлах, что и раньше * Tailwind CSS + shadcn/ui — современный и кастомизируемый UI * Supabase / Giscus — комментарии на выбор * i18n — мультиязычность (ru/en) из коробки

Что появилось нового

* Полный контроль над навигацией — dropdown-ы на hover с кликабельными заголовками * Генерация OG-изображений на лету * Геоблокировка постов через frontmatter * Полнотекстовый поиск по блогу и документации * Страницы тегов и архива по годам * Боковое меню документации с автораскрытием активной категории * View Transitions для плавных переходов между страницами

---

Как прошла миграция

Контент переехал практически без изменений — MDX есть и там, и тут. Основные моменты:

Посты — скопированы из blog/ в content/blog/, убраны , адаптированы пути к изображениям

Документация — перенесена из docs/ в content/docs/ с сохранением структуры категорий

Admonitions — Docusaurus-синтаксис :::tip заменён на компонент

Frontmatter — добавлены новые поля (geo_block, order), убраны специфичные для Docusaurus

Компоненты — GeoCheck, DocCardList, Backlink заменены на встроенные аналоги или убраны

Весь процесс занял один вечер. Больше всего времени ушло на отладку мелочей вроде вложенных тегов в заголовках и inline-отображения shields.io бейджей.

---

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

Вся настройка сайта живёт в одном файле cloudea.config.ts:

``typescript const config: CloudeaConfig = { title: "Cloudea Blog", url: "https://blog.cloudea.org/", homepage: "blog",

themeConfig: { navbar: { title: "Cloudea", links: [ { label: "Блог", href: "/blog", items: [ { href: "/blog", label: "Статьи" }, { href: "/blog/tags", label: "Теги" }, { href: "/blog/archive", label: "Архив" }, ], }, // ... ], }, }, }; ``

---

Вывод

Переход с Docusaurus на собственную платформу дал мне полный контроль над каждым аспектом сайта. Да, это больше работы по поддержке, но взамен — никаких ограничений и компромиссов.

Если вас устраивает Docusaurus — используйте его, это прекрасный инструмент. Но если вы упираетесь в его границы и хотите большего — возможно, пришло время написать своё.

Исходный код платформы открыт: github.com/BazZziliuS/cloudea-blog.