diekershoff.net

/pub/diekershoff/tobias

AsciiDoctor + reveal.js

software #asciidoctor #revealjs #talk #fsfe
Estimated time to read: 8 min.
So 13 Januar 2019

Lately I developed a liking for generating slides and handouts for talks I do with AsciiDoctor and reveljs. Probably rooted in my liking of working with AsciiDoctor to produce PDF, ePUB and HTML files from a single source. Here I’d like to present my setup for doing so.

Ingredients

The three ingredients for this tool chain are AsciiDoctor, reveal.js and deck2pdf. Though deck2pdf is only needed if you need a PDF version of the slides.

AsciiDoctor is a markup processor written in Ruby, that compiles asciidoc files and creates various output formats. There are different backends for AsciiDoctor for the different output formats. By default it can produce files in HTML, DocBook and manpages. But there are also backends for PDF, ePUB and presentations employing the revealjs framework. Asciidoc is easier to use then LaTeX, similar to Markdown, but more powerful compared with the latter.

Revel.js is a framework for HTML5 presentations. It is really flexible and can easily written manually to create slides and speaker notes. But with asciidoctor-revealjs one can produce the slides of the talk and the handout from a single source file.

Deck2PDF is a converter for slides from different HTML5 presentation frameworks to PDF.

For me, what was a new, enjoyable experience, was that working with AsciiDoctor and revealjs led to a totally different workflow. In school and at university, preparing a talk basically started with a set of empty slides. Which then had to be filled with content.

The last couple of talks was more like writing an essay about a topic. Once the basic structure was ready, I started adding output especially for the reveal.js backend at fitting spots within the essay. Sure I chose a number of slides appropriate to the target length of the talk. But I was never able to achieve such an organic evolution of the content of the slides before.

So. the result of essay, slides and speaker nodes felt much more as they belonged together, then talks I’ve done in the past using classic tools like LaTeX of LibreOffice Impress and a separate document for the speaker notes. And for some reason I don’t really understand, I did not start to fix the placement of the slides elements as I did with those classic tools.

Setup

So what is my setup for creating the slides and the handout for the talks.

First install asciidoctor-pdf (github) and asciidoctor-revealjs (github) as described at the projects documentation. Which initials a directory for the talks. I also clone the revel.js as described in the optional step 4 of the installation instructions. Mainly because I like to work offline and maybe apply a custom theme.

Additionally I have created a sub-directory for the images that will be used in the slides. Lets call it images. For my FSFE color inspired theme for revealjs, I’ve added a image for the footer in that directory.

So I end up with a directory structure like this, for the *project: my_awesome_talk_:

my_awesome_talk
+- images
|  +- all_the_images_used
|
+- reveal.js
|  +- (clone of the revealjs repository)
|  +- css
|     + theme
|       +- fsfe.css
|
+- Makefile
+- handout.pdf
+- index.html
+- talk.adoc
+- slides.pdf

Basic AsciiDoctor document

A basic document for a talk. The first 4 lines define the title page content of the generated files. They are followed by a bunch of options to define some behaviour. The nice thing about these is, that AsciiDoc(tor) decided to have them human read and understandable.

I already use the ifdef::backend-pdf[] ... endif::bakcend-pdf[] blocks in the header to have some of the lines only interpreted when using the specified backend of AsciiDoctor. You can also use ifndef::backend-revealjs[] ... endif::backend-revealjs[] to select all but the revealjs backend of AsciiDoctor.

Up to the first header, in this case the == About Me you’ll find the preamble text. I use it e.g. to give a temporal context, like for the last talk about secure passwords and their management (PDF slides DE) some links about the Doxing that took place in the beginning of the year 2019 in Germany.

The About Me section contains three parts. The one used for the HTML5 presentation, including a part that is prepared as speaker notes with reveljs. And the part that is used for any other backend/output format.

= Awesome Topic: and the Subtitle
Tobias Diekershoff <tobias/.)diekershoff(at)gmx(.)net>
v1.0, Date of the talk, and event
:subject:   The subject of the talk
:keywords:  Some.Keywords,For,The,Talk
:imagesdir: images
:icons:     font
:icon-set:  fs
ifdef::backend-pdf[]
:toc:
:pdf-page-size:         A4
endif::backend-pdf[]
ifdef::backend-html5[:toc: left]
ifndef::backend-revealjs[ :source-highlighter:  coderay]
ifdef::backend-revealjs[]
:source-highlighter:    highlightjs
:revealjs_transition:   convex
:revealjs_theme:        fsfe
:revealjs_center:       false
:revealjsdir:           reveal.js
endif::backend-revealjs[]

ifndef::backend-revealjs[]
Here goes the preamble for the handout.
It will not be included in the reveljs slides. 
endif::backend-revealjs[]

== About Me

ifdef::backend-revealjs[]
[NOTE.speaker]
--
Some Word about me

* I'm from Berlin/Germany,
* GNU/Linux user since mid 90s,
* FSFE Supporter, and 
* member of the Friendica developers team.
--

image::Southpark-Tobias-transp.png[my default profile picture]

Tobias Diekershoff

FSFE Fellow,
Friendica Entwickler
endif::backend-revealjs[]
ifndef::backend-revealjs[]
About the author.
Tobias was born in the western part of the divided Berlin.
He is a GNU/Linux user since the mid 90s of the last century.
He is a FLOSS enthusiast and FSFE supporter.
And he is member of the Friendica development team, mostly caring about the translations and documentations.
endif::backend-revealjs[]

By adding a new H2 section with == Section 2 you create a new slide horizontally next to the other H2 section slides. With a H3 section (=== Section 3) you add a slide vertically beneath the current one.

To use the speaker notes feature of revealjs start a web server with ruby (sounds more scary then it is) and open the page in the browser.

ruby -run -e httpd . -p 5000 -b 127.0.0.1

Then open 127.0.0.1:5000 in the browser of your choice and hit the s key. A new browser window will open the speaker notes. Displaying the current slide with your notes, and the upcoming slide. You can select different layouts of the speaker nodes. When you skip through the slides in the speaker notes window, this will also change the slide displayed in the initial browser window. So you can put that on the beamer and use your notebook as remote control.

Compiling slides and handout

So writing a document with AsciiDoc(tor) is basically writing a plain text file. Add some formatting for headers, image inclusion, hyperlinks and so on. Finally you compile the plain text file to various output formats like PDF or ePUB.

In the context of talks, this is the handout as a PDF file and the presentation as HTML5 file using the revealjs framework.

As I’m lazy and don’t want to memorize the commands to compile the output files, I’m using the make / Makefile mechanism.

Here is an example for such a Makefile. By default, calling make will create the HTML5 slides and the PDF version of the handouts. But it also contains sections to compile the handout to ePUB or HTML. Furthermore there is a target deckslides which employs the deck2pdf tool to produce a PDF version of the slides.

MAIN=securepwd.adoc
QUELLEN=
OPDF=handout.pdf
OEPUB=handout.epub
OHTML=handout.html
OSLIDES=index.html
OPT=
# Path to deck2pdf 
DECKPDF=../../deck2pdf/tmp/bin/deck2pdf
DECKOUT=slides.pdf

# What to do, when make is called without parameters
all: pdf slides

# remove the output files
clean:
        rm $(OPDF) $(OEPUB) $(OHTML) $(OSLIDES) $(DECKOUT)

# generate the slides of the talk
slides: $(QUELLEN)
        bundle exec asciidoctor-revealjs -o $(OSLIDES) $(MAIN)

# generate Handouts in various formats
pdf: $(QUELLEN)
        asciidoctor $(OPT) -r asciidoctor-pdf -b pdf -o $(OPDF) $(MAIN)

epub: $(QUELLEN)
        asciidoctor $(OPT) -r asciidoctor-epub3 -b epub3 -o $(OEPUB) $(MAIN)

html: $(QUELLEN)
        asciidoctor $(OPT) -r asciidoctor -b html5 -o $(OHTML) $(MAIN)

# use deck2pdf to convert the revealjs presentation to PDF file
deckslides: $(QUELLEN)
        $(DECKPDF) --profile=revealjs index.html $(DECKOUT)

PDF version of the slides

As mentioned above the Makefile contains a target to create a PDF version of the slides. The PDF file is created using the deck2pdf JavaFX based tool. What this tool does is basically open the HTML file in a separate browser and save screenshots of the slides into the output PDF file.

This approach is working, though I stumbled over two quirks.

  1. Links in the HTML5 version of the talk are not hyperlinked anymore. This means that readers of the PDF slides cannot simply follow the link. So either spell out the URL of the link (painful in some cases) or have those links available in the handlout as well, as asciidoctor-pdf includes the links hyperlinked.
  2. The window size of the browser defines the space available to the slides. Hence it is important to maximize that browser while the conversion to PDF is in process.

Result

So running make slides gives me a nice set of slides for the talk. The last ingredient that was missing for my talks at the meetups of the local FSFE group, where I do most of my talks, was a FSFE color inspired theme for revealjs. So I have taken the white theme that is shipped with revealjs and applied FSFE colors to header elements, links and emphasised text (both strong and em). One thing that was missing from the slides was a nice footer line, holding a logo, my name and the event.

With plain HTML5 using the revealjs framework, this would not have been much of a problem. But as I generate the slides using the asciidoctor backend for revealjs my solution (for now?) was to add an image to the body element (more precise body:after)) of the HTML page that holds the slides. I don’t really like this solution, as the image has to be updated for every talk as the content is not applied dynamically. And because it adds content to the slides by styling them, thus breaking the barrier between code, content and style. But at least it works ;-)

Screenshot of a generated slide with my FSFE inspired theme applied to the asciidoctor-revealjs output

The blue highlighted text is strongly emphasized, the green text is simply emphasized.

If you are interested, you can find my FSFE color inspired theme for revealjs at git.fsfe.org in my talks repository there. Save it into the reveal.js/css/theme directory of you revealjs clone alongside the other themes that are shipped with revealjs.

Have fun!


theme last update

november 2017

License

Unless otherwhise noted the contents of this homepage are governed by a Creative Commins license (CC-BY) that essentially means you may use my content to remix it into your work but name me.

Contact

You can send me an email to tobiasdiekershoff.net or see the imprint for further contacts channels.

Made with

Powered by Pelican. Theme inspired by Bootply using the Sandstone color schema.