blogdown
blogdown copied to clipboard
Update the book
I'm using this issue to flush out some things I'd like to update in the blogdown book:
Get started
- Installation (updated in #618)
- A quick example (updated in #618) [notes: no GitHub,
hugo-lithium
theme, no deploy, edit post only] - A quick deploy (added in #619) [notes: still no GitHub,
hugo-lithium
theme, Netlify Drop] - A complete example (draft in #623) [notes: GitHub, wowchemy theme, edit + add new post, Netlify continuous deployment]
- Other themes (updated in #620)
- 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:
- RStudio Addins (adapt from https://bookdown.org/yihui/blogdown/rstudio-ide.html)
- 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)
- Global options (adapt from https://bookdown.org/yihui/blogdown/global-options.html; be sure to mention all of these)
- Checking functions (adapt from https://blog.rstudio.com/2021/01/18/blogdown-v1.0/#checking-functions)
- 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
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
wascustom
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 ! 💪
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).
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)
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 :)
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/
@bbolker Thanks for the report!
@apreshill Could you add a 301 redirect to your website? Thanks!
oof! yes thank you!
Done- I forgot to do my splats correctly, thanks!
@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 :)