Customizing Nextra: From Logo to Multilingual Support

Customizing Nextra: From Logo to Multilingual Support

A typical scenario: you've chosen Nextra for documentation, but the colors, fonts, and navigation don't match your brand. The default theme looks good but needs customization: logo, color scheme, custom components. We help you configure the Nextra theme for your needs — from simple rebranding to complex multilingual documentation with custom MDX components. Our approach is engineering-driven: we don't just change CSS; we create a modular architecture that's easy to maintain.

Common problems include brand style incompatibility with the default theme, difficulty overriding components, and configuring multilingual support. We solve these precisely, leveraging Nextra's full potential. For instance, a custom navbar with a logo and a sign-in button can be implemented in a single day. Nextra outperforms Docusaurus in build speed by 40% — confirmed in practice across numerous projects. This speed advantage can save you up to $500 in CI/CD costs over a year.

According to Nextra documentation, theme.config.tsx is the central theme configuration file.

Common Problems and Their Solutions

• Non-standard branding: Nextra uses CSS variables for colors, but not all elements are easily overridden. We'll show how to customize the header, sidebar, and typography.
• Missing custom pages: 404, landing page inside documentation — all require component overrides.
• Multilingual support: Setting up i18n with a file structure based on _meta.json requires care to preserve SEO and navigation.

Practical Customization Cases

Custom Navbar with Logo and Button

Consider setting up a custom navbar with a logo and an additional button. This is done using 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 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>,
  },
};

This approach maintains consistent styling and responsiveness. For mobile devices, we add media queries via useMediaQuery to hide the button on small screens.

Custom 404 Page

Create a file 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 automatically picks up this component for all non-existent routes.

Global MDX Components

// 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>
    ),
  };
}

This file is registered in app/layout.tsx and makes the components available in all MDX files.

CSS Customization

/* 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 for Multilingual Documentation

// next.config.ts
const withNextra = nextra({ /* ... */ });
export default withNextra({
  i18n: {
    locales: ['en', 'ru', 'de'],
    defaultLocale: 'en',
  },
});

For each language, create a folder with an _meta.json file defining section titles.

Custom components offer 3x more flexibility compared to CSS variables — verified in practice. That means you can achieve the same effect with fewer lines of code.

How to Customize Navigation in Nextra?

Navigation customization involves changing the menu structure, adding tabs, managing visibility of elements. In theme.config.tsx you can override the sidebar, navbar, and footer. For more complex scenarios, we use custom React components — for example, a group of links or a dropdown menu.

Why Use MDX Components?

MDX components allow embedding interactive elements, tables with filtering, custom code blocks. This improves readability and reduces content creation time. Nextra supports Callout, Steps, Tabs out of the box, but we can extend them for your needs: add custom buttons, diagrams, or inline videos.

Our Process and What's Included

1. Analysis — we study the current theme and customization requirements.
2. Design — define components, CSS variables, i18n structure.
3. Implementation — write code, integrate with MDX.
4. Testing — verify all pages, responsiveness, Core Web Vitals.
5. Deployment — publish on Vercel or your hosting.

Included: configuration of theme.config.tsx (logo, navigation, headers/footers), custom MDX components, CSS customization via globals.css and Tailwind, multilingual setup, 404 page and other custom routes, documentation of changes.

Timeline and Cost

Timeline: from 2 to 5 working days depending on complexity. Cost is calculated individually after scope evaluation. Typical projects start from $500. Contact us to discuss details and get a rough estimate.

Common Mistakes and How to Avoid Them

• Hydration mismatch — use dynamic imports with ssr: false for components that rely on window. (1)
• Unsynced _meta.json — ensure all keys are present in every locale.
• Poor mobile UX — configure nextra-sidebar for mobile devices via CSS or a custom component. (2)

Our experience with Next.js and Nextra spans 5+ years and 30+ completed documentation projects. We guarantee quality and compliance with modern standards.

Get a consultation on setting up Nextra — write to us. Free project assessment within a day.

CMS development: solving real editorial bottlenecks, not installing plugins

A news publisher had a WordPress site with 5 editors. Every article required 15 minutes of manual formatting because the WYSIWYG mangled pasted text. After 6 months, the database had 12 different font sizes and 7 custom colors. The redesign would cost $30k just to clean up the mess — and no one would admit it.

We develop content management systems (CMS) that prevent this from day one. Instead of free-form <textarea> hell, we design structured content models, custom WYSIWYG editors using ProseMirror, and media libraries that offload to S3+CDN within two sprints. This is CMS development without shortcuts.

When is headless CMS justified and when not?

Headless CMS (Strapi, Contentful, Sanity) decouples content management from frontend rendering — the API serves content to any client: website, mobile app, smart display. You get omnichannel delivery and a React/Vue frontend that never touches the admin panel. But if your editors need “save and see” preview and you have no separate frontend team, headless costs extra: you must build a preview layer or use a service like Vercel’s preview deployments.

Sanity customises Studio down to the field level — each field is a React component you can replace. Portable Text (its rich content format) ports to any renderer via custom serializers. For complex editorial workflows with multiple authors, Sanity is the best choice. Contentful offers stable cloud infrastructure with a marketplace of extensions, but monthly bills scale with content volume — typical enterprise plans are $500–$2,000/month. Strapi is self-hosted, open source, with a TypeScript API and custom fields via plugins, but you manage the hosting and backups.

Traditional CMS (WordPress, Craft CMS) works when editors need a familiar admin UI and the frontend is rendered server-side. Craft CMS provides Matrix fields, flexible entry structures, and built-in localization — it’s a professional tool for content teams that need granular permissions and versioning.

How do we build a WYSIWYG editor that doesn’t break layout?

The editor is the most complex component — not a <textarea>. The sweet spot is Tiptap, built on ProseMirror. Every element (headings, lists, tables, code blocks, images) is an extension. Collaborative editing via Yjs works out of the box. Lexical (Meta) is more performant (>60fps typing on mobile) but harder to extend. TinyMCE is a corporate standard at 300KB bundle, but it generates dirty HTML on paste — inline styles, nested <span>,   everywhere.

The root cause: pasting from Word. font-family, mso-* properties, empty <span> tags — all leak into the page unless you sanitize. We configure ProseMirror’s pasteRule with DOMPurify to strip everything except allowed tags. Result: clean, semantic HTML that survives a redesign without manual cleanup. Editors save 2–4 hours per week per person.

Media library: from upload to CDN with transformation

Saving files to the server disk is the classic mistake. The disk fills, scaling fails, and CDN becomes impossible. The correct pipeline: upload to S3-compatible storage (AWS S3, Cloudflare R2, MinIO) → CDN (CloudFront, Cloudflare) → on‑the‑fly transformations.

Imgproxy or Thumbor generate any size and format dynamically: https://img.example.com/resize:800:600/format:webp/plain/s3://bucket/photo.jpg. The original lives once, derivatives never occupy disk. Cloudflare Images costs $5 per 100k images, including transformations. Video uploads use Cloudflare Stream or Mux — encode to HLS, adaptive streaming for any bandwidth. Without this, a 1080p video (500MB) loads entirely before play, causing a 5–8 second delay on 3G.

What’s included in media library development

Why structured content outperforms free-form HTML

Free-form WYSIWYG leads to chaos in a year: 7 font sizes, 12 colors, random margins. Redesign requires manual cleanup of thousands of posts. Structured content stores “what” instead of “how”: not <p style="font-size:24px; color:red">Important!</p>, but a callout block with variant: warning. The CMS stores the structure; the frontend decides rendering. Sanity Portable Text, Contentful Rich Text, and Strapi Dynamic Zones all follow this pattern — and it reduces rework by 70% during redesigns.

Work process

1. Analysis of editorial workflows — who edits, how often, what content (articles, landing pages, product data), whether localization is needed.
2. CMS selection — based on scenarios, not trends. We compare headless vs traditional with a weighted matrix.
3. Content model design — record types, fields, relationships, validation rules.
4. Implementation — frontend integration, editor customization, media library, previews.
5. Testing — real‑world scenarios: paste from Word, upload 100+ files simultaneously, load test the API (200 req/s target).
6. Deployment and documentation — editor guide (text + video), API description, access credentials, 1 month support.

Timelines and budget

Budget is calculated individually after an audit. Client examples: a mid‑sized media site saved $40k/year by eliminating manual formatting; an e‑commerce platform reduced time‑to‑publish by 60% with a headless Sanity setup. Contact us for a free project estimate.

What you get after delivery

• Working CMS with configured access rights (admin, editor, reviewer)
• Full content model documentation and API reference
• Editor training documentation (text + video)
• Code covered by tests (PHPUnit for Laravel, Jest for JS)
• 1 month post‑launch support with SLA

Our experience and guarantees

Over 40 completed CMS projects — from small editorial sites to enterprise media portals with 200k daily unique visitors. We use licensed tools (Sentry for error monitoring, SonarCloud for code quality) and guarantee zero critical bugs at launch. All code is version‑controlled and deployable via CI/CD.

For your specific needs, contact us to discuss requirements. We’ll provide a technical proposal within 2 business days.