My table looks better than yours

JB: I would like to link to examples that show the same R Markdown file compiled to HTML using different CSS ... but this is a good start.

After the data aggregation tutorial, a student noticed that, when run on her machine, my examples did not produce such attractive tables. That's because I am NOT using RStudio's default Markdown CSS upon conversion from R Markdown to HTML.

The default CSS produces wide webpages with small text, which I find hard to read.

First, get a better CSS. I took an entire collection from https://github.com/jasonm23/markdown-css-themes, which are released under a "do what you want with them" license. When I wrote this in September 2013, I was using markdown7.css. I can't promise I won't switch CSS, so there is no absolute guarantee that the HTML you are looking at now was created with markdown7.css.

But how do you actually use a different CSS? Here's a suggested workflow if you're struggling but if you're feeling lucky, just skip to the bottom.

I learned everything I know about this from RStudio's page on Customizing Markdown Rendering.

Specifying a CSS when knitting "by hand"

Put the CSS you want to use, e.g., the file markdown7.css, in the directory associated with your project, which I'll assume is your current working directory and also holds the file(s) you want to use "Knit HTML" or "Compile Notebook" on. BUT instead of using the buttons, compile to HTML yourself. For example:

library(knitr)
knit2html("test.Rmd")

If you get an error, read it and fix it. Once you are error-free, look at, e.g., test.html in a web browser to make sure all is well. You can read more about compiling to HTML here.

Now, request your new non-default CSS. This is controlled by the stylesheet = argument of the markdownToHTML() function, which is being called by knit2html(). We are exploiting the fact that knit2html() includes the very special function argument ... and is passing my stylesheet down to markdownToHTML().

knit2html("test.Rmd", stylesheet = "markdown7.css")

If you get an error, read it and fix it. Once you are error-free, look at, e.g., test.html in a web browser to make sure the overall style is different. For example, the font size is bigger, the page isn't so wide, the tables look different/better.

Once you've proven you can control the CSS, move your stylesheet(s) to another location, probably somewhere higher up in your filesystem, so you can use them in many projects. Note the new absolute path to your CSS and compile your test again "by hand" specifying the new location. Maybe try a different stylesheet just for fun!

knit2html("test.Rmd", stylesheet = "/Users/jenny/resources/css/jasonm23-markdown-css-themes/markdown4.css")

Step 1 is complete.

Using .Rprofile to influence start-up

To better understand what one's .Rprofile does, look at the official R help for Startup. Google is also your friend.

First, find out your home directory. That's where you should put .Rprofile.

path.expand("~/")

## [1] "/Users/jenny/"

Initialize .Rprofile with something minimal like this:

cat("\n  Get some real work done, Jenny!\n\n")

Restart R and verify that your motivational text appears. Remember you can restart R within RStudio with Session > Restart R. If you don't see your text, your .Rprofile is not being processed. Troubleshoot until you know it's working.

Step 2 is complete.

Putting it all together: change the CSS used by RStudio's "Knit HTML" and "Compile Notebook" buttons

Now that you have a working-but-silly .Rprofile and you have proven you can specify the CSS "by hand", you can change the behavior of RStudio's "Knit HTML" and "Compile Notebook" buttons.

Include something like this in your .Rprofile (I added comments for clarity here):

options(rstudio.markdownToHTML = function(inputFile, outputFile) {
    require(markdown)
    
    ## make easy to toggle base64 encoding of images and perhaps other things ...
    htmlOptions <- markdownHTMLOptions(defaults = TRUE)
    ## htmlOptions <- htmlOptions[htmlOptions != 'base64_images']
    
    ## you must customize for where YOU store CSS
    pathToCSS <- "resources/css/jasonm23-markdown-css-themes"
    pathToCSS <- file.path(path.expand("~/"), pathToCSS, "markdown7.css")
    
    markdownToHTML(inputFile, outputFile, options = htmlOptions, stylesheet = pathToCSS)
})

If you are using Windows, you may need to think about the path separator, although this thread seems to suggest not? I'D LOVE TO NAIL THIS DOWN!

Now compile your test document to HTML again, using RStudio's buttons, and confirm your new CSS is being used. You may need to restart RStudio for this to come into effect.

For completeness, let's create a small HTML table here. Note that the R chunk producing the table below includes a very important chunk option: results = 'asis'. You can see that I am using a function from the xtable package to convert a data.frame to an HTML table. Other packages you may want to look at for such conversions are Hmisc, tables, and R2HTML. Learn more in the CRAN Task View: Reproducible Research.

library(xtable)
foo <- head(iris)
foo <- xtable(foo)
print(foo, type = "html", include.rownames = TRUE)