Let's start a discussion #184

wants to merge 394 commits into


None yet
8 participants

burtlo commented May 24, 2012

A few weeks ago I started look at ways I could improve upon Showoff by adding:

  • Github Flavored Markdown

    Syntax Highlighting through code fences instead of the strange
    additional construct of using @@@ LANGUAGE within the code samples.
    Essentially your markdown can now adhere to more accepted markdown

  • Static HTML and PDF

    All javascript, stylesheets, and images are embedded into the static HTML
    and PDF output. This allows the static HTML to better represent the
    presentation. This includes any custom javascript, css, or images defined
    within the presentation. This also embeds locally defined images within the

I think after that I went off the deep end trying to clean up and refactor the monolith sinatra class that contained all the parsing and rendering logic. At some point I questioned the usefulness of a showoff.json file and replaced with a showoff file which contained a DSL that allowed you to define sections and slides.

The README describes in far greater detail this implementation.

Final Note

This pull request is unreasonable in size, scope, and change. It is likely near impossible to visibly inspect it to gain a sense of it. I am absolutely not sure if there is a home for this abomination. However, I felt like freeing this Frankenstein...


goncalossilva commented May 24, 2012


I really think we should join efforts into improving showoff (vs forking it). Thanks for all this!

First of all, I couldn't agree more regarding GitHub's flavored markdown. It's the way to go, imo. I also like the stuff you did with static page & PDF generation. And finally, great work shrinking showoff.rb!

Having said this, I see a few issues with this pull request:

  • I love the syntax of the new config file (I'm a ruby guy, after all), but I strongly believe the JSON config file should not be deprecated (for now). Besides the obvious advantage of not breaking previous presentations, I'd say it's easier on non-programmers... but I could be wrong.
  • The README file cannot be merged as is, since it compares the current showoff with these changes.
  • I believe you missed some recent additions to showoff, like presentation templates, markdown engine configurability, the pause screen and presenter view <—> presentation view 2-way sync. Am I wrong?

Let's discuss this a bit more!


alexch commented May 24, 2012

FYI I'm kinda doing some of this already with deck.rb, which is based on a cleaner JS presentation layer and an arguably cleaner and better tested Ruby tool. http://github.com/alexch/deck.rb

(I'm not using full GFM but I'd love to be, and I'm inlining a lot of the JS and CSS too. Also it should be drop-in-compatible with showoff since I support showoff.json files so I'd love for more people to just give it a try and tell me what breaks.)

burtlo commented May 24, 2012

@goncalossilva this is to start a conversation, so don't feel too bad about the work I have done on the fork coordinating with your work. Thanks for taking a look at it and your feedback.

Supporting showoff.json

I am fairly certain that I could build an adapter to parse the previous showoff.json format.

I think the new format, though Ruby, is a little easier to read and possibly to understand for non-developers. There are overall less symbols { , }, [, ], : in the new format.


That of course would change if you are seriously considering this monstrous body of work.

Missing Features

Markdown Engine Configurability

I likely have broken the markdown engine configurability because I have never navigated this minefield before and when it came time to get Github Flavored Markdown (GFM), I simply opted for a solution that I found that worked. Namely using Redcarpet with Pygments.rb. Perhaps there is a way to restore that functionality

Presenter View and Presentation View

That functionality still exists and is working but is indeed missing from the documentation I composed.

Presentation Templates

I'm not sure what you mean by presentation templates? Are those the classes that can be applied to slides? The ability to request hostname:9090/onepage or hostname:9090/pdf?

burtlo commented May 24, 2012

Alright, both the server and the static generation will look for a showoff then the original showoff.json.

Also I took a moment to make the server and the static generation use the full filepath provided and not simply a directory.

So you could do something like:

$ bin/showoff server examples/showon
$ bin/showoff server examples/custom.json

Which will add those files to the list of files to search for when creating the presentation.

burtlo commented May 27, 2012

@goncalossilva let's talk about what you would love to see in a series of smaller pull requests:

  • Server refactor into parsers and renderers
  • Onepage and PDF inlined assets
  • Showoff DSL support with backwards compatibility to still use the existing JSON format
  • Github Flavored Markdown

I am running into some problems pushing this functionality to Heroku because of some python issues. I'll see what I can do to make this work.

  • Multi-column layout

This was something that I was working on in the last few commits.

  • Updated Example Presentation

I wanted to update the example presentation so that it actually show-cased Showoff and the majority of it's features.

  • RSpec test suite

How do you feel about having an RSpec test suite backed with Guard?

  • Reduced showoff command

I removed a large set of the showoff commands so that showoff could focus ensuring high quality of core commands. I also made the showoff command work when simply given a directory or filepath.


goncalossilva commented May 28, 2012

@burtlo In parts:

Markdown Engine Configurability
I'll try to take a deeper look into this in the near future.

Presentation Templates
I'm talking about this: https://github.com/schacon/showoff#templates

RSpec test suite
Any test suite is better than no test suite :p

The rest seems fine. Your PR breakdown looks good to me. After ironing out the questions about the MD engines and the templates, I think we're good to go.

I think this is the best approach:

  • Iron out the remaining questions
  • Release a new 0.7.X version of showoff
  • Merge most of this in smaller PR, if possible
  • Iron out some rough edges, make a pre release
  • Release 0.8

These are big changes. I'm strongly in favor of most of them. Let's see if @schacon can weigh in on this!

burtlo commented May 28, 2012

Oh templates! I must have forked before templates. I'll work on how that would integrate with the work I've done.


goncalossilva commented May 28, 2012

There were a few commits after that one :|

Everything after 580c025 (https://github.com/schacon/showoff/commits/master?page=2).

burtlo commented May 28, 2012

Looking over the current template implementation, I'm not sure why the templates aren't simply using erb. Would you be opposed to using ERB?

<div style='background-color: red;' id='<%= id %>' class='slide <%= slide_classes %>' data-transition='<%= transition %>'>
  <div class='content <%= content_classes %>' ref='<%= reference %>'>
    <%= content_as_html %>
@burtlo burtlo ERB Templating support with defaulting
Within the showoff file, a template name can be associated with a
template file. That name can be used within the slides to generate
a slide with that template file.

goncalossilva commented May 28, 2012

Not at all. Did you check out the rest of the commits?

burtlo commented May 28, 2012

Yes, I'm looking them over.

burtlo added some commits May 28, 2012

@burtlo burtlo JSON file support templates 2301248
@burtlo burtlo Merge branch 'templates' 43b675a
@burtlo burtlo Pause message feature.
Presentations are able to define a pause message for the pause
screen. Unlike most features which is configurable per section,
this one is only valid on the top level showoff file
@burtlo burtlo Merge branch 'pause-screen' 199872e

burtlo commented May 29, 2012

I had a question about the full-page slide class.

  • full-page - allows an image to take up the whole slide

I took it to mean, from the description, that it should take all images on the slide and center and enlarge them:


In the current implementation it looks like the following:


However, full-page does definitely sound like it should break out of the slide mold and show it full-width.


goncalossilva commented May 29, 2012

Hum. Tough choice. In my opinion "full-page" doesn't mean "enlargement", but this is just my opinion. What about having them both with different names?

PS. Off the top of my head, I just remembered Android dev. When using images, there are various types of scale types (http://developer.android.com/reference/android/widget/ImageView.ScaleType.html)... we're basically discussing if "full-page" means CENTER_INSIDE or CENTER.

burtlo commented May 29, 2012

@goncalossilva I'll return it to the latter option, as the enlargement wasn't great, just what I thought of initially when I saw the text.

I think I have included most of the fixes and pull requests from the past three months; except for the multiple markdown support. I will take a look at that latter this evening.

burtlo added some commits Jun 7, 2012

@burtlo burtlo Metadata Parsers
> Instead of relying on an ever growing if-elsif-else block, the metdata
  parsers is simply a list of classes control the behavior of what data
  is matched and how it is converted to the metadata hash (which is
  then provided to the metadata hash)
@burtlo burtlo Merge branch 'metadata-parsers' aaaa2d2
@burtlo burtlo Added tests for each metadata parser 45cb936

burtlo commented Jun 11, 2012

To further clean up the project, I have started to tackle the javascript. I have been trying to create a more modular system with classes that employ pub/sub.


I am not done with it yet, but getting pretty close.

burtlo added some commits Aug 31, 2012

@burtlo burtlo FIX: Assets paths starting in presenting directory
  Javascript and CSS were failing to load when starting the presentation
  from within the folder. This is because of using gsub which replaced
  all instances of . instead of replacing only the first instance.
@burtlo burtlo Initial implementation of custom resources
  DSL supports a resource paths which will be stored and then added to
  the presentation for the CSS and JS files.
@burtlo burtlo Additional documentation for Metadata classes 6a69f6d
@burtlo burtlo Additional documentation for the DSL and JSON parsers 26b4d20
@burtlo burtlo Server documentation and use of helpers 4386481
@burtlo burtlo Removed redundant #build call c0b7e47
@burtlo burtlo Merge branch 'shared-resources'
@burtlo burtlo Custom CSS/JS files
  * Helpers will merge the filepaths better
  - FIX the request for custom resources by allowing js and css to
    be returned from the custom resources
  * Refactored to use a block to reduce the redundancy of the code
    between the js and css
@burtlo burtlo FIX: More Specific Gem requirements (parslet & gli)
This should address an issue for attempting to run showoff with a recent
bundle call. For some reason the parslet version that was being
installed was 0.9.0 and the gli version was too old.
@burtlo burtlo WIP Presentation JS object
Some presentation methods have been ported over into a class in the
index.erb and removed from the showoff.js
@burtlo burtlo Spine - JS Class Structure
Presentation is now composed of various sub-components:
* NavigationMenu
* DebugView
* SpeakerNotes
* PauseScreen
* HelpMenu
* Footer

Using an pub/sub arch to allow for a less coupled design

Slides are now managed by a Slides and returns a Slide object which
manages the increments, transition, and other information.

Extracted a location watcher which manages watching the
window.location and also watches the changes in slides
@burtlo burtlo JS - Preshow
Created a preshow and have it working in a rudimentary fashion
@burtlo burtlo Cleanup of JS that I do not want or I believe is unused b462f8f
@burtlo burtlo Using an unminified JS 78cfdb9
@burtlo burtlo Unminified coffeescript and upgrade to 1.4.0 899d1c0
@burtlo burtlo Removed the swipe events that were commented out 543e946
@burtlo burtlo Keyboard.js
Using an abstraction library to manage the big behemoth of keyboard
@burtlo burtlo Return to the old coffeescript d8f8115
@burtlo burtlo Removed a console.log fc6393b
@burtlo burtlo Added visor to enter commands; just responds with the command 20f7c71
@burtlo burtlo Keyboard JS added toggle support 37fd3bb
@burtlo burtlo Visor show disables other keys de946ae
@burtlo burtlo Initial command mapping 681a385
@burtlo burtlo Fuzzy matching on commands
n, ne, nex will match next
p, pr, pre, prev, previ, previo, previou will match previous
@burtlo burtlo Visor size and letter spacing; removed welcome message eb73bba
@burtlo burtlo Moved code execution with other commands 976e21f
@burtlo burtlo Working refactor of the code execution a49c2c9
@burtlo burtlo Minor refactor to move the code execution into its own file 1bd2d33
@burtlo burtlo Removed presenter mode until it can be fixed 0525120
@burtlo burtlo Merge branch 'js-refactor' 1440088
@burtlo burtlo Renamed all files to Parade 1d96e45

burtlo commented Dec 3, 2012

I took a break and have now returned to working on these changes. I believe I am going to fork this into a new gem.


alexch commented Dec 3, 2012

I agree that showoff's JS needs work, but instead, I've been using deck.js and it's great; it's fully unit tested with Jasmine and with my deck.rb wrapper gem, it's mostly backwards-compatible with showoff (e.g. understands showoff.json files).


burtlo commented Dec 3, 2012

@alexch I think deck.rb is still missing some fundamental things but I would love to continue this conversation further.


alexch commented Dec 3, 2012

@burtlo So how about you make a "deck.rb is still missing some fundamental things" issue at http://github.com/alexch/deck.rb/issues and we can continue this conversation further :-)

burtlo added some commits Dec 3, 2012

@burtlo burtlo FIX for showing 'help'; removed GLI cruft a106149
@burtlo burtlo Renamed of template to parade 4af60d3
@burtlo burtlo FIX for command-prompt bump when first starting
The prompt is immediately made visible, while the input follows after in
the typewrtier fashion.
@burtlo burtlo Removed unusued parser that should not have been there 02307d9
@burtlo burtlo Command Line Renderer
Added command-line styles to mirror the bash
Changed the time the command is rendered to be based on the length

thesteady and others added some commits Mar 8, 2013

@thesteady thesteady initial fixing of typos fe82d59
@gschorkopf gschorkopf Removed the slide for code -monospaces and the section in the README 3af5f62
@burtlo burtlo README customizing your footer 5c975bd
@burtlo burtlo Merge pull request #46 from gschorkopf/smaller
Changed files to reflect a wider selection of font sizes
@burtlo burtlo Merge pull request #45 from burtlo/remove-full-page-style
Remove full page style
@burtlo burtlo Merge pull request #47 from burtlo/customizable-footer
Customizable footer
@burtlo burtlo Merge pull request #48 from gschorkopf/removes-code-slides
Removes code slides
@burtlo burtlo FIX for footer 5c1cd75
@burtlo burtlo Removed .code styles 353e71e
@burtlo burtlo Executable Ruby only with the plugin b4873ca
@burtlo burtlo Slides can have the blank class 7c86cc8
@burtlo burtlo FIX for integration specs based on example preso change c54836a
@burtlo burtlo Adding rspec option to not run integration by default ad608e9
@burtlo burtlo Merge branch 'blank-slide' bbfa9ca
@burtlo burtlo Slide Title CSS ad6af94
@burtlo burtlo Updated the slide presentation to show off title and center af1727d
@burtlo burtlo Merge branch 'slide-title' a266c5b
@burtlo burtlo Slide style title-and-content 706c588
@burtlo burtlo Merge branch 'slide-title_and_content' 4e8c324
@burtlo burtlo Slide section-header e704f4c
@burtlo burtlo Merge branch 'slide-section_header' 2024b2d
@burtlo burtlo Slide class comparison 1d4519f
@burtlo burtlo Merge branch 'slide-comparison' eefa48d
@burtlo burtlo CSS Clean Up
* Updated css and js helpers to allow multiple files
* Moved parade.css styles to themes/default.css
* Moved slide styles to the slide_formats.css
* Moved navigation menu things to their own partial template
@burtlo burtlo Merge branch 'css-cleanup' 2a982a9
@burtlo burtlo Refined the merlot theme to just the essentials 1108140
@burtlo burtlo Removed subsection slide style e6109fa
@burtlo burtlo Refined the Archetect theme to essentials fc40274
@burtlo burtlo Minor spacing in merlot theme ddf8f2b
@burtlo burtlo Refined hack theme; Added BSOD and ./ 60dbf47
@burtlo burtlo Refined the slate theme 61c9aa1
@burtlo burtlo Hammer.js for touch support 0591490
@burtlo burtlo Merge branch 'touch-events' db15464
@thesteady thesteady Merge branch 'master' of github.com:burtlo/parade into proofread_README 284de8c
@thesteady thesteady edits to the README cd0189e
@burtlo burtlo Updated to support iPad portrait and landscape e33b0da
@burtlo burtlo Merge branch 'mobile/medium-form-factor' 4b90812
@burtlo burtlo Merge pull request #51 from thesteady/proofread_README
Proofread and edits to README
@burtlo burtlo iPhone landscape d176320
@burtlo burtlo Merge branch 'mobile/small-form-factor' 7587d52
@burtlo burtlo Setting Rouge '0.2.14' to workaround issues with loading on heroku e514a7f
@burtlo burtlo iPad Portrait Format reduce the size of the font 0cc709a
@burtlo burtlo FIX: for the iPad landscape code size f860531
@burtlo burtlo Better iPhone Landscape and Portrait Support 4d03a3e
@burtlo burtlo FIX for #31 removed 'reload slides' 268674c
@burtlo burtlo Fixes for Print format and FIX for generation of static pdf 7a4e612
@burtlo burtlo Parade output in HTML and PDF are now correctly styled
* FIX an ugly border that was present
* Updated so that they support themes
* FIX extra page in-between each slide
@burtlo burtlo Merge branch 'print-format' e64619a
@burtlo burtlo Updated /print URL to commands and additional slide movement commands 7683ca0
@burtlo burtlo Cleaned up available commands in README Issue #34 4ef3703
@burtlo burtlo Adding Up and Down arrows to the help menu #33 af3ce8e
@burtlo burtlo FIX: clean up of the print styles 8982598
@burtlo burtlo Renaming theme to jquery-ui dbb1c01
@burtlo burtlo FIX Issue #28 missing pause info from help menu 0601fb7
@burtlo burtlo Slide Image - Resizing
* Presentation will now load the slides through JS and not rely on
  the slides being in the div.
* FIX: /print will load the print.css and the normal view will not
* Images that are too large are resized to the size of the preso
@burtlo burtlo FIX for mobile formats of centered slides and print c87c9dd
@burtlo burtlo Merge branch 'js/slide-images-resolution' c4221e1
@burtlo burtlo Version 0.10.0 4370d9d
@burtlo burtlo Moved presentation loading to index.erb out of parade.js 41d8ee6
@burtlo burtlo Added Presentation Path Prefix
A presentation path prefix is set by the env['SCRIPT_NAME']. This
is restoring a feature that was added with the following pull


* All JS/CSS helpers will now recognize include the path prefix
* The JavaScript presentation will request the slides from the correct prefixed path
* The image paths are updated correctly as well
@burtlo burtlo Allow ImagePaths to be more tolerant of nils in prefixes ddf6e9e
@burtlo burtlo Updated specs for UpdateImagePath to test presentation_path_prefix a436159
@burtlo burtlo Merge branch 'multi-tenat-hosting' 7dcaec3
@burtlo burtlo Version 0.10.1 e615314
@burtlo burtlo Cleaned up Future Plans e2da2f2
@burtlo burtlo Adding a Parade Banner 868a4d9
@burtlo burtlo Flipped Marcy in Parade Image 6b98765
@thesteady thesteady created a new css theme, hayfield 5ca7c1b
@novohispano novohispano Minimal theme b5ea623
@burtlo burtlo Example Preso - commented out the default.css overrides 769f78e
@burtlo burtlo Merge remote-tracking branch 'laura/new_css_theme' 109f743
@burtlo burtlo Hayfield Theme - updated the footer style b39c666
@burtlo burtlo Example default.css really commented out all the styles this time b0bdbf4
@burtlo burtlo Updated Theme list in README aa8bd2d
@burtlo burtlo Merge remote-tracking branch 'jorge/working_on_css'
@burtlo burtlo Updated Minimal theme to have the correct background on command-line …
@burtlo burtlo Adding Minimal Theme to the list of available themes d3d4a00
@ivanoats ivanoats Added example generate presentation command
because I got stuck thinking options were --thing=value
@burtlo burtlo Merge pull request #61 from SustainableWebsites/master
Added example generate presentation command
@novohispano novohispano Adding bullet styles to minimal and minor changes on those slides in …
…the tutorial
@lalalainexd lalalainexd refactored columns renderer a lil bit f8d4eca
@lalalainexd lalalainexd completed inital implementation for content-with-caption renderer c5b4bb5
@lalalainexd lalalainexd added example use of content with caption and fixed slide post render…
…er to user the correct renderer for content with caption
@burtlo burtlo Merge remote-tracking branch 'jorge/working_on_css' fe44462
@burtlo burtlo Merge remote-tracking branch 'elaine/master' 06615b8
@burtlo burtlo Cleaned up spacing in the README bcfb147
@burtlo burtlo Section Slide Classes
Allow the ability to define section specific slide styles and classes.

section "Iteration 0" do
  css_classes "greed-background"
  slides "iteration-zero.md"

section "Iteration 1" do
  css_classes "blue-background"
  slides "iteration-zero.md"
@burtlo burtlo Added a print command to the visor which takes the user to the print …
@burtlo burtlo FIX: Errors in print version when a slide contains JQuery 67a998b
@burtlo burtlo FIX: README Notes Section #35 8caa522
@burtlo burtlo Removed further mention of the presenter d730ad5
@burtlo burtlo Re-arranged the documentation to place styles in a more general to sp…
…ecific order
@burtlo burtlo Updating the README to sell the project better a5c2376
@burtlo burtlo Updated to add Octocat on Deck Failure 68b3228
@burtlo burtlo Removing all support for the JSON file format eb6e817
@burtlo burtlo Removing notes from ever being toggled 4329f9d
@burtlo burtlo Removing the images from the file list b3e41c1
@burtlo burtlo Adding the overriding slide docs e1e0550
@burtlo burtlo Added the new section based css_classes e7446fd
@burtlo burtlo Version 0.10.2 cd4f72a
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment