Overview

tests
package

Lightweight markup language (Markdown, ReST, or Textile) slideshow generator. Forked from landslide.

Demo: http://ionelmc.github.io/python-darkslide/

# Darkslide

---

# Overview

Generate HTML5 slideshows from markdown, ReST, or textile.

![python](http://i.imgur.com/bc2xk.png)

Darkslide is primarily written in Python, but it's themes use:

- HTML5
- Javascript
- CSS

---

# Code Sample

Darkslide supports code snippets

    !python
    def log(self, message, level='notice'):
        if self.logger and not callable(self.logger):
            raise ValueError(u"Invalid logger set, must be a callable")

        if self.verbose and self.logger:
            self.logger(message, level)

Requirements

python and the following modules:

jinja2
pygments for code blocks syntax coloration

Markup Conversion

markdown for Markdown
docutils for reStructured Text
textile for Textile

Optional

watchdog for watching/auto-regeneration with the -w flag

Installation

Install the latest stable version of Darkslide with a python package manager like pip:

$ pip install darkslide

If you want to stay on the edge:

$ git clone https://github.com/ionelmc/python-darkslide.git
$ cd python-darkslide
$ python setup.py build
$ sudo python setup.py install

Formatting

Markdown

Your Markdown source files must be suffixed by .md, .markdn, .mdwn, .mdown or .markdown
To create a title slide, render a single h1 element (eg. # My Title)
Separate your slides with a horizontal rule (--- in markdown) except at the end of md files
Your other slides should have a heading that renders to an h1 element
To highlight blocks of code, put !lang where lang is the pygment supported language identifier as the first indented line

ReStructuredText

Your ReST source files must be suffixed by .rst or .rest (``.txt`` is not supported)
Use headings for slide titles
Separate your slides using an horizontal rule (---- in RST) except at the end of RST files

Textile

Separate your slides using ---, just like in markdown

Rendering

Run darkslide slides.md or darkslide slides.rst
Enjoy your newly generated presentation.html

Viewing

Press h to toggle display of help
Press left arrow and right arrow to navigate
Press t to toggle a table of contents for your presentation. Slide titles are links
Press ESC to display the presentation overview (Exposé)
Press n to toggle slide number visibility
Press b to toggle screen blanking
Press c to toggle double slide display (current and next slides)
Press S to toggle display of link to the source file for each slide
Press '2' to toggle notes in your slides (specify with the .notes macro)
Browser zooming is not supported

Commandline Options

Usage:

darkslide [options] input.md ...

Options:

`--version`	show program's version number and exit
`-h, --help`	show this help message and exit
`-b, --debug`	Will display any exception trace to stdout.
`-d FILE, --destination=FILE`
	The path to the to the destination html file. Default: presentation.html.
`-e ENCODING, --encoding=ENCODING`
	The encoding of your files. Default: utf8.
`-i, --embed`	Embed stylesheet and javascript contents, base64-encoded images and objects in presentation to make a standalone document.
`-l LINENOS, --linenos=LINENOS`
	How to output linenos in source code. Three options available: no (no line numbers); inline (inside <pre> tag); table (lines numbers in another cell, copy-paste friendly).
`-m LEVEL, --max-toc-level=LEVEL`
	Limits the TOC level generation to a specific level.
`-M, --mod=MOD`	Comma-separated list of theme modifiers by name. Available: wide16x9, showpagenums.
`-o, --direct-output`
	Prints the generated HTML code to stdout.
`-P, --no-presenter-notes`
	Don't include presenter notes in the output.
`-q, --quiet`	Won't write anything to stdout (silent mode).
`-r, --relative`	Make your presentation asset links relative to current working dir; This may be useful if you intend to publish your html presentation online.
`-t THEME, --theme=THEME`
	A theme name, or path to a darkslide theme directory
`-v, --verbose`	Write informational messages to stdout (enabled by default).
`-x EXTENSIONS, --extensions=EXTENSIONS`
	Comma-separated list of extensions for Markdown.
`-w, --watch`	Watch source directory for changes and regenerate slides.

Presentation Configuration

Darkslide allows to configure your presentation using a cfg configuration file, therefore easing the aggregation of source directories and the reuse of them across presentations. Darkslide configuration files use the cfg syntax. If you know ini files, you get the picture. Below is a sample configuration file:

[darkslide]
; the old [landslide] is still supported
theme  = /path/to/my/beautiful/theme
source = 0_my_first_slides.md
         a_directory
         another_directory
         now_a_slide.markdown
         another_one.rst
destination = myWonderfulPresentation.html
css =    my_first_stylesheet.css
         my_other_stylesheet.css
js =     jquery.js
         my_fancy_javascript.js
relative = True
linenos = inline

Don't forget to declare the [darkslide] section. All configuration files must end in the .cfg extension.

To generate the presentation as configured, just run:

$ cd /path/to/my/presentation/sources
$ darkslide config.cfg

Macros

You can use macros to enhance your presentation:

Notes

Add notes to your slides using the .notes: keyword, eg.:

# My Slide Title

.notes: These are my notes, hidden by default

My visible content goes here

You can toggle display of notes by pressing the 2 key.

Some other macros are also available by default: .fx: foo bar will add the foo and bar classes to the corresponding slide <div> element, easing styling of your presentation using CSS.

QR Codes

Add a QR Code to your presentation by using the .qr keyword:

.qr: https://github.com/ionelmc/python-darkslide

Footnote

Add footnote to the current and all the following presentations

.footnote: Slides available at https://blog.ionelmc.ro/presentations/

Presenter Notes

You can also add presenter notes to each slide by following the slide content with a heading entitled "Presenter Notes". Press the 'p' key to open the presenter view.

Registering Macros

Macros are used to transform the HTML contents of your slide.

You can register your own macros by creating darkslide.macro.Macro derived classes, implementing a process(content, source=None) method and returning a tuple containing the modified contents and some css classes you may be wanting to add to your slide <div> element. For example:

!python
import darkslide

class MyMacro(darkslide.Macro):
  def process(self, content, source=None):
    return content + '<p>plop</p>', ['plopped_slide']

g = darkslide.generator.Generator(source='toto.md')
g.register_macro(MyMacro)
print g.render()

This will render any slide as below:

!html
<div class="slide plopped_slide">
  <header><h2>foo</h2></header>
  <section>
    <p>my slide contents</p>
    <p>plop</p>
  </section>
</div>

Advanced Usage

Setting Custom Destination File

$ darkslide slides.md -d ~/MyPresentations/presentation.html

Working with Directories

$ darkslide slides/

Working with Direct Output

$ darkslide slides.md -o | tidy

Using an Alternate Darkslide Theme

$ darkslide slides.md -t mytheme
$ darkslide slides.md -t /path/to/theme/dir

Embedding Base-64-Encoded Images

$ darkslide slides.md -i

Enabling Markdown Extensions

See documentation on available Markdown extensions here:

$ darkslide slides.md -x abbr

Theming

A Darkslide theme is a directory following this simple structure:

mytheme/
|-- base.html
|-- css
|   |-- print.css
|   `-- screen.css
`-- js
    `-- slides.js

If a theme does not provide HTML and JS files, those from the default theme will be used. CSS is not optional.

Widescreen 16x9

You can create widescreen 16x9 slides using the --mod=wide16x9 option.

User stylesheets and Javascripts

If you don't want to bother making your own theme, you can include your own user css and js files to the generated presentation.

This feature is only available if you use a Darkslide configuration file, by setting the css and/or js flags:

[darkslide]
; the old [landslide] is still supported
theme  = /path/to/my/beautiful/theme
source = slides.mdown
css =    custom.css
js =     jquery.js
         powerpoint.js

These will link the custom.css stylesheet and both the jquery.js and powerpoint.js files within the <head> section of the presentation html file.

NOTE: Paths to the css and js files must be relative to the directory you're running the darkslide command from.

Publishing your Presentation Online

For online publishing use the --embed option to produce a standalone HTML file with no dependencies:

$ darkslide slides.md --embed

Theme Variables

The base.html must be a Jinja2 template file where you can harness the following template variables:

css: the stylesheet contents, available via two keys, print and screen, both having:
a path_url key storing the url to the asset file path
a contents key storing the asset contents
js: the javascript contents, having:
a path_url key storing the url to the asset file path
a contents key storing the asset contents
slides: the slides list, each one having these properties:
header: the slide title
content: the slide contents
number: the slide number
embed: is the current document a standalone one?
num_slides: the number of slides in current presentation
toc: the Table of Contents, listing sections of the document. Each section has these properties available:
title: the section title
number: the slide number of the section
sub: subsections, if any

Styles Scope

To change HTML5 presentation styles, tweak the css/screen.css stylesheet bundled with the theme you are using
For printing, modify the css/print.css