v0.21 wishlist

[apreshill]

Hi @yihui,

As we discussed, I'm plopping my wishlist for blogdown here. It is quite long! I use blogdown every day with multiple teams within and outside of RStudio, and I teach it a lot too. While I believe addressing these items would improve the user experience, I also understand that there is a lot here and I'm realistic that not all of them will be feasible to tackle 😄

• 1. Two of my biggest previous pain points have been resolved recently 🎉: hitting the preview button in RStudio for .md files generating an errant .html file, and not being able to use the knit button.

• 2. We also got the IDE issue fixed where the page you navigated to in the viewer pane did not carry over when you opened the site in a full browser window; see "Show in new window" opens the page initially opened in the viewer, ignores navigation by user rstudio#6967.

• 3. Develop a system for versioning Hugo for each website project. I often have a few Hugo websites that I jump into on any given day, and sometimes I need to update Hugo to make one theme work, but I explicitly cannot update Hugo for another site b/c the theme isn't compatible with the latest Hugo. This situation is hard 😿 I would love for blogdown to help users manage this realistic situation better. [related issue]

• 4. Along the same lines, develop a way to help users keep the local Hugo version in sync with the Netlify version (if using). hugodown introduced a check on the netlify.toml file if present to make sure that you had the same version of Hugo running locally as you have set in the netlify.toml file for the build. This is huge for teams b/c you often have many people posting (and using blogdown/Hugo) quite sporadically, so this saves the site maintainer from having to be a lifeguard and jump in whenever there is a Hugo version mismatch.

• 5. Fix the blogdown system for detecting changes to the source files (i.e., the pain of serving site and blogdown reknitting en masse). I have had several sites in various stages of paralysis because blogdown tries to reknit posts that already had rendered versions and the source post had not been edited. This is a pretty common story, and appears to be more prevalent for folks who use Github, especially with multiple collaborators. I believe this was a primary source of pain for the tidyverse team, and why hugodown has the two-step rendering by design, where you knit with intention. [see also]

• 6. Develop better system for dealing with post dependencies. They currently all ship off to static/, which can be hard to debug when you cannot tell which post used which version of which lib. hugodown treated each post as its own project, and so the libs folders populated within each post bundle, which I found a pleasant way to work. For example, this is what the rmarkdown-libs/ folder looks like for the tidymodels.org site, and it was hard for me to connect these with the right content. [related issue]

• 7. Better support of post bundles. Post bundles were a great Hugo innovation that happened after the original package design/release. I realize that may mean changing a default option, but most people simply don't know what a post bundle is. Also, when you add the sample .Rmd post, it usually looks very odd in the directory structure of the example site, because most current Hugo themes have example sites with bundled posts. So it would also be good to have the example post be a post bundle itself, perhaps with a single static file and some text in the post itself about what it is and how to use it. I'm happy to contribute this if you agree with the idea.

• 8. Simplify the input file formats. This figure by Emi Tanaka sums it up well, but it also reveals why it is confusing: https://emitanaka.org/r/posts/2018-12-12-scientific-and-technical-blogging-radix-vs-blogdown/#fig:blogdown. I would definitely support treating markdown output as the default, or at least making .md easier to output. For all the reasons we say markdown is better than HTML at readability, diff-ability, etc. It feels more future-proof. This was one of the design decisions for hugodown, and it feels like there may be a happy middle where blogdown can be more md-focused. [related issue]

• 9. Figure out a way for the Hugo .TableOfContents variable to populate from .Rmd (if knitting to .html). Currently, this is another of my reasons for strictly using .Rmarkdown content instead of .Rmd. This variable is commonly used across many themes (including my own), so it feels important to figure out (I think you mentioned at one point it may require some JavaScript?) [related issue] [related issue] [related issue]

• 10. Better support Netlify integration. I really liked the hugodown::use_netlify_toml() function, which populated a file from here. I configure my own a bit differently, but this is a very nice and simple function to offer. It would be great to pre-populate this file with the Hugo version pulling from what is there locally, to start with.

• 11. Along the same lines, a simple function to add the build.R file in project root, or have it come as default with all blogdown sites. This for me is still one of my top blogdown features --- so small yet so impactful.

• 12. Show the output format in new posts by default, but make an option to remove it from future posts when using the add-in or function for new posts. This helps folks troubleshoot, as it is currently difficult to figure out and to search for.

• 13. Update or retire the add image add-in. It was really helpful when all images had to be in static/, but now it is just confusing. If keep, make it be smart about page bundles, and perhaps follow the same UI as the visual markdown editor.

• 14. Small, but given that we warn about draft posts, perhaps if serve site is running, print a warning when a user creates a new content folder named something not currently in layouts (like: "warning- found no layout file for content section named xxx; your theme’s default layout will be used unless you change the file's type or write a new Hugo layout- do you still wish to continue? Learn about Hugo layout lookup orders here: https://gohugo.io/templates/lookup-order"). Or something along those lines. I feel that the Hugo layout lookup orders are pretty hard to grasp onto for anyone who isn't a Hugo theme developer. [related issue from Hugo repo]

• 15. Support and recognize configuration directories. Currently, blogdown moves the config.toml to the root- is it possible to support it inside a config directory? The setup makes it difficult for users to use Netlify's "Deploy to Netlify" button that theme developers sometimes offer (which is so nice!), and often means that theme set-up instructions and other example repos don't match up for unwitting users.

• 16. I would love for HTML widgets to work more reliably. I have heard that shadowdom could be a possible helper here, but this is an ongoing source of pain for myself and many users.

• 17. Enable an easier way to edit layout files. The better practice is to copy the layout file from the themes/ directory then place it in project root and edit that version. But this is annoying with clicking in the IDE, especially when you are teaching or doing it everyday. Would it be possible to provide a simple function like edit_layout("post", template = c("list", "single", "all")) that copies the folders from the theme's directory and plops them into the project root for editing?

• 18. Add a pkgdown site (assigned to self 😉)

• 19. Update the book (also assigned to self 😉 )

Thanks for considering these, and I'm happy to explain my context and thinking on any of these if helpful. And of course, looking forward to contributing.

Alison

P.S. including some blog posts by experienced users that I think offer good insights:

• https://clauswilke.com/blog/2020/09/08/a-blogdown-post-for-the-ages/
• https://drmowinckels.io/blog/2020-05-25-changing-you-blogdown-workflow/
• https://masalmon.eu/2020/02/29/hugo-maintenance/
• https://yutani.rbind.io/post/2017-10-25-blogdown-custom/

[yihui]

Items 3, 4, 5, 6, 7, and 10 are done now, but some need more documentation (beyond the descriptions in NEWS.md).

I still need more time to think about "simplify the input file formats". I'm not sure it's a good idea to throw the .Rmd format away. Other than that, I feel the rest of issues are not urgent, and I can probably do them at my regular pace. Many thanks again for putting together this list. This is extremely helpful!

[yihui]

11 is also done now.

[yihui]

13 is done (the addin was updated to deal with bundle pages, and images will live together with the post, instead of being copied to static/).

[apreshill]

Wanted to pin another example where .Rmarkdown vs. .Rmd saves considerable pain for something that seems simple at first (and you want your syntax highlighting to look consistent across posts): https://twitter.com/andrewheiss/status/1330667790018240513?s=20