Creating a presentation¶ ↑

A Showoff presentation is defined by the contents of the showoff.json file in the root of the presentation directory. It contains configuration keys that define metadata about the presentation and describes the slides themselves.

Example showoff.json¶ ↑

The following file describes a simple presentation with only a few slides. It includes all current configuration keys, which will be described below.

{
  "name": "Something",
  "description": "Example Presentation",
  "favicon": "file/favicon-example.ico",
  "protected": [
    "presenter",
    "onepage",
    "print"
  ],
  "validators": {
    "java": "javac",
    "html": "tidy -q -i --show-errors 0"
  },
  "parsers": {
    "erlang": "escript",
    "swift": "xcrun swift"
  },
  "user": "username",
  "password": "password",
  "version": "0.9.10.7",
  "encoding": "ISO-8859-1",
  "feedback": true,
  "ssl": true,
  "ssl_certificate": "/path/to/some/certificate.pem",
  "ssl_private_key": "/path/to/the/corresponding/private_key.pem",
  "edit": "https://github.com/username/presentation/edit/master/",
  "issues": "https://github.com/username/presentation/issues/new?title=",
  "highlight": "atelier-cave.light",
  "author": "Foo Bar John",
  "templates" : {
      "special" : "simple.tpl"
  },
  "pause_msg": "Paused !!!",
  "sections": [
    "Intro/intro.md",
    "Intro/summary.md",
    "Content/first.md",
    "Content/second.md",
    "Conclusion/overview.md",
  ]
}

Configuration Settings¶ ↑

The configuration settings you may use are listed below. Please see the AUTHORING section for more information.

author

The name of the author.

description

A one sentence description.

edit

A link to a web based editor used when started with --review. The path to the currently viewed slide will be appended and the resulting URI will be opened in a new browser tab. This is currently only tested with GitHub.

encoding

The character encoding of the presentation. Defaults to UTF-8.

favicon

The filename of a favicon image to use. Note that you must prefix the filename with file as shown in the example.

If you place a favicon.ico in the root of your presentation, it will be used by default without setting this.

feedback

Enable the interactive feedback features. Defaults to false.

highlight

The highlight.js theme to use for code snippets.

issues

A link to a web based bug reporter. The currently viewed slide will be appended and the resulting URI will be opened in a new browser tab. This is currently only tested with GitHub and Jira.

locked

An array of pages that will require a presentation key entered as a password in the login dialog. If a user has already logged in, that will take precedence and they won't be prompted again.

key

The key for locked pages.

name

A short name for the presentation.

parsers

Define any custom code parsers to run executable code blocks in your slides.

pause_msg

The message to display when paused.

protected

An array of pages that should require a user login. Usually used for the presenter view.

username

The username for protected pages.

password

The password for protected pages.

sections

The slide definitions for the presentation.

ssl

Enable serving the presentation via SSL. If a certificate is not provided, an autogenerated one will be used. Defaults to false.

Warning

When using self-signed certificates, some browsers require that all viewers *permanently accept the certificate* in order for the interactivity features, such as pace feedback, to work properly. Form submissions are not affected.

ssl_certificate

The path to the PEM format certificate file to use. See the note above about self-signed certificates.

ssl_private_key

The path of the private key for that certificate.

standalone

If you set this to true, then audience interactivity features will be disabled.

templates

A hash of templates to be used.

version

The version of Showoff that this presentation requires. It will refuse to start and will display a warning message if the Showoff version is lower.

validators

Define any custom validation scripts to run against code blocks in your slides.

Defining slides using the sections setting.¶ ↑

The sections section contains the description of the slides making up your presentation and the order they should be displayed in. You may either list them in order using an array, or define sections using an array of hashes.

Array configuration listing each Markdown file:

"sections": [
  "Intro/intro.md",
  "Intro/summary.md",
  "Content/first.md",
  "Content/second.md",
  "Conclusion/overview.md",
]

Hash configuration listing each section as a directory of Markdown files:

"sections": [
  {"section":"one"},
  {"section":"two"},
  {"section":"three"},
  {"section":"four"}
]

Hash configuration listing sections as arrays of Markdown files:

"sections": [
  {
    "section":[
      "Intro/intro.md",
      "Intro/summary.md"
    ]
  },
  {
    "section":[
      "Content/first.md",
      "Content/second.md"
    ]
  },
  {
    "section":[
      "Conclusion/overview.md"
    ]
  }
]

Hash configuration including sections from other JSON files:

"sections": [
  {"include":"Intro/section.json"},
  {"include":"Content/section.json"},
  {"include":"Conclusion/section.json"}
]

Each of the referenced JSON files should list Markdown files in an array:

[
  "intro.md",
  "summary.md"
]

Named sections, decoupled from filesystem layout. Notice that the section names don't necessarily match the directory the files are in:

"sections": {
    "Course Overview": [
         "Course_Overview/Course_Intro.md",
         "Course_Overview/Puppet_Certification.md",
         "shared/Table_of_contents.md",
         "Course_Overview/Course_Objectives.md",
         "Course_Overview/Course_Overview.md",
         "Course_Overview/Course_Agenda.md",
         "shared/demo_install.md",
         "shared/Lab-preinstall.md",
         "shared/Lab-install.md",
         "Course_Overview/Class_Architecture.md",
         "Course_Overview/Lab-update_ca.md",
    ],
    "Basics Review": [
         "Core_Concepts/Section.md",
         "Core_Concepts/Objectives.md",
         "Core_Concepts/How_Puppet_Works.md",
         "Core_Concepts/Data_Flow_for_Nodes.md",
         "Core_Concepts/resource_overview.md",
         "Core_Concepts/resource_type_code.md",
         "Core_Concepts/RAL_overview.md",
         "Core_Concepts/RAL_type_provider.md",
         "Core_Concepts/RAL_providers.md",
         "Core_Concepts/resource_imperative.md",
         "Core_Concepts/resource_idempotent.md",
         "Core_Concepts/describe_state.md",
         "Core_Concepts/Lab-create_module.md",
    ],
}

Named sections by including JSON files:

"sections": {
     "Course Overview" : "Course_Overview/virtual.json",
     "Session One"     : "Session_One/sections.json",
     "About Puppet"    : "About_Puppet/sections.json",
}

Running without a showoff.json¶ ↑

When you run Showoff without defining sections, or when you point to a directory instead of individual files, Showoff will enumerate all *.md files and assume that each is a slide file.

Protected presentations¶ ↑

There are two methods to protect your presentations. You can require the user to log in with a username and password, by defining pages in the protected array, or you may require viewers to provide a viewing key by defining pages in the locked array. This key should be entered as the password of the authentication dialog. The username is ignored.

A useful configuration locking down the presenter view and printing to authorized presenter logins, but allowing the audience to view with only a viewing key is:

"key": "{key}",
"user": "{username}",
"password": "{password}",

You can customize exactly which functionality is available to your audience. For example, if you want to restrict access to the presenter, but allow anyone with the viewing key to use the print endpoint to generate a PDF file:

"protected": ["presenter"],
"locked": ["slides", "print"],

If pages are marked as protected or locked, but no corresponding password or viewing key is set, then only the presenter running on the presentation on the same machine they're viewing with will be allowed access.

Custom code execution¶ ↑

Showoff can execute code from your slides and display the output if you start with the proper flags. Parsers are defined for Perl, Puppet, Python, Ruby, and Shell.

You can execute code in any language you like by defining your own custom parsers with the parsers key in showoff.json:

"parsers": {
  "erlang": "escript",
  "swift": "xcrun swift"
},

The parser is passed the path to a temporary file containing the code to be run. stdout and stderr will be displayed in the output dialog.

In-slide code validation scripts¶ ↑

Showoff can validate all the code blocks on your slides by running showoff validate by running validation scripts against each. Validators are defined for Perl, Puppet, Python, Ruby, and Shell.

It's also easy to define your own custom scripts with the validators key in showoff.json:

"validators": {
  "java": "javac",
  "html": "tidy -q -i --show-errors 0"
},

The validator is passed the path to a temporary file containing the code to be checked. Any output is suppressed and a non-zero exit code is considered to be a failure.

Add a class of no-validate to skip validation for a block of code.

@@@ Ruby no-validate
# Do you see the error here?
# The difference between == and = is easy to miss
# and many languages won't warn you about it.
def fibonacci(n)
  raise "undefined" if n < 0
  succ = 1
  curr = 0
  n.times {succ, curr == succ + curr, succ}
  curr
end

Markdown Engine¶ ↑

It is possible to configure the markdown engine of your choice to use with showoff. The following engines are available:

• redcarpet (default)

• bluecloth

• maruku

• kramdown

• rdiscount

• commonmark

You may configure special options of your markdown engine by including an options hash keyed off the markdown engine name in your configuration file. For example:

"markdown" : "kramdown",
"kramdown" : {
   "space_after_headers": true
}

Configuring an engine (or overriding its default configuration) allows you to access special features of that engine.

Default options¶ ↑

Showoff configures default options for some of the Markdown engines. These defaults can be disabled in your showoff.json file if needed.

Defaults for each engine are:

redcarpet

github.com/vmg/redcarpet

"redcarpet" : {
  "autolink"          : true,
  "no_intra_emphasis" : true,
  "strikethrough"     : true,
  "superscript"       : true,
  "tables"            : true,
  "underline"         : true
}

bluecloth

github.com/ged/bluecloth/blob/master/lib/bluecloth.rb

"bluecloth" : {
  "auto_links"        : true,
  "definition_lists"  : true,
  "strikethrough"     : true,
  "superscript"       : true,
  "tables"            : true
}

rdiscount

github.com/davidfstr/rdiscount/blob/master/lib/rdiscount.rb

"rdiscount" : {
  "autolink"          : true
}

Maruku¶ ↑

When you prefer using Maruku as the markdown engine of choice for your presentation, you can use the LaTeX Math Mode features of maruku. First you need BlahTex and then you need to configure your presentation as following:

"markdown" : "maruku",
"maruku" : {
   "use_tex" : true,
   "png_dir" : "images",
   "html_png_url" : "/file/images/"
}

Note that `use_tex` is required, but configuring the `png_dir` and `html_png_dir` are optional.