2018-08-05 18:27:17 +03:00
# Theming
2019-03-10 03:31:30 +03:00
mdx-deck uses [emotion][] for styling, making practically any part of the presentation themeable.
2018-08-05 18:27:17 +03:00
## Built-in Themes
mdx-deck includes several built-in themes to change the look and feel of the presentation.
Export `theme` from your MDX file to enable a theme.
```mdx
export { dark as theme } from 'mdx-deck/themes'
# Dark Theme
```
2018-08-05 19:41:47 +03:00
View the [List of Themes ](themes.md ).
2018-08-05 18:27:17 +03:00
## Custom Themes
A custom theme can be provided by exporting `theme` from the MDX file.
```mdx
export { default as theme } from './theme'
# Hello
```
The theme should be an object with fields for fonts, colors, and CSS for individual components.
```js
2018-08-05 20:11:25 +03:00
// Example theme.js
2018-08-05 18:27:17 +03:00
export default {
// add a custom font
font: 'Roboto, sans-serif',
// custom colors
colors: {
text: '#f0f',
background: 'black',
2019-02-18 01:49:15 +03:00
},
2018-08-05 18:27:17 +03:00
}
```
2019-03-10 03:31:30 +03:00
## Composing Themes
2018-08-05 18:27:17 +03:00
2019-03-10 03:31:30 +03:00
Multiple themes can be used together.
For example, this allows the use of a syntax highlighting theme,
along with a color theme, and a separate typography theme.
2018-08-05 18:27:17 +03:00
2019-03-10 03:31:30 +03:00
To compose themes together export a `themes` array instead of a single theme.
2018-08-05 18:27:17 +03:00
2019-03-10 03:31:30 +03:00
```mdx
import { syntaxHighlighter } from 'mdx-deck/themes'
import customTheme from './theme'
2018-08-05 18:27:17 +03:00
2019-03-10 03:31:30 +03:00
export const themes = [syntaxHighlighter, customTheme]
2018-08-05 18:27:17 +03:00
2019-03-10 03:31:30 +03:00
# Cool. :sunglasses:
2018-08-05 18:27:17 +03:00
```
2019-03-10 03:31:30 +03:00
Please note that themes are deep merged together and the last theme specified will override fields from themes before it.
2018-08-05 18:27:17 +03:00
2019-03-10 03:31:30 +03:00
### Google Fonts
2018-08-05 18:27:17 +03:00
2019-03-10 03:31:30 +03:00
Themes can specify a `googleFont` field to automatically add a `<link>` tag to the document head.
Alternatively, use the `<Head />` component to add a custom `<link>` tag.
2018-08-05 18:27:17 +03:00
2019-03-10 03:31:30 +03:00
### Syntax Highlighting
2018-08-25 18:25:42 +03:00
2019-03-10 03:31:30 +03:00
By default fenced code blocks do not include any syntax highlighting.
Themes can provide a set of custom MDX components, including a replacement for the default `code` component that can add syntax highlighting with libraries like [react-syntax-highlighter][].
2018-08-25 18:25:42 +03:00
2019-03-10 03:31:30 +03:00
MDX Deck includes two themes for adding syntax highlighting with [react-syntax-highlighter][]: `syntaxHighlighter` and `syntaxHighlighterPrism` .
2018-08-25 18:25:42 +03:00
2019-03-10 03:31:30 +03:00
Since MDX supports using React components inline, you can also import a syntax highlighting component directly, if you prefer.
2018-08-05 18:27:17 +03:00
### Styling Elements
2019-03-10 03:31:30 +03:00
Each element can be styled with a theme.
Add a style object (or string) to the theme to target specific elements.
2018-08-05 18:27:17 +03:00
```js
// example theme
export default {
h1: {
textTransform: 'uppercase',
2019-02-18 01:49:15 +03:00
letterSpacing: '0.1em',
2018-08-05 18:27:17 +03:00
},
blockquote: {
2019-02-18 01:49:15 +03:00
fontStyle: 'italic',
},
2018-08-05 18:27:17 +03:00
}
```
See the [reference ](#reference ) below for a full list of element keys.
2018-08-05 19:41:47 +03:00
## Reference
2018-08-05 18:27:17 +03:00
The following keys are available for theming:
- `font` : base font family
- `monospace` : font family for `<pre>` and `<code>`
- `colors` : object of colors used for MDX components
- `text` : root foreground color
- `background` : root background color
2019-03-10 03:31:30 +03:00
- `code` : text color for `<pre>` and `<code>`
- `codeBackground` : background color for `<pre>` and `<code>`
2018-08-05 18:27:17 +03:00
- `css` : root CSS object
2019-03-10 03:31:30 +03:00
- `heading` : CSS for all headings
2018-08-05 18:27:17 +03:00
- `h1` : CSS for `<h1>`
- `h2` : CSS for `<h2>`
- `h3` : CSS for `<h3>`
2018-08-05 21:09:16 +03:00
- `h4` : CSS for `<h4>`
- `h5` : CSS for `<h5>`
- `h6` : CSS for `<h6>`
2019-03-10 03:31:30 +03:00
- `p` : CSS for `<p>`
- `a` : CSS for `<a>`
2018-08-05 18:27:17 +03:00
- `ul` : CSS for `<ul>`
- `ol` : CSS for `<ol>`
- `li` : CSS for `<li>`
- `img` : CSS for `<img>`
2018-08-05 21:09:16 +03:00
- `blockquote` : CSS for `<blockquote>`
2018-08-05 18:27:17 +03:00
- `table` : CSS for `<table>`
2019-03-10 03:31:30 +03:00
- `pre` : CSS for `<pre>`
- `code` : CSS for `<code>`
2019-03-18 19:55:12 +03:00
- `Slide` : CSS to apply to the wrapping Slide component
2018-08-05 18:27:17 +03:00
- `components` : object of MDX components to render markdown
- `Provider` : component for wrapping the entire app
2019-05-20 21:25:03 +03:00
- `Presenter` : component for wrapping the presenter mode
2019-03-10 03:31:30 +03:00
- `googleFont` : CSS HREF for adding a Google Font `<link>` tag
2018-08-05 18:27:17 +03:00
2018-08-05 20:00:52 +03:00
## Advanced Usage
For more advanced customizations see the [Advanced Usage ](advanced.md ) docs.
2018-08-05 18:33:04 +03:00
2019-03-10 03:31:30 +03:00
[emotion]: https://emotion.sh
2019-02-18 01:49:15 +03:00
[mdx]: https://github.com/mdx-js/mdx
2019-03-10 03:31:30 +03:00
[react-syntax-highlighter]: https://github.com/conorhastings/react-syntax-highlighter
