Add advanced docs

docs/advanced.md

@@ -0,0 +1,98 @@
+
+# Advanced Usage
+
+## Custom MDX components
+
+mdx-deck includes default components for MDX, but to provide custom components to the [MDXProvider][], add a `components` object to the `theme.
+
+```js
+// example theme
+import { theme } from 'mdx-deck/themes'
+import components from './components'
+
+export default {
+  ...theme,
+  components
+}
+```
+
+See the [MDX][] docs for more or take a look
+at the [default set of components](../src/components.js) as a reference.
+
+## Custom Provider component
+
+A custom Provider component can be exported to wrap the entire application.
+This is useful for adding custom context providers in React.
+
+```mdx
+export { default as Provider } from './Provider'
+
+# Hello
+```
+
+A custom Provider component will receive the application's state as props,
+which can be used to show custom page numbers or add other elements to the UI.
+
+#### Props
+
+- `index`: (number) the current slide index
+- `length`: (number) the length of the slides array
+- `mode`: (string) the current mode (one of `'NORMAL'`, `'PRESENTER'`, or `'OVERVIEW'`)
+- `notes`: (object) custom [speaker notes](#speaker-notes) for all slides
+- `step`: (number) the current visible step in an Appear component
+
+
+## Combining multiple mdx files
+
+Unlink the official `@mdx-js/loader`,
+the `mdx-deck/loader` exports an array of components instead of just one.
+Multiple MDX files can be combined into a single presentation if the filesize is getting difficult to manage.
+
+First create a couple `.mdx` files like any other mdx-deck file, with `---` to separate the different slides.
+
+```mdx
+# one.mdx
+
+---
+
+This is the first file
+```
+
+```mdx
+# two.mdx
+
+---
+
+This is the second file
+```
+
+Next, create a `.js` file to import and combine the two `.mdx` files.
+
+```js
+// deck.js
+import one from './one.mdx'
+import two from './two.mdx'
+
+export default [
+  ...one,
+  ...two
+]
+```
+
+Then, point the mdx-deck CLI comment in your `package.json` to the `deck.js` file.
+
+```json
+"scripts": {
+  "start": "mdx-deck deck.js"
+}
+```
+
+## Custom build setups
+
+The core mdx-deck components can also be used in any React application,
+such as [create-react-app][] or [next.js][].
+
+See the [React API](react.md) docs for more.
+
+[create-react-app]: https://github.com/facebook/create-react-app
+[next.js]: https://github.com/zeit/next.js/

docs/react.md

@@ -1,7 +1,7 @@
 
 # React API
 
-mdx-deck components can also be used in any React application, such as [create-react-app][] or [next.js][].
+The core mdx-deck components can also be used in any React application, such as [create-react-app][] or [next.js][].
 
 ### Webpack Loader
 
@@ -32,13 +32,11 @@ import React from 'react'
 import { SlideDeck } from 'mdx-deck'
 import slides from './deck.mdx'
 import theme from './theme'
-import components from './components'
 
 export default () =>
   <SlideDeck
     slides={slides}
     theme={theme}
-    components={components}
     width='100vw'
     height='100vh'
   />

docs/theming.md

@@ -127,44 +127,6 @@ export default {
 
 See the [reference](#reference) below for a full list of element keys.
 
-### Custom MDX Components
-
-mdx-deck includes default components for MDX, but to provide custom components to the [MDXProvider][], add a `components` object to the `theme.
-
-```js
-// example theme
-import { theme } from 'mdx-deck/themes'
-import components from './components'
-
-export default {
-  ...theme,
-  components
-}
-```
-
-See the [MDX][] docs for more or take a look
-
-### Provider component
-
-A custom Provider component can be exported to wrap the entire application.
-This is useful for adding custom context providers in React.
-
-```mdx
-export { default as Provider } from './Provider'
-
-# Hello
-```
-
-A custom Provider component will receive the application's state as props,
-which can be used to show custom page numbers or add other elements to the UI.
-
-#### Props
-
-- `index`: (number) the current slide index
-- `length`: (number) the length of the slides array
-- `mode`: (string) the current mode (one of `'NORMAL'`, `'PRESENTER'`, or `'OVERVIEW'`)
-- `notes`: (object) custom [speaker notes](#speaker-notes) for all slides
-- `step`: (number) the current visible step in an Appear component
 
 ## Reference
 
@@ -199,6 +161,9 @@ The following keys are available for theming:
 - `components`: object of MDX components to render markdown
 - `Provider`: component for wrapping the entire app
 
+## Advanced Usage
+
+For more advanced customizations see the [Advanced Usage](advanced.md) docs.
 
 [styled-components]: https://github.com/styled-components/styled-components
 [MDX]: https://github.com/mdx-js/mdx