1. Bookdown Package Github
2. Bookdown Github Login
3. Bookdown Github Commands
4. Bookdown Github App
5. Bookdown Github
6. Bookdown Github Pages
7. Bookdown Github Actions

A series of tutorials on R, RStudio, and R programming. Wir verwenden bookdown zur Dokumentation unserer SQL-Abfragen, die eine Namenskonvention mit Bindestrichen haben, z. GG1G1SDMP01Q001, zu Testzwecken verwenden wir testunderscore.

Published with bookdown. Data Visualization with R. Data Visualization with R. R is an amazing platform for data analysis, capable of creating almost any. GitHub style markdown is recommended if you wish to use the same source (or with minor changes) in multiple places. R Markdown is a document format based on the R language and Markdown to intermingle computing with narratives in the same document.

Now that you are a confident R programmer and a budding data scientist, how are going to show such accomplishments to the rest of world? People love talking, but you, you know that you must provide data. Why not creating a website to showcase your work? You know from the previous chapters that R/Rstudio provides a wide set of tools, you may have heard that it is possible to build a website, but it seems so complicated. Is it? Well, let’s find out.

11.1 Static website overview

A convenient solution to create a website is to use the R package blogdown. By default, blogdown is based on the static site generator Hugo. A static web page is a document (often HTML) stored as a file for which its content (text, image, videos, …) does not dynamically change according to the context of the user. For Hugo, when you build a static web page, the HTML file is rendered locally on your computer as opposite to a hosting server.⁹ As a result, usually static sites offer better performances. Among different static site generator, Hugo has the reputation the be the fastest.¹⁰ Note that if your interest narrows to making a website for an R package, then you may want to turn to pkgdown which will require less investment of your time, but certainly also less reward.

Bookdown Package Github

11.2 Getting started

You need to install the blogdown package the usual way:

Note that the package has addins functionalities for Rstudio and a project type that we are going to use.

Create a new project selecting Website using blogdown.

11.3 Choosing a theme

The choice of the theme is essential: different themes have different ways to create content, structures, functionalities and maybe most importantly when you get started, different level of details for user documentation. By default, blogdown proposes the hugo-lithium theme, Yihui Xie’s minimal example.¹¹ The complete list of themes is at https://themes.gohugo.io/. The showcase section is also a good indication of what may be achieved. You can find themes with rich user documentation under the tag documentation, check here. Some Hugo templates I considered:

• Learn: This a great and simple theme. It is perfect if the goal is to create documentation. This is for example the one I used for one of my classes, see here. It has a dedicated website for the documentation. This is why I pick it for this chapter.

• Academic: this a very complete theme for academic résumé. It is commonly used in academia (there is a tool to import your BibTeX bibliography!) so there is quite a community behind it, meaning also more support. It has many options and features including widgets to build pages. It is however probably an overkill when getting started.

• Tranquilpeak: a beautiful and neat theme for blogging. It comes with a complete documentation.

Once you’ve picked a theme up, you need to specify under Hugo theme: the USER_NAME/REPOSITORY_NAME from the GitHub repository of the theme. For example, the Learn theme is at https://github.com/matcornic/hugo-theme-learn so we enter:

11.4 Rendering the website

One attractive feature of Hugo is that you can render your site live locally (on your computer) so that you can observe directly the modifications taking place. With blogdown, type in your console:

Or alternatively, use directly the RstudioAddins.

It creates the website in the viewer panel.

I would recommend to open the website on your webrowser, for example by clicking on the Show in new window button . It will be very similar to the online version and you can directly see the modifications.

In order to stop the live rendering of the website, you can either restart the R session, or maybe simply, by typing in your console:

11.5 Creating content

The next step is to create some content. We will create a post and illustrate some features of Hugo.

First, you need to decide whether you want to create a plain Markdown document (.md) or a RMarkdown document (.Rmd) as there are noticeable differences.¹² A plain Markdown document is by default rendered a posteriori in HTML via Goldmark¹³ whereas RMarkdown is compiled a priori using the rmarkdown package. A consequence of using RMarkdown is that your website might be slower to render and less clean with many HTML files. A good rule of thumb is: always write a post with plain Markdown unless you need to runR code (if only display R code, use plain Markdown).

The easiest way to create a document is to click on Addins > Blogdown > New post which generates a windows through a shiny app. Here is an example:

• Marianne skerrett. Archetype is a pre-configured skeleton page. The Learn theme has two archetypes: chapter or default (see here).

• Format: there is a third format, .Rmarkdown. This format will be compiled to a Markdown document (not HTML) so you keep the files clean, however it does not use Pandoc as the rmarkdown package does (see Blogdown output format for more details). Dreamweaver cc.

The post I’ve generated has the following YAML metadata:

Note that the output format has not been specified as it is HTML by default.

We can immediately have a look at the changes on the website.

Note that the address http://127.0.0.1:4321 is local.

Alternatives to create content are as follows:

1. Click on Addins > Blogdown > New post as we have just seen.

2. Equivalently, you can type in your console

3. As an alternative, you can directly create the document (e.g. File > New file > R Markdown). In addition, you will need to know where to store the file (explained in the next section) and adapt the metadata of the file (you can for example have a look at the already existing posts).

4. Eventually, you can use command lines in the terminal as for example shown here.

Second, you can now write some content in your file. Since I want to illustrate some of Hugo’s features, I create a new Markdown file named test.md in the post folder (remember that R Mardown are compiled via rmarkdown, so it will not understand Hugo shortcodes). The header of the file is simply:

Note that you can also add other variables such as: date, weight, description. weight for example is important for organizing the posts. You can find here a complete list of variables.

Most of the content you create is generally in Markdown format, and we let you refer to Chapter 2. Note that since your Markdown file is rendered using Goldmark, there are some differences compared to Pandoc (as used with the library rmarkdown), one noticeable is that you cannot run R code as already discussed. One of the gain of using the Markdown format is that you can use Hugo shortcodes. As stated on Hugo’s website:

Bookdown Github Login

Hugo loves Markdown because of its simple content format, but there are times when Markdown falls short. Often, content authors are forced to add raw HTML (e.g., video iframe’s) to Markdown content. We think this contradicts the beautiful simplicity of Markdown’s syntax.

The idea of shortcodes is to circumvent some of Markdown’s limitations. For example, if you want to embed a Youtube video, say

you can simply use the following syntax

Here is how it looks on the website:

You have other Hugo’s built-in shortcodes useful for example figures, Instagram, Tweeter, Vimeo,… Check this link. There is also the possibility to create custom shortcodes. For example, the Learn theme proposes several. For instance, we can add an info notice using

11.6 Website structure and content organization

If you’ve followed the above steps, you should have something similar to this tree for your website structure:

• config.toml is where you have configuration directives. Some themes such as Academic have config/ directory. These directives could also be stored in JSON or YAML syntax.

• index.Rmd is specific to blogdown.

• The content/ folder is where you will add all the content for your website (although not absolute, see Toha theme for such an exception). Hugo follows the same logic as this folder to construct the website. The organization between different pages at the same level can be specified using the weight variable. Usually a section begins with a _index.md file (see this link). In the tree above, there is in addition the distinction between languages. For example, the _index.md file in the basics/ (not shown in the tree) folder has a weight of 5, whereas it is 10 font cont/ so basics/ appears first.

• The layouts/ folder contains templates in HTML. If empty, it uses the theme defaults. You need to copy such a file from the theme before modifying it, it is a bad habit to modify files from the theme/ directory.

• static/ stores all the static content such as CSS, JavaScript, … This content is served as-is, meaning without modification to the website. For example, the image in static > images > showcase > tat.png can be directly accessed at https://learn.netlify.app/images/showcase/tat.png. Note that there is a static > post directory that contains your R Markdown extra files.

Bookdown Github Commands

See this link for other directories and further information.

11.7 Customizing the theme

Customization depends on the theme you’ve chosen. For example, with the Learn theme, you can easily modify the color variants (see here), but is is limited to 3 colors. To create your own variant, you will have to create a CSS file in static > css with your own setup following this example. You can also modify the logo and the favicon.

Other common customizations include:

• Modify the menu, this is generally easily achieved, check this.

• With blogdown, it is recommended to ignore some files by adding

to your config.toml file. See this link for further explanations.

Bookdown Github App

• Google analyitcs: simply add googleAnalytics: UA-XXX-YY in your config.toml file using your Google Analytics tracking identifier. Apparently the tracking works also when working locally using blogdown::server_site(), this blog offers a solution.

• Disqus: add the popular commenting system by adding disqusShortname: yourdiscussshortname to your config.toml file.

• Add a Robots.txt to your website (see this). Review last chapter on webscraping if you don’t remember what it is.

• LaTeX equations. If you use .Rmd, then you can render math equations (see Chapter 2). For .md file, a solution is to use MathJax but you will need some tweaks following for example this blog.

Bookdown Github

See https://gohugo.io/templates/internal/ for other templates.

11.8 Deployment

Once your website on a GitHub repository (follow our Chapter 3), it is easy, quick and free of charge to publish your website online using for example the service of Netlify. You need to register to Netlify, for example using your GitHub credentials, and then authorize Netlify to access to the relevant repository. The website then will be deployed automatically. You may want to modify the name (usually fantasist by default) and the version of Hugo to compile your website. See Blogdown: deployment with netlify for more details.

11.9 See also

See the following blogs of Dr. Mowinckel’s and Esteban Moro for recent and alternative explanations.

3.3 Travis + GitHub

If you decide not to follow our recommendation to use Netlify to deploy your website, we should warn you that the approach in this section will require substantial knowledge about GIT, GitHub, Travis CI (https://travis-ci.org), and the Linux command line, which we will leave for you to learn on your own. The major advantage of publishing via Travis CI is that you can compile all your Rmd posts on Travis CI (on the cloud) instead of your local computer.

In case you are not familiar with Travis, it is a service to continuously check your software in a virtual machine whenever you push changes to GitHub. It is primarily for testing software, but since you can run a lot of commands in its virtual machine, you can certainly use the virtual machine to do other things, e.g., install R and the blogdown package to build websites. Before I show you how, I’d like to mention two issues that you should be aware of:

• Personally, I prefer taking a look at the output in GIT to see the changes when I have any output that is dynamically computed from R, so that I know for sure what I’m going to publish exactly. With Travis, it is somewhat unpredictable because it is fully automatic and you do not have a chance to see the new content or results to be published. There are many factors that could affect building the site: the R version, availability of certain R packages, system dependencies, and network connection, etc.

• The time required to compile all Rmd files may be very long and cause timeouts on Travis, depending on how time-consuming your R code is. There is a caching mechanism in blogdown to speed up the building of your site (see Section D.9), and if you use Travis to build your website, you will not benefit from this caching mechanism unless you take advantage of Travis’s caching. You have to cache the directories content/, static/, and blogdown/, but Travis’s cache is a little fragile in my experience. Sometimes the cache may be purged for unknown reasons. What is more, you cannot directly cache content/ and static/, because Travis clones your repository before restoring the cache, which means old files from the cached content/ and static/ may overwrite new files you pushed to GitHub.

Bookdown Github Pages

The second problem can be solved, but I do not want to explain how in this book since the solution is too involved. If you really want to use Travis to build your website and run into this problem, you may file an issue to the GitHub repository https://github.com/yihui/travis-blogdown. In fact, this repository is a minimal example I created to show how to build a website on Travis and publish to GitHub Pages.

The Travis documentation shows how to deploy a site to GitHub Pages: https://docs.travis-ci.com/user/deployment/pages/, but does not show how to build a site. Here is the Travis configuration file, .travis.yml, for the travis-blogdown repository:

The key is that we install Hugo via blogdown::install_hugo() and build the site via blogdown::build_site(). To trick Travis into building this repository like an R package, you must have a DESCRIPTION file in the repository, otherwise your website will not be built.

There are a few more things to explain and emphasize in .travis.yml:

• The branches option specifies that only changes in the master branch will trigger building on Travis.

• The cache option specifies all R packages to be cached, so the next time it will be faster to build the site (R packages do not need to be reinstalled from source). The bin/ directory in the home directory is also cached because Hugo is installed there, and the next time Hugo does not need to be reinstalled.

• For the deploy option, there is an environment variable named GITHUB_TOKEN, and I have specified its value to be a GitHub personal access token via the Travis settings of this repository, so that Travis will be able to write to my repository after the website is built. The option on specifies that the deployment will only occur when the master branch is built. The local_dir option is the publish directory, which should default to public in Hugo. By default, the website is pushed to the gh-pages branch of this repository. The fqdn option specifies the custom domain of the website. I have set a CNAME record (see Appendix C) to point travis-blogdown.yihui.org to yihui.github.io, so that GitHub is able to serve this website through this domain (in fact, Travis will write a CNAME file containing the domain to the gh-pages branch).

Bookdown Github Actions

If you use the username.github.io repository on GitHub, the website must be pushed to its master branch instead of gh-pages (this is the only exception). I recommend that you separate the source repository and the output repository. For example, you may have a website-source repository with the same settings as the above .travis.yml except for two new options under deploy:

This means the website will be pushed to the master branch of the repository username/username.github.io (remember to replace username with your actual username).

You can also deploy your website to Amazon S3, and the setup on the R side is very similar to what we have introduced for GitHub Pages. The only difference is in the last step, where you change the target from GitHub Pages to Amazon S3. For more information, please see the documentation on Travis: https://docs.travis-ci.com/user/deployment/s3/.