darkslide 4.0.1

Overview

Landslide generates a slideshow using from markdown, ReST, or textile. It builds off of Google’s html5slides template.

The following markdown produces this slideshow.

# Landslide

---

# Overview

Generate HTML5 slideshows from markdown, ReST, or textile.

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

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

- HTML5
- Javascript
- CSS

---

# Code Sample

Landslide 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

Installation

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

$ pip install landslide

If you want to stay on the edge:

$ git clone https://github.com/adamzap/landslide.git
$ cd landslide
$ python setup.py build
$ sudo python setup.py install

Formatting

Rendering

• Run landslide slides.md or landslide slides.rst

• Enjoy your newly generated presentation.html

Or get it as a PDF document if PrinceXML is installed and available on your system:

$ darkslide README.md -d readme.pdf
$ open readme.pdf

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 current slide context (previous and next slides)

• Press e to make slides filling the whole available space within the document body

• 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)

• Press ‘3’ to toggle pseudo-3D display (experimental)

• Browser zooming is supported

Commandline Options

Several options are available using the command line:

-h, --help            show this help message and exit
-c, --copy-theme      Copy theme directory into current presentation source
                      directory
-b, --debug           Will display any exception trace to stdin
-d FILE, --destination=FILE
                      The path to the to the destination file: .html or .pdf
                      extensions allowed (default: presentation.html)
-e ENCODING, --encoding=ENCODING
                      The encoding of your files (defaults to utf8)
-i, --embed           Embed stylesheet and javascript contents,
                      base64-encoded images in presentation to make a
                      standalone document
-l LINENOS, --linenos=LINENOS
                      How to output linenos in source code. Three options
                      availables: no (no line numbers); inline (inside <pre>
                      tag); table (lines numbers in another cell, copy-paste
                      friendly)
-o, --direct-output    Prints the generated HTML code to stdin; won't work
                      with PDF export
-q, --quiet           Won't write anything to stdin (silent mode)
-r, --relative        Make your presentation asset links relative to current
                      pwd; This may be useful if you intend to publish your
                      html presentation online.
-t THEME, --theme=THEME
                      A theme name, or path to a landlside theme directory
-v, --verbose         Write informational messages to stdin (enabled by
                      default)
-w, --watch           Watch the source directory for changes and
                      auto-regenerate the presentation
-x EXTENSIONS, --extensions=EXTENSIONS
                      Comma-separated list of extensions for Markdown

Presentation Configuration

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

[landslide]
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 [landslide] 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:

# My Slide Title

.notes: These are my notes, hidden by default

My visible content goes here

.qr: http://github.com/adamzap/landslide

.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 landslide.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 landslide

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

g = landslide.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

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

$ darkslide slides/

$ darkslide slides.md -o | tidy

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

$ darkslide slides.md -i

$ darkslide slides.md -d presentation.pdf

$ darkslide slides.md -x abbr

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

$ darkslide slides.md -t /path/to/some/theme --copy-theme

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

If you intend to publish your HTML presentation online, you’ll have to use the --relative option, as well as the --copy-theme one to have all asset links relative to the root of your presentation;

$ darkslide slides.md --relative --copy-theme

That way, you’ll just have to host the whole presentation directory to a webserver. Of course, no Python nor PHP nor anything else than a HTTP webserver (like Apache) is required to host a Darkslide presentation.

Here’s an example.

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 PDF, modify the css/print.css

Authors

Darkslide v4.0.1 (2017-10-19)

• Fixed print css a bit.

• Fixed missing scrolling to current when changing slides while in overview mode.

Darkslide v4.0.0 (2017-10-17)

• Dropped MathJax support. Something less to maintain (also, didn’t work as expected with --embed). User that need this should just use the user_js option. Or a custom theme.

• Changed themes to use a space-adjusted Alegreya Sans as a fallback.

Darkslide v3.2.0 (2017-10-17)

• Changed themes to use Rosario as a fallback. For better or worse it’s smaller and has same width as Candara.

Darkslide v3.1.0 (2017-10-17)

• Changed themes to embed a Candara fallback webfont (Alegreya Sans). It’s slightly narrower but looks more similar than the other alternatives better matching Candara’s width (Acme, Galdeano). It even has ligatures.

Darkslide v3.0.1 (2017-10-15)

• Fixed slightly broken slide class changing.

• Made expose mode scroll to current slide.

• Running presenter mode with no target won’t break anymore if target window is gone.

• Fixed display of presenter notes.

Darkslide v3.0.0 (2017-10-05)

• Removed “expanded mode”. It was too buggy and doesn’t really have a purpose.

• Changed “show context” to be “show next slide” (so two slides at a time). This is way more useful than showing little bits of next and prev slides.

• Fixed --direct on Python 3.

• Fixed glitches when TOC/Help are open.

• Made possible to switch slides when TOC/Help/Overview are open.

Darkslide v2.3.3 (2016-05-15)

• Fixed height of QR svg elements.

Darkslide v2.3.2 (2016-04-12)

• Fixed underline occlusion shadows in the footer (for links).

• Fixed missing presenter_notes class not being set when notes mode was on.

Darkslide v2.3.1 (2016-02-08)

• MathJax is loaded on HTTPS.

Darkslide v2.3.0 (2016-02-07)

• The Darkslide version is shown in the help sidebar.

Darkslide v2.2.1 (2015-10-06)

• Fixed config file parsing for math_output.

Darkslide v2.2.0 (2015-10-06)

• Now macro failures abort rendering. Previously they would just log a message that you’d probably woulnd’t notice.

• Fixed broken handling where you have css/js in the cfg file.

• Allowed setting the math_output option in the cfg file.

• Fixed encoding issues in the QR macro.

• Added back the old theme with completely black background (as “void”).

• Tweak the faux underlines to look better.

Darkslide v2.1.0 (2015-10-05)

• Added demo links.

• Fixed options handling. Options from command line now will actually work if a cfg file is used.

• Corrected relative paths handling:

  • paths in sources are now relative to the cfg file (previously they were relative to whatever was cwd).

  • relative option now correctly works when destination file is not in cwd.

• Fixed layout of slides with many headering (no more paddings for headings, all root elements are spread out evenly anyway).

• Fixed bad styling of ToC (and probably other things in the sidebar).

• Fixed ToC links (contributed by Cyrille Pontvieux).

Darkslide v2.0.4 (2015-09-09)

• Improved handling for filenames that have non-ascii characters in them.

Darkslide v2.0.3 (2015-09-08)

• Fixed handling for filenames that have non-ascii characters in them.

Darkslide v2.0.2 (2015-07-20)

• Added color classes in the abyss theme.

• Fixed link underlines in the presenter notes.

Darkslide v2.0.1 (2015-07-19)

• Don’t use Monaco in the base.css - it’s way bigger than Consolas and the other fonts. And Consolas is nice enough.

Darkslide v2.0.0 (2015-07-17)

• Fix display of RST image target links.

• Add cmd line option to print version.

• Rewrote the default theme (solarized colors)

• Overhauled the abyss theme, improved the coloring.

• Removed all the other themes (they are ugly and broken anyway) (backwards incompatible).

• Fixes for print css.

• Added support for two new css files: base.css and theme.css. This makes reusing styles acros themes and kinds of display (print/screen) more easy.

• Expanded mode is now activated by default.

• Changed macros to use compiled regexes.

• Added a footnote macro.

• Changed QR macro to use qrcode library. Now it’s rendered to SVG. The size is removed (backwards incompatible).

Darkslide v1.2.2 (2015-05-22)

• Fix the blank page issue when generating pdfs (via Chrome’s pdf printer).

Darkslide v1.2.1 (2015-05-21)

• Couple minor improvements to Abyss theme.

Darkslide v1.2.0 (2015-05-19)

• Modifier keys flag was not cleared propertly (kb shortcuts were not working anymore after alt-tab etc); now it’s cleared on visibility changes and focus loss.

• Changed expanded mode to automatically hide the context.

• Fixed window resize flickering (for every resize event the expaded flag was toggled).

• Disabled context hiding in presenter view.

• Other small styling improvements.

• Added “abyss” theme.

Landslide v1.1.3

• Identify each slide by a numbered class (#171) (dkg)

• Fix theme image embedding regex to grab all images (#170)

• Fix blockquote font size for rst (#161)

• Fix display of RST image target links (#87)

• Fix relative path generation (#147)

• Add command line option for print version (#135)

• Add use of ‘—’ as a slide separator to textile files (#163)

• README improvements (#88 and #101)

• Improve image path regex and replacement (#177)

Landslide v1.1.2

• Add support for Python 3

• Allow support for copy_theme argument in CFG files (#139) (syscomet)

• Improve MathJax rendering for Markdown files

• Support math output (#144) (davidedelvento)

• Allow presenter notes in slides with no heading in RST files (#141) (regebro)

• And more…

Landslide v1.1.1

Fixes

• Don’t accidentally require watchdog (#134)

Landslide v1.1.0