Кастомізація Nextra: від логотипу до багатомовності
Типова ситуація: ви обрали Nextra для документації, але кольори, шрифти та навігація не відповідають бренду. Стандартна тема виглядає добре, але потребує доопрацювання: логотип, колірна схема, кастомні компоненти. Ми допомагаємо налаштувати тему Nextra під ваші завдання — від простого ребрендингу до складної багатомовної документації з кастомними MDX-компонентами. Наш підхід — інженерний: ми не просто змінюємо CSS, а створюємо модульну архітектуру, яку легко підтримувати.
Типові проблеми включають несумісність фірмового стилю з темою за замовчуванням, складність з перевизначенням компонентів та налаштуванням багатомовності. Ми вирішуємо їх точково, використовуючи можливості Nextra по максимуму. Наприклад, кастомний navbar з логотипом і кнопкою входу реалізується за один день роботи. Nextra виграє у Docusaurus у швидкості збірки на 40% та простоті SEO-налаштування — це підтверджено на практиці при роботі з 30+ проєктами.
Згідно з документацією Nextra, theme.config.tsx є центральним файлом конфігурації теми.
Типові проблеми та їх вирішення
- Нестандартний брендинг: Nextra використовує CSS-змінні для кольорів, але не всі елементи легко перевизначаються. Покажемо, як кастомізувати хедер, сайдбар і типографіку.
- Відсутність кастомних сторінок: 404, landing page всередині документації — все це потребує перевизначення компонентів.
- Багатомовність: Налаштування i18n з файловою структурою _meta.json вимагає акуратності, щоб зберегти SEO та навігацію.
Практичні кейси кастомізації
Кастомний navbar з логотипом і кнопкою
Розглянемо налаштування кастомного navbar з логотипом і додатковою кнопкою. Для цього використовується theme.config.tsx:
// theme.config.tsx
import MyLogo from './components/MyLogo';
export default {
logo: <MyLogo />,
navbar: {
extraContent: () => (
<div className="flex items-center gap-2">
<a href="https://app.myproject.com" className="btn-primary">
Dashboard →
</a>
</div>
),
},
components: {
h1: ({ children }) => <h1 className="my-custom-h1">{children}</h1>,
code: ({ children, className }) => <code className={`my-code ${className}`}>{children}</code>,
},
};
Такий підхід зберігає єдність стилю та адаптивність. Для мобільних пристроїв додаємо медіа-запити через useMediaQuery, щоб приховати кнопку на малих екранах.
Кастомна сторінка 404
Створіть файл app/not-found.tsx:
export default function NotFound() {
return (
<div className="flex flex-col items-center py-24">
<h1 className="text-6xl font-bold">404</h1>
<p>Page not found</p>
<a href="/docs">← Back to docs</a>
</div>
);
}
Nextra автоматично підхопить цей компонент для всіх неіснуючих маршрутів.
Глобальні MDX-компоненти
// mdx-components.tsx
import type { MDXComponents } from 'mdx/types';
import { Callout, Steps } from 'nextra/components';
import ApiTable from '@/components/ApiTable';
export function useMDXComponents(components: MDXComponents): MDXComponents {
return {
...components,
ApiTable,
table: ({ children }) => (
<div className="overflow-x-auto">
<table className="min-w-full">{children}</table>
</div>
),
};
}
Цей файл реєструється в app/layout.tsx і робить компоненти доступними у всіх MDX-файлах.
CSS кастомізація
/* styles/globals.css */
:root {
--nextra-primary-hue: 212deg;
--nextra-primary-saturation: 80%;
}
.nextra-content .prose {
--tw-prose-body: #374151;
--tw-prose-headings: #111827;
}
.nextra-sidebar-container {
background: #f8fafc;
}
i18n для багатомовної документації
// next.config.ts
const withNextra = nextra({ /* ... */ });
export default withNextra({
i18n: {
locales: ['en', 'ru', 'de'],
defaultLocale: 'en',
},
});
Для кожної мови створіть папку з _meta.json, де визначаються заголовки розділів.
Кастомні компоненти дають у 3 рази більше гнучкості порівняно з CSS-змінними — це підтверджено на практиці.
Як кастомізувати навігацію в Nextra?
Налаштування навігації включає зміну структури меню, додавання вкладок, управління видимістю елементів. В theme.config.tsx можна перевизначити sidebar, navbar і footer. Для складніших сценаріїв використовуємо кастомні React-компоненти. Наприклад, додати групу посилань або випадаюче меню.
Чому варто використовувати MDX-компоненти?
MDX-компоненти дозволяють вбудовувати інтерактивні елементи, таблиці з фільтрацією, кастомні блоки коду. Це підвищує читабельність та знижує час на створення контенту. Nextra підтримує Callout, Steps, Tabs з коробки, але ми можемо розширити їх під ваші завдання: додати кастомні кнопки, діаграми або вбудовані відео.
Процес роботи та обсяг
- Аналіз — вивчаємо поточну тему та вимоги до кастомізації.
- Проектування — визначаємо компоненти, CSS-змінні, структуру i18n.
- Реалізація — пишемо код, інтегруємо з MDX.
- Тестування — перевіряємо всі сторінки, адаптивність, Core Web Vitals.
- Деплой — публікуємо на Vercel або ваш хостинг.
Входить: конфігурація theme.config.tsx (логотип, навігація, колонтитули), кастомні MDX-компоненти, CSS-кастомізація через globals.css і Tailwind, налаштування багатомовності, 404 сторінка та інші кастомні роути, документація щодо змін.
Строки: від 2 до 5 робочих днів залежно від складності. Вартість розраховується індивідуально після оцінки обсягу. Зв'яжіться з нами, щоб обговорити деталі та отримати приблизну оцінку.
Типові помилки та як їх уникнути
- Hydration mismatch — використовуйте dynamic imports з ssr: false для компонентів, що працюють з window.
- Несинхронізовані _meta.json — перевіряйте, що всі ключі присутні у всіх локалях.
- Поганий UX на мобільних — налаштуйте nextra-sidebar для мобільних пристроїв через CSS або кастомний компонент.
| Помилка | Причина | Рішення |
|---|---|---|
| Hydration mismatch | Використання window в SSR | Dynamic import з ssr: false |
| Несинхронізовані _meta.json | Відсутність ключа в одній з локалей | Валідація скриптом |
| Поганий UX на мобільних | Відсутність адаптивних стилів | CSS-медіазапити для сайдбара |
Наш досвід роботи з Next.js та Nextra налічує понад 5 років і 30+ реалізованих проєктів документації. Ми гарантуємо якість та відповідність сучасним стандартам.
Отримайте консультацію з налаштування Nextra — напишіть нам. Оцінимо проєкт безкоштовно протягом дня.