Deploy Marp to GitHub Pages

Presentations to Webpages: Instantly!

What?

Marp lets you create HTML slides from markdown (like this!).

This presentation is both a website and a README.md.

Why?

Treat your presentation the same way you treat code.

• Use git to track changes
• Pull requests to collaborate
• Deploy automatically
• See a problem? Open an issue!

Setup

Want to create your own?

First, create a new repo from the template repo.

Configure GitHub Pages

Open your new repo and setup publishing.

You'll typically use gh-pages as the deploy branch.

Review Build

Click on Actions tab and see if the build succeeded (it may take some time).

You should now see the generated files in the gh-pages branch.

View webpage

Open your deployed webpage to see the content.

Out of the box you should see README.md as /index.html and /README.pdf. Slides under docs/ are also converted.

Running locally

Locally you'll run commands like:

$ marp README.md -o build/README.pdf

or

$ npx @marp-team/marp-cli@latest README.md -o build/README.pdf

As a workflow step

The workflow runs an equivalent step:

- name: Marp Build (README.pdf)
  uses: docker://marpteam/marp-cli:v1.7.0
  with:
    args: README.md -o build/README.pdf
  env:
    MARP_USER: root:root

Note the args match the previous slide.

Customizing the build

Anything in the build/ folder will be deployed to GitHub Pages.

You can copy extra files or run further processing steps using other tools.

Learn more about Marp

This is a good time to learn more about Marp. Here's some resources:

• CommonMark
• Cheat Sheet
• Themes
• CSS Themes
• Directives
• VS Code plugin

Example Sites

Known sites using this action are:

• University of Illinois at Urbana-Champaign's CS 199 Even More Practice (code)
• Exploring agent based models (code)

Send a pull request to get your site added.

Publish your slides

When you are ready to share your presentation, commit or merge to main and your content on GitHub Pages will automatically update.

🎉

Hooray!