presentations

Official Docker Training

Overview

This repository contains all of the modules and presentation definition files for the official Docker training programs.

This content is compiled and served using the docker-present RevealJS controller located here: https://github.com/docker-training/docker-present

Modules and Presentations

Separating content, presentation definitions, and templating provides several advantages over creating one-file RevealJS presentations.

• All content is split into separate smaller modules. One topic or concept per module. Examples:

  • Introduction to Docker
  • Installing Docker
  • Container Concepts
  • Dockerfiles
  • etc...

• Presentation definition files are created to specify which modules will be compiled into a final presentation. These are plain text files with a list of modules (in order) to compile into the final presentation.

• Theme/Templating updates: All presentations use one common theme (Want to change or update your theme? - Edit the base html/css and all presentations are automatically updated). See the templates section in the docker-present README.md

Structuring projects this way makes it quick & easy to remove/include different topics/modules for talks or presentations. Much quicker than creating new presentations by copying & pasting sections of slides from existing presentations.

Project Structure

kizbitz@docker:/git/docker.inc/presentations$ tree
.
├── contents.md
├── CONTRIBUTING.md
├── LICENSE
├── MAINTAINERS.md
├── modules
│   ├── example1
│   │   ├── images
│   │   │   └── small_v.png
│   │   └── slides.html
│   ├── example2
│   │   ├── images
│   │   │   └── small_v.png
│   │   └── slides.md
│   └── example3
│       └── slides.html
├── presentations
│   ├── presentation1
│   ├── presentation2
│   └── presentation3
└── README.md

Important files and directories:

• contents.md: Table of contents for Presentations and Modules
• modules directory: Directory containing all separate modules
• presentations directory: Directory containing the presentation definition files
• CONTRIBUTING.md: Contributing guidelines

Creating new modules

To create a new module:

• Within the existing modules directory create a subdirecty with the name of your topic
  • cd modules
  • mkdir docker-orchestration
  • cd docker-orchestration
• Create either a slides.md or a slides.html (Only one per module, but whichever you prefer)
  • touch slides.md
• If your module will include any images, create a subdirectory for your images. All images will be stored in this directory
  • mkdir images

Your final directory structure for your new module should look like:

kizbitz@docker:/git/docker.inc/presentations$ tree modules
modules
├── docker-orchestration
│   ├── images
│   │   └── image1.png
│   │   └── image2.png
│   └── slides.md

HTML or Markdown?

There are advantages and disadvantages to both:

Markown:

None of the advanced features of RevealJS are available (Using background images, transistions, etc...) but:

• It's easier to read
• Quicker to create, edit, and modify
• Rendered correctly in Github (incuding images)

HTML:

The full range of RevealJS features available for use but:

• It's harder to read and more time consuming to create, edit, and modify
• Images are not rendered when viewing the file in Github

Using a slides.md (markdown) file

The following rules apply when using markdown (slides.md):

• Embedded images always use the format/path: ![name](images/filename.png) - This will always display correctly in Github and the controller will modify the path before serving the presentation
• To separate slides use three dash characters: ---
• To create vertical slides use four dash characters: ----
• To add speaker notes use Note: - Note: This is an example speaker note

Using a slides.html file

The following rules apply when using an HTML file:

• Embedded images always use the format/path: <img src="images/filename.png"> - The controller will modify the path before serving the presentation
• Important: Because of the way the docker-present controller has been coded the only html required in the slides.html file is the RevealJS <section></section> elements. The controller takes this file and compiles it with any other specified modules into the final index.html file that it serves.

An example slides.html:

vagrant@docker:/git/docker.inc/presentations/modules/example1$ cat slides.html
<section>
    <h1>Example 1</h1>
</section>

<section>
        <h2>Example Image</h2>
        <img src="images/small_v.png">
</section>

<section>
    <h1>Reveal.js</h1>
    <h3>The HTML Presentation Framework</h3>
    <p>
        <small>Created by <a href="http://hakim.se">Hakim El Hattab</a> / <a href="http://twitter.com/hakimel">@hakimel</a></small>
    </p>
</section>

The base HTML template the controller uses is located here: https://github.com/docker-training/docker-present/blob/master/present/templates/index.html

For instructions on modifiying your base HTML template and theme see: Templates

Presentations

To specify the modules to server in your presentations create a plain text file with the name of your presentation in the presentations directory:

kizbitz@docker:/git/docker.inc/presentations$ tree presentations
.
├── presentations
│   ├── presentation1
│   ├── presentation2
│   └── presentation3

Required

The following rules apply when creating your presentation files:

• The first line of the file must be a comment (Line that starts with #) which should be a short description of the presentation
• At least one module name (a subdirectory of modules) must be listed

Optional

• Multiple comment lines (All lines must begin with the # character)
• Blank lines
• Multiple modules listed (One module per line)

Notes:

• Modules will be compiled into the final presentation in the order listed
• The controller will merge all listed modules into the final index.html (whether or not the slides were created using HTML or Markdown)

Example presentations files

If we have 3 modules defined:

kizbitz@docker:/share/git/docker.inc/presentations/modules$ tree modules
modules
├── example1
│   ├── images
│   │   └── small_v.png
│   └── slides.html
├── example2
│   ├── images
│   │   └── small_v.png
│   └── slides.md
└── example3
    └── slides.html

Create a presentation with modules example1 and example3:

kizbitz@docker:/share/git/docker.inc/presentations/presentations$ cat presentation1
# All presentation files require a short description on first line

example1
example3

Create a presentation with modules example3 and then example2 (reverse the order):

kizbitz@docker:/share/git/docker.inc/presentations/presentations$ cat presentation2
# This is my example description

# An extra comment line

example3
example2

or all three modules:

kizbitz@docker:/share/git/docker.inc/presentations/presentations$ cat presentation3
# All modules included
example1
example2
example3

Running a Presentation

To run your presentations refer to the instructons for docker-present