In rstudio/blogdown: Create Blogs and Websites with R Markdown

# NOTE: the maximum line width for PDF output is 69. Please make sure that
# verbatim code blocks contain less than 70 characters per line.

options(
  htmltools.dir.version = FALSE, formatR.indent = 2,
  width = 55, digits = 4, warnPartialMatchAttr = FALSE, warnPartialMatchDollar = FALSE
)

# install missing packages, some of theme are for citations references
lapply(c('formatR', 'htmlwidgets', 'servr', 'animation',  'processx', 'widgetframe', 'pkgdown'), function(pkg) {
  if (system.file(package = pkg) == '') install.packages(pkg)
})

# latex post process
options(bookdown.post.latex = function(x) {

  # only build a skeleton for the online version
  if (Sys.getenv('BOOKDOWN_FULL_PDF', '') == 'false') return(bookdown:::strip_latex_body(
    x, '\nThis PDF is only a skeleton. Please either read the free online HTML version, or purchase a hard-copy of this book.\n'
    ))

  x
})

Preface {-}

knitr::include_graphics('images/cover.png', dpi = NA)

In the summer of 2012, I did my internship at AT&T Labs Research,^[In this book, "I" and "my" refer to Yihui unless otherwise noted.] 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.

knitr::include_graphics('images/logo.png', dpi = NA)

We introduce an R package, blogdown, in this short book, to teach you how to create websites using R Markdown and Hugo. If you 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 \@ref(deployment) 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 \@ref(hugo), 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 of dynamic 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 [@xie2016]. For example, it is possible to write LaTeX math equations, citations, and even theorems and proofs if you 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.^[Yihui's homepage is at https://yihui.org. He writes blog posts in both Chinese (https://yihui.org/cn/) and English (https://yihui.org/en/), and documents his software packages such as knitr (https://yihui.org/knitr/) and animation (https://yihui.org/animation/). Occasionally he also writes articles like https://yihui.org/rlp/ when he finds interesting topics but does not bother with a formal journal submission. Amber's homepage is at https://amber.rbind.io, where you can find her blog and project pages. Alison's website is at https://alison.rbind.io, which uses an academic theme at the moment.] All their pages are built from blogdown and Hugo.

If you do not prefer using Hugo, there are other options, too. Chapter \@ref(other-generators) presents possibilities of using other site generators, such as Jekyll and rmarkdown's default site generator.

This book has been published by Chapman & Hall/CRC. The online version of this book is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

Structure of the book {-}

Chapter \@ref(get-started) 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 \@ref(netlify) (to know how to publish a website). The rest of the book is mainly for those who want to further customize their websites.

Chapter \@ref(hugo) 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 \@ref(templates) 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 templates, you will have the full freedom to customize your website.

Chapter \@ref(deployment) tells you how to publish a website, so that other people can visit it through a link. Chapter \@ref(migration) shows how to migrate existing websites from other platforms to Hugo and blogdown. Chapter \@ref(other-generators) gives a few other options if you do not wish to use Hugo as your site generator.

Appendix \@ref(r-markdown) is a quick tutorial on R Markdown, the prerequisite of blogdown if you are going to write R code in your posts. Appendix \@ref(website-basics) contains basic knowledge about websites, such as HTML, CSS, and JavaScript. If you really care about your website, you will have to learn them someday. If you want to have your own domain name, Appendix \@ref(domain-name) provides an introduction to how it works. We have also covered some optional topics in Appendix \@ref(advanced-topics) for advanced users.

Software information and conventions {#software-info .unnumbered}

The R session information when compiling this book is shown below:

requireNamespace("blogdown")
# only show versions of very relevant packages
sessionInfo = function() {
  res = utils::sessionInfo()
  loaded = res$loadedOnly
  res$loadedOnly = loaded[intersect(names(loaded), c(
    'blogdown', 'bookdown', 'knitr', 'rmarkdown', 'htmltools'
  ))]
  res$BLAS = res$LAPACK = NULL
  res
}

sessionInfo()

We do not add prompts (> and +) to R source code in this book, and we comment out the text output with two hashes ## by default, as you can see from the R session information above. This is for your convenience when you want to copy and run the code (the text output will be ignored since it is commented out). Package names are in bold text (e.g., rmarkdown), and inline code and filenames are formatted in a typewriter font (e.g., knitr::knit('foo.Rmd')). Function names are followed by parentheses (e.g., blogdown::serve_site()). The double-colon operator :: means accessing an object from a package.

A trailing slash often indicates a directory name, e.g., content/ means a directory named content instead of a file named content. A leading slash in a path indicates the root directory of the website, e.g., /static/css/style.css means the file static/css/style.css under the root directory of your website project instead of your operating system. Please note that some directory names are configurable, such as public/, but we will use their default values throughout the book. For example, your website will be rendered to the public/ directory by default, and when you see public/ in this book, you should think of it as the actual publishing directory you set if you have changed the default value. Rmd stands for R Markdown in this book, and it is the filename extension of R Markdown files.

A "post" often does not literally mean a blog post, but refers to any source documents (Markdown or R Markdown) in the website project, including blog posts and normal pages. Typically blog posts are stored under the content/post/ directory, and pages are under other directories (including the root content/ directory and its subdirectories), but Hugo does not require this structure.

The URL http://www.example.com is used only for illustration purposes. We do not mean you should actually visit this website. In most cases, you should replace www.example.com with your actual domain name.

An asterisk * in a character string often means an arbitrary string. For example, *.example.com denotes an arbitrary subdomain of example.com. It could be foo.example.com or 123.example.com. Actually, foo and bar also indicate arbitrary characters or objects.

Acknowledgments {-}

Originally I planned to write only one sentence in this section: "I thank Tareef." This book and the blogdown package would not have been finished without Tareef, the president of RStudio. He has been "gently nudging" me every week since Day 1 of blogdown. As a person without strong self-discipline and working remotely, I benefited a lot from weekly meetings with him. He also gave me a lot of good technical suggestions on improving the package. Actually, he was one of the very earliest users of blogdown.

Of course, I'd like to thank RStudio for the wonderful opportunity to work on this new project. I was even more excited about blogdown than bookdown (my previous project). I started blogging 12 years ago, and have used and quit several tools for building websites. Finally I feel satisfied with my own dog food.

Many users have provided helpful feedback and bug reports through GitHub issues (https://github.com/rstudio/blogdown/issues). Two of my favorites are https://github.com/rstudio/blogdown/issues/40 and https://github.com/rstudio/blogdown/issues/97. Some users have also contributed code and improved this book through pull requests (https://github.com/rstudio/blogdown/pulls). You can find the list of contributors at https://github.com/rstudio/blogdown/graphs/contributors. Many users followed my suggestion to ask questions on StackOverflow (https://stackoverflow.com/tags/blogdown) instead of using GitHub issues or Emails. I appreciate all your help, patience, and understanding. I also want to make special mention of my little friend Jerry Han, who was probably the youngest blogdown user.

For this book, I was fortunate enough to work with my co-authors Amber and Alison, who are exceptionally good at explaining things to beginners. That is the ability I desire most. Needless to say, they have made this book friendlier to beginners. In addition, Sharon Machlis contributed some advice on search engine optimization in this book (https://github.com/rstudio/blogdown/issues/193). Raniere Silva contributed Section \@ref(gitlab-pages) (https://github.com/rstudio/blogdown/pull/225).

I'd like to thank all Hugo authors and contributors (Bjørn Erik Pedersen and Steve Francia et al.) for such a powerful static site generator. At least it made me enjoy building static websites and blogging again.

For some reason, a part of the R community started to adopt the "sticker-driven development" model when developing packages. I was hoping blogdown could have a hexbin sticker, too, so I asked for help on Twitter (https://twitter.com/xieyihui/status/907269861574930432) and got tons of draft logos. In particular, I want to thank Thomas Lin Pedersen for his hard work on a very clever design. The final version of the logo was provided by Taras Kaduk and Angelina Kaduk, and I truly appreciate it.

This is the third book I have published with my editor at Chapman & Hall/CRC, John Kimmel. I always love working with him. Rebecca Condit and Suzanne Lassandro proofread the manuscript, and I learned a lot from their comments and professional suggestions.

{block2, type='flushright', html.tag='p'} Yihui Xie Elkhorn, Nebraska

rstudio/blogdown documentation built on Feb. 5, 2024, 10:09 p.m.