Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 158 lines (120 sloc) 6.156 kb

deck.rb

slides in markdown, using deck.js

Home: http://github.com/alexch/deck.rb

Installation

gem install deckrb

Usage

Put this in a file named meals.md:

# Breakfast
* scrambled eggs
* coffee
* bacon

# Lunch
## Ham Sandwich
## Caesar Salad

<!SLIDE>
![a picture of my lunch](ham-sandwich.jpg)

# Dinner
> "To eat is to live." -Anon.

then run this:

deck run meals.md

and you'll get a web server running on http://localhost:4333 serving up a slide presentation with four slides:

  • One titled "Breakfast" with three bullet points
  • One titled "Lunch" with three H2 headers ("Lunch", "Ham Sandwich", and "Caesar Salad")
  • One with no headers, just a picture (stored in the same directory as meals.md)
  • One titled "Dinner" with a blockquote

Details

deck.js is a JavaScript library for building slide presentations using HTML 5. deck.rb builds on top of deck.js, adding some features:

  • clean(ish) page skeleton allows you to focus on your slides, not the HTML/CSS infrastructure
  • multiple slide source formats, including
    • Markdown
    • should be easy to add other formats
  • presentations can span several source files, and can be assembled piecemeal
  • source files look good as source, built HTML, preview HTML, or as a deck doc
    • each H1 (single hash) designates the beginning of a new slide
    • explicit !SLIDE or <!SLIDE> directives can split slides too -- use <!SLIDE> so they look like comments when rendered into normal HTML
    • links to image files are resolved relative to the source file -- no more broken images in markdown previews, and no need to put all your images in a separate directory!
    • add CSS classes to slides inside the slide directive - - e.g. <!SLIDE center> gives <section class="slide center">
    • generated HTML is pretty-printed for easier "view source"
  • uses deck.js' "swiss" theme and several extensions, including goto, menu, navigation, status, hash, and scale
  • uses RedCarpet markdown extensions, including
  • mostly backwards-compatible with Showoff, i.e. you can specify a showoff.json file on the command line
  • if the parameter (or 'sections' entry) starts with '# ' then it's parsed as literal markdown, not a file
  • code syntax highlighting using Coderay
    • specify language at the top of the block using either ::: or @@@
    • e.g. @@@ ruby

Command-Line API

deck run foo.md

  • start a local Rack server (probably Sinatra) on port 4333
  • http://localhost:4333/ serves the presentation built from foo.md
  • can specify multiple source files in a row
  • can also specify a showoff.json file to load multiple markdown files

deck build foo.md

  • creates a static page foo.html in the current directory
  • unfortunately the deck.js source code will not be around so this won't really work yet

Options

  • none yet :-)

Command-Line API (proposed)

deck build foo.md

  • create a static site
  • default output dir = ./public (even if foo.md is elsewhere)
  • copies (or inlines) deck.js source
  • also copies (or inlines) "img" directory if it exists

Credits

See Also

Bugs and Limitations

  • auxiliary files (e.g. images) are interleaved in URL path space, so overlapping file names might not resolve to the right file
    • todo: rewrite internal links to files and serve them relative to current dir, not slide dir
  • H1s (which split slides) are converted to H2s for compatibility with deck.js's CSS themes
    • unless they're the only item on the slide, in which case they remain H1s
  • we use RedCarpet to process markdown, which doesn't work exactly the same as RDiscount... for example:
    • indented code blocks under a bullet point may need to be indented more
    • code blocks must be separated from the previous text by a newline
  • slide scaling isn't perfect; sometimes either resizing or reloading will improve the layout

TODO

  • fix title tag (base it off of presentation name or something)
  • scale images to fit on the page
  • if no files are specified, use either './showoff.json' or all .md files under current directory
  • deck.json config file
  • config options:
    • show/hide theme selector
    • show/hide page number/nav
    • choose deck extensions
    • theme
    • specify which Redcarpet Markdown extensions to use
  • command-line tool can take a directory
    • first pass: globs all *.md files in it
  • command-line options (overriding or complementing config file options)
    • --output dir
    • --config deck.json
    • --port portnum
    • --theme themename
  • more slide file types
  • option to render all JS and CSS inline, for a self-contained HTML doc
    • and maybe images too, base64-encoded
  • build and push into a gh-pages branch
  • build and push into a heroku app
  • find any lines that start with a

    .(something) and turn them into

    • see showoff.rb:189
  • some way to build/rebuild a project that is deployable to heroku
  • PDF
  • rewrite internal links to files and serve them relative to current dir, not slide dir
  • custom .css, .scss, and .js files, which will get imported into all slides

TODO (community)

Something went wrong with that request. Please try again.