docs | |
---|---|
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)
python
and the following modules:
jinja2
pygments
for code blocks syntax coloration
markdown
for Markdowndocutils
for reStructured Texttextile
for Textile
watchdog
for watching/auto-regeneration with the-w
flag
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/adamzap/landslide.git $ cd landslide $ python setup.py build $ sudo python setup.py install
- 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
wherelang
is the pygment supported language identifier as the first indented line
- 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
- Separate your slides using
---
, just like in markdown
- Run
landslide slides.md
orlandslide slides.rst
- Enjoy your newly generated
presentation.html
- Press
h
to toggle display of help - Press
left arrow
andright 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
Usage:
darkslide [options] input.md ...
- Options:
--version show program's version number and exit -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 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). -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 landlside 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.
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
You can use macros to enhance your presentation:
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.
Add a QR Code to your presentation by using the .qr
keyword:
.qr: 450|https://github.com/ionelmc/python-darkslide
Add footnote to the current and all the following presentations
.footnote: Slides available at https://blog.ionelmc.ro/presentations/
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.
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>
$ 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
See documentation on available Markdown extensions here:
$ darkslide slides.md -x abbr
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.
Last, you can also copy the whole theme directory to your presentation
one by passing the --copy-theme
option to the darkslide
command:
$ darkslide slides.md -t /path/to/some/theme --copy-theme
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.
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.
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
andscreen
, 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 titlecontent
: the slide contentsnumber
: the slide numberembed
: is the current document a standalone one?num_slides
: the number of slides in current presentationtoc
: the Table of Contents, listing sections of the document. Each section has these properties available:title
: the section titlenumber
: the slide number of the sectionsub
: subsections, if any
- 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
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