slides

go-slides/slides

🌐 Website · 📚 Documentation

Marp-compatible slide decks in pure Go (no cgo, no Node, no browser), with two additions:

• Go templates in slides. {{ .title }}, {{ range }} loops that generate slides, {{ page }} / {{ total }}, {{ include "part.md" }}.
• Slide kinds. A slide says what it is (kind: title) instead of repeating how it looks. A kind is a named preset of header, footer, page numbering, class and background.

---
theme: gaia
paginate: true
footer: "{{ .title }} — {{ page }}/{{ total }}"
title: Quarterly review
kind: content
data:
  topics: [Revenue, Hiring, Roadmap]
---

<!-- _kind: title -->

# {{ .title }}

{{ range .topics }}
---

## {{ . }}
{{ end }}

go install github.com/go-slides/slides/cmd/slides@latest
slides deck.md            # writes deck.html

Marp compatibility

The deck format is Marp's: Marpit directives and Marp Core's flavour of CommonMark. Its behaviour was ported from the Marpit and Marp Core sources rather than from their documentation. Every case below is pinned by a test against output that marp-cli 4.5.1 (Marp Core 4.4.0) produced; see testdata/oracle.

• Slides split at ---, or at the headings that headingDivider names.
• Global, local and spot (_name) directives, from the front matter or from HTML comments. Loose YAML is on, as in Marp Core: backgroundColor: #eee is a colour, not a comment.
• header, footer (inline Markdown), paginate (true, false, hold, skip), class, color, and the background* directives.
• The image syntax: w: / h:, CSS filters, ![bg] backgrounds. Several backgrounds and split backgrounds (bg left:40%) render as layers, as in Marp's inline SVG mode.
• Fragmented lists (* and 1)), speaker notes (the comments that are not directives), and <style> / <style scoped>.
• Marp Core's built-in default, gaia and uncover themes, the size directive (16:9, 4:3), custom themes (@theme, @import, @size).
• GFM tables, strikethrough, URL linkify, line breaks as <br>, heading ids slugged as Marp Core does them.
• Emoji shortcodes and Unicode emoji as Twemoji images (see Emoji).
• Raw HTML filtered through Marp Core's allowlist; --html allows it all.

slides expand writes a deck back out as plain Marp Markdown, with templates expanded and kinds replaced by the directives they stand for, so marp-cli and the Marp editor extensions render it the same way. The kinds test renders the expanded deck with Marp and requires the same HTML as slides produces for the original.

Templates

The deck body is one Go text/template, executed before the Markdown is parsed. Its data (the dot) is the front matter, overlaid by the front matter's data: mapping, then by data in slides.yaml, --data files and --set key=value flags. A missing key is an error that names the file and line, rather than printing <no value>.

Front-matter values and kind definitions are templates too, so footer: "{{ .title }} — {{ page }}" numbers every slide.

Code is left alone. Text inside fenced code blocks and inline code spans is never interpreted, so a slide about Go templates can show {{ .Name }} as it is. Front matter template: code interpolates code too, and template: false turns templates off. delims: ["<%", "%>"] changes the delimiters.

Kinds

kinds:
  title:              # redefines a built-in kind
    class: lead
    paginate: false
    header: ""
    footer: ""
  quote:
    extends: blank    # starts from another kind
    class: invert
    backgroundColor: "#111"

• kind: name applies a kind like a local directive: to this slide and to the ones after it. _kind: name applies it to one slide.
• Switching kinds first clears what the previous kind set, so a class or a footer never leaks from one kind into the next.
• Directives written by hand always win over the kind. They carry over to the following slides as Marp's local directives do, kind switches included.
• A kind accepts the local directives: backgroundColor, backgroundImage, backgroundPosition, backgroundRepeat, backgroundSize, class, color, footer, header, paginate. It also accepts extends.
• Each slide carries data-kind="<name>", so a theme can style a kind directly.

Built-in kinds: title (class lead, no header, footer or page number), section (class lead), content (the deck's defaults) and blank (nothing around the content). Only the gaia theme defines lead; with the other themes, give title and section a class your theme knows.

Kinds come from, in increasing priority: the built-ins, slides.yaml, --kinds files, and the deck's front matter kinds: key. That key takes either a mapping or the path of a file, or a list of paths, so several decks can share one file. slides kinds deck.md lists what a deck can use; with --json (after v0.5.0), as a list of {name, extends, directives: [{key, value}]}, the directives resolved through extends.

HCL

Everywhere slides reads YAML, it also reads HCL2's native syntax, for its expressions and functions:

---hcl
theme    = "gaia"
paginate = true
title    = "Quarterly review"
data = {
  company = "ACME"
  quarter = 3
}
header = format("%s — Q%d", data.company, data.quarter)
footer = "${upper(data.company)} · ${page()}/${total()}"
date   = formatdate("D MMMM YYYY", now())

kind "chapter" {
  extends = "section"
  class   = ["lead", "invert"]
}
---

# {{ .title }}

• Attributes are the YAML keys under the same names: Marp's directives (theme, paginate, header, footer, class, backgroundColor, …), the metadata (title, author, …), template, delims, kinds (file paths) and data, an object. kind "<name>" { … } blocks define kinds, in a front matter, in slides.hcl and in kinds files. slides.hcl takes themes, html, lang, data and kinds attributes besides.
• Values reach the directives in the string forms YAML gives them (true is "true", a list of classes is a list), so a directive behaves the same whichever syntax set it. null leaves a directive unset. data keeps its types: in templates an integral number is an int, others a float64, and lists and objects stay lists and maps.
• Variables: data is the template data — the front matter's own data overlaid by slides.hcl's, --data files and --set — so "${data.company}" works wherever {{ .company }} would. Front-matter attributes may reference data.* but not each other; spot directives (_class…) are not HCL identifiers, so write them in a comment.
• Functions: page() and total() (the page number and the last page number, as {{ page }} and {{ total }}), now() and timestamp() (RFC 3339, local and UTC), env(name), and file(path), which reads a UTF-8 text file of at most 1 MiB relative to the deck or configuration file. From go-cty's standard library: abs ceil floor log max min parseint pow signum, chomp format formatlist join lower regex regexall regexreplace replace split strlen strrev substr title trim trimprefix trimspace trimsuffix upper, chunklist coalesce coalescelist compact concat contains distinct element flatten keys length lookup merge range reverse slice sort values zipmap, csvdecode jsondecode jsonencode, formatdate timeadd. None reaches the network.
• An HCL value is final: Go templates do not run over it a second time. The deck body stays a Go template.
• Errors carry HCL's diagnostics, positioned in the deck file itself. footer = data.compnay on the deck's fourth line gives deck.md:4:14: Unsupported attribute: This object does not have an attribute named "compnay".
• Marp reads ---hcl as the start of a front matter too (its rule opens on any first line beginning with three dashes) and, the block not being a YAML mapping, applies none of it: testdata/oracle/hcl-frontmatter.md pins this against Marp Core. slides expand writes the front matter back as YAML, so the expanded deck is plain Marp.
• Directive comments (<!-- class: invert -->) stay YAML, as in Marp.

Command line

slides [build] [flags] deck.md...  write the presentation as HTML
slides [build] [flags] -I dir      ... every deck under dir, mirrored under -o
slides expand  [flags] deck.md     print plain Marp Markdown
slides notes   [flags] deck.md     print the speaker notes
slides kinds   [flags] deck.md     list the kinds and what they set
slides themes  [--theme-set ...]   list the themes
slides version                     print the version (also --version)
slides completion bash|zsh|fish|powershell

Flags may come before or after the deck. slides <command> --help lists a command's flags. build takes several decks, a directory (its decks, found recursively) or a pattern; -o then needs -I, or -. Unlike marp-cli, standard input is read only for -, not whenever it is a pipe.

# slides.yaml
kinds: kinds.yaml        # or a mapping, or a list of files
themes: [themes/acme.css]
data: {company: ACME}    # or file paths
html: false
lang: en

# slides.hcl, the same in HCL
kinds  = "kinds.hcl"
themes = ["themes/acme.css"]
data   = { company = "ACME", year = 2026 }
html   = false
lang   = "en"
kind "quote" {
  extends = "blank"
  footer  = "${data.company} ${data.year}"
}

The HTML page is self-contained. Navigate with the arrow keys, Space and PageUp/PageDown, f toggles full screen, a click advances, and the URL hash names the slide. Fragments reveal one at a time. Printing gives one slide per page.

Transitions and the presenting page

<!-- transition: fade 1s --> (or _transition: for one slide) is marp-cli's directive: a built-in name (fade, slide, cover, cube, swipe, zoom, … 33 of marp-cli's, their keyframes generated from its bundle by internal/cmd/gentransitions) and an optional duration. The <section>s carry data-transition and data-transition-back as marp-cli writes them (compared with its output), and the page plays the transition with the View Transition API around the change of slide — leaving the slide that has it, and, going back, coming to it — where the browser has the API, with a plain fade when the viewer asks for reduced motion. Keyframes of a theme's own (marp-transition-NAME) are found by name in the page's styles as marp-cli's runtime finds them; marp-cli's rewriting of a name for scoped keyframes is not done. The on-screen controller (previous, page, next, full screen) shows while the pointer or a key moves and hides after 2.5 s. --bespoke.progress, --bespoke.osc=false, --bespoke.transition=false and --template bare choose what the page has. The page was driven in headless Chrome to check it.

Configuration files. marp-cli's .marprc, .marprc.json, .marprc.yaml, package.json (the marp key) and the --config-file file are read when they are JSON or YAML, from the working directory only (marp-cli's search does not look in the parents; marp.config.json is only loaded by --config-file). marp.config.js and the other JavaScript or TypeScript files are programs, which slides does not run: it says so. Options that mean something here (title, theme, themeSet, html, inputDir, output, bespoke, template, pdfOutlines ...) are applied under the flags, and paths are relative to the file; engine, options and browser* have no meaning without Marp's engine and a browser and are ignored with a warning.

Watch, serve, preview

--watch, --server and --preview are marp-cli's, with its routes, query keys and live reload protocol (read from its 4.5.1 sources), and with the security a local server needs:

• --server dir serves the directory: files as they are, decks converted per request (?pdf, ?pptx, ?png, ?jpg, ?notes; the PPTX comes as an attachment; a failing deck answers 503 with its message), index.md or PITCHME.md as a directory's page, else a listing with links to each deck's PDF and PPTX. Pages open a WebSocket to /.__marp-cli-watch-notifier__/<id> and reload when the deck, or anything under the directory, changes. At most a few decks are converted at once.
• Bound to the loopback (marp-cli listens on every interface). --host changes it and warns. The Host header must be a loopback name (or the host it listens on), which stops DNS rebinding; a WebSocket's Origin must be the server's own; cross-site subresource requests (<script src>, fetch) are refused by their Sec-Fetch-* headers. A path is cleaned, its symbolic links are resolved and the result must be inside the directory (.. and a link out of it are refused, ?pdf included); dotfiles (.git, .env) are never served; only GET and HEAD are answered.
• --watch builds again the deck that changes and, if a theme, kinds, data or configuration file changed, all of them; a deck that fails is reported and watched still. The pages it writes open a socket on a loopback port (37717 or the next free one) whose address holds the SHA-256 of the deck's path; the socket accepts the null origin of a file page and the loopback's, nothing else.
• --preview opens the default browser (open, xdg-open, rundll32) on the server, or on the HTML pages just built (the first only when there are more than three decks). There is no window of its own: unlike marp-cli's, which drives Chrome, slides has none to drive.

Images and PDF without a browser

Marp CLI drives a headless Chrome for its PDF and image output. slides uses the go-* libraries instead:

• go-webengine lays out and paints each slide. The slides go through the box frame (deck.FrameBox), which needs neither <foreignObject> nor generated content: the theme's section::after is lowered to a real element carrying its evaluated content.

• go-pdfkit writes the PDF: one page per slide at the slide's size, and an outline of the slides and their headings. The pages are vectors: go-webengine draws the laid-out slide through its pdfcanvas instead of into pixels, so the text is text in the fonts it was laid out with (subset-embedded, selectable, searchable), backgrounds, borders and gradients are paths and shadings, an image used on many slides is embedded once, and links are clickable. An element with no vector form here (opacity, a filter, a blurred shadow, a fading gradient) is drawn as a bitmap of that element only, its text kept selectable over it; formulas are still bitmaps. --pdf-raster writes one image per page instead.

• The fonts the built-in themes ask for (Lato, Roboto Mono) come from go-opentype/fonts, embedded, so no render touches the network.

• --image-scale 2 renders at two device pixels per CSS pixel (2560×1440 for 16:9). Text and vectors are drawn at that density, not enlarged.

• Local images are refused unless --allow-local-files is given, as with marp-cli. Even then, only files under the deck's directory are read: a deck from elsewhere cannot reach ~/.ssh.

Several and split backgrounds (![bg left:40%]) render as Marp's layers do.

Slides render four at a time and are written as they come, so a long deck is never held in memory as images. Against marp-cli 4.5.1 on the same machine, a 100-slide deck exports to PNG in 0.97 s against 5.4 s and to PDF in 0.31 s against 1.8 s, in a ninth of the memory; the PDF is 758 KiB against marp-cli's 837 KiB (10 MiB when its pages were images). See BENCHMARKS.md.

Lato (Regular, Bold, Black) and Roboto Mono (Regular, Bold) are embedded upright and italic, so gaia's headings, code and emphasis render with their own faces.

Math and code

• Math: $…$ inline and $$…$$ display, with Marp Core's delimiter rules (a $ followed by a space does not open, one followed by a digit does not close). Formulas are typeset by go-tex/math (STIX Two Math) into inline SVG sized in em, so they follow the text's size and sit on its baseline, in the HTML as in images and PDF. A formula that does not parse stays visible as written.
• Code: fenced blocks are coloured by go-rouge in highlight.js class names, which is what Marp's themes style. A language go-rouge does not know is written as plain text, as Marp Core does.

PowerPoint and OpenDocument

--pptx writes the deck through go-ooxml's WritePresentation, and --odp through go-odf's, with the speaker notes and the deck's title, author, description and keywords.

The slides are editable — marp-cli's PPTX is one picture a slide. Each slide is drawn from its layout, the one the PNG and PDF exports draw, by go-webengine's officecanvas: one text box per line of text, in the fonts the slide was laid out with (embedded in the file, so the slide looks the same on a machine without Lato or Inter), with bold, italic, colours, letter spacing and links; backgrounds, borders and rounded boxes as shapes; gradients as gradient fills (as pictures in the ODP, whose gradients have two colours); pictures stored once however many slides show them. What a slide cannot express — an element under opacity, a filter, a blurred shadow, a formula — is a picture of that element, its text kept over it. Rendered back by LibreOffice, a slide is within 0.04–2 % of the PNG export's pixels (go run ./internal/cmd/officecheck).

--pptx-raster and --odp-raster write one picture a slide instead, as before. Pictures render at scale 2 unless --image-scale says otherwise.

Fitting headings

# <!-- fit --> Title scales the heading so its one line fills the slide's width, up or down, as Marp Core does. The HTML page and the image, PDF and PPTX outputs all run the same small script: it measures the heading's natural width and scales its font size by the ratio. Only slides with a fitting heading run a script when exporting.

Emoji

Emoji shortcodes (:smile:, :+1:, :heart_eyes:: markdown-it-emoji's 1,903 names, which are the ones Marp Core knows) and Unicode emoji (😄, 👩‍💻, 🇫🇷, 1️⃣) become Twemoji images, exactly as Marp Core writes them:

<img class="emoji" draggable="false" alt="😄" src="data:image/svg+xml;base64,…" data-marp-twemoji=""/>

Marp Core's src is a CDN URL, which a deck shown offline, printed or turned into a PDF cannot fetch; here it is a data: URI of the SVG, taken from the embedded set of go-icons/twemoji (2 MB compressed, read lazily: a deck without emoji pays nothing). The rule that sizes the image (img[data-marp-twemoji], one em) is added to the theme as Marp Core adds it. HTML, images, PDF, PPTX and ODP all draw them. The SVG is rasterised by go-webengine through go-gfx/oksvg, the fleet's fork of oksvg with clipPath and correct multi-set arc commands: all 4,009 graphics are drawn, and the ones that srwiley/oksvg got wrong (🪇, about 200 in all) match Chrome.

The rules are Marp Core's, pinned by testdata/oracle/emoji.md:

• Shortcodes are recognized in text, not in code; Unicode emoji are also converted inside code spans and blocks, as Marp Core does.
• Text-default characters (© ™ ✔ ▶) stay text unless followed by U+FE0F (✔️); ❤ is the exception. A U+FE0E after an emoji keeps it text.
• A heading's id and outline use the emoji a shortcode stands for.
• --no-emoji (Config.NoEmoji, Marp Core's emoji: false) leaves all of it as text.

Where it differs, it converts more: ✌️ ☝️ ✍️ 🏋️ and a few other text-default characters that Marp Core's emoji-regex leaves as text. See the twemoji README.

Attribution. The graphics are Twemoji, Copyright 2020 Twitter, Inc and other contributors, licensed CC-BY 4.0, continued by the jdecked/twemoji project. Decks that show them should credit them.

Packages

The VS Code extension runs editor compiled to WebAssembly: decks preview in VS Code's Markdown preview, on vscode.dev too, with problems, completion and export through slides.

License

BSD-3-Clause. The built-in themes in theme/marp are Marp Core's, under its MIT license (theme/marp/LICENSE). The emoji graphics are Twemoji, CC-BY 4.0 (see Emoji).

HCL support links hashicorp/hcl/v2 (MPL-2.0, used unmodified as a library) and zclconf/go-cty (MIT).