Getting Started

Before getting started, make sure you have Node and NPM installed.

TLDR

# 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, the browser will automatically refresh when you save
vim src/presentation.mdx
# Build presentation once you're happy with the end result
npm run build

Recommended

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. You can read more about how everything works here.
To use it, just run the following command:

# NPM >= 6.1.0
npm init @mdxp/webpack -g my_presentation
cd my_presentation
# NPM >= 5.2.0
npx @mdxp/create-webpack -g my_presentation
cd my_presentation

NOTE
The -g flag enables the initialisation of a git repository. Remove that flag if you do not want a repository.

This command will create a project with your chosen name. The project will contain a src directory for your source files and a dist directory where the resulting build will go. The src directory already contains a presentation.mdx file, which you can edit to start writing your presentation right away. Of course, nothing stops your from also modifying the index.html or index.jsx files to your liking.

The project also comes with a few commands to create your presentation:

• npm run start
  This sets up a development server which will rebuild your presentation whenever you make changes.
• npm run build:web
  This will create a build from your presentation, which is optimised for serving online. The resulting build can be found in dist/web.
• npm run build:onepage
  This will create a build which is optimised for presenting. Most data will be consolidated into a single index.html, with only large images, videos or other data files added separately. You can find this build in the dist/onepage folder and should be able to run your presentation in any (modern) browser by just opening the index.html file.
• npm run build:pdf
  This will create a pdf from your presentation, which you can find in dist/presentation.pdf. Note that you first need to run npm run build:onepage, as the pdf is generated from this build.
• npm run build
  This command creates both web, onepage and pdf versions of your presentation with a single command.
• npm run clean:web, npm run clean:onepage, npm run clean:pdf and npm run clean
  These commands clean up the various files of the different build commands.
• npm run analyze:web
  This will analyze the javascript bundle file of your web bundle with webpack-bundle-analyzer. Note that you first need to run npm run build:web to generate the bundle and statistics file.

If you need to modify or extend the Webpack build pipeline, you can do so by editing the webpack.config.js file.

Manual

At the end of the day, MDXP is just a react library, so you can get it working with any bundler of your liking. While we do recommend to use our Webpack template, some people might prefer to setup their own build pipeline. A complete and thorough guide on how to create your own build pipeline is nigh impossible, but here are some guidelines on what you need to get working:

• Include react, react-dom, theme-ui and @mdxp/core packages. You will probably also want the @mdxp/components package.
• Process JSX into JavaScript (technically not necessary, but who writes React in pure JavaScript?).
• Transform MDX into JavaScript. This is necessary as you will write your presentation in that format. Optionally, you can add the plugins from @mdxp/rehypex-plugins or others to enhance your markdown syntax.
• Handle assets (eg. images) somehow. You can place them into a separate folder or have your bundler process them.
• You need to insert a Deck component from @mdxp/core, which contains your presentation. Below is a minimal example, written as JSX.

// Note that the main index.html includes this file and has a div with an ID of 'root'
// If you do not want @mdxp/components, you can remove the import and the 'components' property from <Deck />
import React from 'react';
import ReactDOM from 'react-dom';
import Deck from '@mdxp/core';
import components from '@mdxp/components';
import MDXPresentation from './presentation.mdx';
ReactDOM.render(
  <Deck components={components}>
    <MDXPresentation />
  </Deck>,
  document.getElementById('root')
);

NOTE
Note that all examples and guides on this website assume you use the template.