@rebass/mdx
v2.0.0Rebass MDX
⚛️#️⃣ MDX + Styled System + Emotion
npm i @rebass/mdx
Wrap your application with the RebassMDX
provider component.
All child MDX documents will receive component and theming context from this provider.
import React from 'react'
import RebassMDX from '@rebass/mdx'
import Document from './document.mdx
export default props =>
<RebassMDX>
<Document />
</RebassMDX>
Theming
Pass a theme
object to the RebassMDX
provider component to add an Emotion theming context.
The theme is a Styled System Theme that can be used to apply consistent colors and typography across an entire app.
// example theme
export default {
colors: {
text: '#000',
background: '#fff',
primary: '#07c',
},
fonts: {
body: 'system-ui, sans-serif',
heading: 'inherit',
monospace: 'Menlo, monospace',
},
}
Styles
An additional styles
object can be added to the theme
object to apply styles to MDX elements.
// example theme styles
export default {
colors: {
primary: 'tomato',
},
styles: {
h1: {
color: 'primary',
}
},
}
The styles
object uses @styled-system/css so that core Styled System props can be mixed with CSS syntax.
// example theme styles
export default {
colors: {
primary: 'tomato',
},
styles: {
h1: {
// using Styled System props
fontSize: [ 4, 5 ],
fontFamily: 'heading',
color: 'primary',
// alongside other CSS
textTransform: 'uppercase',
letterSpacing: '0.2em',
}
}
}
Built-in Themes
Rebass MDX includes a handful of built-in themes that can be used out-of-the-box or as a basis for extending into a custom theme.
import React from 'react'
import { RebassMDX } from '@rebass/mdx'
import themes from '@rebass/mdx/themes'
export default props =>
<RebassMDX theme={themes.base}>
{props.children}
</RebassMDX>
base
: the default themefuture
: theme with Avenir Nextdark
: dark mode theme
Custom Components
Custom MDX components can be added to context. This can be useful for adding syntax highlighting, live code editors, or linked headings.
import React from 'react'
import { RebassMDX } from '@rebass/mdx'
import Link from './Link'
export default props =>
<RebassMDX
components={{
a: Link,
}}>
</RebassMDX>
Any component can be added to context to apply theming with the RebassMDX
provider.
These components can be rendered with the Styled
component.
Styled Components
For usage outside of an MDX file, use the Styled
component to render styled components anywhere in your app.
These components can be styled using the theme and the theme.styles
object.
import React from 'react'
import { Styled } from '@rebass/mdx'
export default props =>
<Styled.wrapper>
<Styled.h1>
Hello
</Styled.h1>
</Styled.wrapper>
For custom components, use the tag
prop.
import React from 'react'
import { Styled } from '@rebass/mdx'
export default props =>
<Styled.wrapper>
<Styled tag='CustomComponent'>
Hello
</Styled>
</Styled.wrapper>
useComponents
Hook
Alternatively, Rebass MDX components can be accessed by using the useComponents
hook.
import React from 'react'
import { useComponents } from '@rebass/mdx'
export default props => {
const Styled = useComponents()
return (
<Styled.h1>
Hello
</Styled.h1>
)
}
Nesting Providers
The RebassMDX
component can be nested to change styles contextually.
This can be useful for styling sections of a page differently where needed.
// example root-level provider
import React from 'react'
import RebassMDX from '@rebass/mdx'
export default props =>
<RebassMDX>
{props.children}
</RebassMDX>
// example nested provider for style overrides
import React from 'react'
import RebassMDX, { Styled } from '@rebass/mdx'
export default props =>
<RebassMDX
theme={{
styles: {
h1: {
fontSize: 3,
}
}
}}>
<Styled.h1>Hello</Styled.h1>
</RebassMDX>
API
RebassMDX
: core provider component- props:
theme
add a custom Styled System Themetheme.styles
override component styles
components
override specific components or add custom components to code fence examples
- props:
Styled
useComponents
MIT License