Styling MDX Content

The theme.styles object combined with useThemeStylesWithMdx function is the primary way to style content in MDX documents. This allows you to add typographic styles to markdown without the need to pollute the global scope. Styles within this object have access to other values in the theme object.

import { MDXProvider } from '@mdx-js/react'
import { useThemedStylesWithMdx } from '@theme-ui/mdx'
import { ThemeProvider } from 'theme-ui'

const theme = {
  colors: {
    text: '#000',
    background: '#fff',
    primary: '#07c',
  },
  fonts: {
    body: 'system-ui, sans-serif',
    heading: 'Georgia, serif',
  },
  fontWeights: {
    heading: 700,
  },
  styles: {
    h1: {
      fontSize: 32,
      fontFamily: 'heading',
      fontWeight: 'heading',
      color: 'primary',
      mt: 4,
      mb: 2,
    },
  },
}

function Provider({ children, theme, components }) {
  const componentsWithStyles = useThemedStylesWithMdx(
    useMDXComponents(components)
  )

  return (
    <ThemeProvider theme={theme}>
      <MDXProvider components={componentsWithStyles}>
        {children}
      </MDXProvider>
    </ThemeProvider>
  )
}

Typography.js

To use Typography.js themes with Theme UI, install the @theme-ui/typography package and any Typography.js theme.

npm i @theme-ui/typography typography-theme-wordpress-2016

Use the toTheme utility to convert the theme for use in Theme UI.

// example theme with Typography.js
import { toTheme } from '@theme-ui/typography'
import wordpress2016 from 'typography-theme-wordpress-2016'
import merge from 'lodash.merge'

const typography = toTheme(wordpress2016)

export default merge(typography, {
  // optional style overrides go here
})

Content in MDX documents will be rendered with styles from the Typography.js theme. The toTheme function accepts the same Typography.js configuration options as the core library, allowing you to create custom themes with this approach as well.

Syntax Highlighting

To support syntax highlighting libraries like Prism.js, colors and other styles can be added to theme.styles.pre to target child elements with class selectors. Prism.js adds <span> elements with class names that can be used as child selectors.

To enable syntax highlighting in MDX, see the @theme-ui/prism package.

{
  colors: {
    gray: '#666',
  },
  styles: {
    pre: {
      '.comment': {
        // theme.colors and other values can be referenced
        color: 'gray',
      }
    }
  }
}
}