Web Slides Made Easy

MDX Presenter allows you to create slides easily with React and MDX.
With this tool, you can:

• Write your presentations in Markdown.
• Use React components, or even build your own.
• Create a consistent look and feel with Theme-UI.
• Present on any computer with a (modern) browser, by using the onepage build mode.
• Integrate it in any of your favourite web bundlers, static site generators, ...

Under the hood

NOTE
This is very much an entry level explanation. If you are a seasoned web developer, all you need to know is that this project consists of a few react packages to help you build your presentation, which you write using MDX.
This project also has a package with some plugins for transpiling MDXAST/MDXHAST and a basic template for getting started, which sets up a Webpack environment to develop and build your slide deck.

While it is not really necessary to understand all this in order to use MDXP, I believe that it is always helpful to understand how your code gets transformed into the end result you see.

At the very bottom of this tech stack sits React, which allows you to "build encapsulated components, then compose them to make complex UIs". Because doing this in plain old JavaScript is quite tedious and error-prone, they created their own file format JSX, which allows you to write with an HTML-like syntax inside of JavaScript.

Of course, you still need to transpile this JSX to valid JavaScript, in order for the browser to understand your code. This is where Babel comes into play. Babel is a JavaScript transpiler, which allows you to write next-generation JavaScript, with all the new features, and convert it to browser-compatible JavaScript code. Babel can also read JSX and transpile it to valid JavaScript, which is the main reason we use it.

You can now transpile a JSX file to browser-compatible JavaScript, but what if you want to split your code into multiple files and modules ? This is the task of a bundler, like Webpack. While bundlers used to only combine different JavaScript files into one minified file, which you could then include in your HTML page, they have since evolved and are now able to do much more! With Webpack, you can include any file format, as long as you provide a way to process those files to your end bundle. This allows us to import images and videos, and Webpack will process those files according to our pipeline. For videos, we just copy the file to the destination folder (in fact we do this for any file format that we do not know), but if images are small enough, we instead store them as raw data inside our javascript bundle, which means there is no need to copy the images along with your presentation. Feel free to look inside your webpack.config.js and webpack.onepage.js files, if you build your presentation with our template.

Finally, Webpack also allows us to setup a pipeline for processing MDX files. MDX is a file format which enhances markdown, by allowing you to import and use React components inside of it. This works, because the MDX transpiler transforms your MDX code into JSX, which is then transpiled into JavaScript with Babel. The cool thing about the MDX transpiler is that it is build with the Unified toolset. This allows us to extend the transpiler and add our own features to the MDX format.

How is this different from MDX-Deck

I started using MDX-Deck and immediately loved the concept of writing your presentations with MDX.
However, I found one big flaw with it and that is that it builds your presentation as a Gatsby website.

I have two reasons for disliking this:

1. When presenting at conferences, you are sometimes obliged to present on a given computer and thus it is not feasible to present with a local server on your computer. While you could host your presentation somewhere and just browse to it, that has the downside that you are at the mercy of internet speeds at the conference, which might be a serious issue if you have lots of images and/or videos. The best solution would be to have a single file, like a .ppt, that you can just open on any computer. MDXP allows to build your presentation in onepage mode, which means you end up with one index.html file (+ any videos or huge images), which you can open in any (modern) browser, without the need for a server.
2. The fact that it uses Gatsby adds a whole layer of complexity. Gatsby is not a small tool and learning to use it takes some time. This also means that the threshold for someone being able to contribute to the project becomes much higher. The core of MDXP is just a react library and thus it is easier to learn and contribute to this repository. If need be, you can still integrate MDXP into a Gatsby project, thus having the best of both worlds.

I would like to express my gratitude towards the MDX-Deck project and the team behind it!
I took a lot of inspiration and even some code from it, and would not have been able to build MDXP without it.

Contributing

This project is setup as a monorepo with lerna and yarn workspaces.
After installing yarn, you can clone this repository and run the following commands to set everything up and start developing:

yarn install
lerna bootstrap