blogdown: Knit on Save, or Save on Knit?

Yihui Xie 2021-05-30

One of the hardest decisions in blogdown that I had to make was whether to make “Knit on Save” or “Save on Knit” the default behavior. I chose the former, to which everyone seemed to object. In this post, I will explain my rationale.

Before I start, I want to take this opportunity to reemphasize the most important thing to remember about blogdown, even if it is irrelevant to this post: when in doubt, run blogdown::check_site()! I’ll save this for another blog post in the future, but it is so important that I repeat it everywhere this year. If you still experience any major pain with blogdown (e.g., the Hugo version pain) and blogdown::check_site() does not help you fix it, I will be happy to write you a check. Seriously.

Knit on Save, and Save on Knit—What do they mean?

When you edit an R Markdown post in a blogdown site project, “Knit on Save” means blogdown will automatically (re)compile your post as soon as you save the post, and “Save on Knit” means your R Markdown post is saved (and also knitted) as soon as you click on the Knit button in RStudio.

Before I explain the rationale, let me emphasize that the default behavior can be easily changed via a global option blogdown.knit.on_save. If you do not like the current default behavior, you can set this option to FALSE. Please see the Section “Global options” in the blogdown book for details.

1. Backward compatibility

The Knit button in RStudio never worked for blogdown until v0.21. That means the alternative option “Save on Knit” was not really available in the three years, and users had to use “Knit on Save,” which was not good, but I thought I had no choice until I was told that the Knit button could work. I was well aware of this problem and wished that the Knit button could work from the beginning of blogdown. I asked the question back then, but did not push hard enough. Three years later I asked again, and it turned out the problem was simple enough to fix.

The good news made me struggle on whether the default behavior should be changed. Every team member suggested that it should, but I was worried about backward compatibility. I really did not know if I would be killed sooner by users who found that the Knit button suddenly started working (because I made them wait for so long), or users who found that the Save button suddenly stopped working (because I had trained them for so long).

2. Consideration of non-RStudio users

I did not want to assume or recommend that everyone uses RStudio. If you do not use RStudio, you do not have the Knit button to click on. In this case, your only option is probably “Knit on Save,” because every text editor must have a Save button (or a keyboard shortcut) to save a file. Well, that is not really the only option, but you would have to run blogdown::build_site(build_rmd = "path/to/post.Rmd") over and over again in R, which is a tedious task.

3. Clicking on the Knit button works now

Even with the default “Knit on Save,” the Knit button actually still works fine if you click on the Knit button. More importantly, if you have not set the option blogdown.knit.on_save, this option will be automatically set to FALSE when you click on the Knit button for the first time, with a message in the console telling you why it was set to FALSE. The option is set only temporarily for the current R session, and the message also tells you how to set it permanently for future R sessions if you really mean to only use the Knit button to compile R Markdown posts. With this option set to FALSE, your R Markdown post will no longer be automatically compiled when you save the post. That means when you click on the Knit button, we guess that you are probably a “Knit person” and set the right option for you. This guess may not always be correct, but again, the message should explain the situation, and the guess only takes place when you have not already set the option by yourself.

4. Consistent behavior with .md posts

Thanks to Hugo’s LiveReload feature, you can live preview Markdown posts (.md files) as soon as you save them, i.e., “Preview on Save.” It is unnecessary to click on the Knit button to preview .md posts. If you click on the button anyway, it does nothing behind the scenes in addition to saving the post. Once the .md post is saved, Hugo will show you the preview almost instantly. Choosing “Knit on Save” as the default in blogdown makes the authoring experience consistent between .Rmd and .md posts.

Note that blogdown’s default post type is .md (which can also be easily changed to .Rmd via the global option blogdown.ext). I have found for several times that people use .Rmd even when they do not have any R code chunks in the post, or have a few R code chunks but all are marked with the option eval = FALSE (i.e., no code chunks are to be evaluated). In these cases, it will be much cleaner and faster to use .md instead. I guess I’m not a typical user of blogdown myself, because I rarely write .Rmd posts. I’m too used to “Preview on Save.”

Downsides of “Knit on Save” as the default behavior

The default behavior may not be desirable to a lot of users, but again, it is fairly easy to change via a global option. The main downsides of this behavior are:

For the first one, I cannot defend myself. For the second one, I wonder how common it is for an average blog post to contain intensive computing (probably not very common), but I understand that it could be annoying that blogdown starts to compile the post when a code chunk is still being developed.

Conclusion (or no conclusion)

As I said in the beginning, this was a hard decision to make. Even to this point, I’m not totally sure I should change the behavior. If blogdown were less than one year old, I would change it without much hesitation. Now I just wish users who have had to set options(blogdown.knit.on_save = FALSE in their .Rprofile could forgive me for this hassle…