blogdown

Creating Websites with R Markdown

Yihui Xie, Alison Presmanes Hill, Amber Thomas

• Publisher: Chapman and Hall/CRC
• Year: 2017
• Print ISBN: 9781138480452
• eBook ISBN: 9781351108171
• Edition: 1
• Topic: Economics
• Subtopic: Web Design
• Index: Economics

blogdown: Creating Websites with R Markdown provides a practical guide for creating websites using the blogdown package in R. In this book, we show you how to use dynamic R Markdown documents to build static websites featuring R code (or other programming languages) with automatically rendered output such as graphics, tables, analysis results, and HTML widgets. The blogdown package is also suitable for technical writing with elements such as citations, footnotes, and LaTeX math. This makes blogdown an ideal platform for any website designed to communicate information about data science, data analysis, data visualization, or R programming.

Note that blogdown is not just for blogging or sites about R; it can also be used to create general-purpose websites. By default, blogdown uses Hugo, a popular open-source static website generator, which provides a fast and flexible way to build your site content to be shared online. Other website generators like Jekyll and Hexo are also supported.

In this book, you will learn how to:

• Build a website using the blogdown package;
• Create blog posts and other website content as dynamic documents that can be easily edited and updated;
• Customize Hugo templates to suit your site's needs;
• Publish your website online;
• Migrate your existing websites to blogdown and Hugo.

Table of Contents

List of Figures

List of Tables

Preface

About the Authors

1 Get Started

1.1 Installation

1.1.1 Update

1.2 A quick example

1.3 RStudio IDE

1.4 Global options

1.5 R Markdown vs. Markdown

1.6 Other themes

1.7 A recommended workflow

2 Hugo

2.1 Static sites and Hugo

2.2 Configuration

2.2.1 TOML Syntax

2.2.2 Options

2.3 Content

2.3.1 YAML metadata

2.3.2 Body

2.3.3 Shortcode

2.4 Themes

2.4.1 The default theme

2.5 Templates

2.5.1 A minimal example

2.5.2 Implementing more features

2.6 Custom layouts

2.7 Static files

3 Deployment

3.1 Netlify

3.2 Updog

3.3 GitHub Pages

3.4 Travis + GitHub

3.5 GitLab Pages

4 Migration

4.1 From Jekyll

4.2 From WordPress

4.3 From other systems

5 Other Generators

5.1 Jekyll

5.2 Hexo

5.3 Default site generator in rmarkdown

5.4 pkgdown

Appendix

A R Markdown

B Website Basics

B.1 HTML

B.2 CSS

B.3 JavaScript

B.4 Useful resources

B.4.1 File optimization

B.4.2 Helping people find your site

C Domain Name

C.1 Registration

C.2 Nameservers

C.3 DNS records

D Advanced Topics

D.1 More global options

D.2 LiveReload

D.3 Building a website for local preview

D.4 Functions in the blogdown package

D.4.1 Exported functions

D.4.2 Non-exported functions

D.5 Paths of figures and other dependencies

D.6 HTML widgets

D.7 Version control

D.8 The default HTML template

D.9 Different building methods

E Personal Experience

Bibliography

Index

List of Figures

1.1 The homepage of the default new site.

1.2 Create a new post using the RStudio addin.

1.3 Update the metadata of an existing post using the RStudio addin.

1.4 Create a new website project in RStudio.

1.5 Create a website project based on blogdown.

1.6 RStudio project options.

2.1 Possible files and folders created when you create a new site using blogdown.

2.2 A tweet by Jeff Leek.

2.3 Edit a text file online on GitHub.

3.1 Example settings of a website deployed on Netlify.

B.1 Developer Tools in Google Chrome.

C.1 Some DNS records of the domain yihui.name on Cloudflare.

List of Tables

1.1 Global options that affect the behavior of blogdown.

D.1 A few more advanced global options.

百千万劫弹指过，春夏秋⼼凭谁托。
日月星灭观夜落，天地⼈间对⽂酌。

Life is short. Write for eternity.

Preface

In the summer of 2012,1 did my internship at AT&T Labs Research, ¹ where I attended a talk given by Carlos Scheidegger (https://cscheid.net), and Carlos said something along the lines of “if you don’t have a website nowadays, you don’t exist.” Later I paraphrased it as:

“I web, therefore I am a spiderman.”

Carlos’s words resonated very well with me, although they were a little exaggerated. A well-designed and maintained website can be extremely helpful for other people to know you, and you do not need to wait for suitable chances at conferences or other occasions to introduce yourself in person to other people. On the other hand, a website is also highly useful for yourself to keep track of what you have done and thought. Sometimes you may go back to a certain old post of yours to relearn the tricks or methods you once mastered in the past but have forgotten.

We introduce an R package, blogdown, in this short book, to teach you how to create websites using R Markdown and Hugo. Ifyou have experience with creating websites, you may naturally ask what the benefits of using R Markdown are, and how blogdown is different from existing popular website platforms, such as WordPress. There are two major highlights of blogdown:

1. It produces a static website, meaning the website only consists of static files such as HTML, CSS, JavaScript, and images, etc. You can host the website on any web server (see Chapter 3 for details). The website does not require server-side scripts such as PHP or databases like WordPress does. It is just one folder of static files. We will explain more benefits of static websites in Chapter 2, when we introduce the static website generator Hugo.
2. The website is generated from R Markdown documents (R is optional, i.e., you can use plain Markdown documents without R code chunks). This brings a huge amount of benefits, especially if your website is related to data analysis or (R) programming. Being able to use Markdown implies simplicity and more importantly, portability (e.g., you are giving yourself the chance to convert your blog posts to PDF and publish to journals or even books in the future). R Markdown gives you the benefits ofdynamic documents — all your results, such as tables, graphics, and inline values, can be computed and rendered dynamically from R code, hence the results you present on your website are more likely to be reproducible. An additional yet important benefit of using R Markdown is that you will be able to write technical documents easily, due to the fact that blogdown inherits the HTML output format from bookdown (Xie, 2016). For example, it is possible to write LaTeX math equations, BibTeX citations, and even theorems and proofs ifyou want.

Please do not be misled by the word “blog” in the package name: blogdown is for general-purpose websites, and not only for blogs. For example, all authors of this book have their personal websites, where you can find information about their projects, blogs, package documentations, and so on. ² All their pages are built from blogdown and Hugo.

If you do not prefer using Hugo, there are other options, too. Chapter 5 presents possibilities of using other site generators, such as Jekyll and rmarkdown’s default site generator.

Structure of the book

Chapter 1 aims at getting you started with a new website based on blogdown: it contains an installation guide, a quick example, an introduction to RStudio addins related to blogdown, and comparisons of different source document formats. All readers of this book should finish at least this chapter (to know how to create a website locally) and Section 3.1 (to know how to publish a website). The rest of the book is mainly for those who want to further customize their websites.

Chapter 2 briefly introduces the static website generator Hugo, on which blogdown is based. We tried to summarize the official Hugo documentation in a short chapter. You should consult the official documentation when in doubt. You may skip Section 2.5 if you do not have basic knowledge of web technologies. However, this section is critical for you to fully understand Hugo. We have spent the most time on this section in this chapter. It is very technical, but should be helpful nonetheless. Once you have learned how to create Hugo templa...

Table of contents

• Cover
• Halftitle
• Title Page
• Copyright Page
• Table of Contents