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

1.3 A quick deploy

Publishing a blogdown website involves copying the output directory containing all your rendered site files (typically, a bunch of *.html files and site assets like fonts, CSS, JavaScript, and images) to a web server or web hosting service.

In this section, we will walk you through a quick deploy to publish your website using a drag-and-drop tool from https://www.netlify.com. Netlify is a platform that offers cloud hosting and serverless backend services for static websites. Lucky for us, that is exactly what we need—since blogdown helps us create static websites using Hugo.

If you followed along with Section 1.2, you should now have s static website using the Hugo lithium theme with knitted .Rmd content for one post and served locally using blogdown.

The drag-and-drop method we describe next is a good workflow to start with if you are not familiar with GIT or GitHub or deploying websites. There are many options for publishing static websites, and we will talk more about them plus advanced workflows involving version control and continuous deployment in Chapter 3.

1.3.1 Build site

The publishing directory of a Hugo site is public/ by default. Your built website will be generated to this directory, which you can upload to any web server that can serve static websites, and your website will be up and running.

Serving your Hugo site locally using blogdown::serve_site() does not generate the public/ directory. To follow this drag-and-drop method, you’ll need to build your site locally first.

Restart the R session, and run:

blogdown::build_site()

Alternatively, if you use RStudio, you may use:

  • the “Build Website” button in the Build pane, or

  • press Ctrl + Shift + B (Cmd + Shift + B on macOS) to build the website.

You should see a new public/ directory under the root directory of your project. Never edit files in this directory, as your changes will always be overwritten whenever you re-build your site.

Note that this function does not re-knit R Markdown files by default, because it may be expensive and often undesirable to render .Rmd files that have been knitted before. Given that R package upgrades have a tendency to break older code, continuously re-knitting old content is nearly impossible to do without errors, especially over longer periods of time.

We recommend always using blogdown::serve_site() first to preview your site before building it. By default, that function will knit your R Markdown content that has not been knitted yet. As mentioned earlier, we also recommend running blogdown::check_content(). Among other things, we check if you have content that needs to be re-knit:

| Checking your R Markdown content...
○ All R Markdown files have been knitted.
○ All R Markdown output files are up to date with their source files.

1.3.2 Use Netlify Drop

Next, go online to Netlify Drop at https://app.netlify.com/drop. You can drag and drop the public/ folder from your file viewer to the indicated area on the Netlify web page, where it says “Drag and drop your site output folder here.”

Wait for a few seconds for Netlify to deploy the files, and it will assign a random subdomain of the form random-word-12345.netlify.app to you. After your site is live, you will be able to share the link to your new blogdown site if you would like to.

You will notice a disclaimer that this site will be deleted after 24 hours. You need to create an account to save this link and keep your site online.

1.3.3 Sign up for Netlify

Netlify has a free plan with plenty of useful features, so we recommend signing up for an account. To sign up:

  1. Go online to https://www.netlify.com.

  2. Click on the “Sign Up” button.

  3. If you have a GitHub account (https://github.com), we recommend signing up using your existing GitHub account (no need to create another account), so select “GitHub” (you may need to sign in), and click to “Authorize Netlify.”

  4. From your account, if you used Netlify Drop, you can (and should) change your random subdomain to a more meaningful one. You may read the docs for changing a site’s default Netlify subdomain here: https://docs.netlify.com/domains-https/custom-domains/#assign-a-domain-to-a-site

  5. Also from your account, you may update your existing site by making changes locally, reknitting if necessary, then rebuilding your site with blogdown::build_site(). In the “Deploys” tab on Netlify, scroll down to where you see “Need to update your site? Drag and drop your site output folder here.” Drop your updated public/ folder there to update the deployed website.

1.3.4 What is next?

The workflow described above can be cumbersome the more you work on your website. It can be much easier to publish a website if you are familiar with GIT and GitHub.

We recommend that you create a new site on Netlify from your GitHub repository that contains the source files of your website, so that you can enjoy the benefits of continuous deployment instead of manually uploading the public/ folder every time.

With this advanced workflow, you do not need to run blogdown::hugo_build() locally, because the website can be built on Netlify via Hugo. Instead, you would rely on blogdown::serve_site() locally to preview your site before pushing your changes to GitHub. See Chapter 3 for more information.