Guide · Open source
How to use mdx-deck: write React slides in Markdown
Updated · written with AI from the project's own documentation and checked against our catalogue data
mdx-deck is an open-source tool for making slide presentations by writing Markdown mixed with React components, a format called MDX. Each slide is content in a file, and the tool turns that file into a deck you present in a browser. This guide explains what it is, what you need before starting, how to get the source, and when a different tool is a better fit.
mdx-deckjxnblk/mdx-deck · ★ 11.5k · MIT Install options & downloads Quick start
- 1Check the prerequisites. Make sure Node.js is installed and that you are comfortable working in a Node.js project.
- 2Clone the repository. Run git clone https://github.com/jxnblk/mdx-deck in the folder where you want the project.
- 3Read the full README. Open the project homepage at mdx-deck.jxnblk.com to find the setup and run steps that are not in this excerpt.
- 4Write your first slides. Create an MDX file with Markdown content and add React components where a slide needs them.
- 5Open the deck in a browser. Follow the project's run instructions to view the deck and present it from the browser.
What is mdx-deck and who is it for?
mdx-deck is a React MDX-based presentation tool. You write slides as Markdown and can place React components inside them, so a slide can contain live components or code rather than only static text.
It suits developers who already write React and want to present technical material. It also suits teams that keep documentation in Markdown and want slides built from the same source.
- Good fit: developers who already write React
- Good fit: teams that want slides from existing Markdown docs
- Poor fit: people who want a visual drag-and-drop slide editor
- Poor fit: people who need a finished PowerPoint or Keynote file, since the output is a web presentation
What do you need before you install mdx-deck?
The listed prerequisite is Node.js. The project's README describes a JavaScript toolchain, so you should be comfortable setting up a Node.js project before you start. If that sounds like too much setup, a visual slide tool will be easier.
The project is released under the MIT licence and is written in JavaScript.
- Node.js installed on your machine
- Basic familiarity with React and Markdown
- A willingness to write code and MDX files
Get the mdx-deck source code
The README's install instruction starts by cloning the repository with git. Run the command below in the folder where you want the project to live.
The source you are working from is a README excerpt, so it does not show the remaining setup steps. For dependency installation and run commands, read the full README on the project homepage before you continue.
git clone https://github.com/jxnblk/mdx-deckWrite your slides in an MDX file
Each slide is written as content in a file. Because the format is Markdown mixed with React components, you can write normal prose and headings and add components where you need interactive or code-based content.
Keep each slide's content focused. Slides work best when they show one idea, and the React components are there for the parts that a static slide cannot show well.
- Write headings and text in Markdown as usual
- Add React components where a slide needs live or code content
- Keep one idea per slide
Present your deck in the browser
mdx-deck turns your file into a deck you present in a browser. Because the output is a web presentation, you present it from a browser window rather than from PowerPoint or Keynote.
Check the project homepage for the exact commands that start the deck and any options it supports, since those details are not in the excerpt this guide is based on.
- Output is a web presentation, not a PowerPoint or Keynote file
- Use the homepage documentation for run commands
How does mdx-deck compare with other slide tools?
Comparable projects include Spectacle, reveal.js and Slidev. All of them make web-based presentations, so the choice comes down to how you prefer to write slides and which features you need.
mdx-deck is a good choice if your slides should be React components and MDX. If you want a different authoring model or a different set of built-in features, compare the options before committing.
- Spectacle: another React-based option
- reveal.js: a widely known HTML presentation framework
- Slidev: another Markdown-based slide tool
What people use it for
- Presenting a technical talk on a React library with live component examples
- Turning existing project Markdown documentation into a slide deck
- Sharing a web-based deck that can be opened in a browser
Frequently asked questions
Is mdx-deck free to use?
Yes, mdx-deck is released under the MIT licence. That licence allows you to use the project, but check the licence text for the exact terms before you rely on it.
What do I need to install mdx-deck?
The listed prerequisite is Node.js. You also need git to clone the repository, as shown in the README's install instruction.
Can I make slides with mdx-deck without writing code?
No. mdx-deck requires writing code and MDX files, so it is not a visual slide editor. If you need a no-code tool, choose a different option.
Can mdx-deck export a PowerPoint file?
No. The output is a web presentation that you view in a browser. If you need a finished PowerPoint or Keynote file, mdx-deck is not the right tool.
What are the alternatives to mdx-deck?
Comparable projects named in our analysis are Spectacle, reveal.js and Slidev. Each makes web-based slides, so compare how each one handles authoring before you choose.
Where do I find the run commands if the README is cut short?
Our source is a truncated README excerpt. The project homepage at mdx-deck.jxnblk.com is the place to check for the full setup and run steps.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
mdx-deck suits developers who already write React and want slides that can include components or code, or teams that want slides built from Markdown docs. If you need a visual slide editor, a PowerPoint or Keynote file, or you do not want to set up a Node.js project, pick a different tool such as Slidev or reveal.js.
Install options & downloads