ramnathv/slidify

Generate reproducible html5 slides from R markdown

Slidify helps you create and publish beautiful HTML5 presentations from RMarkdown

Getting Started

Install

Slidify is still under heavy development. You can install it from github using the devtools package. You will also need slidifyLibraries which contains all external libraries required by slidify.

install_github('ramnathv/slidify')
install_github('ramnathv/slidifyLibraries')

Initialize

You can initialize a presentation by running create. This will create a scaffold for your presentation and open an Rmd file for you to edit.

library(slidify)
author('mydeck')

Author

Write your presentation in RMarkdown, using a newline followed by three dashes to separate slides. You can mix markdown with code chunks to create a reproducible slide deck.

Generate

Generate your presentation by running slidify. This will create a static HTML5 presentation that you can open locally in your browser.

slidify('index.Rmd')

Publish

# publish to github
# create an empty repo on github. replace USER and REPO with your repo details
publish(user = USER, repo = REPO) 

# publish to rpubs
publish(title = 'My Deck', 'index.html', host = 'rpubs')

---

Customize

Slidify is designed to be modular and provides a high degree of customization for the more advanced user. You can access the defaults using slidifyDefaults(). It is possible to override options by passing it to slidify as a named list or as a yaml file.

framework      : slide generation framework to use
theme          : theme to use for styling slide content
highlighter    : tool to use for syntax highlighting
hitheme        : style to use for syntax highlighting
mode           : selfcontained, standalone, draft
url            : paths to lib
widgets        : widgets to include

Slidify makes it easy to create, customize and publish, reproducible HTML5 slide decks from R Markdown.

It is designed to make it very easy for a HTML novice to generate a crisp, visually appealing HTML5 slide deck, while at the same time giving advanced users several options to customize their presentation.

The guiding philosophy of slidify is to completely separate writing of content from its rendering, so that content can be written once in R Markdown, and rendered as an HTML5 presentation using any of the HTML5 slide frameworks supported.

slidify's Issues

Think about using --- as slide separator!

It is simple enough to use, yet creates quite a bit of ambiguity. Some examples include:

1. Setext style level 3 headers
2. GFM Tables

Write unit tests to ensure that future updates dont break slidify

I think it would be necessary to write good unit tests. I need to refresh my memory on how to write tests with testthat.

Add license as a valid parameter

It would be nice to add LICENSE as a parameter and a partial {{ > license }} which would automatically add a license page to the slide deck. For starters, I can just use the MIT license and a few other open source licenses.

Think about decoupling slidify from knitr

The primary purpose of slidify is to generate HTML5 slide decks from markdown. By tying it down to knitr, I am reducing the user base which can benefit from it. In the spirit of modularity, I can add this as an option to preprocess the source file before it is rendered.

I can use the option engine which by default is set to knitr so that the current behavior remains unchanged. However, a user wishing to process a .md file can choose to set engine = NULL and use slidify directly.

Write OpenCPU App for slidify

The knitr app on opencpu looks cool! Once I stabilize the API for slidify, it would be a good idea to write an app that can be put on opencpu.

HTML5 Slides CSS: Too much space in list

Copy template to assets folder to allow user to modify it.

This would allow the user to tweak the default template to his or her liking, thereby providing greater control over the output. A simple use case would be where a user wants to add a footer to every page. It is easier to achieve this by directly manipulating the template rather than manipulating the CSS.

Provide option to export as beamer pdf using pandoc.

In order to enable this option, I need to follow the guidelines for slide formatting in pandoc. Here are the key things
to do in order to make slidify decks pandoc compatible

1. Remove class definitions from slide separators.
2. Download and replace online images with local images.
3. Remove content with iframe, script etc.

Allow users to specify a configuration file to generate a slide deck.

Allow users to specify a configuration file to generate a slide deck.

The idea is similar to showoff.json file in showoff and landslide.cfg in landslide. I am thinking of using a slidify.yml file to specify the options. Here is how a sample configuration file will look like

source: [intro.Rmd, overview.Rmd, examples]
framework: html5slides
highlighter: R
histyle: acid

This should be straightforward to implement now. Here is how I am thinking the logic would work.

1. Check if the slide directory has a slidify.yml file.
2. If it does, then set options = yaml.load_file('slidify.yml')
3. Else, set options = slidifyOptions()

I want to give it a little more thought before implementing this and closing this issue.

Allow metadata specification in document using YAML front matter

I think it would be useful to allow a metadata block in the document where the title, author and date can be specified. I have two options on how to go about it. The main tradeoff is simplicity vs. extensibility. The pandoc style title blocks are very simple, but lack the ability to be extended. The jekyll or MMD style YAML front matter provides a lot of flexibility in the metadata that can be provided.

I think I am going to go with YAML front matter, due to the flexibility it offers. I need to think about importing YAML or just leaving it as a suggested package.

Pandoc Style Title Blocks

% title 
% author(s) (separated by semicolons) 
% date

YAML Front Matter

Title:   A Sample MultiMarkdown Document  
Author:  Fletcher T. Penney  
Date:    February 9, 2011  
Comment: This is a comment intended to demonstrate  
         metadata that spans multiple lines, yet  
         is treated as a single value.  
Test:    And this is a new key-value pair  

Fix errors due to empty header or empty slide

The error due to empty header is already fixed. For empty slides, I just need to search for a regex pattern.

Think about choice of slide separator

Currently, slidify recognizes the following as slide separators.

1. --- foo bar #my-id
2. !SLIDE foo bar #my-id
3. <!SLIDE foo bar #my-id>

I need to think about rationalizing them in order to keep the design simple. The advantage of --- is that

a. easy to use and logical
b. resulting markdown document displays well

If users add slide classes to the same line, they can enclose it within angled brackets so that it doesnt show up in the rendered version of the markdown document.

I will give this a little more thought, but I am more or less convinced that the way to go about it is to allow the following three separator formats

1. --- foo bar #my-id
2. < --- foo bar #my-id >
3. <!-- ---foo bar #my-id >

Write a commandline version of slidify using 37signals/sub

This is done. I just need to put it together.

Figure out adding build to specific elements

It is important to figure out how to add build to specific elements. It is an essential part of a good presentation to be able to step through different parts of a slide in sequence.

Figure out conversion to PDF

A major drawback with web based presentations is that you need to be online. I would like to figure out solutions that would allow users to export an HTML5 presentation as a pdf file.

Add short title to landslide template to allow nicer looking toc

Folder Structure

As slidify continues to evolve, here are some additional thoughts on the structure of the assets folder of the slide deck.

fonts : font kit downloaded from a source like fontsquirrel
stylesheets : custom css files to include in the slide deck
javascripts  : custom js files to include in slide deck
layouts : layout to use for slide deck
partials: partials to use for slide deck including templates

Implement slide templates

This idea is from showoff. The idea is that while slide classes allow you to style slides to an extent, allowing for templates lets you do more powerful stuff.

A use case I can think of is when you want a two column slide.

fenced code blocks go missing

I don't see any in the slides. Using slidify at defaults

Figure out how to print slides to pdf

Here is a presentation made with html5slides that has a pdf version: http://goo.gl/lmoGB. I wonder how it was done.

Add google prettify to highlighters

I have added prettify and the associated themes. A few rough edges remain.

1.The linenums option is not turned on by default and I don't have a mechanism for the user to turn it on.
2. Setting linenums as an option manually in the html file leads to mangled code box, where everything is shifted. This might be an issue related to css and has to be fixed before prettify can be used.

I am going to accord this issue low priority since prettify is NOT a good highlighter for R.

Automatically upload source file as a gist and link back to slides

Look at using httr and the gist API to auto upload source files as a gist and link back.

Automatically detect title based on first page

The <h1> tag of the first page may be used for the title of slide.

Generate slide deck from gist!

I think it would be cool to be able to write your slide deck as a gist that you can edit from anywhere, and then have slidify render it as a slide deck.

Invisible slide

E.g., the slide is invisible if it begins with two lines of ---

---

---

This will be useful when one Rmd is used for the static html report and html slides.
The static page includes all information while the slides may not show some detailes of output (e.g., output of statistical analysis).

Consider ideas from beamer

Since beamer is the de-facto standard for presentations in the tech community, I think it makes sense to draw ideas from beamer. Here are some ideas that might be useful to explore.

1. The idea of splitting a theme into outertheme, innertheme, colortheme etc. is neat. This can be easily replicated in terms of css by splitting the theme file of a css into multiple parts.
2. The idea of overlays is very well developed in beamer. It would be interesting to replicate some of the features using javascript. For example \alert<2> shows text alerted on the second slide. I am wondering if there already exists javascript frameworks which can do such overlays.

Consider renaming package to slidifyR

There are several projects on github called slidify. It might make sense for me to rename this repository and package to slidifyR. I can retain the name of the main function as slidify.

Make it Easy to Publish a Slidify Presentation

It would be useful to think about either a utility function, or a tutorial on how to publish a slidify presentation. Two options that come to my mind are:

1. Github
2. Dropbox

For github, it would be relatively straightforward to write a utility function, while for dropbox, I might consider rDrop which looks promising.

Debug presenter notes in html5rocks

Presenter Notes are visible in slide unless content is given the class middle. Need to figure out if this is a bug or I am not doing it correctly.

Use shadowbox.js for displaying multiple images on a single page

Use jquery to provide links to functions

Here is an idea from Barry Rowlingson's blog on using jquery to provide links to functions in source code. It would be cool to provide this as a partial along with slidify

$("span.functioncall").replaceWith(function(){
  return '< a href="http://rgm2.lab.nig.ac.jp/RGM2/search.php?query='+$(this).text()+'" >'+
     $(this).text()+'< /a >'
})

Implement more slide classes

I am taking inspiration from some of the best slide generating tools out there.

Showoff

Here is list of useful styles picked verbatim from showoff by Scott Chacon.

• center - centers images on a slide
• full-page - allows an image to take up the whole slide
• bullets - sizes and separates bullets properly (fits up to 5, generally)
• smbullets - sizes and separates more bullets (smaller, closer together)
• subsection - creates a different background for titles
• command - monospaces h1 title slides
• commandline - for pasted commandline sections (needs leading ‘$’ for commands, then output on subsequent lines)
• code - monospaces everything on the slide
• incremental - can be used with ‘bullets’ and ‘commandline’ styles, will incrementally update elements on arrow key rather than switch slides
• small - make all slide text 80%
• smaller - make all slide text 70%

Add modified uulm theme for html5slides

This would also be a good test bed for testing slide specific templates.

Clean up meta data in all mustache templates

I need to clean up meta data information in all mustache templates. I should think about adding a <meta generator = 'slidify'> tag.

Allow users to specify options as yaml front matter

It would be good to allow users to specify options as yaml front matter. The key design question is how to override options. A clean way to do this would be to use the YAML front matter to override defaults.

UPDATE. merged with #39 now.

Add support for more slide generation frameworks!

1. HTML5 Rocks
2. Slideous

Mirror Repository on Google Code for using as CDN

I want to use Google Code as CDN for serving javascripts and stylesheets for the various html5 slide frameworks, so that the html5 slide deck generated is more stand alone.

Tentatively, I can use gh-pages as a CDN, but it is not a long term solutions since github is not intended to be used as a CDN.

Consider using documentup for quick and easy documentation

In the long run, I would want a nice website containing all the documentation for slidify. But in the short run, I think I can take advantage of documentup and maintain all documentation in README.md.

Plan for Monteral R Users Talk

This is just a rough checklist.

1. Create a git repository for the talk.
2. Create an outline for the talk
3. Consider Hangout on Air for webcasting.

Outline

Use slide title to make id if not defined

The id for a slide can be constructed based on the title. For instance, if the title is Introduction to Slidify, the id would be #introduction-to-slidify

presenter display and presenter notes

It seems to me slidify neither offers the possibility of writing presenter notes and nor a separate presenter display where the notes are displayed and also a timer with the remaining time for the presentation. I'd love to be proven wrong because I use knitr and markdown and Apple's keynote could hardly fit less within my toolset, but the dual display is a must-have.

Bug in Regex that causes single titles to be repeated

If a title slide has a ? it gets rendered twice. The error is in the regular expression in get_slide_vars.

---

# What is this?

gets rendered as

<h1> What is this> </h1>
<h1> What is this> </h1>

Add google analytics and social sharing tools to slidify

Figure out how to manage LICENSES

slidify is built on the hard work of several developers who put together time and effort in developing HTML5 slide generation frameworks. Moreover, it is also built on the work of R developers, especially knitr, whisker and markdown.

I need to figure out a way to manage the licenses of all included CSS and Javascripts, so that I abide by the original licenses in the first place.

Refactoring Ideas

Highlighter

Currently, I am writing a lot of code to convert highlighter into 2 binary variables highlight_js and google_prettify. This also requires me to specify two partials in my templates {{ > highlight_js }} and {{ google_prettify }}. I can simplify this significantly by defining a single partial highlighter, which only reads the partial specified. So the code would look somewhat like this

partials$highlighter = get_partial(highlighter)

I need to redefine the function get_partial to something like this

get_partial <- function(partial){
  partial <- file.path(partials_path, sprintf('%s.html', partial))
  readLines(partial)
}

It would be good to have a path specification for partials as well.

Figure out default color palette and fonts

I want slidify to have an identity of its own. One way to do this is to make slidify decks stand out by way of choosing good defaults for fonts and colors.

Consider making slidify pandoc-compatible

Pandoc parses a markdown document into slides using the following rules (as taken from http://goo.gl/4CVWO)

By default, the slide level is the highest header level in the hierarchy that is followed immediately by content, and not another header, somewhere in the document. In the example above, level 1 headers are always followed by level 2 headers, which are followed by content, so 2 is the slide level. This default can be overridden using the --slide-level option.

• A horizontal rule always starts a new slide.
• A header at the slide level always starts a new slide.
• Headers below the slide level in the hierarchy create headers within a slide.
• Headers above the slide level in the hierarchy create “title slides,” which just contain the section title and help to break the slide show into sections.
• A title page is constructed automatically from the document’s title block, if present. (In the case of beamer, this can be disabled by commenting out some lines in the default template.)

Add slide table and interlinking

http://goo.gl/SmEUd

Look into the jquery cycle plugin to provide more transition options

Some ideas from Ruhoh

I am very impressed with the thought put into making Ruhoh modular. In particular, I like the way themes are implemented in Ruhoh. Here is a description lifted verbatim from the documentation.

A theme's primary role is to provide styling and assets to your your content. Ideally a theme should do this in an unobtrusive and modular way, always acting as an asset namespace.

A theme is simply a collection of layouts, partials, and assets such as stylesheets, images, and javascripts that those partials and layouts depend on.

The directory structure for every theme is fixed. Themes merely act as namespaces for the assets.

|- theme
|--- javascripts
|--- layouts
|--- media
|--- partials
|--- stylesheets
|--- widgets