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.
• 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.

Command line

slides [build] [flags] deck.md     write the presentation as HTML
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.

# 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

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.

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 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.

Lato Regular, Bold and Black and Roboto Mono Regular and Bold are embedded, so gaia's headings get their weight. No italic face is embedded yet, so italic text in those families renders upright.

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

--pptx writes the deck through go-ooxml's WritePresentation: one full-slide picture per slide, at the slide's size, with its speaker notes and the deck's title, author, description and keywords. As with marp-cli, the slides are pictures, not editable text. It renders at scale 2 unless --image-scale says otherwise. LibreOffice opens and converts it.

Roadmap

• Emoji, and fitting headings (<!-- fit -->).

Packages

License

BSD-3-Clause. The built-in themes in theme/marp are Marp Core's, under its MIT license (theme/marp/LICENSE).