From badfea9b60c59f4ab5af4185a0e311b4c1f6a693 Mon Sep 17 00:00:00 2001 From: Brent Jackson Date: Sun, 5 Aug 2018 13:00:52 -0400 Subject: [PATCH] Add advanced docs --- docs/advanced.md | 98 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/react.md | 4 +- docs/theming.md | 41 ++------------------ 3 files changed, 102 insertions(+), 41 deletions(-) create mode 100644 docs/advanced.md diff --git a/docs/advanced.md b/docs/advanced.md new file mode 100644 index 0000000..7b4b7b9 --- /dev/null +++ b/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/ diff --git a/docs/react.md b/docs/react.md index fe0263b..10f6b39 100644 --- a/docs/react.md +++ b/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 () => diff --git a/docs/theming.md b/docs/theming.md index ff93dea..1352cb2 100644 --- a/docs/theming.md +++ b/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