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
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, 1 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:
- 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.
- 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. 2 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...