Кастомизация 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 — напишите нам. Оценим проект бесплатно в течение дня.