Use options(blogdown.serve_site.startup = FALSE) as default, and improve messages

[apreshill]

After playing with creating new sites a lot over the break, I feel like the experience of creating that first new site could be a bit smoother. Here was my screen after creating a new site:

There is a lot of red text and it is easy to miss key info (like how to stop the server). But also, we don't say how to actually start it. What about some formatting like the checking functions?

― Creating your new site
| Downloading theme files from: _______
| Rendering sample R Markdown post from: _______
| New site setup complete!
― Using your new site
○ To start a local preview: use blogdown::serve_site(), or the "Serve Site" Add-in
○ To stop a local preview: use blogdown::stop_server(), or restart your R session
○ Use ?serve_site and ?build_site to learn more.
▶ Want blogdown to start a Hugo server now? y / n

(unicode triangle: https://en.wikipedia.org/wiki/Geometric_Shapes)

Just an idea, thanks for considering!

[yihui]

To clarify, blogdown.serve_site.startup = FALSE is the default. The server was started because of new_site(serve = TRUE) by default in an interactive R session (see ?blogdown::new_site). If you use the RStudio project wizard to create a new site in a new R session, it won't start the server automatically.

I'm definitely open to improving the messages. Thanks!

[apreshill]

Wow- gosh I've tested this eight ways from Sunday and didn't see that difference. So perhaps they could be the same, new_site(serve = FALSE), then both ways of creating a project would be actually interchangeable? It is hard to write tutorials when things like that differ, and I like the idea of purposefully opting in to the serving site for you as the default (regardless of whether you use the project wizard or the console). What do you think?

[yihui]

I'm okay with interactively asking if the user wants to start the server or not.

Re: new_site() vs the RStudio project wizard, personally I prefer using the latter instead of the former for the following reasons:

1. For new_site(), you'd need an empty directory to start with, which is guaranteed by the wizard;
2. The site created with new_site() is not fully recognized by RStudio in that 1) It is not an RStudio project (doesn't have the *.Rproj file); 2) It won't have the Build pane since RStudio doesn't know that it is a website project (hence users won't be able to click the Build Website button in the pane, or Cmd + Shift + B to build the site, and have to run blogdown::build_site() manually).
3. The wizard provides a GUI, which can be more friendly than the command line;
4. The wizard doesn't serve the site automatically;
5. The wizard provides an option to create and open the project in a new R session.

[apreshill]

Thank you! This is very helpful. One very important difference in workflows between new_site() vs the RStudio project wizard for anything involving GitHub is that it is easier for beginners to:

1. create a new repo on github.com
2. setup a new RStudio project via the GitHub project wizard
3. use new_site()
4. push! success!

If you use the project wizard, but want to use GitHub via the IDE, you instead need to:

1. make your site
2. add git (which you can do in a "bare" new project via wizard, but is not an option for blogdown). I tell folks to usethis::use_git()
3. set up a GitHub PAT- I send instructions to: https://happygitwithr.com/github-pat.html
4. connect the local repo to GitHub. I tell folks to usethis::use_github().
5. push! success!

From an education point of view, the second workflow is less ideal- more steps, and more steps that feel like "inessential weirdness". Setting up a PAT is confusing, and it forces users to leave the IDE to do something that they don't totally understand, and I have to introduce another package, usethis. You are right that a GUI like the wizard is more friendly than the command line- but on balance this is why I tend to teach with new_site() because the project wizard approach ends up forcing more extraneous command line "to do" items in a complete workflow.

This is also different than distill, which I really like that the project wizard is the same as create_site() and create_blog()- both from the command line add an .Rproj file:

https://github.com/rstudio/distill/blob/495872da3f8b82367fdd4006b9fc252b811dcd9f/R/create.R#L365-L367

  # if we are running in RStudio then create Rproj
  if (have_rstudio_project_api())
    rstudioapi::initializeProject(dir)

It seems like if new_site() behaved like that, points 2 and 5 above are addressed for you, and for me point 4 (reducing command line) is achieved for teaching a full GitHub workflow. For point 4, can new_site(serve = FALSE, prompt_serve = TRUE) (or something like that)?

Then the two main differences can be just point 1 (empty dir) and point 3, whether you prefer a UI or the use the R console? You might still need to restart to get the build pane, but in the very first session, we'll likely orient users to serve to preview anyway? build_site() definitely seems (to me) a more advanced workflow than serve_site().

[yihui]

Oh I didn't know you were starting from an empty Github repo (I thought you were starting from a local empty dir). Then my point 1 is no longer a concern.

I didn't think of using rstudioapi::initializeProject() to create the *.Rproj file, but this is definitely a good idea. I'll do that. Thanks for the tip!

I'm curious why the wizard workflow requires setting up Github PAT but the other workflow doesn't. If you work with a GIT repo, you have to set up credentials at some point.

[yihui]

Done now. Thanks!

[apreshill]

it is a thing of beauty!! 🌟