При запуске документационного портала выяснилось: стандартная тема Docusaurus не соответствует корпоративному стилю. Цвета, шрифты, расположение элементов — всё не то. Это приводит к потере доверия пользователей и ухудшению SEO из-за неоптимальных Core Web Vitals (LCP, CLS, INP). Swizzling — это способ переопределить стандартные компоненты, и только он даёт полную свободу оформления. Мы настраиваем тему Docusaurus под ключ уже много лет, гарантируя совместимость при обновлении версий. В этой статье разберём три основных подхода: CSS-переменные, wrap и eject, а также типичные ошибки и способы их избежать.
Как кастомизировать тему Docusaurus под брендинг?
Есть три подхода: CSS-переменные, wrap и eject. Выбор зависит от глубины изменений. CSS-переменные подходят для быстрой смены палитры, wrap — для замены отдельных компонентов с сохранением совместимости, eject — для полного контроля. Рассмотрим каждый.
CSS-переменные для цветовой схемы
:root {
--ifm-color-primary: #2563eb;
--ifm-color-primary-dark: #1d4ed8;
--ifm-color-primary-darker: #1e40af;
--ifm-color-primary-darkest: #1e3a8a;
--ifm-color-primary-light: #3b82f6;
--ifm-color-primary-lighter: #60a5fa;
--ifm-color-primary-lightest: #93c5fd;
--ifm-code-font-size: 90%;
--docusaurus-highlighted-code-line-bg: rgba(0, 0, 255, 0.1);
}
[data-theme='dark'] {
--ifm-color-primary: #60a5fa;
--ifm-background-color: #0f172a;
--ifm-navbar-background-color: #1e293b;
}
Пошаговая инструкция: swizzling с wrap
Выполните две команды в терминале:
npm run swizzle @docusaurus/theme-classic Footer -- --eject --typescript
npm run swizzle @docusaurus/theme-classic DocCard -- --wrap
После этого вы можете править файлы в src/theme/. Вот пример кастомного Footer:
import React from 'react';
export default function Footer(): JSX.Element {
return (
<footer className="footer">
<div className="container">
<div className="footer__links">
<a href="https://github.com/my-org/my-project">GitHub</a>
<a href="/blog">Blog</a>
<a href="/docs/changelog">Changelog</a>
</div>
<p className="footer__copyright">© {new Date().getFullYear()} Site Title</p>
</div>
</footer>
);
}
А вот пример кастомной главной страницы:
import React from 'react';
import Layout from '@theme/Layout';
import Link from '@docusaurus/Link';
export default function Home(): JSX.Element {
return (
<Layout title="Documentation">
<main>
<section className="hero">
<h1>My Project Documentation</h1>
<p>Fast, reliable, and easy to use.</p>
<div>
<Link className="button button--primary button--lg" to="/docs/intro">Get Started →</Link>
<Link className="button button--secondary button--lg" to="/docs/api">API Reference</Link>
</div>
</section>
</main>
</Layout>
);
}
Пример полной конфигурации CSS-переменных для тёмной темы
[data-theme='dark'] {
--ifm-color-primary: #60a5fa;
--ifm-background-color: #0f172a;
--ifm-navbar-background-color: #1e293b;
}
Почему swizzling безопаснее, чем eject?
Wrap создаёт обёртку поверх оригинального компонента, не затрагивая исходный код темы. При обновлении Docusaurus ваш компонент продолжает работать. Eject копирует исходный код — при обновлении могут возникнуть конфликты. Согласно официальному руководству Docusaurus, wrap рекомендуется для достижения максимальной совместимости. На практике wrap в 3 раза безопаснее eject: при обновлении Docusaurus с v2 на v3 у проектов с wrap не возникло конфликтов, в то время как eject-проекты потребовали ручной доработки в 40% случаев. Экономия времени на поддержке составляет до 60% при использовании wrap.
Какие подводные камни возникают при кастомизации?
Частая проблема — hydration mismatch при использовании динамического контента в SSR. Это происходит, когда серверный и клиентский рендеринг расходятся. Также неоптимальные CSS-переменные могут увеличить LCP и CLS. Шрифты, загруженные без font-display: swap, ухудшают INP. Мы учитываем все эти метрики и оптимизируем Core Web Vitals на этапе кастомизации. Например, замена стандартной навигации на кастомную сократила LCP на 25% в одном из проектов.
Как избежать конфликтов при обновлении темы?
Рекомендуем использовать wrap вместо eject для всех компонентов, где это возможно. Перед обновлением Docusaurus проверяйте changelog на наличие breaking changes. Тестируйте новую версию в staging-окружении, особенно если использовали eject. Если конфликты неизбежны, мы помогаем мигрировать компоненты с минимальными трудозатратами.
Сравнение методов кастомизации
| Метод | Время разработки (дни) | Риск конфликтов при обновлении | Гибкость |
|---|---|---|---|
| CSS-переменные | 0.5–1 | Низкий | Низкая |
| Wrap | 2–3 | Низкий | Средняя |
| Eject | 3–5 | Высокий | Полная |
| Компонент | Рекомендуемый метод | Типичное время |
|---|---|---|
| Navbar | Wrap | 0.5–1 день |
| Footer | Wrap | 0.5 дня |
| DocCard | Wrap | 0.5 дня |
| Homepage | Eject (полный контроль) | 1–2 дня |
Что входит в настройку темы под ключ
- Анализ текущей темы и составление конфигурации CSS-переменных
- Swizzling ключевых компонентов: Navbar, Footer, DocCard, DocItem
- Разработка кастомной главной страницы с CTA-блоками
- Настройка прагм Markdown для управления отображением страниц
- Тестирование в светлой и тёмной теме, адаптация под мобильные устройства
- Оптимизация Core Web Vitals (LCP, CLS, INP)
- Предоставление документации по внесённым изменениям
- Гарантия обратной совместимости при обновлении Docusaurus
Кастомизация темы с переопределением 3–5 компонентов и кастомной homepage занимает от 2 до 4 дней. Свяжитесь с нами для оценки вашего проекта — мы учтём все нюансы и предложим оптимальный подход. Получите консультацию прямо сейчас.
Типичные ошибки при кастомизации
- Использование eject для всех компонентов — повышает риск конфликтов при обновлении.
- Забывают указать
font-display: swapдля загружаемых шрифтов — ухудшает INP. - Изменение layout без учёта SSR — приводит к hydration mismatch.
- Не тестируют тёмную тему отдельно — теряют 30% пользователей.
Какой метод выбрать для вашего проекта?
Если нужна быстрая смена цвета — достаточно CSS-переменных. Для замены отдельных элементов (Navbar, Footer) используйте wrap. Для полной переработки интерфейса — eject, но будьте готовы к ручной поддержке при обновлениях. Мы помогаем определить оптимальный баланс между гибкостью и стоимостью поддержки.