Переход с 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 есть и там, и тут. Основные моменты:

1. Посты — скопированы из blog/ в content/blog/, убраны <!-- truncate -->, адаптированы пути к изображениям
2. Документация — перенесена из docs/ в content/docs/ с сохранением структуры категорий
3. Admonitions — Docusaurus-синтаксис :::tip заменён на компонент <Callout>
4. Frontmatter — добавлены новые поля (geo_block, order), убраны специфичные для Docusaurus
5. Компоненты — GeoCheck, DocCardList, Backlink заменены на встроенные аналоги или убраны

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

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

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

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.