Guide · Open source
How to use remark: build a Markdown slideshow in your browser
Updated · written with AI from the project's own documentation and checked against our catalogue data
remark is an open-source JavaScript library that shows a slideshow in a web browser. You write your slides in Markdown inside an HTML file, separate them with dividers, and open the page to present. This guide is for people who already know some HTML and CSS, and it walks you through creating, editing and presenting a remark slideshow.
remarkgnab/remark · ★ 13k · MIT Install options & downloads Quick start
- 1Create the HTML file. Make an HTML file and paste in the boilerplate from the README, which loads remark and holds your slides in a textarea with id source.
- 2Open it in a browser. Open the HTML file in a modern web browser to see the first slide.
- 3Write your slides. Replace the sample content with Markdown and separate each slide with a line of three dashes.
- 4Style with CSS. Adjust fonts and layout with ordinary CSS in the head of the file.
- 5Refresh to check changes. Save the file and refresh the browser after each edit.
- 6Open presenter mode. Press C to clone the display, then P to switch to presenter mode, and h for the help menu.
- 7Export if needed. Use Chrome's Print to PDF, knowing the styling may not be exact, or try DeckTape.
What you need before you start
remark runs in a modern web browser, and the source says that is the only prerequisite. You also need a text editor to write the HTML file that holds your slides.
remark is aimed at people who already know their way around HTML and CSS, because styling is done with ordinary CSS. If you prefer a visual slide editor, the project's own description suggests it is not the right fit.
- A modern web browser
- A plain text editor for the HTML and Markdown
- Basic familiarity with HTML and CSS
Create the HTML file for your slideshow
Create an HTML file to hold your slideshow. The quickest start is to copy the boilerplate from the remark README. It loads remark, declares a textarea with the id source, and calls remark.create() to start the show.
The README also points to boilerplate-*.html files in the project. The -local one requires building remark first, so the copy-and-paste boilerplate is the simpler option.
<!DOCTYPE html>
<html>
<head>
<title>Title</title>
<meta charset="utf-8">
<style>
body { font-family: 'Droid Serif'; }
h1, h2, h3 {
font-family: 'Yanone Kaffeesatz';
font-weight: normal;
}
.remark-code, .remark-inline-code { font-family: 'Ubuntu Mono'; }
</style>
</head>
<body>
<textarea id="source">
class: center, middle
# Title
---
# Agenda
1. Introduction
2. Deep-dive
3. ...
---
# Introduction
</textarea>
<script src="https://remarkjs.com/downloads/remark-latest.min.js">
</script>
<script>
var slideshow = remark.create();
</script>
</body>
</html>Write slides in Markdown
Each slide is Markdown text inside the textarea. Separate slides with a line containing three dashes. The boilerplate shows a title slide using the class line class: center, middle, followed by ordinary Markdown headings and lists.
The README says remark supports Markdown formatting with smart extensions, and it includes syntax highlighting for a range of languages. Templates for customised slides are covered in the project wiki.
- Separate slides with a line of three dashes (---)
- Use # headings, lists and other Markdown as you would elsewhere
- Use class lines such as class: center, middle to style a slide
Open, refresh and style the slideshow
Open the HTML file in your browser. To change the content, edit the Markdown or the CSS, save the file and refresh the page. The README summarises this loop as edit, save and refresh.
Styling uses plain CSS in the head of the file, as the boilerplate shows with font-family rules for headings and code.
- Open the HTML file directly in a browser
- Edit the Markdown or CSS, save, then refresh
Use presenter mode and the cloned display
remark includes a presenter mode with speaker notes written in Markdown, plus a cloned slideshow view. The README gives these keys: press C to clone a display, press P to switch to presenter mode, and press h to open the help menu.
Touch devices are supported, so you can swipe to move between slides on a phone or tablet.
- C clones the display
- P switches to presenter mode
- h opens the help menu
- Swipe to navigate on touch devices
Export to PDF or print
The README says PDF output relies primarily on Chrome's Print to PDF feature, and that the styling is not exact. The project's issue #50 has recommended CSS you can add to your styles.
Alternatively, the README mentions DeckTape, a PDF exporter for HTML presentation frameworks that supports remark.
- Use Chrome's Print to PDF feature first
- Add the CSS suggested in issue #50 if the layout needs fixing
- Try DeckTape as an alternative exporter
What people use it for
- Teaching a course with slides kept as plain text in version control
- Giving a technical talk with Markdown code blocks and syntax highlighting
- Presenting with speaker notes on a second screen using presenter mode
- Showing a slideshow on a phone or tablet with swipe navigation
Frequently asked questions
Is remark free to use?
Yes. The README says remark is licensed under the MIT license, and the full terms are in the project's LICENSE file. Check that file for the exact wording.
What do I need to install remark?
According to the source, you need a modern web browser. The README's install step is to clone the repository with git clone https://github.com/gnab/remark. You can also copy the boilerplate HTML to start.
Can remark export slides to PDF?
PDF output mainly relies on Chrome's Print to PDF feature, and the README warns that styling is not exact. You can also use DeckTape, which the README mentions as a PDF exporter that supports remark.
Do I need to build remark before using it?
The copy-and-paste boilerplate loads remark from a URL and does not need a build. The README notes that the boilerplate -local file requires building remark first.
Is remark good for people who are not developers?
The project is aimed at people who know HTML and CSS, and the README describes editing HTML and Markdown by hand. Non-technical users who want a visual slide editor are better served by other tools.
How does remark compare to reveal.js, Marp or Slidev?
The source lists reveal.js, Marp, Slidev and impress.js as comparable projects but does not compare them in detail. Choose remark if you want a minimal, hand-edited Markdown-in-HTML slideshow with CSS styling.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
remark suits people comfortable with HTML and CSS who want slides written in Markdown and stored as plain text, including developers and teachers who want presenter notes. If you want a visual editor, built-in PDF export or an offline setup without a build step, look at the comparable projects the source lists, such as reveal.js, Marp or Slidev.
Install options & downloads