Readme Files That Are Also Slide Decks
I hate doing work twice, don’t you? That’s why I built a Docker container that allows me to write readme files that are also slide decks. Here’s how to do it with Docker and Reveal.js.
I do lots of demo’s. I like to make the code available for those who find them useful. This means I need to write documentation for the code as well slides to support delivery of the demo’s. Most of the content is duplicated across these two documents. They differ only in the level of detail needed. The written word needs full details, the presentation deck needs high level points that I will talk to.
Since the convention, these days, is to weite a README.md file in the root of your projects wouldn’t it be great if we could use Markdown to write a single document that is useful in both cases?
Well now I can. Here’s how.
Reveal.js is a framework for building slide decks in Markdown (or HTML if you prefer). It’s not as feature rich as something like Powerpoint but it’s pretty good, certainly good enough for the kind of presentation I do. Take a look.
I’ve packaged Reveal.js as a Docker container using ONBUILD to allow it to be reused for building self contained presentations that will be delivered via the browser. I’ll describe how to do this in a moment, first a little about what this means for writing slide and longform content.
By default slides come from a readme.md file and looks like this:
Writing Long Form content
You can add long form content by adding a subheading in the form ‘## Details’. Content that follows this heading will not be displayed on the slide, but will be availble in any other markdown rendering of the content. A slide with longform details would therefore look like this:
This results in a document that has some summary information at the start of each section followed by the expanded detail. This format not only allows us to maintain slides and longform in the same document, but it also facilitates speed reading of the longform document.
The following command starts the revealjs container with some default content (which is actually the readme file of the corresponding GitHub project)
Now point your browser at http://yourhost:8000
Creating Your Own Slides
Creating your own presentation container is really easy. First, create a Dockerfile:
Now create your readme.md content as described above.
Build your container:
Start your container:
Navigate to your deck:
You can, of course, use your Dockerfile to make your container behave differently. For example you might choose to use a different markdown file for your slides:
Or you could Reveal.js replace index.html with your own version in order to customize the behaviour of reveal.js.
There is much more to reveal.js than this I’ve covered here See the reveal.js documentation for more.
- Searching for a Cure for Cancer with Docker and Azure
- Load Balancing for Docker Containers with HA Proxy
- Create a Simple Swarm Cluster on Azure with ARM
- Getting Started With Docker Swarm on Azure
- Simple Load Balancing for Docker Containers
- Install Docker and Docker Machine
- Mounting Volumes in Boot2Docker on Hyper-V
- Using Docker Machine to create a Docker Host on Azure
- Experiments With Development Using Docker
- Dockerizing a Jekyll Site