jxnblk/mdx-deck
1
1
Fork 0
mirror of https://github.com/jxnblk/mdx-deck.git synced 2024-09-11 06:35:24 +03:00
Code Issues Projects Releases Wiki Activity

Edit docs

Browse Source
This commit is contained in:
Brent Jackson 2020-01-25 17:40:18 -05:00
parent 8b819765c6
commit d2e4d46c0b
7 changed files with 63 additions and 163 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
docs/advanced.md
View File

@ -1,36 +0,0 @@
# Advanced Usage
## Custom Provider component
A custom Provider component is useful for adding custom context providers in React or adding persistent UI elements to the entire deck.
To define a custom Provider component, you'll need to import it and add it as the `Provider` key in your theme.
```js
// example theme.js
import Provider from './Provider'
export default {
fonts: {
body: 'Georgia, serif',
},
Provider,
}
```
Use the `useDeck` hook to get the presentation state in your custom `Provider` component.
```js
// example Provider.js
import React from 'react'
import { useDeck } from 'mdx-deck'
export default props => {
const state = useDeck()
return (
<div>
{props.children}
</div>
)
}
```

59
docs/api.md
View File

@ -1,30 +1,13 @@
# API
The core `mdx-deck` package is a wrapper around the Gatsby CLI with the `gatsby-theme-mdx-deck` package.
## Components
- `Head`: Adds elements to the document `<head>`
- `Notes`: Adds speaker notes to a slide
- `Appear`: Steps through child elements one-by-one
- `Embed`: Embed MDX Deck slides in other React applications
- `Steps`: Steps through child elements one-by-one
See [Components](components.md) for more info.
## Layouts
- `Image`: A fullscreen background image layout component
- `Invert`: Inverts the foreground and background colors of the slide
- `Split`: Renders the first element on the left and other elements to the right
- `SplitRight`: Renders the first element on the right and other elements to the left
- `Horizontal`: Renders all child elements side-by-side
- `FullScreenCode`: Renders a single child code block fullscreen
See [Layouts](layouts.md) for more info.
## Hooks
### `useSteps`
## `useSteps`
The `useSteps` hook can be used to register custom components that rely on multiple "steps" within a single slide,
similar to the Appear component.
@ -49,41 +32,5 @@ export default props => {
## `useDeck`
The `useDeck` hook returns the MDX Deck state, including:
The `useDeck` hook returns the MDX Deck state.
- `setState`
- `mode`
- `index`
- `length`
- `step`
- `metadata`
- `steps`
- `notes`
- `slug`
```jsx
// example
import React from 'react'
import { useDeck } from 'mdx-deck'
export default props => {
const state = useDeck()
return (
<div>
{props.children}
<div>
Slide {state.index + 1}/{state.length}
</div>
</div>
)
}
```
## CLI Options
```
-p --port Dev server port
-h --host Host the dev server listens to
--no-open Prevent from opening in default browser
```

2
docs/gatsby.md
View File

@ -1,7 +1,7 @@
# Usage with Gatsby
The core MDX Deck application is built as a Gatsby theme.
MDX Deck includes a Gatsby theme, which can be used in any existing Gatsby site.
This means you can install MDX Deck as a theme within an existing Gatsby site to include presentations along with other content, such as a landing page or blog.
The theme also supports adding multiple presentations to a single site.

9
docs/themes.md
View File

@ -106,12 +106,3 @@ Poppins
import { poppins } from 'mdx-deck/themes'
```
---
Syntax Highlighting
```js
import { highlight } from 'mdx-deck/themes'
import { prism } from 'mdx-deck/themes'
```

25
docs/theming.md
View File

@ -48,21 +48,7 @@ export default {
## Composing Themes
Multiple themes can be composed together,
allowing you to create separate themes for typography, color, and components, and mix and match them as needed.
To compose multiple themes together, export a `themes` array instead of a single theme.
```mdx
import { syntaxHighlighter } from 'mdx-deck/themes'
import customTheme from './theme'
export const themes = [syntaxHighlighter, customTheme]
# Cool. :sunglasses:
```
Note that themes are deeply merged together and the last theme specified will override fields from themes before it.
To compose multiple themes together, merge the objects together into a single theme and export that theme from your deck.
## Google Fonts
@ -77,9 +63,11 @@ Themes can provide a set of custom MDX components, including a replacement for t
MDX Deck includes two themes for adding syntax highlighting with [react-syntax-highlighter][]: `highlight` and `prism`.
```mdx
import { prism } from 'mdx-deck/themes'
import { themes } from 'mdx-deck'
export const themes = [ prism ]
export const theme = {
...themes.prism
}
```
Since MDX supports using React components inline, you can also import a syntax highlighting component directly, if you prefer.
@ -122,8 +110,9 @@ export default {
- `fonts.monospace`: font family for `<pre>` and `<code>`
- `text.heading`: styles for all headings
- `styles.Slide`: styles for the wrapping Slide component
- `styles.Header`: styles for the Header component
- `styles.Footer`: styles for the Footer component
- `components`: object of MDX components
- `Provider`: component for wrapping the entire presentation
- `googleFont`: Stylesheet URL for adding a Google Font
[emotion]: https://emotion.sh

2
packages/gatsby-plugin/src/index.js
View File

@ -19,3 +19,5 @@ export const wrapPageElement = ({ element, props }) =>
</Page>
export { useDeck } from './context'
export { useSteps } from './use-steps'
export * from './components'

93
packages/mdx-deck/README.md
View File

@ -20,10 +20,20 @@ Award-winning React [MDX][]-based presentation decks
- :zero: Zero-config CLI
- :tipping_hand_woman: [Presenter mode](#presenter-mode)
- :notebook: [Speaker notes](#speaker-notes)
- :fire: Available as a Gatsby theme
[View demo](https://mdx-deck.jxnblk.com)
- [Getting Started](#getting-started)
- [Using MDX](#using-mdx)
- [Theming](#theming)
- [Components](#components)
- [Layouts](#layouts)
- [Presenter Mode](#presenter-mode)
- [Keyboard Shortcuts](#keyboard-shortcuts)
- [CLI Options](#cli-options)
- [Videos & Articles](#videos-articles)
- [Examples](#examples)
## Getting Started
```sh
@ -33,29 +43,21 @@ npm i -D mdx-deck
Create an [MDX][] file and separate each slide with `---`.
````mdx
# This is the title of my deck
# Hello
---
# About Me
## This is my deck
---
```jsx
<CodeSnippet />
```
## The End
---
import Demo from './components/Demo'
## <Demo />
# The end
````
Add a run script to your `package.json` with the MDX Deck CLI
pointing to the `.mdx` file to start the dev server:
pointing to the `.mdx` file to start the development server:
```json
"scripts": {
@ -63,12 +65,14 @@ pointing to the `.mdx` file to start the dev server:
}
```
Start the dev server:
Start the development server:
```sh
npm start
```
Use the left and right arrow keys to navigate through the presentation.
## Using MDX
MDX uses Markdown syntax and can render React components inline with JSX.
@ -78,7 +82,7 @@ MDX uses Markdown syntax and can render React components inline with JSX.
To import components, use ES import syntax separated with empty lines between any markdown or JSX syntax.
```mdx
import { Box } from 'rebass'
import { Box } from 'theme-ui'
<Box color="tomato">Hello</Box>
```
@ -95,15 +99,21 @@ Read more about MDX syntax in the [MDX Docs][mdx].
MDX Deck uses [Theme UI][] and [Emotion][] for styling, making practically any part of the presentation themeable.
It also includes several built-in themes to change the look and feel of the presentation.
See the list of available [Themes](docs/themes.md),
or read more about theming in the [Theming](docs/theming.md) docs.
- See the list of available [Themes](docs/themes.md)
- Read more about theming in the [Theming docs](docs/theming.md).
## Components
MDX Deck includes built-in components to help with creating presentations, including a background `Image` component, an `Appear` component that allows stepping through parts of a single slide, and a `Notes` component for adding speaker notes.
MDX Deck includes built-in components to help with creating presentations,
a `Notes` component for adding speaker notes,
a `Head` component for the document head,
`Header` and `Footer` components for persistent header and footer content,
and a `Steps` component for adding multiple intermediate steps in a single slide.
Read more in the [Components](docs/components.md) docs.
## Third-Party Components
### Third-Party Components
These optional libraries are intended for use with MDX Deck.
@ -153,29 +163,37 @@ import Layout from './Layout'
```
The layout component will wrap the MDX elements within that slide,
which means you can add layout styles, use a nested ThemeProvider, or style elements with CSS-in-JS.
## Built-in Layouts
MDX Deck includes a few [built-in layouts](docs/layouts.md) for inverting theme colors and changing the layout of a slide.
which means you can add custom layout styles
or style child elements with CSS-in-JS.
## Presenter Mode
Use [_Presenter Mode_](docs/presenting.md) when on stage to show a preview of the next slide, a timer, and speaker notes.
Press `Option + P` to toggle *Presenter Mode*,
which will show a preview of the next slide, a timer, and speaker notes.
![presenter mode screenshot](docs/images/presenter-mode.png)
The presentation can be opened in two separate windows at the same time and will stay in sync with each other.
## Keyboard Shortcuts
| Key | Description |
| ----------- | -------------------------------------------- |
| Left Arrow, Page Up, Shift + Space | Go to previous slide (or step in [Appear][]) |
| Right Arrow, Page Down, Space | Go to next slide (or step in [Appear][]) |
| Left Arrow, Page Up, Shift + Space | Go to previous slide (or step in [Steps][]) |
| Right Arrow, Page Down, Space | Go to next slide (or step in [Steps][]) |
| Option + P | Toggle [Presenter Mode](#presenter-mode) |
| Option + O | Toggle [Overview Mode](#overview-mode) |
| Option + O | Toggle Overview Mode
| Option + G | Toggle Grid Mode
[appear]: docs/components.md#appear
[steps]: docs/components.md#steps
## CLI Options
```
-p --port Dev server port
-h --host Host the dev server listens to
--no-open Prevent from opening in default browser
```
## Videos & Articles
@ -195,19 +213,8 @@ Use [_Presenter Mode_](docs/presenting.md) when on stage to show a preview of th
[ks-egghead]: https://egghead.io/lessons/javascript-build-a-custom-provider-component-for-mdx-deck
[kyle shevlin]: https://twitter.com/kyleshevlin
## Docs
- [Theming](docs/theming.md)
- [Built-in Themes](docs/themes.md)
- [Layouts](docs/layouts.md)
- [Components](docs/components.md)
- [Presenting](docs/presenting.md)
- [Exporting](docs/exporting.md)
- [Usage with Gatsby](docs/gatsby.md)
- [Advanced Usage](docs/advanced.md)
- [API](docs/api.md)
## Real-World Examples
## Examples
See how others have used MDX Deck for their presentations.
@ -219,7 +226,7 @@ See how others have used MDX Deck for their presentations.
- [MDX, authors and richer JAMstack content][mdx-talk] by [Josh Dzielak](https://mobile.twitter.com/dzello)
- [Components as Data: A Cross Platform GraphQL Powered Component API][components-as-data] by [Luke Herrington](https://mobile.twitter.com/lukeherrington)
## Usage Examples
### Usage Examples
The following examples will open in CodeSandbox.