Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/davetron5000/trickster

Developer-Friendly, In-Browser Presentation Software with auto-resize and syntax highlighting
https://github.com/davetron5000/trickster

Last synced: 18 days ago
JSON representation

Developer-Friendly, In-Browser Presentation Software with auto-resize and syntax highlighting

Awesome Lists containing this project

README 

        
= trickster



Trickster is a developer's in-browser presentation software.



Instead of focusing on flashy transitions, it focuses to encourage making a good presentation that looks good on the big screen.  As such, each slide is dynamically sized to be as big as possible.  Code slides have syntax highlighting, and you can call out lines of interest very easily, as well as create animated command-line slides.



It does this by compiling your presentation into an HTML file that, when loaded, will execute the Trickster

JavaScript, which will dynamically resize each slide to the biggest it can be based on the browser's current size.



== Presentation Format



Your presentation is stored in a text file.  Each slide has the following format:



    !: options

    

    

    



Where slide_type is one of the types listed below.  options is a space-delimited key/value string of options.  content is the content of the slide, interpreted based on the slide type.



=== Example:



    !TITLE: background=262626

    Welcome to my presentation!

    It's going to be awesome!



    !CODE

    def some_method(x)

      if x.nil?

        return "foo"

      else

        return x.upcase

      end

    end



    !BULLETS

    Check these bullets out!

    * This slide

    * is great!

    * and will be huge!



This defines three slides, the first of which is a TITLE with a custom background, the second of which is code, and the third of which is bullets.  When you play the presentation, each bullet is revealed one at a time.



Also note that each slide will be in a +section+ tag, with the CSS class of its type.  This allows you to control styling per slide type.

== options



background:: although you can customize each slide based on its CSS class, this option allows you to customize the background of this particular slide.  This is useful for IMAGE slides where you might want to better match the image's colors

transition:: number of milliseconds to transition to the *next* slide.  The default is in the config object, but this can override it per slide.



== TypeKit Support



When you build your presentation with trickster build, you can provide your typekit ID via -t.  Note that the fonts won't work unless you serve the page via a webserver, as TypeKit won't serve the fonts for a file:// URL.  You can do this via trickster serve.



== Slide Types



== BULLETS

The first line is the "title" if this slide, rendered in an +H1+.  The remaining are bullets.  If a bullet line is preceded with a *, -, or +, that bullet character is omitted automatically.



== IMAGE

The first line is the url to the image to show.  Trickster will size the image down only if it is too big, preserving its aspect ratio.



== CODE



If the first line starts with file://, the contents of this file is read in as the contents of the code block.  Otherwise, the entire contents of the slide is verbatim put into a +pre+ and then +code+ block.  Syntax highlighting is done using +highlight.js+.



== FREEFORM



The slide's content is passed through verbatim (keeping in mind that blank lines are slide delimiters).  This allows you to do more sophisticated layouts like tables or floats.



=== Language



By default, no language is specified for highlighting, so +highlight.js+ will make a guess.  If you'd like to be explicit, use the +language+ option, e.g.



    !CODE language=scala

    def doit(x:String) = {

      "foo"

    }



=== Callouts



A code slide accepts an option of +callout+ which is a comma-delimited list of the lines of code to "call out" with special styling.  This is useful if you are talking about particular lines, or are demonstrating new lines having been added to a previous example.



Further, if the line number is preceded with a dash (e.g. -3), that line will be styled for strikethrough, in addition to being highlighed.  This is useful to show lines of code that are going to be deleted based on whatever you are talking about.



=== Highlighting Themes



Trickster comes with all the themes provided by highlight.js, as well a customizable theme in SCSS.  When you create your slideshow, use --theme to specify the syntax highlighting theme.  trickster help init will show the list of themes available.



If you want easily create a custom highlighting scheme, the theme +custom+ generates a SASS template with variables to allow you to easily set the colors you want.



Once your slideshow has been created, you can change the theme via trickster update theme. This is destructive so make sure your slideshow is checked into version control.



== COMMANDLINE



This slide is for showing command-line invocations and results. It is assumed to start with a CLI invocation and that such invocations are followed by results, that can be many lines.  When you present the slideshow, the command will be output in a "typewriter" style, after which the result will be shown automatically, with each command acting like a "bullet" to be revealed.



=== Example



    !COMMANDLINE

    > ls -l

    -rw-r--r--  1 davec  staff     25 Aug 25 14:49 Gemfile

    -rw-r--r--  1 davec  staff   1563 Sep  9 16:11 Gemfile.lock

    -rw-r--r--  1 davec  staff   4136 Sep 10 18:54 README.rdoc

    drwxr-xr-x  3 davec  staff    102 Sep 10 18:50 tmp

    > vim Gemfile

    editing Gemfile



Prompts can be >, %, and #.



=== Any other type



These slides take the first three lines of content and display them in an +H1+, +H2+, and +H3+, respectively.  All other lines are ignored.



== Timer



Currently, there will be a small timer on the bottom left of your presentation.  By default, it will show the number of minutes elapsed since you clicked the play button.  It can be customized:



* If you don't want to use the timer, simply add display: none to the #timer stanza in the stylesheet.

* If your presentation might go over an hour, remove display: none from the #timer .hours stanza in the stylesheet.

* If you want to see seconds elapsing,  remove display: none from the #timer .seconds stanza in the stylesheet.

* If you want to hide the controls (e.g. because you know the keyboard shortcuts or have a presentation remote), add display: none to the #controls stanza in the stylesheet.

* You can adjust the style in any other way you see fit in the stylsheet



=== Timing



The config allows you to specify the length of your talk, a time at which to warn you, and a time at which to alert you.  These all boil down to adding CSS to the timer:



* If you are under time, alerting, and warning, time-ok is the class of the timer.

* If you are under time and alerting, but over for the warning, time-warn is the class of the timer.

* If you are under time but over alerting, time-alert is the class of the timer.

* If you are over time, time-over is the class of the timer.



You can modify what happens with these styles in your styles.css.



== Customizations/Styling



You have two points of customization: +custom.js+, which is loaded *after* all the other JS, but before the +load+ event.  This is where you can override Trickster's configuration if you like (e.g. for default transition time).



The second, and more useful, point of customization is +styles.css+ or +styles.scss+.  This is loaded in your presentation and is where you can customize the look and feel of your slideshow.  If you create a .scss file, trickster will run SASS on it to convert it to CSS, so you have the full awesome power of SASS available.



=== Styling Recommendations



* Prefer 'em' over explicit sizes, as this will aloww your sizing choices to work at any size (remember that Trickster tries to fit your content to the screen)

* The BODY element will be given the class of the currently-displayed slide, so if you want to, for example, change the background color of a slide based on its type, apply styles to body.SLIDE_TYPE and not section.SLIDE_TYPE

* If you want to customzie the syntax highlighting, you can.  trickster update will leave it alone.  If you want to build a more invovled highlighting theme, use the "custom" theme when you create your presentation or migrate to it via trickster update theme -t custom



== Delivering the Presentation



Simply open `index.html` in your browser.  Your browser should be Safari or Chrome.



Every time you reload, the presentation will be dynamically sized to the size of the browser, so you should configure your browser and monitor to the size of your presentation, then reload.



Occasionally, Trickster will size the slides too larger or too small.  In that case, you can use "-" and "+" to resize the slides on the fly.  Note that if you you reload, the sizes will be reset.



Finally, if you want to see your elapsed time, click the play button before you start (see keyboard shortcuts below).



=== Keyboard Commands



advance:: "j", space-bar, right-arrow, or the advance button on the Kensington Wireless Presenter.

back:: "k", backspace, left-arrow, or the back button the Kensington Wireless Presenter.

restart:: down/stop button on the Kensington Wireless Presenter.

increase font-size:: "+" or "=" (font-size will be reset if you reload the page)

decrease font-size:: "-" (font-size will be reset if you reload the page)

start timer:: down on your Kensington remote, or "p"

pause timer:: "a"



== Tips



Trickster discourages verbose slides with lots of text or lots of bullets. This is because these are aspects of terrible presentations.  Instead, create many more slides with fewer amounts of text.



= CLI



== trickster - Bootstrap, generate, and manage your trickster presentation



v1.3.1



=== Global Options

=== --help

Show this message



=== --version

Display the program version



=== Commands

==== Command: build  [slides_file]

Generate the presentation from your slides



Given your slides_file (defaults to 'slides' in current directory), generates an HTML file (based on --output-file) that, when loaded, can be used to play your presentation.



Any .scss files found in the css/ directory will be run through SASS to be converted.



Note that currently, the CSS and JS files included are fixed, so keep all your customizations to styles.css/styles.scss and custom.js (these files will not be overwritten when you do a trickster update).

===== Options

===== -o|--output-file file



Name of the generated HTML file



[Default Value] index.html



===== -t|--type-kit-id id



Your TypeKit ID, if using TypeKit



[Default Value] None



==== Command: help  command

Shows a list of commands or help for one command



Gets help for the application or its commands. Can also list the commands in a way helpful to creating a bash-style completion function

===== Options

===== -c

List commands one per line, to assist with shell completion



==== Command: init  dir_name

Create a new trickster presentation



This will create a completely self-contained presentation that can be run just from the files

in the directory you name.  It will have a static copy of the JavaScript files, JavaScript third-party

libraries and CSS files you need to run your trickster application.



You can examine the file `slides` to see some examples of how to format your

presentation.  You can run `trickster build` in the directory to create the HTML

file from your slides.



Note that if you upgrade trickster, you should run `trickster update` in your slide directory

to get the latest JavaScript and CSS files.

===== Options

===== -t|--theme arg



Specify the syntax highlighting theme to use.  One of arta, ascetic, brown_paper, custom, dark, default, far, github, googlecode, idea, ir_black, magula, monokai, pojoaque, rainbow, school_book, solarized_dark, solarized_light, sunburst, tomorrow, tomorrow-night, tomorrow-night-blue, tomorrow-night-bright, tomorrow-night-eighties, vs, xcode, zenburn.  Use 'custom' to get an scss file you can easily customize.



[Default Value] default

[Must Match] ["arta", "ascetic", "brown_paper", "custom", "dark", "default", "far", "github", "googlecode", "idea", "ir_black", "magula", "monokai", "pojoaque", "rainbow", "school_book", "solarized_dark", "solarized_light", "sunburst", "tomorrow", "tomorrow-night", "tomorrow-night-blue", "tomorrow-night-bright", "tomorrow-night-eighties", "vs", "xcode", "zenburn"]



==== Command: serve 

Serve your presentation on a local port



If using TypeKit, you'll need to actually run your presentation on a web server so the fonts will be downloaded.  This is an easy way to do that without having to mess with any other gems, libraries, or configuration.

===== Options

===== -p|--port port



Port on which to run



[Default Value] 9090



==== Command: update  [dir_name]

Update your slideshow with files provided by trickster



===== Commands

====== Command: files  slide_dir

Update the trickster JS/CSS files when you've updated the trickster gem



Run this after you've upgraded trickster and want to get the latest features.  Since your 

  slideshow is entirely self-contained, when you upgrade trickster, your static JavaScript and

  CSS files will be out of date.



  Note that `styles.css`, which was provided by trickster as a basis for styling, will not

  be touched, and your customizations will remain. All other files that trickster gave you

  when you ran `trickster init` will be overwritten.

====== Command: theme  slide_dir

Update the syntax-highlighting theme for your presentation



A normal 'trickster update' will leave your theme.css alone, since you can customize it.  This will overwrite

  your existing theme.css with the theme from trickster that you specify.  You should check your presentation

  into source control to avoid the destructive nature of this command.

======= Options

======= -t|--theme slide_dir



Specify the syntax highlighting theme to use.  One of arta, ascetic, brown_paper, custom, dark, default, far, github, googlecode, idea, ir_black, magula, monokai, pojoaque, rainbow, school_book, solarized_dark, solarized_light, sunburst, tomorrow, tomorrow-night, tomorrow-night-blue, tomorrow-night-bright, tomorrow-night-eighties, vs, xcode, zenburn.  Use 'custom' to get an scss file you can easily customize.



[Default Value] default

[Must Match] ["arta", "ascetic", "brown_paper", "custom", "dark", "default", "far", "github", "googlecode", "idea", "ir_black", "magula", "monokai", "pojoaque", "rainbow", "school_book", "solarized_dark", "solarized_light", "sunburst", "tomorrow", "tomorrow-night", "tomorrow-night-blue", "tomorrow-night-bright", "tomorrow-night-eighties", "vs", "xcode", "zenburn"]

A normal 'trickster update' will leave your theme.css alone, since you can customize it.  This will overwrite

  your existing theme.css with the theme from trickster that you specify.  You should check your presentation

  into source control to avoid the destructive nature of this command.



[Default Command] files