Update the book

[apreshill]

I'm using this issue to flush out some things I'd like to update in the blogdown book:

Get started

1. Installation (updated in #618)
2. A quick example (updated in #618) [notes: no GitHub, hugo-lithium theme, no deploy, edit post only]
3. A quick deploy (added in #619) [notes: still no GitHub, hugo-lithium theme, Netlify Drop]
4. A complete example (draft in #623) [notes: GitHub, wowchemy theme, edit + add new post, Netlify continuous deployment]
5. Other themes (updated in #620)
6. Recommended workflows (will need an update after all of the above, idea is more like a cheatsheet/tl;dr version of above content, will include GitHub)

The blogdown package

Propose a new chapter with these sections:

1. RStudio Addins (adapt from https://bookdown.org/yihui/blogdown/rstudio-ide.html)
2. Using R Markdown (adapt from https://bookdown.org/yihui/blogdown/output-format.html, plus add https://blog.rstudio.com/2021/01/18/blogdown-v1.0/#better-support-for-markdown-format)
3. Global options (adapt from https://bookdown.org/yihui/blogdown/global-options.html; be sure to mention all of these)
4. Checking functions (adapt from https://blog.rstudio.com/2021/01/18/blogdown-v1.0/#checking-functions)
5. Hugo versioning system (adapt from https://blog.rstudio.com/2021/01/18/blogdown-v1.0/#hugo-versioning-system)

WIP draft chapter in branch here: https://github.com/apreshill/blogdown/blob/blogdown-chapter/docs/02-blogdown.Rmd

Some rationale

Help users realize what blogdown actually does, vs Hugo/GitHub/Netlify. Folks often ask this in workshops and meetups, and with the checking functions and versioning system, I think the package now deserves its own chapter to highlight how we make using Hugo in the RStudio IDE easier.

Hugo...

(and all other chapter updates I leave up to @yihui)

Advanced

Wonder if we should add a section on GitHub Actions for blogdown? See: https://drmowinckels.io/blog/2021-03-23-using-github-actions-to-build-your-hugo-website/

Notes to self

Need a link to early demo sites. Also this is effectively a gallery: https://github.com/rbind, as is: https://pkgs.rstudio.com/blogdown/articles/articles/examples.html

[cderv]

I like this outline.

Personal thoughts and feelings:

• For the new chapter called blogdown, I see that as "Going Further" which is the usual path after "Getting Started". Having a chapter called with the same name of the book feels weird to me.
• I would not but RStudio IDE chapter first. I think you already show some new project screenshot in get started so maybe it is just a part about the Addin to add in the book ?
• Regarding output format, is this where you plan to talk about the different methods ? with new markdown mode to be able to do .Rmd -> .md directly ? Currently the other supported method after the default html was custom and it was explained in Appendix only https://bookdown.org/yihui/blogdown/methods.html Maybe that worth mentioning in this chapter about output formats and keep the custom method as advanced topic for Appendix.

Thank you for all this @apreshill ! 💪

[apreshill]

For the new chapter called blogdown, I see that as "Going Further" which is the usual path after "Getting Started". Having a chapter called with the same name of the book feels weird to me.

Open to renaming- although I was moving those sections from "Get Started" that were about the specific package/addins/functions. In teaching and convos with users, a major point of confusion is "what DOES blogdown actually do" vs. Hugo/themes/GitHub/Netlify/etc. So I'd prefer to be ridiculously clear here. Readers would see a chapter labeled "The blogdown package" and would probably think to look there to find the checking functions (since this is also our docs), for example, but I'd have a hard time knowing those are in a chapter called "Going further". It also assumes folks are reading from start to finish- I don't think we can assume that. "Get started" is a special one to catch beginners, but not sure the other is helpful.

I would not but RStudio IDE chapter first. I think you already show some new project screenshot in get started so maybe it is just a part about the Addin to add in the book ?

That was a moved section from "Get Started"- one of the earliest from there. I think Addins are really important and I highlight when teaching. Where would you put this?

Regarding output format, is this where you plan to talk about the different methods ? with new markdown mode to be able to do .Rmd -> .md directly ? Currently the other supported method after the default html was custom and it was explained in Appendix only https://bookdown.org/yihui/blogdown/methods.html Maybe that worth mentioning in this chapter about output formats and keep the custom method as advanced topic for Appendix.

I'm not sure yet- although I don't think this should be reserved for advanced users. Depending on their theme, users may already be flailing around with file output formats. I would definitely not touch the build_site() args here, but I think the markdown mode (because it is an R option) is pretty simple (i.e., hugodown was based on the idea, and many users ask for plain md output in workshops).

[cderv]

a major point of confusion is "what DOES blogdown actually do" vs. Hugo/themes/GitHub/Netlify/etc. So I'd prefer to be ridiculously clear here.

That make sense. It would indeed be more clear if it is called : the blogdown package.

I do not have another name idea for now. It just feels that with a chapter with this name I would expect to find everything about the package in this part - for now blogdown::shortcode() is mentionned in the Hugo chapter when shortcodes are mentioned. So other chapters also mentioned blogdown features. That is what I guess I am unsure.

I think Addins are really important and I highlight when teaching. Where would you put this?

We could rename the RStudio IDE current chapter to RStudio Addins : it is currently mainly about that. Other thing it currently mentions is New project and build site, but it could be shown in Get started

I would definitely not touch the build_site() args here

If we don't mention the build_site agument in the Blogdown chapter, I don't know where except appendix maybe for a part specific on this if we consider too advanced for main book. In the main book, I was thinking in this part:

5.Using R Markdown (adapt from bookdown.org/yihui/blogdown/output-format.html, plus add blog.rstudio.com/2021/01/18/blogdown-v1.0/#better-support-for-markdown-format)

[apreshill]

I do not have another name idea for now. It just feels that with a chapter with this name I would expect to find everything about the package in this part - for now blogdown::shortcode() is mentionned in the Hugo chapter when shortcodes are mentioned. So other chapters also mentioned blogdown features. That is what I guess I am unsure.

Yes! I noticed that was missing last night- I think it should be added there, highlighting the default Hugo shortcodes (vs theme-specific ones): https://gohugo.io/content-management/shortcodes/

We could rename the RStudio IDE current chapter to RStudio Addins : it is currently mainly about that. Other thing it currently mentions is New project and build site, but it could be shown in Get started

That sounds good. I want it to be complete though, since this is docs. I think repetition is possibly preferable here, since some folks will always skip "beginner" sections- even if they should not :)

[bbolker]

broken link on the website to https://alison.rbind.io/post/new-year-new-blogdown/ ? Should be https://alison.rbind.io/blog/2020-12-new-year-new-blogdown/

[yihui]

@bbolker Thanks for the report!

@apreshill Could you add a 301 redirect to your website? Thanks!

[apreshill]

oof! yes thank you!

[apreshill]

Done- I forgot to do my splats correctly, thanks!

[yihui]

@apreshill It seems you changed an utterances setting recently: https://github.com/rbind/apreshill/blob/28569ca6cf964b225d458d90fa09b5db5da499b9/config.toml#L80 Previously you were using title. That's why the comments are not loading for this post.

BTW, this issue needs to stay open :)