Generating the files

To build the website from the beggining using normal Rmarkdown and HTML documents:

1. Open RStudio and click on the Project button at the top-right corner, click at New Project and tell RStudio that you want to start the R project in a New directory. Then, select Simple R Markdown Website. This will create a new project with four files (an Rproj file, the _site.yml, the index.Rmd and the about.Rmd) in the project directory.

• If you are brand new to RStudio, you will possibly have to install the rmarkdown package by running install.packages('rmarkdown') in the console.

• If you don’t have the rmarkdown package and don’t want to install it, you can start a new project, indicating New Project as the project type. But you will have to create all the files by yourself and you will have to render to HTML all the Rmd files one by one or configure the building options of the project to website.

2. Create the Rmd files in the icon at the top-left corner of the screen. Write what you want in them. You have an Rmarkdown cheat sheet here.

3. Modify the _site.yaml to include all the files that you want with the desired organization and features. Typical options for a _site.yml are:

• name: name of the website
• output_dir: directory where the HTML files are generated from the Rmd files.
• navbar: configuration of the navigation bar.
  • title: title shown in the navbar.
  • left: tabs that will be shown in the left side of the navbar. Each - inside this section denotes a tab.
    • - text and href: text that will be shown in the navbar and HTML file of reference (relative to the output_dir).
    • - icon: you can include font awesome icons in the navbar (i.e - icon: fa-github). They can be linked to an href and can be placed in the same tab as a text.
  • right: same as left but in the right site.
• output: this is normally set to html_document but different packages have different outputs (i.e. distill has distill::distill_article), and each output can have several options.

4. Go to the build tab in the top-right panel and click to Build webside (if you did not set Simple R Markdown Website as project type and set it to New Project, you will have to set the Build tools inside Project options to Website.)

Remember that you can rename almost every file, but you must have one index.Rmd which will be knit to index.html. This index.html will be the homepage of your website.

I won’t show it here, but if you want to see the code I used to build my personal website the first time, you can take a look at this repository.

Publishing the website

Once the HTML files have been created, the website has to be published. A quick way to do it is to push your files into a GitHub repository which must be named as username.github.io, where username is your GitHub user name. Create the repository through the GitHub website, set it public and with the correct name and upload the files directly to it, make it public and upload the files through:

• The GitHub website (the easiest way to do it, but the slowest to update).
• The GitHub Desktop application (easy, fast and with a graphical interface).
• The terminal by running the appropriated git commands (requires command line knowledge, but it is really fast and comfortable to use). You can do a DataCamp introductiory course to git here.

Figure 1: Three steps to create a repository on GitHub to publish your website in username.github.io: 1) Go to your GitHub account and create a new repository with the ‘+’ tab in the top-right corner; 2) name your repository as ‘username.github.io’, where username is your GitHub username, and click at ‘create repository’ at the end of the page; 3) click to ‘uploading existing files’ and, in the new page, drag or upload your files.

After uploading all the files to the repository, go to the Settings tab, in the GitHub Pages section to set the GitHub branch of the repository where to look for the HTML files. Note that if you are using GitHub (in GitLab is different), your HTML files must be in the root directory or in a folder named docs, together wit all the needed files (i.e. images, etc).

Now, you are able to see your website at https://username.github.io/

Creating the blog

After trying both, I decided to use distill because it have an structure similar to what I had been using and that is easier to modify and format as I like, but there are a lot of peaople using both. Let’s see a little example:

• Open RStudio and set an empty directory as working directory with setwd().

• In the R console, run the following code:

  # Install the distill package
  install.packages('distill')
  
  # Create a blog
  distill::create_blog(dir = "/path/to/blog/directory", title = "My blog")

• Optionally, if you have distill installed, you can create a New R project indicating Distill Blog as the project type. This will enable a Build tab at the top-right panel in RStudio that will allow to render all the Rmd files to HTML.

• Moreover, instead of create_blog() you can use create_website() or create a new project selecting Distill Website as the project type. This, instead of a blog will create a website, which is basically the same, but you don’t have the post listing in the homepage.

After running the create_blog() function (or creating the new R project), you will see that the directory where you run the function (the path/to/blog/dir), has the following files and folders:

• index.Rmd: this is the Rmd that will generate the HTML of the homepage where the posts will be listed.

• about.Rmd: where you can write some details about the blog

• _posts: folder where you will write the desired posts organized in different folders. It already contains a sample post in the folder welcome.

• _site: folder where, by default, the HTML files will be rendered from the Rmd files. This can -and should- be cahnged in the _site.yml file.

• _site.yml: YAML file that will determine the organization of the website. In this file you can set an output_dir: which is the name of the directory where HTML files will be generated. For distill, the default output directory is _site, but remember that if you are using GitHub Pages to publish the website it should be the root directory (.) or docs. The _site.yaml from our example is the following:

  name: "distillTest"
  title: "My Blog"
  description: |
    My Blog
  output_dir: "_site"
  navbar:
    right:
      - text: "Home"
        href: index.html
      - text: "About"
        href: about.html
  output: distill::distill_article

  For more examples of _site.yaml you can look for examples in the internet. Here you can see an example from my personal website, made with distill and published through GitHub pages.

Creating posts

To create a post for the blog or another page can be done in the same way we described before, but it can be done in a much easier way since distill have templates for this purpose. You have two options:

• Run distill::create_article(file = "file_name") in the R console with file_name being the name of the file where the new article will be saved.

• Create a new R markdown file with the in the top-left corner, going to From Template option in the left and setting the template to Distill Article.

Now you can modify the data of the author, date… and write everything you want into your new post. You can write a new option in the header to set the post as a draft -the post won’t be listed in the website- by writing draft: true, and many other options.

Finally, to generate the HTML file from this Rmd, you can click at the Knit button or the Build button. Clicking the build website button will render all the Rmd files present in the project, while Knit will only affect to the current Rmd.

Extra features

Distill has a lot of exciting things that allow to add extra features to the website in an simple way

• It is very easy to add a footer: just add a _footer.html file to the main directory (tipically where the Rmd files are) and write what you want to show in the website footer inside this file.

• You can easily add a favicon to your website. A favicon is an image or an icon that is shown in the browser tab when you access to the website. To add the favicon, just go to the _site.yml file and write favicon: your/favicon.png in a new line, where your/favicon.png is the relative path from the _site.yml to the image you want to add in the browser tab.

  The other way to do it, is to create an HTML file (i.e. favicon.html) where you link the image you want as favicon and then, in the end of the _site.yml, where you specify the output, you have to write the following:

  output:
    html_document:
      include:
        in_header: path/to/favicon.html

  Note that I have specified html_document as the output, since this is what it’s done when you work only with Rmarkdown (without distill or other packages). In the case of distill you should have distill::distill_article instead of html_document.

  At the moment, although it is shown locally and on my personal website published through GitHub pages, this blog don’t show the favicon. I suspect that there could be a problem with this feature in Netlify, which is the platform I used to publish the blog.

• It is easy to add footnotes and things on the side.

• You can easily to allow comments to the post and sharing options to social networks (i.e. Linkedin and Twitter). To do so, you have to modify your _site.yml and add the following section:

  collections:
  posts:
    disqus: BioBit
    share: [twitter, linkedin]

  Where disqus must have the same value as the name section of the _site.yml. ¹

• And much more things you can discover at distill’s website.

Disadvantages

However, not all are advantages, for example:

• Working with tabs inside each page (not in the nabvar) is much more difficult that when using normal HTML outputs, which you only have to add a {.tabset} at the end of your section or subsection header.