Кастомизация темы Nextra: от логотипа до мультиязычности

Кастомизация 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 из коробки, но мы можем расширить их под ваши задачи: добавить кастомные кнопки, диаграммы или встроенные видео.

Процесс работы и объём

1. Анализ — изучаем текущую тему и требования к кастомизации.
2. Проектирование — определяем компоненты, CSS-переменные, структуру i18n.
3. Реализация — пишем код, интегрируем с MDX.
4. Тестирование — проверяем все страницы, адаптивность, Core Web Vitals.
5. Деплой — публикуем на 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 или кастомный компонент.

Наш опыт работы с Next.js и Nextra насчитывает более 5 лет и 30+ реализованных проектов документации. Мы гарантируем качество и соответствие современным стандартам.

Получите консультацию по настройке Nextra — напишите нам. Оценим проект бесплатно в течение дня.