To go along with the Embedded Systems Analysis material I've been developing, I wanted to have slide decks for each section. I originally started writing the material in markdown as a way to enforce more accessibility. Using something like PPT would betray that notion and so I began to look at other options...
There are two options for presentations that I was willing to entertain:
In summary, MDX is compiled with React and Remark into CJS and HTML that can be rendered by browsers.
From the demos that I browsed on the net, the following two libraries are the tools I decided to take a close look at:
Based on the amazing work done by Sam Larsen-Disney (sld.codes), I thought for sure whatever he did would be good enough for my needs. I hunted down the code for his website on github. Now, its Dec 2021 and the latest LTS node is v16. Turns out that a lot of the tools that are used these days just aren't ready for the current generation of node.
After a bunch of build issues with Sam's personal site code, I stepped back to build a
mdx-deck from scratch. There are several ways to accomplish this.
- You can create a
mdx-deckpresentation from scratch, as seen in Create developer presentations with MDX Deck - Part 1
- You can grab an old version of gatsby (~2.x) and install the
- You can grab an mdx-deck example from their examples repo and build in-place.
- You can also grab a gatsby starter (e.g. gatsby-stater-deck)
I'm sure in 2019, all of these options were great and worked flawlessly. But as mentioned before they have all fell out of maintenance over the past ~18 months and therefore don't work with moderns tools. I was able to get them working to a degree, but I was really upset with how out of date the documentation was and didn't have as much patience to reverse engineer behaviors.
I may have missed this feature from
mdx-deck, but MDXP has a presenter mode that allows a presenter to open a slide with a preview of the next slide and notes for the current slide. The way this presenter mode works is that if you have say, a chrome window with presenter mode and a chrome window with normal mode... when you switch slides on one, it automatically synchs the others. Therefore, you can full screen a Chrome window for audience viewing and keep a presenter tab available for your private presenter monitor.
MDXP also has seemed to falling out of maintenance, but this time only by ~14 months. I basically grabbed the demo code and was able to build it, albeit with a gazillion warnings.
OK, so I was able to successfully build both mdx-deck and MDXP and they both have their issues, but I decided to invest some time in MDXP because it seemed more recently maintained, documentation was more thorough and update to date. Also, the presentation mode really struck me as fancy.
Things that needed to be updated ASAP...
At the time of this writing, these are the packages that I updated:
@mdx-js/loader from ^1.5.9 to ^1.6
react-dev-utils from ^10.2.1 to ^11
webpack from ^4.44.2 to ^5
webpack-bundle-analyzer from ^3.9.0 to ^4
webpack-cli from ^3.3.12 to ^4
webpack-dev-server from ^3.11.0 to ^4
webpackbar from ^4.0.0 to ^5
This in turn lead me to removing the
@svgr/webpack and all references to SVGs in the presentations. I don't use SVGs often so this didn't phase me, but I would like to re-integrate SVG support eventually. The issue had to do with the way webpack saw some of the SVGs as being exported as default multiple times.
I also had to patch the webpack.config.js so that at line ~175:
was replaced with:
I also attempted to upgrade the remark packages, but there were way to many errors for me to deal with at this time. That'll likely be a part 2 to this effort if revisited.
Supporting Multiple Presentations
Unless you're using a gatsby integration, both the
mdx-deck project and the MDXP projects both create a single presentation per
node_modules folder (which we all know become ridiculous in size very quickly.)
In the multi-presentation design I used:
I created a top-level
decksfolder (outside of the
src) folder. Within, there are folders named for the deck files they hold, (e.g.
Of course, reusable react components and layouts are kept in the
distor output folder now also has folder named after the
decksfolder name. Within this folder you'll find outputs for
The way I selected a deck is through a cross-env environment variable that was then loaded by
webpack.config.js(similar to the way the original author passed their arguments).
Originally the way the builds were occurring in MDXP had a long string of commands being run as
package.json scripts. To better parameterize the
deck selection, I created a
build.js script that ran the same commands, but now with my
deck option and argument parsing with
yargs. This script could be written without the need for
spawn, but I'm really just trying to get a thing done, not attempting to maintain a library at the moment. Note:
build.js assumes you are using
Now when I build with, for example
yarn build:onepage --deck test-deck, it'll source my presentation from
./decks/test-deck/ and output the results into
For more details on the implementation specifics, feel free to browse the
mdxp multi-presentation code on github.
Wish List Items
- Pull requests for MDXP that include support for Node 16.
- Pull requests for MDXP that include multi-presentation support.
- Remote synchronization of presentation similar to sld-clicker.
- SVG support re-integrated.