Marp: Create Presentations with Markdown
Marp is a powerful and user-friendly presentation framework that simplifies the process of creating visually appealing slide decks using Markdown. In this blog post, we’ll explore what Marp is, why you might want to use it, how to get started. I’ll share my process and show you how you can automate hosting your presentations on GitHub Pages using GitHub Actions.
What is Marp?
Marp is an open-source presentation framework that allows you to create beautiful, customizable slide decks using the simplicity and flexibility of Markdown. By harnessing the power of Markdown, Marp enables you to focus on your content and message without getting bogged down in complex formatting and design choices. Marp has CLI and VS Code extensions, and it supports exporting presentations to various formats, including HTML, PDF, and PowerPoint.
Why Use Marp?
There are several reasons why you might want to consider using Marp for your presentations:
- Simplicity: Marp allows you to write your presentations in plain text using the intuitive Markdown syntax, which is easy to learn and use.
- Focus on content: With Marp, you can concentrate on your message and content without worrying about complex formatting and design choices.
- Customizable: Marp offers a range of customization options, allowing you to create presentations that align with your personal style and preferences.
- Integration with Visual Studio Code: Marp seamlessly integrates with the popular Visual Studio Code editor, providing real-time previews and a smooth workflow for creating and editing presentations.
-
Export options: Marp supports exporting presentations to various formats, including HTML, PDF, and PowerPoint.
Working with Marp
For me, the ideal way to interact and work with Marp is through the Marp for VS Code extension. This extension provides a seamless workflow for creating and editing presentations in Visual Studio Code. It also offers real-time previews, allowing you to see your presentation as you write it.
To get started, install the Marp for VS Code extension and open a new Markdown file. You can then start writing your presentation. A sample presentation is shown below:
---
marp: true
---
# My Presentation
---
## Slide 1
- Item 1
- Item 2
- Item 3
---
## Slide 2
---
## Slide 3
> This is a quote.
---
## Slide 4
| Column 1 | Column 2 |
| -------- | -------- |
| Item 1 | Item 2 |
| Item 3 | Item 4 |
Once you’ve added the content to VSCode with Marp, your presentation will look like this:
Official Themes and Resources
Marp comes with a few built-in themes that you can use as a starting point for your custom themes or as inspiration for your own designs. You can also refer to the Marpit documentation for more information on styling Marp presentations. There is good documentation on image sizing and positioning on the Marp website.
GitHub Pages and Marp
I have created a GitHub repo for each of my talks. For each talk, I have a slides folder that contains the Markdown files for the presentation. All images are stored in slides/img. I use GitHub Pages to host the HTML files, which allows me to share the presentation with others. I use a GitHub Actions workflow that automatically builds and publishes the presentation to GitHub Pages whenever I push changes to the slides folder. This workflow is shown below:
name: Deploy marp site to Pages
on:
# Runs on pushes targeting the default branch
push:
branches: ["main"]
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
# Build job
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Copy images
run: mkdir build && cp -R slides/img build/img
- name: Marp Build (README)
uses: docker://marpteam/marp-cli:v1.7.0
with:
args: slides/Slides.md -o build/index.html --html
env:
MARP_USER: root:root
- name: Setup Pages
uses: actions/configure-pages@v3
- name: Upload artifact
uses: actions/upload-pages-artifact@v1
with:
# Upload entire repository
path: 'build'
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v1
Marp Template
I’ve created a marp-slides-template, which provides a minimal template to create a Marp site that can be built and published on GitHub Pages. This template comes with a GitHub Pages / Actions workflow, allowing you to easily build and publish your Marp presentation on GitHub Pages. With this template, you can quickly create and customize your presentation, preview it in Visual Studio Code using the Marp extension, and then share it with the world by publishing it to GitHub Pages. You can use the template by clicking on the link or visiting the repo and clicking on the “Use this template” button.
Conclusion
Marp is a powerful, flexible, and user-friendly presentation framework that simplifies the process of creating visually appealing slide decks. By harnessing the simplicity of Markdown and offering a range of customization options, Marp enables you to focus on your content and message without getting bogged down in complex formatting and design choices. With its seamless integration into Visual Studio Code and various export options, Marp is an excellent choice for anyone looking to streamline their presentation creation process. Check out the official documentation and repositories to get started on creating your next presentation with Marp today.
Resources
Some of my Marp Presentations
- Feature Flags
- GitHub Actions Demos
- Secure Terraform on Azure
- Build with Bicep
- Dotnet Configuration in Depth
- Dev Containers
Official Repos and Docs
For more information on Marp and to dive deeper into its features and capabilities, check out the following resources:
CommonMark markdown syntax: https://commonmark.org/help/
Marp Official Repository: https://github.com/marp-team/marp
Marp Official Documentation: https://marpit.marp.app/markdown
Marp for VS Code Documentation: https://marketplace.visualstudio.com/items?itemName=marp-team.marp-vscode
Top comments (2)
Wow, this is the first time I've seen this way of creating presentations! It's really interesting and unusual, and I'm definitely intrigued by the idea of using Marp to create my next presentation. I'm used to using other tools where there are worksheet templates on the website that I can use to quickly create well-designed slides. I'm particularly intrigued by the idea of using Marp to create my presentation content since I'm already familiar with that syntax from my coding work. I'm really excited to give Marp a try and see how it works for me. Thanks for sharing this article and introducing me to this new tool!
I'm not sure how simple it is to use, especially with so many other simple presentation tools out there. I would like to know more about how Marp works and how it can help me create better presentations.