create presentation from markdown

Creating and publishing presentations using Markdown

I know people that just hate markdown. They hate the fact that they can not see bold or underlined text while editing. That you have to enclose text in batiks or asterisks to change how it’s displayed. Or that headlines and regular text have the same size.

I am not one of those people… I loooove Markdown.

As a text driven guy that does everything in the keyboard, that uses NeoVim and Zsh on a regular basis, and that hates to touch the mouse or trackpad, I have to say that there is nothing better than writing documentation or articles in Markdown.

Let me give you some additional reasons:

• Markdown can be converted to almost everything: HTML, PDF, Latex, etc. And all of this with open source tools.
• Markdown documents are pretty readable by themselves. They are just text with some simple decoration symbols . Try doing that on an HTML or LateX file.
• You can write Markdown in literally any editor. No need of MS Word or Mac Pages. Or any other kind of tool for that matter.
• Markdown is Version Control friendly. You can keep versions of your documents using Git, SVN, CVS, etc. After all, its just text.

That’s why I use Markdown for almost everything, including this blog. Is written in Markdown and converted to HTML with JavaScript using Gatsby

So I wanted to implement the same workflow, but for presentations. I wanted to create Slides using markdown, and then converted them to PDF or HTML.

But it turns out that there is more than one way to do it. Here I’ll show a few.

So how do you create Slides with Markdown?

Before we get into the actual tools to convert Markdown to PDF, or HTML, lets first talk on how to create a Markdown presentation. In other words, how to create slides.

If you already know Markdown, you only have to take into account 3 things when creating Markdown slides documents:

• You only need one markdown file for all your slides
• You separate slides by using --- (3 dashes) between the content of each slide. And this can be configured on some conversion tools
• The first Heading 1 or # is the title of the slide

So this could be a 3 slide markdown presentation:

And that’s it, that’s a 3 slide presentation!

If you open the previous markdown with Marp (which I’ll will explain further down) this is what You’ll get:

The BIG caveat on creating slides with Markdown is that it depends on the tools you are using to covert markdown to PDF/HTML/ODF . Fortunately, most of the tools follow the previous 3 principles.

Front matter

The previous “presentation” consisted of only 3 slides. Easy right? But what if you want to add Meta information to your final PDF or HTML file? Information like:

• The Creation Date
• The Title that gets displayed in the browser tab when the markdown gets converted to HTML for instance

Also, what about styling:

• Set a background color
• Apply a theme
• Override some of the styling

That’s what the Front Matter of the presentation is used for.

This is a presentation of one slide, but with Front Matter :

As you can see, the Front Matter is a small section with keys and values that can be almost anything. But as as suggestion you should provide a Front Matter with at lest:

• A Title of the presentation with the key title
• The Authors name with the key author
• The Creation Date with date

Note : Some tools will break if you use unsupported Front Matter options. An example of this is the tool lookatme which doesn’t support the theme key.

How the Front Matter affects the final presentation and which keys are valid changes from tool to tool , so I’ll try to specify which items can be in the front matter but it’s up to you to find out the complete list of items that can be placed in the front matter depending on the tools you end up selecting.

You can read more about the Front Matter here

Creating a test presentation

OK, enough of theory. Les’s create a Markdown Presentation and convert it to HTML and PDF with different tools. Our first step will be creating a Git repo and initialize it with npm :

The reason why I’m using npm  is to create the package.json  file which I’ll use to automate some of the steps and have some sort of a Makefile where I can save all the commands I’ll be using to convert the presentation to HTML or PDF. Also, because even though all the tools can be installed globally, I prefer to install them locally.

Next, add the following contents to the slides.md file:

What is left to do is to install and configure the tool we’ll use to convert and/or lint our presentation.

Linting your markdown with Markdownlint

I’m an absolute nerd for code quality. That’s why I use tools like eslint , prettier , phpcs and of course markdownlint .

If you are like me, then I recommend you install markdownlint-cli to lint your presentation:

And then create the file .markdownlint.json with the following contents:

This will allow you to fix format issues in your markdown file ignoring 3 rules:

• Do not complain about lines longer than 80 characters. This one is for me since I tend to write long lines in my slides and I don’t like to break them
• Do not complain about having more than one H1 heading. Very important since each slide will start with an H1
• Do not change the * to - in bulleted lists. This is very specific to Marp.

Now you can use the command npx markdownlint --fix slides.md to fix any linting issues.

And better yet if you add the following new scripts in package.json (see, already useful):

Now you can lint and format your files with:

With linting in place, we’re ready for our first conversion tool.

First tool: Marp

By far, the easies way to convert Markdown presentations to HTML is using Marp . And the reason is because it can be used as a cli tool , but also you can use it inside Visual Studio Code with an extension

As I said I’m a CLI guy, so I’m going to focus on the marp-cli tool. That’s why I’m going to install it in the current project with:

And here is the cool part. You can start your presentation using:

The PORT  variable is not necessary. If you omit it it will use the port 8080 . But since us developers use the 8080 port so often, and that’s Marp’s default port, I thought it was best to mention it right from the get go.

And if you click on slides.md you will see your presentation right on the browser:

A useful tip is to add the previous command as a script in your package.json file:

And run the presentation with

If you want to publish your presentation somewhere, then you can execute npx marp slides.md and you’ll get a slides.html file on the root directory of your project.

Marp’s Front Matter

Marp supports a lot of configuration directives in the Front Matter. But that could make your file to be incompatible with other tools. That’s why I recommend the creation of a .marprc.yml file with the Front Matter directives:

Note: At the time of this writing, April 10 2023, the .marprc.yml does not support all the configuration options

This would make your presentation look like this:

One very cool thing about Marp is that it bundles themes that can be configured using CSS.

To enable a theme you could add key theme in the Front Matter . And then, before the first slide (the first Title) add a CSS code like so:

Note that this can make the markdown not compatible with other tools.

You can read more about the Theme directive here

Backgrounds

It’s very common that you want a slide to have a different background or add an image as a background. This can be done by using a local directive .

Again, this is not compatible with other tools, but very cool to use:

Marp Resources

There aren’t may Marp resources outside the official documentation . But it’s worth mentioning this great presentation about Marp created by it’s author. It explain some advanced concepts about the tool.

Second tool: Lookatme

The second tool is my absolute favorite because is 100% terminal based.

With lookatme you can present directly in the terminal. Which in my opinion is very, very… Very VERY cool.

Lookatme is written in Python and you need to have pip  version 3 installed in your system. If you meet this requirement, you only have to execute pip install  to install it:

There is an option to run lookatme  using Docker. But that’s beyond the scope of this article.

And you start a presentation with:

One big drawback with lookatme is that you can NOT add non standard Front Matter keys . If you do you’ll get an exception since lookatme   does not ignore incompatibilities .

Lookatme options

Lookatme doesn’t have that many options since it works in the terminal. So instead of customizing the presentation using the Front Matter , I recommend using the CLI options . This makes your slides less error prone:

The one you’ll use more often is --style which will change the color scheme for your code:

For more options and documentation you can got the official documentation

And as we’ve done before, you can add the command to package.json :

Third Tool: Reveal-md

If you want to go for broke, then Reveal.js is the tool for you!

Now, Reveal.js is actually a very complicated tool to use. So complicated that it’s author sells a 5 hour course on how to create presentations with the tool. If you’ve used Slides.com then you have an idea of what Reveal.js can do since that’s the engine behind the site.

The “drawback”, is that to create presentations you have to create a React application. This means that you have to create HTML and JavaScript to have a simple presentation. And as you’ve noticed, we want to use Markdown, not HTML. Still, if you want to go that route, you can follow the documentation on how to install and create a presentation using just Reveal.js.

Thankfully Lars Kappert created reveal-md which, in his own words, is reveal.js  on steroids . But most importantly, it supports displaying presentations created in Markdown!

Since reveal-md is an npm package, you can install it with:

And to start the presentation you can use good ‘ol npx :

Notice that reveal-md  uses port 1948  by default, so keep that in mind when you are starting your presentation. Or better yet, use the --port parameter to change it for something more friendly.

As most of the tools we’ve seen, you can modify the style and several Front Matter options with cli parameters:

Here the --watch  flag will reload the presentation when the slides.md   file is changed.

Reveal-md is really powerful when it comes to theming, not only you can change the slide theme, but the code highlight theme. Just pass the --theme  flag pointing to a local or an online css  stylesheet and you are good to go.

You can see a list of presentation themes here . And a list of highlight themes here

Advanced styling

But what is really powerful is when you integrate the reveal.js slide attributes to add things like background images:

Or assign a custom class or id attributes

Reveal-md Override CSS

With Themes you can create or use a complete look for your presentation, but if you only want to change a couple of things from your presentation, then you can use a separate CSS file with just then thing you want to change.

And if you add to this the fact that you Reveal use CSS variables to customize parts of the presentation like the background color, you have a pretty powerful and flexible way to make the presentations your own.

Take for instance this CSS file:

If you execute reveal-md with the --css parameter, you can change the background color:

The css variables can change from theme to theme, so just open the Chrome Tools and look for what you can change.

Reveal-md options

In a similar fashion as Marp , you can configure your presentation by using a JSON file called reveal-md.json and place it in the root of your project. Here you can add all of the reveal.js  options

This way, you just need to execute npx reveal-md slides.md and reveal will pick up all of your changes

In case you want to understand the power of reveal-md, take a look at this presentatio

All the code used in this blog post, can be accessed in this GitHub repo.

4 Markdown-powered slide generators

Vector Open Stock. CC BY-SA 3.0.

Imagine you've been tapped to give a presentation. As you're preparing your talk, you think, "I should whip up a few slides."

Maybe you prefer the simplicity of plain text , or maybe you think software like LibreOffice Writer is overkill for what you need to do. Or perhaps you just want to embrace your inner geek.

It's easy to turn files formatted with Markdown into attractive presentation slides. Here are four tools that can do help you do the job.

One of the more flexible applications on this list, Landslide is a command-line application that takes files formatted with Markdown, reStructuredText , or Textile and converts them into an HTML file based on Google’s HTML5 slides template .

All you need to do is write up your slides with Markdown, crack open a terminal window, and run the command landslide followed by the name of the file. Landslide will spit out presentation.html , which you can open in any web browser. Simple, isn’t it?

Don't let that simplicity fool you. Landslide offers more than a few useful features, such as the ability to add notes and create configuration files for your slides. Why would you want to do that? According to Landslide's developer, it helps with aggregating and reusing source directories across presentations.

Viewing presenter notes in a Landslide presentation

Marp is a work in progress, but it shows promise. Short for "Markdown Presentation Writer," Marp is an Electron app in which you craft slides using a simple two-pane editor: Write in Markdown in the left pane and you get a preview in the right pane.

Marp supports GitHub Flavored Markdown . If you need a quick tutorial on using GitHub Flavored Markdown to write slides, check out the sample presentation . It's a bit more flexible than baseline Markdown.

While Marp comes with only two very basic themes, you can add background images to your slides, resize them, and include math. On the down side, it currently lets you export your slides only as PDF files. To be honest, I wonder why HTML export wasn’t a feature from day one.

Editing some simple slides in Marp

You probably know pandoc as a magic wand for converting between various markup languages. What you might not know is that pandoc can take a file formatted with Markdown and create attractive HTML slides that work with the Slidy , Slideous , DZSlides , S5 , and Reveal.js presentation frameworks. If you prefer LaTeX , you can also output PDF slides using the Beamer package .

You'll need to use specific formatting for your slides, but you can add some variables to control how they behave. You can also change the look and feel of your slides, add pauses between slides, and include speaker notes.

Of course, you must have the supporting files for your preferred presentation framework installed on your computer. Pandoc spits out only the raw slide file.

Viewing slides created with Pandoc and DZSlides

Hacker Slides

Hacker Slides is an application for Sandstorm and Sandstorm Oasis that mates Markdown and the Reveal.js slide framework. The slides are simple, but they can be visually striking.

Craft your slide deck in a two-pane editor in your browser—type in Markdown on the left and see it rendered on the right. When you're ready to present, you can do it from within Sandstorm or get a link that you can share with others to present remotely.

What’s that—you say that you don’t use Sandstorm or Sandstorm Oasis? No worries.There's a version of Hacker Slides that you can run on your desktop or server.

Editing slides in Hacker Slides

Two honorable mentions

If you use Jupyter Notebooks (see community moderator Don Watkins' article ) to publish data or instructional texts, then Jupyter2slides is for you. It works with Reveal.js to convert a notebook into a nice set of HTML slides.

If you prefer your applications hosted, test-drive GitPitch . It works with GitHub, GitLab, and Bitbucket. Just push the source files for your slides to a repository on one of those services, point GitPitch to that repository, and your slides are ready to view at the GitPitch site.

Do you have a favorite Markdown-powered slide generator? Share it by leaving a comment.

Related Content

• Skip to primary navigation
• Skip to main content
• Skip to primary sidebar
• Skip to footer navigation

The Geek Diary

mdp Command Examples

“mdp” is a command-line tool that allows users to create presentations directly from Markdown files. Markdown is a lightweight markup language that uses plain text formatting syntax, making it easy to write and read. With “mdp,” users can leverage the simplicity of Markdown to create slides for presentations without the need for complex presentation software. Here’s a deeper look into the features and functionality of “mdp”:

• Markdown Support : “mdp” supports Markdown syntax, allowing users to create slides using familiar Markdown formatting conventions. Users can use headers, lists, code blocks, links, images, and other Markdown elements to structure their slides and add content.
• Simple Interface : “mdp” provides a straightforward command-line interface for creating and navigating presentations. Users can easily switch between slides, navigate within slides, and control the presentation flow using keyboard shortcuts or commands.
• Customization Options : “mdp” offers customization options to control the appearance and layout of slides. Users can specify themes, colors, fonts, and other styling preferences to tailor the presentation’s visual design to their liking.
• Embedding Media : “mdp” supports embedding media such as images and videos into slides. This allows users to enhance their presentations with multimedia content to engage and captivate their audience.
• Export Options : “mdp” provides options for exporting presentations to different formats, including PDF, HTML, and images. This enables users to share their presentations in various formats and platforms, making them accessible to a wider audience.
• Integration with Markdown Workflow : Since “mdp” uses Markdown as its input format, users can seamlessly integrate presentation creation into their existing Markdown-based workflow. This allows for efficient content creation, version control, and collaboration using Markdown-compatible tools and platforms.
• Open Source : “mdp” is an open-source project hosted on GitHub, meaning that its source code is freely available for inspection, modification, and contribution by the community. This fosters transparency, collaboration, and innovation in the development of the tool.
• Documentation and Community : “mdp” is accompanied by documentation that provides guidance on installation, usage, and customization. Additionally, there may be community forums, mailing lists, or other channels where users can seek support, share feedback, and collaborate with other users and developers.

1. Launch a presentation in the terminal from a Markdown file:

2. Disable fading transitions:

3. Invert font colors to use in terminals with light background:

4. Disable transparency in transparent terminals:

Overall, “mdp” provides a convenient and flexible solution for creating presentations from Markdown files. Its simplicity, customization options, and integration with Markdown workflows make it a valuable tool for individuals and teams who prefer Markdown-based content creation and presentation authoring.

You May Also Like