darkslide 6.0.0
Lightweight markup language-based html5 slideshow generator. Forked from Landslide.
License: Apache-2.0
Requires Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*
Keywords: markdown,slideshow,presentation,rst,restructuredtext,textile,landslide

========
Overview
========



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 <http://en.wikipedia.org/wiki/Markdown>`__
-  ``docutils`` for `reStructured
   Text <http://en.wikipedia.org/wiki/ReStructuredText>`__
-  ``textile`` for
   `Textile <http://en.wikipedia.org/wiki/Textile_(markup_language)>`__

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
                        Specify a theme modifier by name. Available: wide16x9.
  -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:

.. code-block:: ini

    [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: 450|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 <https://pythonhosted.org/Markdown/extensions/index.html>`__:

::

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

**NOTE:** The ``--mod=wide16x9`` option causes the files in Darkslide's ``themes/wide16x9/``
directory to supersede the corresponding files in Darkslide's ``themes/default/``
directory before the selected theme (if any) is applied.

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 <http://jinja.pocoo.org/2/documentation/templates>`__ 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``

Authors
=======

The project was originally named Landslide and was authored by
Adam Zapletal (adamzap@gmail.com) and Nicolas Perriault (nperriault@gmail.com)

Slide code is based on html5-slides.

More details: https://github.com/ionelmc/python-darkslide/contributors

=========
Changelog
=========

Darkslide v6.0.0 (2020-07-24)
=============================

* Dropped the ``--copy-theme`` option (**backwards incompatible**).
* Added support for theme mods (the ``--mod`` option) and reworked the asset management internals.
* Added a wide 16:9 theme mod.
  Contributed by Eric Moyer in `#19 <https://github.com/ionelmc/python-darkslide/pull/19>`_.

Darkslide v5.1.0 (2020-01-13)
=============================

* Added support for embedding webfonts.
  Contributed by Emmanuel Ohayon in `#17 <https://github.com/ionelmc/python-darkslide/pull/17>`_.
* Refactored user css and js path processing code.
* Relativized user css and js paths to the configuration directory (CWD if there's no configuration file).

Darkslide v5.0.2 (2019-12-07)
=============================

* Fixed a small bug in the image embedding feature (image detection in CSS file
  could fail).

Darkslide v5.0.1 (2019-10-01)
=============================

* Fixed media for user css to be always be ``all``. Previously it was ``screen, projection`` if embedded.

Darkslide v5.0.0 (2019-09-29)
=============================

* Removed PDF export support. You should just use the PDF export from
  Google Chrome (it works way better than the alternatives).
* Fixed transitions in presenter mode.
* Added support for Up/Down arrow navigation.
  Contributed by Heiko Schlittermann in `#13 <https://github.com/ionelmc/python-darkslide/pull/13>`_.
* Added support for Markdown 3.0+ and Textile 2.3+.
* Changed the broken ``.notes:`` macro to output presenter notes.

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
================

Major Enhancements
------------------

-  Add CHANGELOG
-  Add "ribbon" theme from "shower" presentation tool (#129) (durden)
-  Add ``-w`` flag for watching/auto-regenerating slideshow (#71, #120)
   (jondkoon)

Minor Enhancements
------------------

-  Supress ReST rendering errors
-  CSS pre enhancements (#91) (roktas)
-  Add an example using presenter notes (#106) (netantho)
-  Run macros on headers also, to embed images (#74) (godfat)
-  Allow PHP code snippets to not require <?php (#127) (akrabat)
-  Allow for line numbers and emphasis with reStructuredText (#97)
   (copelco)
-  Add an option to strip presenter notes from output (#107) (aaugustin)

Fixes
-----

-  Firefox offset bug on next slide (#73)
-  Fix base64 encoding issue (#109) (ackdesha)
-  Fix to embed images defined in CSS (#126) (akrabat)
-  Minor documentation fixes (#119, #131) (durden, spin6lock)
-  Use configured encoding when reading all embedded files (#125)
   (iguananaut)
-  Allow pygments lexer names that include special characters (#123)
   (shreyankg)