A note from the authors: Some of the information and instructions in this book are now out of date because of changes to Hugo and the blogdown package. If you have suggestions for improving this book, please file an issue in our GitHub repository. Thanks for your patience while we work to update the book, and please stay tuned for the revised version!

In the meantime, you can find an introduction to the changes and new features in the v1.0 release blog post and this "Up & running with blogdown in 2021" blog post.

— Yihui, Amber, & Alison

D.4 Functions in the blogdown package

There are about 20 exported functions in the blogdown package, and many more non-exported functions. Exported functions are documented and you can use them after library(blogdown) (or via blogdown::). Non-exported functions are not documented, but you can access them via blogdown::: (the triple-colon syntax). This package is not very complicated, and consists of only about 2000 lines of R code (the number is given by the word-counting command wc):

wc -l ../R/*.R ../inst/scripts/*.R
      54 ../R/addin.R
     583 ../R/check.R
      48 ../R/clean.R
      74 ../R/format.R
     875 ../R/hugo.R
     420 ../R/install.R
      44 ../R/package.R
     330 ../R/render.R
     300 ../R/serve.R
      65 ../R/site.R
    1074 ../R/utils.R
     125 ../inst/scripts/insert_image.R
     105 ../inst/scripts/new_post.R
      78 ../inst/scripts/update_meta.R
    4175 total

You may take a look at the source code (https://github.com/rstudio/blogdown) if you want to know more about a non-exported function. In this section, we selectively list some exported and non-exported functions in the package for your reference.

D.4.1 Exported functions

Installation: You can install Hugo with install_hugo(), and install a Hugo theme with install_theme().

Wrappers of Hugo commands: hugo_cmd() is a general wrapper of system2('hugo', ...), and all later functions execute specific Hugo commands based on this general wrapper function; hugo_version() executes the command hugo version (i.e., system2('hugo', 'version') in R); hugo_build() executes hugo with optional parameters; new_site() executes hugo new site; new_content() executes hugo new to create a new content file, and new_post() is a wrapper based on new_content() to create a new blog post with appropriate YAML metadata and filename; hugo_convert() executes hugo convert; hugo_server() executes hugo server.

Output format: html_page() is the only R Markdown output format function in the package. It inherits from bookdown::html_document2(), which in turn inherits from rmarkdown::html_document(). You need to read the documentation of these two functions to know the possible arguments. Section 1.6 has more detailed information about it.

Helper functions: shortcode() is a helper function to write a Hugo shortcode {{% %}} in an Rmd post; shortcode_html() writes out {{< >}}.

Serving a site: serve_site() starts a local web server to build and preview a site continuously; you can stop the server via stop_server(), or restart your R session.

Dealing with YAML metadata: find_yaml() can be used to find content files that contain a specified YAML field with specified values; find_tags() and find_categories() are wrapper functions based on find_yaml() to match specific tags and categories in content files, respectively; count_yaml() can be used to calculate the frequencies of specified fields.

D.4.2 Non-exported functions

Some functions are not exported in this package because average users are unlikely to use them directly, and we list a subset of them below:

  • You can find the path to the Hugo executable via blogdown:::find_hugo(). If the executable can be found via the PATH environment variable, it just returns 'hugo'.

  • The helper function modify_yaml() can be used to modify the YAML metadata of a file. It has a ... argument that takes arbitrary YAML fields, e.g., blogdown:::modify_yaml('foo.md', author = 'Frida Gomam', date = '2015-07-23') will change the author field in the file foo.md to Frida Gomam, and date to 2015-07-23. We have shown the advanced usage of this function in Section 4.1.

  • We have also mentioned a series of functions to clean up Markdown posts in Section 4.1. They include remove_extra_empty_lines(), process_bare_urls(), normalize_chars(), remove_highlight_tags(), and fix_img_tags().

  • In Section D.3, we mentioned a caching mechanism based on the file modification time. It is implemented in blogdown:::require_rebuild(), which takes two arguments of filenames. The first file is the output file, and the second is the source file. When the source file is older than the output file, or the output file does not exist or is empty, this function returns TRUE.