Write once, present anywhere in every format: preparing an interactive secure coding workshop

It is always very rewarding teaching people the principles behind secure coding, about the OWASP top 10, and how to test web applications for vulnerabilities. Workshops are an excellent format to convey that knowledge, as participants can immediately practice their knowledge which reinforces the theory.

I recently had a situation, where I could not physically attend the workshop itself - and, when you're supposed to prepare and lead that workshop, it presents a challenge. I like challenges!

Usually I present materials using a slidedeck (either PDF or HTML5 format). As I wanted to deliver all materials to the participants beforehand I felt that the slidedeck format wasn't the best 'fit' for this remote workshop. Yes, a slidedeck format works when you're in the 'classroom', presenting, but to actually structure knowledge it is too rigid. Not each diagram or list of 'best practices' is suited for the screen-optimized slideshow screen ratio of 4:3. Therefore I wanted to use a text format which would not only allow me to export the data to a slidedeck as usual, but also to export it to a HTML website.

Most if not all of my documentation is written in plaintext format - or, to be more precise, the Org mode format. Org mode is amazingly well-suited to organize and structure text. It can be exported to almost any format, like HTML, PDF, OpenOffice, Word or Markdown. The universal open source document converter Pandoc also has support for Org mode.

However, it isn't really well suited to build an interactive website with. I wanted at least to have a good website navigation, search capabilities, automatically include output of programs, and a format which allows easy formatting of images. Initially I wanted to use a wiki (Dokuwiki in particular, as it's really versatile, and stores all pages as plaintext). But that has the disadvantage of using a wiki-specific markup language, which makes it more difficult to export to other formats. Markdown is too fragmented to use consistently, and lacks a lot of formatting options.

Example of Dokuwiki markup to right-align an image in HTML:

{{ wiki:dokuwiki-128.png}}

Example of Org mode to right-align an image (when exported to HTML):

#+ATTR_HTML: style="float:right;"

Then I discovered the reStructuredText format. It's plaintext, and also has Pandoc (and Emacs) support, so it can be converted to 'any other format'. Not only that, but the open source tool Sphinx (and underlying docutils) makes it super easy to convert a number of reStructuredText files into an interactive HTML website. It has built-in interactive search capabilities, uses a Jinja-based templating system, comes with out-of-the-box navigation menu's. Sphinx can also convert the same source into an ePub, or PDF file, a slidedeck, or a number of other formats.

Example of reStructuredText to right-align an image in any format:

.. image:: _static/sunny.svg

   :align: center

It allowed me to build a website specifically for the interactive secure coding workshop in no time, so that I could focus on the content instead of on the presentation. As reStructuredText is plaintext it's really easy to work with, and Emacs has built-in support for it. The content can be exported as ePub and PDF, and optionally used as slidedeck, all without having to alter the content or the formatting.

This is an example of reStructuredText, what it looks like:

And this is part of the resulting HTML, when it's converted using Sphinx:

The secure coding / OWASP top 10 workshop went according to plan, and I'm looking forward to convert more workshops, workshop materials and documentation of projects I'm part of to the reStructuredText format. That allows me to switch easier between slidedecks, interactive HTML websites, ePub and PDF formats - all having the same content.

Write once, export to anything.