Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 323 lines (216 sloc) 11.614 kB
448e661 @adamzap Refined README.md
authored
1 # Overview
f3830f0 @adamzap Initial commit. It works.
authored
2
448e661 @adamzap Refined README.md
authored
3 Landslide generates a slideshow using the slides that power
f3830f0 @adamzap Initial commit. It works.
authored
4 [the html5-slides presentation](http://apirocks.com/html5/html5.html).
5
e43f434 @adamzap Updated docs for 0.6.0
authored
6 ![demo](http://adamzap.com/random/landslide.png)
3165374 @n1k0 added screenshot in the README, for pure marketing purpose
n1k0 authored
7
e8dce6e @adamzap Renamed project to Landslide
authored
8 A sample slideshow is [here](http://adamzap.com/random/landslide.html).
096c935 @adamzap Updated README and sample slides for new commits
authored
9
a7e5424 @n1k0 updated README, which is now itself transformable into a presentation :)
n1k0 authored
10
448e661 @adamzap Refined README.md
authored
11 # Features
afd3d08 @n1k0 added print stylesheet and PDF support (using PrinceXML if available …
n1k0 authored
12
e8242f9 @n1k0 added RST support
n1k0 authored
13 - Write your slide contents easily using the [Markdown](http://daringfireball.net/projects/markdown/syntax) or [ReStructuredText](http://docutils.sourceforge.net/rst.html) syntaxes
14 - [HTML5](http://dev.w3.org/html5/spec/), Web based, stand-alone document (embedded local images), fancy transitions
afd3d08 @n1k0 added print stylesheet and PDF support (using PrinceXML if available …
n1k0 authored
15 - PDF export (using [PrinceXML](http://www.princexml.com/) if available)
16
17
448e661 @adamzap Refined README.md
authored
18 # Requirements
24bf661 @adamzap Updated README
authored
19
20 `python` and the following modules:
21
22 - `jinja2`
e8242f9 @n1k0 added RST support
n1k0 authored
23 - `pygments` for code blocks syntax coloration
24 - `markdown` if you use Markdown syntax for your slide contents
25 - `docutils` if you use ReStructuredText syntax for your slide contents
f3830f0 @adamzap Initial commit. It works.
authored
26
448e661 @adamzap Refined README.md
authored
27 ## Optional
28
29 - `textile` for textile support
a7e5424 @n1k0 updated README, which is now itself transformable into a presentation :)
n1k0 authored
30
448e661 @adamzap Refined README.md
authored
31 # Installation
957d567 @n1k0 added installation instructions
n1k0 authored
32
33 The easiest way to install Landlside is probably using `pip`:
34
35 $ pip install landslide
36
37 Alternatively, you can use `easy_install`:
38
39 $ easy_install landslide
40
41 If you want to stay on the edge:
42
43 $ git clone https://github.com/adamzap/landslide.git
f3bde79 Fixed installation README
Vincent Jousse authored
44 $ cd landslide
45 $ python setup.py build
46 $ sudo python setup.py install
957d567 @n1k0 added installation instructions
n1k0 authored
47
448e661 @adamzap Refined README.md
authored
48 # Formatting
e8242f9 @n1k0 added RST support
n1k0 authored
49
448e661 @adamzap Refined README.md
authored
50 ## Markdown
f3830f0 @adamzap Initial commit. It works.
authored
51
fe3232f @n1k0 updated README
n1k0 authored
52 - Your Markdown source files must be suffixed by `.md`, `.markdn`, `.mdown` or `.markdown`
b6e2177 @n1k0 Project layout is currently being reorganized, to prepare future pack…
n1k0 authored
53 - To create a title slide, render a single `h1` element (eg. `# My Title`)
361c8bc @adamzap Updated README for issue #16 fix
authored
54 - Separate your slides with a horizontal rule (`---` in markdown) except at the end of md files
b6e2177 @n1k0 Project layout is currently being reorganized, to prepare future pack…
n1k0 authored
55 - Your other slides should have a heading that renders to an `h1` element
a7e5424 @n1k0 updated README, which is now itself transformable into a presentation :)
n1k0 authored
56 - To highlight blocks of code, put !`{lang}` where `{lang}` is the pygment supported language identifier as the first indented line
e8242f9 @n1k0 added RST support
n1k0 authored
57
448e661 @adamzap Refined README.md
authored
58 ## ReStructuredText
e8242f9 @n1k0 added RST support
n1k0 authored
59
fe3232f @n1k0 updated README
n1k0 authored
60 - Your ReST source files must be suffixed by `.rst` or `.rest` (**`.txt` is not supported**)
e8242f9 @n1k0 added RST support
n1k0 authored
61 - Use headings for slide titles
361c8bc @adamzap Updated README for issue #16 fix
authored
62 - Separate your slides using an horizontal rule (`----` in RST) except at the end of RST files
f3830f0 @adamzap Initial commit. It works.
authored
63
448e661 @adamzap Refined README.md
authored
64 ## Textile
a7e5424 @n1k0 updated README, which is now itself transformable into a presentation :)
n1k0 authored
65
448e661 @adamzap Refined README.md
authored
66 - Textile cannot generate <hr />, so you must insert those manually to separate slides
67
68 # Rendering
f3830f0 @adamzap Initial commit. It works.
authored
69
e8242f9 @n1k0 added RST support
n1k0 authored
70 - Run `landslide slides.md` or `landslide slides.rst`
f3830f0 @adamzap Initial commit. It works.
authored
71 - Enjoy your newly generated `presentation.html`
2710f15 @adamzap Added three TODOs to README
authored
72
448e661 @adamzap Refined README.md
authored
73 Or get it as a PDF document if PrinceXML is installed and available on your system:
afd3d08 @n1k0 added print stylesheet and PDF support (using PrinceXML if available …
n1k0 authored
74
af66cc3 @n1k0 updated README
n1k0 authored
75 $ landslide README.md -d readme.pdf
cdf9fd1 @n1k0 refactored Generator not to depend on OptParse anymore, the source op…
n1k0 authored
76 $ open readme.pdf
afd3d08 @n1k0 added print stylesheet and PDF support (using PrinceXML if available …
n1k0 authored
77
448e661 @adamzap Refined README.md
authored
78 # Viewing
e43f434 @adamzap Updated docs for 0.6.0
authored
79
d3ef02e Typo (wrong key description for help).
Sébastien Douche authored
80 - Press `h` to toggle display of help
e43f434 @adamzap Updated docs for 0.6.0
authored
81 - Press `left arrow` and `right arrow` to navigate
82 - Press `t` to toggle a table of contents for your presentation. Slide titles are links
fe3232f @n1k0 updated README
n1k0 authored
83 - Press `ESC` to display the presentation overview (Exposé)
e43f434 @adamzap Updated docs for 0.6.0
authored
84 - Press `n` to toggle slide number visibility
e1d5668 @adamzap Added screen blanking by pressing 'b'
authored
85 - Press `b` to toggle screen blanking
e245631 @n1k0 updated docs
n1k0 authored
86 - Press `c` to toggle current slide context (previous and next slides)
87 - Press `e` to make slides filling the whole available space within the document body
fe3232f @n1k0 updated README
n1k0 authored
88 - Press `S` to toggle display of link to the source file for each slide
e43f434 @adamzap Updated docs for 0.6.0
authored
89 - Press '2' to toggle notes in your slides (specify with the .notes macro)
fe3232f @n1k0 updated README
n1k0 authored
90 - Press '3' to toggle pseudo-3D display (experimental)
e43f434 @adamzap Updated docs for 0.6.0
authored
91 - Browser zooming is supported
92
448e661 @adamzap Refined README.md
authored
93 # Commandline Options
9960ea1 @n1k0 enhanced documentation
n1k0 authored
94
95 Several options are available using the command line:
96
1fec9cf @n1k0 merged lothiraldan 'linenos' feature
n1k0 authored
97 -h, --help show this help message and exit
98 -c, --copy-theme Copy theme directory into current presentation source
99 directory
100 -b, --debug Will display any exception trace to stdin
101 -d FILE, --destination=FILE
102 The path to the to the destination file: .html or .pdf
103 extensions allowed (default: presentation.html)
104 -e ENCODING, --encoding=ENCODING
105 The encoding of your files (defaults to utf8)
106 -i, --embed Embed stylesheet and javascript contents,
107 base64-encoded images in presentation to make a
108 standalone document
109 -l LINENOS, --linenos=LINENOS
2cbda19 Spelling correction in README
holdensmagicalunicorn authored
110 How to output linenos in source code. Three options
1fec9cf @n1k0 merged lothiraldan 'linenos' feature
n1k0 authored
111 availables: no (no line numbers); inline (inside <pre>
112 tag); table (lines numbers in another cell, copy-paste
113 friendly)
2cbda19 Spelling correction in README
holdensmagicalunicorn authored
114 -o, --direct-output Prints the generated HTML code to stdin; won't work
1fec9cf @n1k0 merged lothiraldan 'linenos' feature
n1k0 authored
115 with PDF export
116 -q, --quiet Won't write anything to stdin (silent mode)
117 -r, --relative Make your presentation asset links relative to current
118 pwd; This may be useful if you intend to publish your
119 html presentation online.
120 -t THEME, --theme=THEME
121 A theme name, or path to a landlside theme directory
122 -v, --verbose Write informational messages to stdin (enabled by
123 default)
124 -x EXTENSIONS, --extensions=EXTENSIONS
125 Comma-separated list of extensions for Markdown
9960ea1 @n1k0 enhanced documentation
n1k0 authored
126
448e661 @adamzap Refined README.md
authored
127 # Presentation Configuration
579c6fc @n1k0 added a way to configure a presentation using a CFG file
n1k0 authored
128
2461a02 @durden Fix mispelling of "across"
durden authored
129 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:
579c6fc @n1k0 added a way to configure a presentation using a CFG file
n1k0 authored
130
131 [landslide]
132 theme = /path/to/my/beautiful/theme
133 source = 0_my_first_slides.md
134 a_directory
135 another_directory
136 now_a_slide.markdown
137 another_one.rst
1661125 @n1k0 added a way to configure the destination in the cfg file
n1k0 authored
138 destination = myWonderfulPresentation.html
1c7e0ea @n1k0 added user css and js management through configuration file
n1k0 authored
139 css = my_first_stylesheet.css
140 my_other_stylesheet.css
141 js = jquery.js
142 my_fancy_javascript.js
f008d8f @n1k0 tweaked up README to reflect latest added features
n1k0 authored
143 relative = True
9e9c516 @Lothiraldan Add a linenos option (used by pygment to generate output of source code)
Lothiraldan authored
144 linenos = inline
579c6fc @n1k0 added a way to configure a presentation using a CFG file
n1k0 authored
145
0015ef9 @durden Make sure README mentions that config files need .cfg, could be a tri…
durden authored
146 Don't forget to declare the `[landslide]` section.
147 All configuration files must end in the .cfg extension.
148
149 To generate the presentation as configured, just run:
579c6fc @n1k0 added a way to configure a presentation using a CFG file
n1k0 authored
150
1661125 @n1k0 added a way to configure the destination in the cfg file
n1k0 authored
151 $ cd /path/to/my/presentation/sources
579c6fc @n1k0 added a way to configure a presentation using a CFG file
n1k0 authored
152 $ landslide config.cfg
153
448e661 @adamzap Refined README.md
authored
154 # Macros
7fc3806 @n1k0 added macros to display notes and add css classes in slides
n1k0 authored
155
156 You can use macros to enhance your presentation:
157
448e661 @adamzap Refined README.md
authored
158 ## Notes
7fc3806 @n1k0 added macros to display notes and add css classes in slides
n1k0 authored
159
160 Add notes to your slides using the `.notes:` keyword, eg.:
161
162 # My Slide Title
e43f434 @adamzap Updated docs for 0.6.0
authored
163
7fc3806 @n1k0 added macros to display notes and add css classes in slides
n1k0 authored
164 .notes: These are my notes, hidden by default
e43f434 @adamzap Updated docs for 0.6.0
authored
165
7fc3806 @n1k0 added macros to display notes and add css classes in slides
n1k0 authored
166 My visible content goes here
167
e43f434 @adamzap Updated docs for 0.6.0
authored
168 You can toggle display of notes by pressing the `2` key.
7fc3806 @n1k0 added macros to display notes and add css classes in slides
n1k0 authored
169
579c6fc @n1k0 added a way to configure a presentation using a CFG file
n1k0 authored
170 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.
171
448e661 @adamzap Refined README.md
authored
172 # Presenter Notes
173
53a1346 @reagle clarification in readme on presenter notes
reagle authored
174 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.
3854c96 @BestFriendChris Now you can add notes to a slide by adding a presenter notes section …
BestFriendChris authored
175
7fc3806 @n1k0 added macros to display notes and add css classes in slides
n1k0 authored
176
448e661 @adamzap Refined README.md
authored
177 # Registering Macros
66e971b @n1k0 added a convenient way to register macros programmatically
n1k0 authored
178
448e661 @adamzap Refined README.md
authored
179 Macros are used to transform the HTML contents of your slide.
66e971b @n1k0 added a convenient way to register macros programmatically
n1k0 authored
180
181 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:
182
183 !python
4830e16 @n1k0 minor fixes, enhancements and documentation
n1k0 authored
184 import landslide
1c7e0ea @n1k0 added user css and js management through configuration file
n1k0 authored
185
fe3232f @n1k0 updated README
n1k0 authored
186 class MyMacro(landslide.Macro):
66e971b @n1k0 added a convenient way to register macros programmatically
n1k0 authored
187 def process(self, content, source=None):
188 return content + '<p>plop</p>', ['plopped_slide']
1c7e0ea @n1k0 added user css and js management through configuration file
n1k0 authored
189
fe3232f @n1k0 updated README
n1k0 authored
190 g = landslide.generator.Generator(source='toto.md')
66e971b @n1k0 added a convenient way to register macros programmatically
n1k0 authored
191 g.register_macro(MyMacro)
192 print g.render()
193
4830e16 @n1k0 minor fixes, enhancements and documentation
n1k0 authored
194 This will render any slide as below:
195
196 !html
9960ea1 @n1k0 enhanced documentation
n1k0 authored
197 <div class="slide plopped_slide">
4830e16 @n1k0 minor fixes, enhancements and documentation
n1k0 authored
198 <header><h2>foo</h2></header>
199 <section>
200 <p>my slide contents</p>
201 <p>plop></p>
202 </section>
203 </div>
204
448e661 @adamzap Refined README.md
authored
205 # Advanced Usage
66e971b @n1k0 added a convenient way to register macros programmatically
n1k0 authored
206
448e661 @adamzap Refined README.md
authored
207 ## Setting Custom Destination File
be3404a @n1k0 updated README
n1k0 authored
208
af66cc3 @n1k0 updated README
n1k0 authored
209 $ landslide slides.md -d ~/MyPresentations/KeynoteKiller.html
be3404a @n1k0 updated README
n1k0 authored
210
448e661 @adamzap Refined README.md
authored
211 ## Working with Directories
be3404a @n1k0 updated README
n1k0 authored
212
af66cc3 @n1k0 updated README
n1k0 authored
213 $ landslide slides/
be3404a @n1k0 updated README
n1k0 authored
214
448e661 @adamzap Refined README.md
authored
215 ## Working with Direct Output
be3404a @n1k0 updated README
n1k0 authored
216
af66cc3 @n1k0 updated README
n1k0 authored
217 $ landslide slides.md -o | tidy
be3404a @n1k0 updated README
n1k0 authored
218
448e661 @adamzap Refined README.md
authored
219 ## Using an Alternate Landslide Theme
be3404a @n1k0 updated README
n1k0 authored
220
ce53ecb @n1k0 added theming capability; themes are structured directories shipping …
n1k0 authored
221 $ landslide slides.md -t mytheme
222 $ landslide slides.md -t /path/to/theme/dir
be3404a @n1k0 updated README
n1k0 authored
223
448e661 @adamzap Refined README.md
authored
224 ## Embedding Base-64-Encoded Images
9d413f9 @n1k0 added support for embedding base64-encoded image versions in standalo…
n1k0 authored
225
af66cc3 @n1k0 updated README
n1k0 authored
226 $ landslide slides.md -i
9d413f9 @n1k0 added support for embedding base64-encoded image versions in standalo…
n1k0 authored
227
448e661 @adamzap Refined README.md
authored
228 ## Exporting to PDF
afd3d08 @n1k0 added print stylesheet and PDF support (using PrinceXML if available …
n1k0 authored
229
af66cc3 @n1k0 updated README
n1k0 authored
230 $ landslide slides.md -d PowerpointIsDead.pdf
afd3d08 @n1k0 added print stylesheet and PDF support (using PrinceXML if available …
n1k0 authored
231
448e661 @adamzap Refined README.md
authored
232 # Theming
ce53ecb @n1k0 added theming capability; themes are structured directories shipping …
n1k0 authored
233
94d82ac @adamzap Updated README for new theming features
authored
234 A Landslide theme is a directory following this simple structure:
ce53ecb @n1k0 added theming capability; themes are structured directories shipping …
n1k0 authored
235
236 mytheme/
237 |-- base.html
238 |-- css
239 | |-- print.css
240 | `-- screen.css
241 `-- js
242 `-- slides.js
243
94d82ac @adamzap Updated README for new theming features
authored
244 If a theme does not provide HTML and JS files, those from the default theme will be used. CSS is not optional.
245
f008d8f @n1k0 tweaked up README to reflect latest added features
n1k0 authored
246 Last, you can also copy the whole theme directory to your presentation one by passing the `--copy-theme` option to the `landslide` command:
247
248 $ landslide slides.md -t /path/to/some/theme --copy-theme
249
448e661 @adamzap Refined README.md
authored
250 # User stylesheets and Javascripts
1fec9cf @n1k0 merged lothiraldan 'linenos' feature
n1k0 authored
251
252 If you don't want to bother making your own theme for tweaking up a bit your presentation style and/or add some interactivity using tiny bits of Javascript, you can include your own user css and js files to the generated presentation.
253
254 This feature is only available if you use a landslide configuration file, by setting the `css` and/or `js` flags:
255
256 [landslide]
257 theme = /path/to/my/beautiful/theme
258 source = slides.mdown
259 css = custom.css
260 js = jquery.js
261 powerpoint.js
262
263 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.
264
265 **NOTE:** Paths to the css and js files must be relative to the directory you're running the ``landslide`` command from.
266
267
448e661 @adamzap Refined README.md
authored
268 # Publishing your Presentation Online
f008d8f @n1k0 tweaked up README to reflect latest added features
n1k0 authored
269
270 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;
271
272 $ landslide slides.md --relative --copy-theme
273
274 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 landslide presentation.
275
0a94c21 @n1k0 added an example of customized presentation to README
n1k0 authored
276 Check out a [Landslide presentation customized this way](http://www.akei.com/presentations/2011-Djangocong/index.html).
277
3311815 @n1k0 added more supported file extensions for markdown and rst
n1k0 authored
278
448e661 @adamzap Refined README.md
authored
279 ## Theme Variables
3311815 @n1k0 added more supported file extensions for markdown and rst
n1k0 authored
280
ce53ecb @n1k0 added theming capability; themes are structured directories shipping …
n1k0 authored
281 The `base.html` must be a [Jinja2 template file](http://jinja.pocoo.org/2/documentation/templates) where you can harness the following template variables:
282
4a1c1bb @n1k0 refactored static assets management and base template to allow full e…
n1k0 authored
283 - `css`: the stylesheet contents, available via two keys, `print` and `screen`, both having:
1c7e0ea @n1k0 added user css and js management through configuration file
n1k0 authored
284 - a `path_url` key storing the url to the asset file path
4a1c1bb @n1k0 refactored static assets management and base template to allow full e…
n1k0 authored
285 - a `contents` key storing the asset contents
286 - `js`: the javascript contents, having:
1c7e0ea @n1k0 added user css and js management through configuration file
n1k0 authored
287 - a `path_url` key storing the url to the asset file path
4a1c1bb @n1k0 refactored static assets management and base template to allow full e…
n1k0 authored
288 - a `contents` key storing the asset contents
ce53ecb @n1k0 added theming capability; themes are structured directories shipping …
n1k0 authored
289 - `slides`: the slides list, each one having these properties:
290 - `header`: the slide title
291 - `content`: the slide contents
292 - `number`: the slide number
4a1c1bb @n1k0 refactored static assets management and base template to allow full e…
n1k0 authored
293 - `embed`: is the current document a standalone one?
be5bc1c @n1k0 fixed typos
n1k0 authored
294 - `num_slides`: the number of slides in current presentation
ce53ecb @n1k0 added theming capability; themes are structured directories shipping …
n1k0 authored
295 - `toc`: the Table of Contents, listing sections of the document. Each section has these properties available:
296 - `title`: the section title
297 - `number`: the slide number of the section
298 - `sub`: subsections, if any
299
448e661 @adamzap Refined README.md
authored
300 # Styles Scope
3311815 @n1k0 added more supported file extensions for markdown and rst
n1k0 authored
301
e43f434 @adamzap Updated docs for 0.6.0
authored
302 * To change HTML5 presentation styles, tweak the `css/screen.css` stylesheet bundled with the theme you are using
303 * For PDF, modify the `css/print.css`
3311815 @n1k0 added more supported file extensions for markdown and rst
n1k0 authored
304
448e661 @adamzap Refined README.md
authored
305 # Authors
2710f15 @adamzap Added three TODOs to README
authored
306
448e661 @adamzap Refined README.md
authored
307 ## Original Author and Development Lead
096c935 @adamzap Updated README and sample slides for new commits
authored
308
e43f434 @adamzap Updated docs for 0.6.0
authored
309 - Adam Zapletal (adamzap@gmail.com)
a7e5424 @n1k0 updated README, which is now itself transformable into a presentation :)
n1k0 authored
310
448e661 @adamzap Refined README.md
authored
311 ## Co-Author
e43f434 @adamzap Updated docs for 0.6.0
authored
312
313 - Nicolas Perriault (nperriault@gmail.com)
314
448e661 @adamzap Refined README.md
authored
315 ## Contributors
d29d3c2 @adamzap Updated README for 0.8.0
authored
316
448e661 @adamzap Refined README.md
authored
317 See https://github.com/adamzap/landslide/contributors
e43f434 @adamzap Updated docs for 0.6.0
authored
318
448e661 @adamzap Refined README.md
authored
319 ## Base Template Authors and Contributors (html5-slides)
096c935 @adamzap Updated README and sample slides for new commits
authored
320
e43f434 @adamzap Updated docs for 0.6.0
authored
321 - Marcin Wichary (mwichary@google.com)
322 - Ernest Delgado (ernestd@google.com)
448e661 @adamzap Refined README.md
authored
323 - Alex Russell (slightlyoff@chromium.org)
Something went wrong with that request. Please try again.