Creating slide presentations has been a necessary part of technical life for a long time, but creating crisp and beautiful slides using the popular traditional tools requires a lot of tedious work. I have always been intrigued by the elegant presentations in Golang community talks, but there was no clear-cut information available on how those beautiful presentations were rendered. In researching, I stumbled upon a Golang package named, not surprisingly, present [1], which renders amazing presentation slides from markup text description. For many years now, present has been my go-to tool for creating and delivering impressive presentations.

Getting Started

There is no separate installation step needed to start using the present utility. It's just a statically linked binary that is grab-and-run; there's no need to set up any other runtime dependencies. You do need the Golang compilation toolchain already set up on your machine if you want to run the present command natively. Alternatively, you can run present out of the box, provided Docker Engine is installed on your machine (which is very common nowadays). I personally took the Docker route to use present without doing any extra work. You can use the Dockerfile (Listing 1) and script (Listing 2) to fetch and run present to display your slides on your local machine.

01 FROM golang:alpine
02
03 RUN apk add --no-cache git \
04   && go get golang.org/x/tools/cmd/present
05
06 COPY run.sh /usr/local/bin/
07
08 ENTRYPOINT ["run.sh"]
09 CMD ["-notes"]

01 #! /bin/sh
02
03 PORT=${PORT_PRESENT:-8888}
04
05 exec present -http "0.0.0.0:${PORT}" -content /src/files "$@"

To create a Docker image from which you can launch present, use the following command:

docker build . -t present

You can also launch the present container to serve your slides from a bind-mounted directory (e.g., files in your current directory), by executing the command:

docker run -d --rm -v ${PWD}/files:/src/files:ro -p 58888:8888 present

Now open your web browser and access localhost:58888 to ensure everything is running to deliver your presentation. Figure 1 shows the present container accessed by its localhost endpoint in my browser. Don't be confused about it not showing a presentation – I'll create the presentation next.

Figure 1: The present home page in a web browser without a presentation.

Slides Basics

Now it's time to dirty your hands with present's slides description language. The preferred way to craft your slides is using the CommonMark markup language [2]. (You can also use legacy syntax [1] to describe your slides, but that's not discussed here.) To start, create a file named mytest.slide (Listing 3) in the bind-mounted ./files directory.

01 # My Test Presentation
02
03 Free Libre Open Source Software Hacker
04 A FLOSS Hacker, FLOSS Universe
05 flosshacker@flossuniverse.com
06 https://url/
07 @flosshacker
08
09 ## TBD

Now refresh your present endpoint browser page, and the newly created slide file link should appear (Figure 2).

Figure 2: After creating mytest.slide, you can now click on a slide deck in the browser.

If you click mytest.slide now, you'll see an elegant three-slide presentation (the first and last slides are shown in Figures 3 and 4). Congratulations, you have created a presentation – without the frustration of dragging and dropping and the impossible formatting in a slide creation tool. You can move between the slides using the left and right arrow keys and also create a PDF using the Ctrl+P print dialog.

The slide description starts with a header block with the presentation topic prefixed with # and a space. Optionally, you could put other metadata such as a subtitle, date, tags, summary, and old URL lines after the #. An optional author block follows the header section, with at least a space in between them. The author block can contain your name, title, email, URL, twitter handle, etc. present automatically renders the last slide with the author block (Figure 4). It only puts author info that is not an email, URL, or twitter handle on the first slide (Figure 3). You could have multiple author blocks, each separated with at least a space between them. Any line starting with // is treated as a comment.

Figure 3: The first slide rendered by present.

Figure 4: The last slide rendered by present.

The presentation slide sections follow the author blocks. A slide section starts with ## followed by at least one space. Each slide could have a subsection too, starting with ### and followed by at least one space. The content of a slide is governed by CommonMark to format text.

To add more content to the slides, update your mytest.slide file with the code in Listing 4 and refresh the browser page rendering the presentation.

01 # My Test Presentation
02
03 Free Libre Open Source Software Hacker
04 A FLOSS Hacker, FLOSS Universe
05 flosshacker@flossuniverse.com
06 https://url/
07 @flosshacker
08
09 ## Free Libre Open Source Software
10 What is [FLOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software)?
11 - anyone is freely licensed to use, copy, study, and change the software in any way
12 - the source code is openly shared so that people are encouraged to voluntarily improve the design of the software
13 - Free as in **freedom**, not _free beer_
14
15 ---
16 > FSF prefers dangerous freedom over peaceful slavery
17
18 ![FSF][1]
19
20 [1]: https://upload.wikimedia.org/wikipedia/commons/thumb/4/4a/Free_Software_Foundation_logo_and_wordmark.svg/260px-Free_Software_Foundation_logo_and_wordmark.svg.png
21
22 type this command in your terminal:
23 ```
24 python -c 'import this'
25 ```
26
27 : intro slide

Now you should see common markup features (bold/italic text, lists, block quotes, links, images, horizontal rules, in-line code, etc.) implemented on your slide (Figure 5). To learn more about these markup features, see the CommonMark documentation [2].

Figure 5: A rendered slide using various common markup features.

Lines starting with a colon are treated as presenter notes. Pressing N in the browser showing your presentation opens a separate pop-up window displaying the notes (Figure 6).

Figure 6: Pressing N in the browser displays a pop-up notes window.

More Enriched Slides

If you want more than text, hyperlinks, and logos in your slides, you can use present description language features to render eye-candy slides. To do this, present provides a number of special commands using invocations. Any line starting with a dot character is an invocation. These commands include adding images, setting background, showing/editing/running code, creating a hyperlink, injecting video, including figure captions, and more. As an example, use the code in Listing 5 to once again update your mytest.slide file content, put the necessary images and sources into your presentation directory, and refresh the browser page rendering the presentation. Figure 7 shows a slide rendered using various invocations.

01 # My Test Presentation
02
03 Free Libre Open Source Software Hacker
04 A FLOSS Hacker, FLOSS Universe
05 flosshacker@flossuniverse.com
06 https://url/
07 @flosshacker
08
09 ## Free Libre Open Source Software
10 What is [FLOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software)?
11 - anyone is freely licensed to use, copy, study, and change the software in any way
12 - the source code is openly shared so that people are encouraged to voluntarily improve the design of the software
13 - Free as in **freedom**, not _free beer_
14
15 ---
16 > FSF prefers dangerous freedom over peaceful slavery
17
18 ![FSF][1]
19
20 [1]: https://upload.wikimedia.org/wikipedia/commons/thumb/4/4a/Free_Software_Foundation_logo_and_wordmark.svg/260px-Free_Software_Foundation_logo_and_wordmark.svg.png
21
22 type this command in your terminal:
23 ```
24 python -c 'import this'
25 ```
26
27 : intro slide
28
29 ## More FLOSS
30 ---
31
32 .background matrix.png
33
34 .image logofsforg.png 50 _
35 .caption FSF Logo
36
37 .code -edit -numbers hellofloss.c
38
39 .play hellofloss.go

Figure 7: A slide rendered using invocations.

The .image invocation optionally takes height and width arguments. If any of these arguments are specified as an underscore, then scaling preserves the aspect ratio of the image. The .background invocation doesn't take any argument except the image. If your image is not big enough, then the background command will fill your slide with a repeated pattern of the mentioned image.

Both .code and .play invocations can strip the unnecessary code from the respective source and only display the necessary portion of the code. The -edit command enables you make modifications in the displayed code during your presentation. The play command displays code with a Run button to run the Go program from the browser.

Now you have enough knowledge to render rich presentations using the present description language. You can explore the full details of the present description language in the package documentation [1]. For more example slides and scripts, check out my GitHub repository [3].