Skip to content
Cantrip

The command line

text
cantrip <command> [options] [file...]

One command with five verbs. cantrip --help prints the same list, and cantrip --version prints the version.

Verbs

VerbDoesWrites
buildboth outputs, from one parse<input>.html and <input>.pdf
htmlthe slideshow only<input>.html
pdfthe printable deck only<input>.pdf
inforeport the deck's shapenothing
themeslist the themes, ratios, and transitionsnothing
sh
cantrip build talk.md              # talk.html and talk.pdf
cantrip html talk.md               # talk.html
cantrip pdf talk.md --notes        # talk.pdf, presenter's copy
cantrip info talk.md               # what is in there
cantrip themes                     # what is available

info is the one to reach for when a deck does not come out the way you expected - it shows the slide numbering, each slide's heading, and which slides carry notes, without writing anything:

text
$ cantrip info examples/sample.md
Cantrip: 12 slide(s), 6 with notes
   1 * Cantrip
   2 * The format is just Markdown
   3   Front matter sets the deck up
   ...

A * marks a slide with speaker notes. (no heading) means the slide has no heading at all, which is usually a separator in the wrong place.

Options

OptionDoesDefault
-o, --out PATHwhere to writebeside the input
-t, --theme NAMEoverride the deck's themethe deck's, else plain
--mode light|darkHTML: the mode the page opens inthe deck's mode:, else light
-r, --ratio NAMEoverride the deck's ratiothe deck's, else 16:9
--transition NAMEoverride the deck's HTML slide transitionthe deck's, else fade
-f, --footer TEXTtext at the foot of every slidenone
--bookmarks NPDF outline depth, 0 for none2
-n, --notesput speaker notes into the PDFoff
--no-notesleave speaker notes out of the HTMLoff
--notes-panel open|closedHTML: the speaker-notes panel open or closed when the page opensthe deck's notes:, else closed
--start-slide NHTML: the slide the page opens on, from 1the deck's slide:, else 1
--overview open|closedHTML: open in the slide overviewthe deck's overview:, else closed
--no-numbersomit slide numbersoff
--raw-htmlpass raw HTML through unescapedoff
-v, --verbosereport byte counts, and each image skipped and whyoff

--flag=value and --flag value both work, short flags bundle (-nv), and -- ends the options.

Why notes have two flags

The two outputs start from opposite defaults, because they go to different people. The HTML is what you present from, so notes are in by default and --no-notes takes them out for the copy you publish. The PDF is what the audience gets, so notes are out by default and --notes puts them in for your own copy.

sh
cantrip html talk.md --no-notes -o public/talk.html   # for the attendees
cantrip pdf  talk.md --notes    -o talk-presenter.pdf # for you

--notes-panel is a third, separate thing: whether the HTML's notes panel is open when the page loads (--notes already means "notes in the PDF"). It needs the notes in the page, so --no-notes --notes-panel open is refused with exit code 1 rather than producing a page whose panel cannot open. See How the slideshow opens.

What --out means

For html and pdf it is the exact file to write:

sh
cantrip html talk.md -o public/index.html

For build it is the path without an extension, since one run writes two files:

sh
cantrip build talk.md -o dist/talk    # dist/talk.html and dist/talk.pdf

With no --out, an output replaces the input's extension and sits beside it: slides/talk.md gives slides/talk.html.

Note

cantrip writes files but never creates directories. -o dist/talk needs dist to exist.

An output is never written over one of the input files: -o talk.md on cantrip html talk.md is refused with exit code 1, and the deck is left alone.

Exit codes

CodeMeans
0it worked
1it was asked correctly but could not be done - a missing file, an unknown theme, a deck with no slides, a deck over a size limit (2 MiB a file, 2,000 slides), an output that would overwrite an input
2it was asked incorrectly - no arguments, an unknown verb or flag, a malformed flag value such as --bookmarks x, --notes-panel maybe or --start-slide 0, a verb with no input file

The split matters in a shell script: a 2 is a bug in your command line, a 1 is a problem with the deck or its surroundings. --help and --version exit 0. Errors, warnings, and the usage text printed for a misuse go to stderr; stdout carries only what you asked for - the wrote ... lines, info, themes, --help, and --version. Text taken from the deck, such as the titles info lists, the image paths --verbose names, or a theme name in an error, is printed with its control characters escaped (\x1B), so a deck cannot send escape sequences to your terminal.

sh
cantrip build talk.md || echo "deck did not build" >&2

Presenting the HTML

Open the file. No server is needed, and nothing is fetched.

KeyDoes
<kbd>→</kbd> <kbd>space</kbd> <kbd>PageDown</kbd> <kbd>n</kbd>next slide
<kbd>←</kbd> <kbd>PageUp</kbd> <kbd>p</kbd>previous slide
<kbd>Home</kbd> <kbd>End</kbd>first / last slide
digits then <kbd>Enter</kbd>jump to a slide
<kbd>o</kbd>slide overview; click, <kbd>Enter</kbd>, or <kbd>space</kbd> to jump
<kbd>s</kbd>speaker-notes panel
<kbd>m</kbd>light / dark mode
<kbd>f</kbd>fullscreen
<kbd>?</kbd>the shortcut list
<kbd>Esc</kbd>close an overlay

The current slide is in the URL fragment (talk.html#4), so a reload keeps your place and you can link to a slide. ?notes=1 / ?notes=0 and ?overview=1 / ?overview=0 in the URL open or close the notes panel and the overview when the page loads (talk.html?notes=0#4), and ?mode=light / ?mode=dark pick the mode, whatever the deck was built with. While the notes panel is open, the slide is scaled into the space above it. The slide scales to the window, so the deck looks the same on a laptop and a projector.

Printing from the browser

The print stylesheet lays one slide per page at the deck's own page size, and hides the progress bar, notes, and overlays. The browser's own print dialog is therefore a second route to a PDF. The pdf verb is the better one - it carries metadata, bookmarks, and a running footer, and it needs no browser - but the print route is there when you want the browser's exact rendering.