Fast-track publishing using knitr: the setup using .RProfile with custom CSS + some HTML goodies (part II)

Flexing RStudio/knitr where you want can be a challenge. The image is CC by Ben Barnes.
Flexing RStudio/knitr where you want can be a challenge. The image is CC by Ben Barnes.

Fast-track publishing using knitr is a short is a short series on how I use knitr to get my articles faster published. This is part II where I will show how you can tweak RStudio into producing seamless MS Word-integration by using the .RProfile together with CSS, a few basics about HTML that might be good to know, and lastly some special characters that can be useful. In the previous post, part I, I explained some of the more general concepts behind fast-track publishing and why I try to get my manuscript into MS Word instead of using LaTeX or other alternatives.

The series consists out of five posts:

  • First post – an intro motivating knitr in writing your manuscript and a comparison of knitr to Word options.
  • Second post – setting up a .RProfile and using a custom.css file (current post).
  • Third post – getting your plots the way you want.
  • Fourth post – generating tables (current post).
  • Fifth post – summary and example.

RStudio is in my opinion currently the best tool for using knitr. It allows code folding, navigating through chunks, direct knitr integration, spell checking, and is actively being developed. It is therefore a little odd that the default markdown document generated in knitr looks… terrible:


As you can see there are no margins, allowing no white space that would enhance the reading. As nicely put by Carrie Cousins:

“Don’t forget about the margins. Remember to leave some white space around the entire text frame, creating an almost invisible halo. This margin will help set text apart from other “noise,” easing the reader into the copy.”

This becomes even more difficult to read if we change the window width:


The solution to this is to attach your own CSS file. RStudio has a basic help page that you can find here about changing the CSS. Important to remember is that changing the CSS-rendering must be done before knitting the document.


Inspired by LaTeX’ wide margins, I usually submit my manuscript with wide margins (2 inches/5.08 cm left and right) in order to keep the optimal character count between 65 and 75 characters per line. This helps reading the document and hinting how the paragraphs (more guidelines) will feel in the published article.

A RStudio/knitr .RProfile

The .RProfile is a document allowing you to execute code at startup. All you need to do is create a file called .RProfile in your home directory, If you are uncertain: then start RStudio (close any open project) and write getwd() = your home directory. The home directory is on OS X/Unix/Linux systems located at the “~/” directory, in Windows 8 this is the “Documents” or “My Documents” folder, Windows 7 it is your user folder (the one with your username).

My .RProfile has a few tweaks in it:

  • Use custom.css if exists: If there is a file at the same location as the knitr .Rmd document called custom.css it automatically switches to this alternative. As this runs at startup I don’t need to worry about running any code before knitting.
  • Skip embedded png: Libre Office can’t handle embedded png-images, it hangs as it tries to process them. You can still use embedded png-images by specifying: options(base64_images= "inline").
  • Fix headers: Libre Office “forgets” the margins for the headers object if they are specified in the CSS, I have therefore a crude gsub() fix for this, to skip it simply set the option options(LibreOffice_adapt= "skip").

The custom.css file

CSS is extremely flexible although it is important to keep in mind that if you aim at Libre Office or MS Word import these are rather limited in their CSS abilities. I use the one below that is optimized to be as similar as possible to the Word template and imports nicely (copy the text into a file that you name custom.css):


If you want to generate your own custom CSS I suggest you start by tweaking the original CSS that you can find here. While I thought the heading colors were a little silly at the beginning I now like how they softly integrate into the text. Microsoft probably put top designers when generating the default style for Word and I think it is sensible to trust their judgment, their settings is probably a pretty safe starting point.

A few HTML basics

HTML (HyperText Markup Language) was developed in 80:s and has remained the main way to communicate documents on the web. Although it has been refined over the years the basic structure is mostly the same. The document markup consists of <start> </end> tags, where the text within <> contains the element type. The basic structure of the document is:

HTML doc structure

Everything is wrapped within the main document, the <html> corresponds to the grey area. Subelements to the <html> are the <head> and <body> elements. The <head> contains meta-data not shown in the document and the style sheet should be defined within this area. The <body> contains the actual text with all the paragraphs, tables, and images.


As you may have noticed the <body> element was also present in the CSS-elements above. CSS you can set the CSS properties of each <body> element, you can for instance see that the paragraph element, <p>, has the attributes:

The above states that the padding should be 0 on all sides while the margin should be 10 points below. The 4-in-1 description of the different sides can be confusing although all you need to remember is TRouBLe (top, right, bottom, left). If you still feel a little queasy you can go with the specific parameter by expanding the above into:

You can also find the headings <h1>, <h2>, <h3>, … (the number corresponds to the heading level), first with the common attributes:

And then with specific attributes for each heading later on (although note that the margin setting is also overridden in the .RProfile due to the Libre Office incompatibility):

Using this knowledge you should be able to tailor your document layout to your needs. Remember though that Word/Libre Office has not prioritized handling HTML and you may need to try some different alternatives before you get it to work.

Useful HTML-features

I’ve found that <sup> </sup> for superscript is very convenient although markdown has a shorthand for this ^ where you write 106 as 10^6. Perhaps more useful is subscipting <sub> </sub> with that currently doesn’t work as intended in default RStudio markdown (H~2~O does not translate into H2O while H<sub>2</sub>O does, note that the H~2~O works with Pandoc).

Special characters

Another thing that is very useful is special characters. Special characters basically any characters outside the English alphabet. Some very useful for tables are for instance the daggers and similar:

Code Glyph Description
&dagger; Dagger
&Dagger; Double dagger
&sect; § Section sign
&#8226; Bullet
&dot; ˙ Dot accent
&curren; ¤ General currency sign
&deg; ° Degree sign
&permil; Per mill sign (10-3)
&ap; Approximate sign
&plusm; ± Plus minus
Just enter the code and it should work, don’t forget the & and the ending ; without any intervening space

Well that’s it for this part, I hope you enjoyed it.

Flattr this!

This entry was posted in R, Tutorial and tagged , . Bookmark the permalink.

11 Responses to Fast-track publishing using knitr: the setup using .RProfile with custom CSS + some HTML goodies (part II)

  1. Owe Jessen says:

    Have you given any thougth to using pandoc for the export into word? I build a small example here, it works with ubuntu as well as with windows:

    • Max Gordon says:

      Thank you for sharing the example. I like Pandoc and I commented on it in my intro, it is definitively useful but due to it’s limitations with table design I don’t use it. As far as I understand it Pandoc skips any advanced HTML.

  2. Yihui says:

    I definitely agree the default CSS style needs improvement. Frankly, I do not quite like it, either. Perhaps we will change the default style in the future.

    If you check out the last two vignettes in knitr, you may see two of my own favorite styles:

  3. Tom says:

    Thanks for this great series (and right when I need it!) It’s great to see this process streamline better and better.

    A couple of points I found useful from here:

    – You can make a project specific .Rprofile in the folder of the project.
    – Remember to re-open the project for this to take effect.

  4. David Duncan says:

    Thanks for this Max, and thanks O & Y for also sharing some examples.

    Yihui, can the Linear Docco style elements can be read and implemented (effectively cut and paste) into a css file? That example addresses many of the elements that don’t please my eye in either the default css or MG’s MS word leaning one.

  5. Max Gordon says:


    I don’t think Yihui automatically receives e-mail updates from my blog. That said I would suggest that you use Firefox with the Firebug-plugin. Through that you can inspect each elements CSS-properties, tweak it to your liking and then update your CSS-file accordingly.

    Note though that the FTP-concept is partly about being able to import your document into a word-processor and these have serious limitations in their CSS-capabilities. You may need to take that into account.

    If you have a CSS that you like and works nicely with Word/LibreOffice, please share – I’ll gladly add it to the post – my email is max at gforge dot se

  6. Hans Grapenthin says:

    Hi Max

    thank you for this very useful article. Helped me to feel better with knitr.
    Just a hint for your readers: If anybody does not succeed with .RProfile, he shoul try .Rprofile.

    Regards Hans

  7. Thomas Speidel says:

    Thank you for the wonderful tutorial. It has helped the visual appeal and readability of my knitr documents a lot.

    One thing I was not able to figure out is how one can adjust the “white space” (margins?) in the CSS file. I’m talking about the L and R margins that are too wide for my taste (especially with figures). I played around with the CSS margin: statement to no avail.

    Many thanks,

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.