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

• One-shot conversion without installing marp-cli

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

---

• Or, install marp-cli in the current directory with npm

$ npm install --save-dev @marp-team/marp-cli

• Running the command above creates a package.json file in the current directory, like this

{
	"devDependencies": {
		"@marp-team/marp-cli": "^4.0.0"
	}
}

---

• Now the marp command is available in the current directory when prefixed by npx

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

• And here's the output

[  INFO ] Converting 1 markdown...
[  INFO ] README.md => build/README.pdf

---

• If you already have the package.json file in the current directory, simply run this to install packages specified by it.

$ npm install

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
• Marp Online Editor

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!