0phoff / mdxp

Web Slides Made Easy

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, ...

Click here to view a demo built with MDXP or
Click here to take a look at the documentation.

Gettting started

The easiest and recommended way to get started with MDXP is to use our Webpack template. Webpack allows to bundle all your source files and combine them into an output, which you can display in the browser. First, you'll want to install it like so:

npm i -g @mdxp/create-webpack

You should then be able to run the commands below to start and run a presentation.

# Initialize presentation project
npm init @mdxp/webpack -g my_presentation
cd my_presentation

# Start dev server
npm run start

# Edit presentation with your favourite editor
vim src/presentation.mdx

# Build presentation
npm run build

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 expres 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

mdxp's Issues

Remove -g from ' npm init @mdxp/webpack -g my_presentation' in Readme.md

the Readme.md line
npm init @mdxp/webpack -g my_presentation
should have the -g removed, so my_presentation directory will be create under the current user and not root.

ERR_OSSL_EVP_UNSUPPORTED when using Node 17

´´´npm run start``` results in this error when using Node 17.9 (but also 17.0, so probably all Node 17 version), I had to switch to Node 16. Tested on an M1 Mac with macOS 12.3.1.

node:internal/crypto/hash:67
  this[kHandle] = new _Hash(algorithm, xofLen);
                  ^

Error: error:0308010C:digital envelope routines::unsupported
    at new Hash (node:internal/crypto/hash:67:19)
    at Object.createHash (node:crypto:130:10)
    at module.exports (/Users/wwb/Projekte/my_presentation/node_modules/webpack/lib/util/createHash.js:135:53)
    at NormalModule._initBuildHash (/Users/wwb/Projekte/my_presentation/node_modules/webpack/lib/NormalModule.js:417:16)
    at handleParseError (/Users/wwb/Projekte/my_presentation/node_modules/webpack/lib/NormalModule.js:471:10)
    at /Users/wwb/Projekte/my_presentation/node_modules/webpack/lib/NormalModule.js:503:5
    at /Users/wwb/Projekte/my_presentation/node_modules/webpack/lib/NormalModule.js:358:12
    at /Users/wwb/Projekte/my_presentation/node_modules/loader-runner/lib/LoaderRunner.js:373:3
    at iterateNormalLoaders (/Users/wwb/Projekte/my_presentation/node_modules/loader-runner/lib/LoaderRunner.js:214:10)
    at Array.<anonymous> (/Users/wwb/Projekte/my_presentation/node_modules/loader-runner/lib/LoaderRunner.js:205:4) {
  opensslErrorStack: [ 'error:03000086:digital envelope routines::initialization error' ],
  library: 'digital envelope routines',
  reason: 'unsupported',
  code: 'ERR_OSSL_EVP_UNSUPPORTED'
}

Code syntax highlighting

Looks like syntax-highlighting isn't supported. In my presentation.mdx file I added the ```ts and the code block isn't highlighted with TypesScript syntax highlighting. I tried other languages as well.

Should I submit a PR? or should I fork?

@0phoff said over 20 months ago:

I don't have a lot of time to work on MDXP right now, but once I do, I will probably go through the entire codebase and try to update each of the packages to their newest versions.

Originally posted by @0phoff in #5 (comment)

After 20 months, I wonder if anything will move?

I want to repair a few of those issues for the courses I do. I want to publish a few slide decks for React Academy (https://www.reactacademy.live/live). So I'll be doing a major PR.

Here's I what I want to do:

• Update to the latest version of MDX and React.
• Make it run under Vite.
• Make it compatible with Prism

Anything else?

Install error "create-webpack: command not found"

Looks excellent, but I can't even install the starter project (macOS 11.2.3, M1 MacBook Pro), since I'm getting an "sh: create-webpack: command not found" error. The whole log is below. I tried both npx @mdxp/create-webpack -g my_presentation and npm init @mdxp/webpack -g my_presentation.

0 verbose cli [
0 verbose cli '/usr/local/bin/node',
0 verbose cli '/usr/local/bin/npm',
0 verbose cli 'init',
0 verbose cli '@mdxp/webpack',
0 verbose cli '-g',
0 verbose cli 'my_presentation'
0 verbose cli ]
1 info using [email protected]
2 info using [email protected]
3 timing config:load:defaults Completed in 1ms
4 timing config:load:file:/usr/local/lib/node_modules/npm/npmrc Completed in 1ms
5 timing config:load:builtin Completed in 1ms
6 timing config:load:cli Completed in 2ms
7 timing config:load:env Completed in 0ms
8 timing config:load:file:/Users/wwb/Projekte/.npmrc Completed in 0ms
9 timing config:load:project Completed in 1ms
10 timing config:load:file:/Users/wwb/.npmrc Completed in 0ms
11 timing config:load:user Completed in 0ms
12 timing config:load:file:/usr/local/etc/npmrc Completed in 0ms
13 timing config:load:global Completed in 0ms
14 timing config:load:cafile Completed in 0ms
15 timing config:load:validate Completed in 0ms
16 timing config:load:setUserAgent Completed in 0ms
17 timing config:load:setEnvs Completed in 1ms
18 timing config:load Completed in 6ms
19 verbose npm-session 4230e4fb0393ad0e
20 timing npm:load Completed in 13ms
21 http fetch GET 200 https://registry.npmjs.org/@mdxp%2fcreate-webpack 12ms (from cache)
22 timing arborist:ctor Completed in 1ms
23 timing arborist:ctor Completed in 0ms
24 timing command:exec Completed in 103ms
25 timing command:init Completed in 130ms
26 verbose stack Error: command failed
26 verbose stack at ChildProcess. (/usr/local/lib/node_modules/npm/node_modules/@npmcli/promise-spawn/index.js:64:27)
26 verbose stack at ChildProcess.emit (node:events:379:20)
26 verbose stack at maybeClose (node:internal/child_process:1065:16)
26 verbose stack at Process.ChildProcess._handle.onexit (node:internal/child_process:296:5)
27 verbose cwd /Users/wwb/Projekte
28 verbose Darwin 20.3.0
29 verbose argv "/usr/local/bin/node" "/usr/local/bin/npm" "init" "@mdxp/webpack" "-g" "my_presentation"
30 verbose node v15.6.0
31 verbose npm v7.4.0
32 error code 127
33 error path /Users/wwb/Projekte
34 error command failed
35 error command sh -c create-webpack "my_presentation"
36 verbose exit 127

Switch from Webpack to Turbopack or Vite

What do you think about using Turbopack or Vite instead of Webpack?

Maybe Webpack is not the fastest, something that is possible to change with Turbopack or Vite in the future. Turbopack is currently in alpha and not yet ready for production use, but do you consider a change?

If the proposal does not sound good and you don't want to switch Webpack with Turbopack or Vite, maybe consider using SWC instead of Babel for the webpack loader.

Hey! This looks pretty sweet!

I was searching for something that wasn't MDX Deck and found this!

Looks like you have done a great job here than you so much, I was just trying to get my head around if I could import MDX Embed into this, I'm guessing I have to do it on a slide by slide basis?

Like with the wrapper components?

Feature Request: Use of external template

Noticed the package used to bootstrap a new project has a default template. Would love to be able to create a new presentation based on a template hosted somewhere or from another mom package

Support React 17 as a peer dependency

Hello !
I can't install mdxp in my app that uses React 17 (unless I install --force).

Would it be possible to add React 17 in the list of supported versions for React as a peer dependency ?

I know this isn't a common use case, but MDXP is the only react presentation library that I can use somewhat easily inside another app (and with MDX). And since React 17 has very few breaking changes, this shouldn't be too risky.