Кастомізація теми Docusaurus: swizzling, CSS, налаштування

При запуску документаційного порталу виявилося: стандартна тема 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> ); } 

[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-змінних
• 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, але будьте готові до ручної підтримки при оновленнях. Ми допомагаємо визначити оптимальний баланс між гнучкістю та вартістю підтримки.