├── .gitignore ├── README.html ├── README.md ├── _site.R ├── _site.yml ├── advanced ├── _footer.html ├── example.Rmd ├── important_data.csv └── my_script.R ├── basic_workflow.Rmd ├── basic_workflow.html ├── first_observations.Rmd ├── first_observations.html ├── getting_sophisticated.Rmd ├── getting_sophisticated.html ├── getting_sophisticated_files └── figure-html │ ├── plot iris-1.png │ ├── plot-1.png │ └── source gdp script-1.png ├── images ├── Rmd_cheatsheet.png ├── Rmd_output_formats.png ├── fork.png ├── gh-pages.png ├── markdown_rmarkdownlesson-2.png ├── markdown_rmarkdownlesson-8.png ├── practicalDev_changingstuff.jpg ├── practicalDev_googleErrorMessage.jpg └── r4ds_r-markdown.png ├── index.Rmd ├── index.html ├── rmarkdown-website-tutorial.Rproj ├── site_libs ├── bootstrap-3.3.5 │ ├── css │ │ ├── bootstrap-theme.css │ │ ├── bootstrap-theme.css.map │ │ ├── bootstrap-theme.min.css │ │ ├── bootstrap.css │ │ ├── bootstrap.css.map │ │ ├── bootstrap.min.css │ │ ├── cerulean.min.css │ │ ├── cosmo.min.css │ │ ├── flatly.min.css │ │ ├── fonts │ │ │ ├── Lato.ttf │ │ │ ├── LatoBold.ttf │ │ │ ├── LatoItalic.ttf │ │ │ ├── NewsCycle.ttf │ │ │ ├── NewsCycleBold.ttf │ │ │ ├── OpenSans.ttf │ │ │ ├── OpenSansBold.ttf │ │ │ ├── OpenSansBoldItalic.ttf │ │ │ ├── OpenSansItalic.ttf │ │ │ ├── OpenSansLight.ttf │ │ │ ├── OpenSansLightItalic.ttf │ │ │ ├── Raleway.ttf │ │ │ ├── RalewayBold.ttf │ │ │ ├── Roboto.ttf │ │ │ ├── RobotoBold.ttf │ │ │ ├── RobotoLight.ttf │ │ │ ├── RobotoMedium.ttf │ │ │ ├── SourceSansPro.ttf │ │ │ ├── SourceSansProBold.ttf │ │ │ ├── SourceSansProItalic.ttf │ │ │ ├── SourceSansProLight.ttf │ │ │ └── Ubuntu.ttf │ │ ├── journal.min.css │ │ ├── lumen.min.css │ │ ├── paper.min.css │ │ ├── readable.min.css │ │ ├── sandstone.min.css │ │ ├── simplex.min.css │ │ ├── spacelab.min.css │ │ ├── united.min.css │ │ └── yeti.min.css │ ├── fonts │ │ ├── glyphicons-halflings-regular.eot │ │ ├── glyphicons-halflings-regular.svg │ │ ├── glyphicons-halflings-regular.ttf │ │ ├── glyphicons-halflings-regular.woff │ │ └── glyphicons-halflings-regular.woff2 │ ├── js │ │ ├── bootstrap.js │ │ ├── bootstrap.min.js │ │ └── npm.js │ └── shim │ │ ├── html5shiv.min.js │ │ └── respond.min.js ├── highlight │ ├── default.css │ ├── highlight.js │ └── textmate.css ├── highlightjs-1.1 │ ├── default.css │ ├── highlight.js │ └── textmate.css ├── highlightjs-9.12.0 │ ├── default.css │ ├── highlight.js │ └── textmate.css ├── jquery-1.11.3 │ └── jquery.min.js ├── jqueryui-1.11.4 │ ├── README │ ├── images │ │ ├── ui-icons_444444_256x240.png │ │ ├── ui-icons_555555_256x240.png │ │ ├── ui-icons_777620_256x240.png │ │ ├── ui-icons_777777_256x240.png │ │ ├── ui-icons_cc0000_256x240.png │ │ └── ui-icons_ffffff_256x240.png │ ├── index.html │ ├── jquery-ui.css │ ├── jquery-ui.js │ ├── jquery-ui.min.css │ ├── jquery-ui.min.js │ ├── jquery-ui.structure.css │ ├── jquery-ui.structure.min.css │ ├── jquery-ui.theme.css │ └── jquery-ui.theme.min.css ├── navigation-1.1 │ ├── codefolding.js │ ├── sourceembed.js │ └── tabsets.js └── tocify-1.9.1 │ ├── jquery.tocify.css │ └── jquery.tocify.js ├── your_turn.Rmd └── your_turn.html /.gitignore: -------------------------------------------------------------------------------- 1 | # History files 2 | .Rhistory 3 | .Rapp.history 4 | 5 | # Session Data files 6 | .RData 7 | 8 | # Example code in package build process 9 | *-Ex.R 10 | 11 | # Output files from R CMD build 12 | /*.tar.gz 13 | 14 | # Output files from R CMD check 15 | /*.Rcheck/ 16 | 17 | # RStudio files 18 | .Rproj.user/ 19 | 20 | # produced vignettes 21 | vignettes/*.html 22 | vignettes/*.pdf 23 | 24 | # OAuth2 token, see https://github.com/hadley/httr/releases/tag/v0.3 25 | .httr-oauth 26 | 27 | # knitr and R markdown default cache directories 28 | /*_cache/ 29 | /cache/ 30 | 31 | # Temporary files created by R markdown 32 | *.utf8.md 33 | *.knit.md 34 | .Rproj.user 35 | 36 | # also 37 | README.html 38 | -------------------------------------------------------------------------------- /README.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 |
6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 |A tutorial for creating websites using R Markdown.
211 |To build the website, run rmarkdown::render_site()
, which knits each Rmarkdown (*.Rmd) based on parameters in _site.yml
before pushing the files back to Github.
Building websites uses the same reproducible workflow you can use for your analyses and collaborations. It is very iterative. You can do it all from RStudio, with a combination of clicking or typing commands as you feel comfortable.
210 |_site.yml
(perhaps, if it is a new file)rmarkdown::render_site()
Let’s see what this looks like. We are not going to have time to learn all of the capabilities of R Markdown today, but the purpose here is to give you familiarlity with the workflow and confidence to explore further on your own.
224 |Here is what you’ll see when you’ve opened our rmarkdown-website-tutorial
project in RStudio.
The ‘Build tab’ in the top right corner will show up once RStudio knows you’re making a website, don’t worry if you don’t have it yet.
229 |If we open index.Rmd
we will see that it’s all text with a bit of formatting. This top part is called the ‘front matter’.
Now let’s look explore the first few webpages/R Markdown files to get familiar with Markdown syntax:
239 |index.Rmd
first_observations.Rmd
basic_workflow.Rmd
These first few pages have simple formatting (bold, italics), headers, bullet points, links, and images. These are the majority of things you’ll do in Markdown. See a full list of options at RStudio’s Markdown basics or go to Help > Markdown Quick Reference. Also, check out their R Markdown cheatsheet.
245 |Notice that you can insert images locally (from the /images folder), or from online e.g. Google Drawings!
246 |From rmarkdown.rstudio.com lesson 8:
247 |Let’s make a few changes to this file and knit it to inspect. Try adding some new Markdown formatted text.
256 |Also, now is a good time to make sure you have the the Build tab; you may need to install rmarkdown
if you haven’t already (below).
Click Build Website
in the Build tab (or type rmarkdown::render_site()
in the Console) and inspect your Website! Commit and push to see it live online.
In Markdown, spaces can be tricky.
265 | To start a new line here, I needed 2 spaces after tricky.
above. As you can see, a simple carriage return doesn’t cut it.
To force carriage returns, use the <br>
html tag…
…like this.
269 |Also, this bulleted list won’t render properly: - because there is no carriage return between the line above - and where the bullet points start.
270 |To have the bullet points render nicely:
271 |If you want to build a website from scratch (i.e. not fork this one), follow RStudio’s instructions here: R Markdown Websites.
280 |Troubleshooting:
281 |We recently had trouble having our nicely built website display online: the website’s url only showed the README (nicely formatted though!). We solved it by adding:
282 |output_dir: "."
283 | to the _site.yml
. This knits all the .html files in place in the home directory instead of in a _site
folder, and this solved our problem!
rmarkdown
packageYou can do this by:
288 |paste this code in the Console and hit enter
290 |install.packages('rmarkdown')
291 | library(rmarkdown)
from the bottom right pane, click on the Packages tab, click on Install, “rmarkdown”
With this tutorial, we have a working example website that we will explore together. We’ll learn a few rules and look for patterns to get an understanding of what things do. And you can continue to use this website as a reference after the tutorial, along with RStudio’s instructions for R Markdown websites.
210 |We’ll start our exploration online looking at the website architecture, then we’ll clone the repo to our local computers. Locally, we will explore further by going back and forth between the R Markdown editor and built webpages, and make modifications. Pushing to Github will make our modifications live!
211 |This website has 5 pages:
220 |github.io
means that there is a Github repo behind this website, and we also know the username and repo name:
http://jules32.github.io/rmarkdown-website-tutorial <=> https://github.com/jules32/rmarkdown-website-tutorial
229 |(Note: you can have github websites point to different urls if you don’t want the github.io
.)
Let’s go to https://github.com/jules32/rmarkdown-website-tutorial.
235 |First, note the gh-pages
branch - this is critical for building free webpages. You can usually name branches whatever you want, but the gh-pages
name means it can be built as a website. I set it as my default branch.
Now let’s look at the filenames. We can recognize the names of the webpages we’ve seen, and there is also a _site.yml
file, which is the website’s configuration file. The simplest website possible would have 2 files only: _site.yml
and index.Rmd
Let’s start digging deeper and playing with this.
252 |Fork the jules32/rmarkdown-website-tutorial repo into your own account.
Edit the URL for the website by replacing jules32
with your GitHub username
Clone to your local computer using RStudio (preferred) the Desktop App, or the command line.
There are a lot of ways to get sophisticated here, and we’re only covering a few possibilites here. See RStudio’s R Markdown lessons for other R Markdown capabilities. Plus, R Markdown can render styling from Cascading Style Sheets (CSS) and Hyper Text Markup Language (HTML), which is what non-R Markdown websites use.
308 |So, Googling what you want to do and trying it in your R Markdown files is a good way to learn. Disclaimer: that’s how I’ve learned the following, so there are most definitely better and more elegant ways to do this. But here are some ideas of what you may want to do with your website.
309 |These are options that you can do from the Front Matter.
313 |Note that on this page:
317 |This is all done in the front matter:
321 |output:
322 | html_document:
323 | toc: true
324 | toc_float: true
325 | We can change the website’s theme in _site.yml
. Explore options here: http://rmarkdown.rstudio.com/html_document_format.html#appearance_and_style:
333 |335 |Valid themes include “default”, “cerulean”, “journal”, “flatly”, “readable”, “spacelab”, “united”, “cosmo”, “lumen”, “paper”, “sandstone”, “simplex”, and “yeti”.
334 |
By default, images are displayed left-aligned.
343 |Resize an image using HTML tags (side note: check out RStudio’s R Markdown Cheatsheet):
344 |Here’s a big image:
345 | <img src="images/Rmd_cheatsheet.png" width="350px">
346 |
And a small image:
348 | <img src="images/Rmd_cheatsheet.png" width="150px">
349 |
Align an image using HTML tags:
351 |Small image centered:
352 | <center><img src="images/Rmd_cheatsheet.png" width="150px"></center>
Small image right-aligned:
357 | <div align="right"><img src="images/Rmd_cheatsheet.png" width="150px"></div>
Column 1
376 |<div class="col2">
and </div>
Column 2
381 |<br>
there<center>**Here the text is centered. Here are good resources:**</center>
390 | Here the text is centered. Here are good resources:
<font size="3" color="red">Text here!</font>
This is red text size 3!
399 | This is blue text size 2!
400 | This is green text in verdana!
R
codeYou can execute R code each time you build your website. Even if you don’t yet know R, this is a little taste of the types of things you can do. There are two ways you’ll see R code; in-line and in a code chunk. This is from the R Markdown chapter in R for Data Science.
407 |Here is an example inline. The date when I last built the website is 2018-02-22. My favorite number is 13.1415927. There are 19 files and folders in our repo. This is not just text; his is executable R code that is 100% awesome!
415 |And here is an example of a code chunk. Let’s plot the first bit of an iris
variable (which is a dataset that comes with base R).
x <- iris$Sepal.Length[1:15]
421 | plot(x)
422 | R
scriptYou can source an R script. This is a super powerful way to avoid copy-pasting your analyses. For example:
429 |## source an external script
430 | source("advanced/my_script.R")
431 |
432 | ## use the calc_gdp() function `my_script.R`
433 | my_data <- calc_gdp(my_country <- 'Slovenia')
434 |
435 | ggplot(data = my_data, aes(x = year, y = pop)) +
436 | geom_point() +
437 | labs(title = my_data$country)
438 | _site.R
This is something that R Markdown websites will look for; when it exists it will give you ‘global variables’ that will be available for all pages across your site.
444 |source("_site.R")
445 | You can insert separate R Markdown files too; text and code will be incorporated seamlessly into this page. This R Markdown file is considered the ‘parent’ file, and the one that is incorporated is the ‘child’ file. In the code chunk below, we’ll say {r, child='advanced/important_example.Rmd'}
.
This text comes from a separate R Markdown file – how would you ever know that this is a separate file!
451 |Here is an example of inline R code: if you round 3.1415927 you get 3.
452 |This is the end of this separate and important R Markdown child file.
453 |You’ll get errors as you work; this is how you learn. These are a few things you may encounter:
460 |If when running rmarkdown::render_site()
you get this error:
Error in object[seq_len(ile)] :
463 | object of type 'symbol' is not subsettable
464 | Go to Session > Restart R and try again.
When knitting, if you get this error:
466 |Error in parse_block(g[-1], g[1], params.src) : duplicate label 'setup'
467 | Calls: <Anonymous> ... process_file -> split_file -> lapply -> FUN -> parse_block
468 | Execution halted
469 | Here you have 2 R
code chunks named the same thing (in this case ‘setup’), you must change one of them because there cannot be two code chunks with the same name.
When you get an error message you don’t understand: Copy-paste it into Google.
It’s possible to create well-designed websites for free using RStudio’s R Markdown and hosting them on Github. This is very new and incredibly cool. It is a really powerful way to communicate science using the same reproducible workflow you use for your analyses and collaborations.
213 |Creating websites with R Markdown can be done without knowing R or HTML, CSS, etc, and that’s where we’ll start. However, R Markdown integrates with these tools so the more you know the more complex and beautiful your website can be. This tutorial borrows heavily from a lot of great tutorials and resources you should check out too – there are links throughout.
214 |The best way to learn is to follow along with your own laptop, but all are welcome. We’ll spend half the time with the tutorial and half the time for you to work on your own website and get help. If you bring your laptop please do this beforehand:
215 |Examples:
227 |We have been using R Markdown for the Ocean Health Index: ohi-science.org/ohi-global.
228 | And R Markdown is much more than just websites – here’s a one-minute video about R Markdown to get you excited.
Try changing a few things and reknitting a single page or rebuilding the whole site. Do your own thing, or here are a few things to try:
312 |You’ll need to add it to the nav bar in _site.yml
too.
How would you approach this? See what we did for 3 columns, or Google it.
329 |Submit a pull request to this tutorial and we can update it with what you learn!
334 |