Merge pull request #62 from jdan/themes

The Big Theme Pull Request

Author: jdan

README.md

@@ -53,66 +53,109 @@ And run it like so:
 
 ```bash
 cleaver path/to/something.md
+```
+
+You can also watch for changes on a file and automatically recompile with:
+
+```bash
+cleaver watch path/to/something-changing.md
 
-# to recompile on changes:
-# cleaver watch path/to/something.md
+# Watching for changes on presentation.md. Ctrl-C to abort.
+# Rebuilding: Thu Nov 07 2013 00:15:03 GMT-0500 (EST)
+# Rebuilding: Thu Nov 07 2013 00:15:21 GMT-0500 (EST)
+# Rebuilding: Thu Nov 07 2013 00:16:01 GMT-0500 (EST)
+# Rebuilding: Thu Nov 07 2013 00:16:09 GMT-0500 (EST)
 ```
 
 ## More Info
 
 **Cleaver** is a one-stop shop for generating HTML presentations in
 record time. Using some spiced up markdown, you can produce
-good-looking, interactive presentations without writing any code
-or placing a measly textbox.
+good-looking, interactive presentations with a just a few lines of text.
 
 All you need to do is write some blocks of markdown, separated by `--`
-on its own line and include metadata at the top.
+on its own line and include options at the top.
 
-Cleaver also looks great on mobile.
+Slides are written in [Markdown](http://daringfireball.net/projects/markdown/),
+and are separated by two dashes (`--`).
 
-Let's walk through the above example piece by piece.
-
-### Metadata
+## Options
 
     title: Basic Example
     author:
       name: Jordan Scales
       twitter: jdan
       url: http://jordanscales.com
+    style: basic-style.css
     output: basic.html
-    controls: true
 
-The first section of any cleaver document is the metadata. Currently cleaver supports
-the following fields. **All metadata is optional**.
+Cleaver supports several basic options that allow you to further customize the
+look and feel of your presentation, including author info, stylesheets, and
+custom templates.
+
+See the documentation on
+[options](https://github.com/jdan/cleaver/blob/master/docs/options.md) for more
+information.
+
+## Themes
+
+    title: Theme Example
+    output: theme.html
+    theme: jdan/cleaver-retro
+
+Cleaver has substantial theme support to give you more fine-grained control
+over your presentation, similar to [options](#options). Instead of manually
+specifying a stylesheet, template, layout, and others, you can specify a single
+theme containing each of these assets. More specifically, a theme may contain:
+
+* style.css - styles for your presentation
+* template.mustache - a template used to render the slides in your presentation
+* layout.mustache - a template used to render the entire document of your
+presentation
+* script.js - javascript to be included in your slideshow
+
+A theme does not need to contain all of these files, only the ones present
+will be loaded into your slideshow.
+
+### Examples
+
+* [jdan/cleaver-retro](http://github.com/jdan/cleaver-retro)
 
-**Ordinary Users**
+![cleaver-retro](https://i.cloudup.com/HLtcPJWJJl-1200x1200.png)
 
-* **title**: The title of the slideshow
-* **author**
-    * **name**: Your full name
-    * **url**: A url to your website
-    * **twitter**: Your twitter handle (*please note that the character '@'
-      must be wrapped in quotes - e.g. "@jdan" - as per the YAML specification*)
-    * **email**: Your email address
-* **style**: An optional stylesheet to load
-* **output**: A location to save the rendered document (default: *FILENAME-cleaver.html*)
-* **controls**: Option whether or not arrow buttons should be included (default: *true*)
-* **agenda**: Option whether or not to insert an agenda slide (similar to a table of contents) after the title (default: *false*)
-* **encoding**: A specified content encoding (default: *utf-8*)
-* **progress**: Option whether or not to display a small progress bar at the top of the page
-(default: *true*)
+* [matmuchrapna/cleaver-ribbon](http://github.com/matmuchrapna/cleaver-ribbon)
 
-**Power Users**
+![cleaver-ribbon](https://i.cloudup.com/GECEx5BmxI-1200x1200.png)
 
-* **template**: Location of the template used to render the slides (default:
- *default.mustache*)
-* **layout**: Location of the layout template used to render everything (default:
- *layout.mustache*)
+### Specifying Themes
 
-If author is included, the following slide will be automatically inserted
-at the end of your presentation:
+Themes may be specified by one of the following options:
 
-![author slide](https://i.cloudup.com/f0zVsUwqF0-3000x3000.png)
+* An absolute or relative path to a directory
+* A URL to a directory
+* A github repostitory in the form of *username/reponame*
+
+### Overriding Themes
+
+By default, *style.css* and *script.js* will be **appended** to the default
+stylesheets and javascripts included in cleaver presentations. If you wish to
+completely override these defaults, you must include another file in your
+theme - options.json - corresponding to the following:
+
+```json
+{
+  "override": true
+}
+```
+
+Template files will automatically override the default templates.
+
+### More Info
+
+For more information on themes, check out
+[the documentation]([options](https://github.com/jdan/cleaver/blob/master/docs/themes.md)
+
+## Slide Types
 
 ### Title slide
 
@@ -138,57 +181,18 @@ you can include things like lists, images, and arbitrary HTML.
 **h3** tags (prefaced `###`) are automatically given a bottom border to
 represent a slide title.
 
-### Navigation
+## Navigation
+
+Cleaver supports keyboard navigation for switching between slides.
 
 To navigate the slideshow:
 
 * **reverse**: H, J, LEFT, DOWN, and Backspace
 * **forward**: K, L, ENTER, UP, RIGHT, and Space
 
-Or click the buttons
-
-### Templates
-
-By default, cleaver slides are rendered in the following template:
-
-```html
-{{#progress}}
-  <div class="progress">
-    <div class="progress-bar"></div>
-  </div>
-{{/progress}}
-
-<div id="wrapper">
-  {{#slides}}
-    <section class="slide">{{{.}}}</section>
-  {{/slides}}
-</div>
-{{#controls}}
-  <div class="controls">
-    <div class="arrow prev"></div>
-    <div class="arrow next"></div>
-  </div>
-{{/controls}}
-
-<script type="text/javascript">
-  {{{navigation}}}
-</script>
-```
-
-Power users may wish to render into custom templates. To do so, simply copy the above file
-somewhere, make some changes, and specify the template like so:
-
-```yaml
-title: Basic Example
-output: basic.html
-template: example.mustache
-```
-
-You can also replace the entire layout (`<head>` tags and all) with the `layout` option. Use
-[layout.mustache](https://github.com/jdan/cleaver/blob/master/templates/layout.mustache) as
-an example to note what fields you should include in your custom layout.
+Alternatively, click the control buttons located below the presentation.
 
-### Contributing
+## Contributing
 
 * Fork it
 * Clone it

docs/options.md

@@ -0,0 +1,104 @@
+## Options
+
+Cleaver supports several basic options for adding a bit of customization to
+your presentations. These options are placed at the top of your document, in
+YAML format. A typical option setup resembles the following.
+
+    title: Basic Example
+    author:
+      name: Jordan Scales
+      twitter: jdan
+      url: http://jordanscales.com
+    style: basic-styles.css
+    output: basic.html
+
+### title
+
+The title of the slidshow.
+
+**Default**: Untitled
+
+### author
+
+Several fields which, if included, populate a basic author "credits" slide at
+the end of your presentation.
+
+![author slide](https://i.cloudup.com/f0zVsUwqF0-3000x3000.png)
+
+These fields include:
+
+* **name**: Your full name
+* **url**: A url to your website
+* **twitter**: Your twitter handle
+* **email**: Your email address
+
+Please note that some characters must be escaped. For example, "@username"
+would need to be wrapped in quotes. You can leave out the "@" when specifying
+a twitter handle.
+
+### theme
+
+An optional theme to load. A theme is a directory, URL, or a github repo in
+the form of *username/repo* that may contain stylesheets, javascript, or
+rewritten templates. Themes group together many of the other options listed
+in this article.
+
+For example, check out the [retro theme](http://github.com/jdan/cleaver-retro).
+
+For more information on themes, check out
+[the documentation]([options](https://github.com/jdan/cleaver/blob/master/docs/themes.md).
+
+### style
+
+An optional stylesheet to load. This can be either a URL, or an
+absolute/relative path to a file. *Relative to the markdown document you are
+sending to cleaver*.
+
+These styles will be **appended** to Cleaver's default style. For more
+fine-grained control, check out the docs on Theming.
+
+### output
+
+The filename (or absolute/relative path to a file) you wish to save your
+output to.
+
+**Default**: FILENAME-cleaver.html
+
+### controls
+
+An option determining whether or not you want to render simple navigation
+buttons on your presentation.
+
+**Default**: true
+
+### progress
+
+Displays a small progress bar at the top of your document.
+
+**Default**: true
+
+### agenda
+
+Inserts an agenda (table of contents) slide at the beginning of your
+presentation, based on the titles of your individual slides.
+
+**Default**: false
+
+### encoding
+
+Content encoding to use on the rendered document.
+
+**Default**: utf-8
+
+### template
+
+URL or absolute/relative path to a mustache template used to render the slides.
+See [default.mustache](https://github.com/jdan/cleaver/blob/master/templates/default.mustache)
+for inspiration.
+
+### layout
+
+URL or absolute/relative path to a mustache template used to render the entire
+slideshow. See
+[layout.mustache](https://github.com/jdan/cleaver/blob/master/templates/layout.mustache)
+for inspiration.

docs/themes.md

@@ -0,0 +1,60 @@
+## Themes
+
+    title: Theme Example
+    output: theme.html
+    theme: jdan/cleaver-retro
+
+Cleaver has substantial theme support to give you more fine-grained control
+over your presentation, similar to [options](#options). Instead of manually
+specifying a stylesheet, template, layout, and others, you can specify a single
+theme containing each of these assets. More specifically, a theme may contain:
+
+* style.css - styles for your presentation
+* template.mustache - a template used to render the slides in your presentation
+* layout.mustache - a template used to render the entire document of your
+presentation
+* script.js - javascript to be included in your slideshow
+
+A theme does not need to contain all of these files, only the ones present
+will be loaded into your slideshow.
+
+### Examples
+
+* [jdan/cleaver-retro](http://github.com/jdan/cleaver-retro)
+
+![cleaver-retro](https://i.cloudup.com/HLtcPJWJJl-1200x1200.png)
+
+* [matmuchrapna/cleaver-ribbon](http://github.com/matmuchrapna/cleaver-ribbon)
+
+![cleaver-ribbon](https://i.cloudup.com/GECEx5BmxI-1200x1200.png)
+
+### Specifying Themes
+
+Themes may be specified by one of the following options:
+
+* An absolute or relative path to a directory
+* A URL to a directory
+* A github repostitory in the form of *username/reponame*
+
+### Overriding Themes
+
+By default, *style.css* and *script.js* will be **appended** to the default
+stylesheets and javascripts included in cleaver presentations. If you wish to
+completely override these defaults, you must include another file in your
+theme - options.json - corresponding to the following:
+
+```json
+{
+  "override": true
+}
+```
+
+Template files will automatically override the default templates.
+
+### Theme Behavior
+
+Themes group together many options such as style, template, and layout. Please
+not that the individual options will be loaded *after* the theme, allowing you
+to override a theme's properties. This is not recommended, however, as the
+theme author may construct his or her styles in such a way that they are not
+meant to be overridden.