This page outlines the process of making a basic website using R Markdown, and hosting that website on GitHub – the content assumes familiarity with both .Rmd and GitHub.
This is the first module in the Interactivity topic.
Publish a personal website using GitHub pages.
The example below is built around the construction of a “personal” website, but the steps are the same for any other website you want to create.
This is going to hold everything you want on your website, and the name does matter:
<YOUR_GH_NAME>.github.ioif you want this to be your personal website
All websites have an
index.html file – it’s the most common name for the default page and gets served up whenever someone shows up at your site. We’ll start by using this
index.Rmd file. This has usual RMD stuff: a title, some headings, some content. Anything you could put in any other RMD file, you can put in here, too. Then, as usual, you can knit to create
index.html; you should get something like the following.
NOTE: Web page names are case sensitive, and
index.html has to start with a lower-case “i”.
Your website can include text, of course; you can also include code and figures generated from analyses. Like I keep saying, you’re writing in RMD.
One important feature of your site will be hyperlinks. The general format for links is
[text for link](address.of.link). So, to link to my favorite tool for data science, I’d use
Your website usually has more than one page. These pages can be created using the same process as
index.html: create an Rmd file and knit to html. Once you have another page (e.g.
about.html) you need to link to it from your home page (e.g. using use
[about](about.html)), or no one will be able to find it.
Sometimes you want to add images – pictures you’ve taken or found on the internets, rather than things that are generated from analyses. This is a bit more involved than other things you might want to do. RMD’s default image settings (using
!(image.jpg)) aren’t great. I often use a line of HTML:
<img src="images/image.jpg" style="width:75%">
This will load and display
images/image.jpg (I usually keep my images inside an
images folder to reduce clutter). The
style components control things like adding a border or adjusting the image height or width, along with lots of other things – googling around can help if you want to change the style settings. If you want your style rules to apply to all images it can be easier to write a short CSS file, but that’s beyond what we’re going to do now.
Right now, all our pages have styling, output, and structure coming from page-specific YAML. It’s better to have one set of rules that apply site-wide instead. To do this, we’ll create a single file with all the YAML stuff we need, and at the same time remove extraneous YAML header content from individual Rmd files.
_site.yml file by going to File > New File > Text file. Copy the content below, and save the file as
_site.yml in your project’s home folder.
name: "Yay internet!" output_dir: "." navbar: title: "Home" right: - text: "About" href: about.html - icon: fa-envelope fa-lg href: mailto:<firstname.lastname@example.org> - icon: fa-github fa-lg href: http://github.com/<YOUR_GH_NAME>/ output: html_document: theme: cerulean
This contains some usual kinds of formatting stuff, like
output options, but also the
navbar. After saving this (and removing YAML from each page), re-knit
about.Rmd – there’s a navigation bar across the top that has nothing to do with
There are several ways you can arrange the nav bar (right vs. left; single pages vs. drop-down menus) but the idea is to give a way to navigate through your site, not just your page. The two icons are there to encourage good practices – an easy way for someone to email you, and a link to the source for the site on GitHub (icons come from font awesome). I’ve also included an “About” page, which is pretty common for pages describing projects.
We’ve been creating a website from scratch, but it’s sometimes helpful to have a quick-start template with a couple of pages and a
_site.yml file. We’ve put together such a website template for that reason.
One nice feature is that RStudio will recognize your project as a website, and give you a quick way to build the complete website using the “build website” button. This is really just a shortcut to
rmarkdown::render_site(), but it’s still nice.
This rebuilds the full website, whereas the
knit button only rebuilds a page. Rebuilding the site can be useful if you’ve made big changes, like changing the
Once you’ve built your site, your directory should include
about.html (in addition to the respective RMD files),
_site.yml, the .Rproj, and a folder with some stuff you don’t need to worry about. That’s great – you have a website! Except it exists only on your computer, so … not really a web site…
This is where GitHub helps. GitHub will recognize your repository as a website and host it as such. If your repo is named
<YOUR_GH_NAME>.github.io, that’s your personal site address. If your repo has another name, your site address will be
<YOUR_GH_NAME>.github.io/<YOUR_PROJECT_NAME>. Often this “just works”, but sometimes you have to update the repo settings for GitHub to know this is a website, especially for websites that are not
Moving forward, make edits to your website by editing your .Rmd files or
_site.yml and then rebuilding your site in RStudio (which will update the .html files). Then push these changes from your local directory to GitHub so they are reflected online.
The important stuff on your website is the content – what you say, how clearly you say it, and how easy it is for a reader to find the information they care about. Keeping things up-to-date is critical, and can require frequent tweaking (of e.g. your resume or list of projects).
Default website themes are pretty good. You can modify these if you want; speaking from experience, you can also fall down a rabbit hole and spend a few days learning CSS to make stylistic changes that seem critical but that, in fact, no one will ever notice. That’s probably not a good use of your time, and you will eventually get tired of any styling you do anyway. Instead, add a default theme to your YAML and change it from time to time. (RStudio is a bit behind in their bootstrap themes; if you find another one you want to add, you might find this thread useful.)
The best way to extend your website is to copy from other websites you like. You can borrow structurally (e.g. how content is organized) or specific elements (e.g. how that person added a twitter button). People generally understand that this happens (and make their code public to help!), but if you borrow a lot it’s friendly to shoot the person an email to say their stuff was useful.
As noted, the preceding example is about a personal website but illustrates useful ideas. If you’re making a website about a data science project, I recommend including:
There’s a lot of material online to help with making websites. You should use it.