mirror of
https://github.com/jxnblk/mdx-deck.git
synced 2024-09-11 06:35:24 +03:00
Edit docs
This commit is contained in:
parent
8b819765c6
commit
d2e4d46c0b
@ -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
59
docs/api.md
@ -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
|
||||
```
|
||||
|
@ -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.
|
||||
|
||||
|
@ -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'
|
||||
```
|
||||
|
||||
|
@ -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
|
||||
|
@ -19,3 +19,5 @@ export const wrapPageElement = ({ element, props }) =>
|
||||
</Page>
|
||||
|
||||
export { useDeck } from './context'
|
||||
export { useSteps } from './use-steps'
|
||||
export * from './components'
|
||||
|
@ -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.
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user