Customization

MDX Docs uses Material-UI under the hood, giving you a flexible theming system with support for light/dark modes, preset themes, and deep component-level overrides.

The theme option can optionally be passed to createApp():


import { createApp } from 'mdx-docs'

createApp({ pages, site, theme: { /* ... */ } })

Shorthand properties

The simplest way to customize your docs is with the top-level shorthand properties:

Property	Type	Description
`primaryColor`	`string`	Primary brand color (hex, rgb, etc.)
`fontFamily`	`string`	CSS font-family string


createApp({
  pages,
  site,
  theme: {
    primaryColor: '#6200ea',
    fontFamily: '"Inter", sans-serif',
  },
})

These apply to both light and dark mode automatically.

Built-in presets

mdx-docs ships with four presets you can use as a starting point:


import { createApp, themes } from 'mdx-docs'

createApp({ pages, site, theme: themes.ocean })

Preset	Description
`themes.default`	The default blue/pink palette
`themes.ocean`	Ocean blues — calm and professional
`themes.forest`	Forest greens — natural and subdued
`themes.rose`	Rose reds — warm and bold

Presets are plain objects, so you can extend them with spread syntax:


createApp({
  pages,
  site,
  theme: {
    ...themes.forest,
    fontFamily: '"Merriweather", serif',
  },
})

Mode-specific colors

Use the light and dark keys to change the MUI palette for each color mode. They're deep-merged on top of the built-in palette, so you only need to specify what you want to change.


createApp({
  pages,
  site,
  theme: {
    primaryColor: '#6200ea',
    light: {
      palette: {
        background: {
          default: '#f0f4f8',
          paper: '#ffffff',
        },
      },
    },
    dark: {
      palette: {
        primary: {
          main: '#bb86fc',
        },
        background: {
          default: '#0d0d0d',
        },
      },
    },
  },
})

Each mode's colors become CSS variables, so prerendered pages show the visitor's color mode before JavaScript loads.

light and dark only take a palette. createApp throws an error for anything else under them, like typography or components, so put those in the top-level keys below instead.

Component overrides

To restyle individual MUI components, use the top-level components key. It applies in both color modes:


createApp({
  pages,
  site,
  theme: {
    components: {
      MuiButton: {
        styleOverrides: {
          root: {
            borderRadius: 8,
            textTransform: 'none',
          },
        },
      },
      MuiLink: {
        styleOverrides: {
          root: {
            textDecoration: 'none',
          },
        },
      },
    },
  },
})

For a style that should only apply in one mode, use theme.applyStyles inside the override:


createApp({
  pages,
  site,
  theme: {
    components: {
      MuiAppBar: {
        styleOverrides: {
          root: ({ theme }) =>
            theme.applyStyles('dark', { backgroundColor: '#000' }),
        },
      },
    },
  },
})

Typography

Override the font for headings and body text independently using the top-level typography key. It takes precedence over fontFamily:


createApp({
  pages,
  site,
  theme: {
    fontFamily: '"Inter", sans-serif',
    typography: {
      h1: { fontWeight: 800 },
      h2: { fontWeight: 700 },
      body1: { lineHeight: 1.75 },
    },
  },
})