jxnblk/mdx-deck

♠️ React MDX-based presentation decks

MDX Deck

Award-winning React MDX-based presentation decks

• 📝 Write presentations in markdown
• ⚛️ Import and use React components
• 💅 Customizable themes and components
• 0️⃣ Zero-config CLI
• 💁‍♀️ Presenter mode
• 📓 Speaker notes

View demo

• Getting Started
• Using MDX
• Theming
• Components
• Layouts
• Presenter Mode
• Keyboard Shortcuts
• CLI Options
• Videos & Articles
• Examples

Getting Started

npm i -D mdx-deck

Create an MDX file and separate each slide with ---.

# Hello

---

## This is my deck

---

## The End

Add a run script to your package.json with the MDX Deck CLI pointing to the .mdx file to start the development server:

"scripts": {
  "start": "mdx-deck deck.mdx"
}

Start the development server:

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.

Imports

To import components, use ES import syntax separated with empty lines between any markdown or JSX syntax.

import { Box } from 'theme-ui'

<Box color="tomato">Hello</Box>

Read more about MDX syntax in the MDX Docs.

Theming

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
• Read more about theming in the Theming docs.

Components

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.

Third-Party Components

These optional libraries are intended for use with MDX Deck.

• CodeSurfer: React component for scrolling, zooming and highlighting code.
• mdx-code: Runnable code playgrounds for MDX Deck.
• mdx-deck-live-code: Live React and JS coding in slides.

Note: please check with version compatibility when using these libraries.

Layouts

Each slide can include a custom layout around its content, which can be used as a template for visually differentiating slides.

// example Layout.js
import React from 'react'

export default ({ children }) => (
  <div
    style={{
      width: '100vw',
      height: '100vh',
      backgroundColor: 'tomato',
    }}>
    {children}
  </div>
)

import Layout from './Layout'

# No Layout

---

<Layout>

# Custom Layout

</Layout>

The layout component will wrap the MDX elements within that slide, which means you can add custom layout styles or style child elements with CSS-in-JS.

Presenter Mode

Press Option + P to toggle Presenter Mode, which will show a preview of the next slide, a timer, and speaker notes.

The presentation can be opened in two separate windows at the same time, and it will stay in sync with the other window.

Keyboard Shortcuts

Key	Description
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
Option + O	Toggle Overview Mode
Option + G	Toggle Grid Mode

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

• Egghead Tutorial by Andrew Del Prete.
• mdx-deck: slide decks powered by markdown and react by Kent C. Dodds
• Make Fast & Beautiful Presentations with MDX-Deck by Harry Wolff (Demo)
• What is MDX by Kent C. Dodds
• Build a Custom Provider Component for MDX-Deck by Kyle Shevlin

Examples

See how others have used MDX Deck for their presentations.

• Design Systems & React by Diana Mounter
• Bringing Brazil to the Cloud, Now by Guillermo Rauch
• Simplify React by Kent C. Dodds
• I Got 99 Problems but GraphQL Ain't One by Sara Vieira
• Stop de #divFest by Sara Vieira
• MDX, authors and richer JAMstack content by Josh Dzielak
• Components as Data: A Cross Platform GraphQL Powered Component API by Luke Herrington
• A short history of webdevs future 🔮 by Hendrik Wallbaum

Usage Examples

The following examples will open in CodeSandbox.

• Basic Example
• Syntax Highlighting
• Steps
• Head
• Header & Footer

---

Related

• MDX
• Gatsby
• Theme UI
• Emotion
• Spectacle

MIT License

mdx-deck's Issues

My content is not slidered

Hi,

I separated my content by "---" markdown but i have only 1 slide ( slide.png )

Use Presentation API

https://developer.mozilla.org/en-US/docs/Web/API/Presentation_API

Code zooming transitions

Hi! This repo is great, and I'm incredibly looking forward to use it for my next presentation! 😄

The thing is, I want to achieve the effect I saw in this talk where you are actually showing code, but zooming in some parts and just scrolling from top to bottom. Is there any easy (or maybe built-in) option that I don't know of to do this? I know some people use Spectacle.js for that but I think this is way easier! 😊

Thanks in advance and keep up the good work! 😎

---

EDIT: Added gif for reference 😉 (thanks @trevordmiller)

Disable swipe on desktop

If I'm selecting text during my talk, mdx-deck interprets that as a swipe and goes forward to the next slide:

serving/building static content

🤚,

Wanted to show an image in my presentation. So I put it near the .mdx file and addressed in the presentation as ![](flow.png), which was resolved into <img class="sc-kpOJdX eTwYLo" src="./flow.png">.

All good, but the image was not served via dev server.
Neither the image was added to the dist folder during the build.

I think all the files relative to the .mdx file which is being built/served - should be available via http://.

Regards,

Page Numbers

An option to display the page numbers.

Styles for ul/ol components appear to not be working

Modes

It would be great to have separate modes for presenting, editing, etc. This is a placeholder for discussing what that could look like

Syntax Highlighting

Just tried out the new syntax highlighting feature, but got an error:

Warning: React.createElement: type is invalid -- expected a string (for built-in components) or a class/function (for composite components) but got: object.

Check the render method of `MDXTag`.

What I'm doing wrong?

import { future } from 'mdx-deck/themes'
import okaidia from 'react-syntax-highlighter/styles/prism/okaidia'
import prismRuby from 'react-syntax-highlighter/languages/prism/ruby'

export default {
  ...future,
  prism: {
    style: okaidia,
    languages: {
      ruby: prismRuby
    }
  }
}

# Title Slide

---

```ruby
def index
  @posts = Post.all
end
```

---

## Another slide

- feature 1
- feature 2
- feature 3

Left column overview mode

Add a mode (or replace current overview mode) with a layout with all slides listed vertically in a left column and the current slide to the right. This should mimic other presentation apps like Keynote and Google Slides

Spectacle API

Make MDX components export for use in Spectacle

Automatic og/twitter card

With the addition of the screenshot command, it would be great to automatically add twitter card meta tags for the presentation. Since twitter:image requires a full URL, the domain name where the presentation is hosted would need to be configured somehow

Add support for og meta tags

Would be rad to be able to add og metadata for sharing on twitter and such!

PDF export

• Print styles
• CLI integration with Puppeteer

Last slide behavior

Currently, once you reach the last slide and push next, the presentation goes to the very first slide.

Maybe it makes more sense to loop endlessly (so when you are on the first slide, you can quickly go back to the last by pushing left).

What do you think?

custom webpack configurations.

Currently, cli.js contains setup for webpack.
If someone want to add extra remark mdPlugins or webpack loaders, user may need to modify cli.js manually.

Do you consider to consider options to allow users add extra mdPlugins or webpack loaders?

Show all Appear steps in presentation mode next slide preview

The next slide preview should show all steps revealed to be useful.

Module missing

Below error will report if babel-core not installed.

$ npm start

> @ start /Users/ppt
> mdx-deck deck.mdx

[mdx-deck] starting dev server
✖ ｢wdm｣:
ERROR in ./node_modules/[email protected]@mdx-deck/dist/entry.js
Module build failed (from ./node_modules/[email protected]@babel-loader/lib/index.js):
Error: Cannot find module 'babel-core'
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:581:15)
    at Function.Module._load (internal/modules/cjs/loader.js:507:25)
    at Module.require (internal/modules/cjs/loader.js:637:17)
    at require (internal/modules/cjs/helpers.js:20:18)
    at Object.<anonymous> (/Users/geekplux/project/ppt/node_modules/[email protected]@babel-loader/lib/index.js:3:13)
    at Module._compile (internal/modules/cjs/loader.js:689:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:700:10)
    at Module.load (internal/modules/cjs/loader.js:599:32)
    at tryModuleLoad (internal/modules/cjs/loader.js:538:12)
    at Function.Module._load (internal/modules/cjs/loader.js:530:3)
 @ multi ./node_modules/[email protected]@mdx-deck/dist/entry.js ./node_modules/[email protected]@mdx-deck/lib/overlay.js main[0]

looks like should add babel-core into devDependencies. 🌞

Speaker notes component

Enable to step through fragments inside a slide

Would be interesting to uncover blocks inside a slide.
f.e. bullet points or parts of a code?
If interesting, I have time this week and could try to add this feature.
Maybe without animations at first, just uncovering fragment for fragment.
What would the markup look like to declare blocks as fragments?

Just an example

---

4 reasons to use Reason

-o Based on OCaml
-o Types
-o Community
-o Interop

---

Should links always open in new tabs?

There is a remark plug-in, but I have no idea how to add it to this project, & may be a bit too much code just to add a few letters a an <a> link. & I'm not excited about the nofollow & noreferrer defaults; AFAIK few do not want free SEO & stats details.

Syntax highlighting

• React component
• Markdown code fences
• Should be themeable
• Include JSX language by default
• Add docs

Move default Dots to a default Provider component

When setting a custom provider, users will need to add their own progress indicators

Enable Auto-Transition

Add a settings option to define auto-transitions.
The autoTransition constant needs to define the transition time in seconds, i.e.

// index.mdx

export const autoTransition = 5

Also see comment by @tomByrer in #75

Video component

For videos etc.

Feature request: code block step through

First, thanks so much for such a great tool! It’s been very helpful :)

Second, would it be possible / desired to have a code revealing walkthrough option? Like this:

From https://github.com/jamiebuilds/spectacle-code-slide

I personally think this is very useful for digesting code snippets. For example, a talk at React Rally this past week that used this:
https://github.com/joshwcomeau/explorable-explanations-with-react

Add built-in layout components

Layout components can be used to change the look of a single slide, similar to templates in other presentation apps. Some built-in layouts could work with the current theme to invert colors and make other small style adjustments.

Example:

export { yellow as theme } from 'mdx-deck/themes'

# Normal Slide

---
export { Invert as default } from 'mdx-deck/layouts'

# Slide with Layout

Default styles for markdown tables

addEventListener dont work

When there is an anchor tag on the slide and it is focused, the right and left key events no longer work.

Can you check: https://github-ds.now.sh/#28 (click on link and try move to other slide pressing right or left key).

I use this browser:

Changing slide animation

Hey, love this project! Is there a way to change the slide animation, ideally through some configuration like export { fade as animation } from 'mdx-deck/animations? If not I'd like to look into working on that, if I could have a few pointers 🤓

Actual React Component Example

To highlight the power of mdx-deck, it might be good to add an actual interactive React Component to the slides. Just to show that you can run actual code inside these slides. We could even go meta and wrap this component with a provider and update the actual presentation state (f.e. toggle between presenter and non-presenter mode or jump to a specific index etc.)

Serving static export from sub-folder

I've exported and deployed index.html and main.js to a sub-folder via FTP. Since it's not served from a sub-domain, once you go back and forth it removes the URL path and appends the #slide_no to the main domain.

Is there any setting for the base URL?

PS: Thank you for this great tool!

Add support for custom `components` and `Provider` to themes

Instead of separate exports, custom components and Provider could be added to a theme – this makes themes a little more powerful and hopefully simplifies the API a bit.

// example
import { theme } from 'mdx-deck/themes'
import Provider from './Provider'
import Heading from './Heading'

const theme = {
  ...theme,
  font: 'Georgia, serif',
  Provider,
  components: {
    h1: Heading
  }
}

Add grid/overview mode

Add a mode that shows all slides as a grid for writing presentations

Clean up URL params and store `overview` mode in URL

Update state on URL change

Currently back button does not work

Custom theme not working?

Trying to make a custom theme, but it's not working, but without a clear error message, so I'm not sure what I'm doing...

import { theme } from 'mdx-deck/themes'

export default {
  ...theme,
  font: 'Roboto, sans-serif',
  colors: {
    text: 'black',
    background: 'white',
    link: 'black',
  },
  css: {
    fontSize: 'calc(16px + 6 * ((100vw - 320px) / 680))',
    textAlign: 'left'
  }
}

# Yo!

This is my first mdx-deck slide.

---

# Hey!

This is my second.

---

and I get a blank page with some vague (at least to me) error messages in the console:

sooooooo...don't know what I'm doing wrong here, so any help would be appreciated :-)

Detect mode when registering notes

Open new window button in presenter mode

In presenter mode, there should be a button that opens a new window (that's not in presenter mode) that can be used to display the audience.

Markdown tables do not properly render

Due to https://github.com/jxnblk/mdx-deck/blob/master/lib/loader.js#L14

Suggestion: Use first slides's <h1> as HTML's <title>

We programmers are lazy; DRY, don't RTFM, & stuff.

Open to using the entire first slide's text as <title>, with CLI --title as overried.

Make Appear work with left/right keys

To simplify things, stepping through the steps inside an Appear component should happen via left/right arrows, just like stepping through regular slides.

Countdown timer in presentation mode

Enable to countdown the time when running in presentation mode.
Depending on the mode, a presenter can either define a presentation time and countdown the time from there or simply use the normal timer, to see the elapsed time.

Add contributing.md

HTML Document format

Right now the static output is semi-valid html document.

<!DOCTYPE html>
<meta name='viewport' content='width=device-width,initial-scale=1'>
<style>*{box-sizing:border-box}body{font-family:system-ui,sans-serif;margin:0}</style>
<title>mdx-deck</title>
<div id=root></div>
<script src="main.js"></script>

This doesn't hints the browser about the encoding, which renders weird symbols.

I'd like to achieve something more like:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <title>mdx-deck</title>
  <style>*{box-sizing:border-box}body{font-family:system-ui,sans-serif;margin:0}</style>
</head>
<body>
    <div id=root></div>
    <script src="main.js"></script>
</body>
</html>

I see this comes from https://github.com/jxnblk/ok-mdx/blob/master/packages/ok-cli/lib/index.js#L55-L65

What's the idea behind skipping <html>, <head> and <body>.

Should I open PR over ok-mdx with improvements for the template?

Prevent tabs from changing the slide

If you go to this deck and just lay on the tab key, you'll see it focuses the next element which advances the slideshow. I'd prefer the current slide to capture the tab and loop it back as if the current slide is all that's on the page.

Appear: Missing Props

Hi there – just started with mdx-deck.
It's awesome, thanks!

But having some issues with using Appear.
As soon as use the component the following errors occur and the app breaks.

Warning: Failed prop type: The prop `slide` is marked as required in `Appear`, but its value is `null`.

Warning: Failed prop type: The prop `deck` is marked as required in `Appear`, but its value is `null`.

Haven't found any hint in the docs.

---

env
npm: 6.2.0
node: 10.9.0
@mdx-js/mdx: 0.15.0
mdx-deck: 1.6.4

Mobile layout & touchscreen UI

• Swipe support #91
• Previous/Next buttons #69
• viewport-fit=cover
• Prevent vertical scroll
• Touchscreen controls for mode/slide/etc
• Adjust font sizes/zoom for mobile

Internal Links

Not sure if this an issue. But how would internal linking between slides function?
An initial try via [Go to](#3) or [Go to](/#3) would open the slide in a new tab, not navigate to the selected slide. Is there a different way to navigate between slides?

Hook Appear component into state/routing

Related to #34