Adding checking functions to help users check their sites themselves

[apreshill]

🤕 Problem: there are lots of (predictable) ways that blogdown users can stumble into pain. We have added some printed messages like errors and warnings to help teach users, but the problem with those is that users still experience pain first. They may get frustrated and give up early, or start to tune out these “helpful” messages.

Proposed solution: take a more proactive stance to guide users toward success first by offering some targeted functions to help them sidestep predictable pain points, while at the same time helping users understand all the moving pieces. We could perhaps offer individual checking functions, then wrap them all up in a larger check_site() function? The key here would be printing the output in a user-friendly way.

1. check_config()

   • Do they have unsafe = TRUE?

   • Do they have a baseURL set?

   • Do they have ignoreFiles = _files$?

2. check_gitignore()

   • Did they ignore the right files?

   • OK to ignore: blogdown, public, resources (if netlify.toml exists)

   • NOT OK to ignore: *.html files, *.md files, the static/ directory

3. check_hugo() (see options(blogdown.hugo.version = xxx))

   • What version Hugo are you running with blogdown?

   • What is the minimum version of Hugo that your theme requires?

   • Have multiple local Hugo versions? If so, advise how to clean them up.

4. check_netlify() (see options(blogdown.check.netlify = FALSE))

   • What HUGO_VERSION do you have in your netlify.toml?

   • Is it the same as your local Hugo version that blogdown is using?

   • Does the publish directory match config.toml?

5. check_content() (see options(blogdown.check.html = FALSE))

   • Draft/future content: Check for content marked as draft or with a future publish date; list and advise (see options(blogdown.warn.future = FALSE) and options(blogdown.draft.output = TRUE))

   • Forgot to knit: Check for source files with no rendered file versions

   • Bad knitted .html: Detect .html files that seem to be generated by clicking the Knit button in RStudio with blogdown < v0.21; list and advise

   • Duplicate .md + .html files: users often “double render” and Hugo by default shows the .html over the .md. Confusing to debug.

   • Source/output out-of-sync: source is newer than output (see options(blogdown.files_filter = blogdown:::md5sum_filter/blogdown:::timestamp_filter))

Thoughts? Any pitfalls I've missed? Other ideas for achieving similar outcomes?

Checklist

When filing a feature request, please check the boxes below to confirm that you have provided us with the information we need. Have you:

• [x] searched for an existing feature request to avoid creating duplicate requests? If you find an existing feature request, please give it a thumbs-up reaction, as we'll use these reactions to help prioritize the implementation of these features in the future.

• [x] provided a clear and concise description of the problem this proposed feature would address? For example, I struggle to do [...] with blogdown.

• [x] provided a clear and concise description of what you want to happen?

• [x] provided a clear and concise description of alternative solutions or workarounds you've considered?

• [x] added any other context or screenshots about your feature request?

[cderv]

It seems two more options can be useful to show in the overview:

• blogdown.new_bundle : is the site using Page Bundle by default for new post ?
• blogdown.author (and if null whoami::fullname() if whoami installed): default author name for new post

From: https://community.rstudio.com/t/blogdown-addin-newpost-no-longer-working-after-updating-from-r3-6-1-to-r4-0-3/90110

[yihui]

The checks have been disabled when starting up the site project, so users won't be baffled initially.

I've also pushed blogdown:::check_site() to the dev version. I haven't finished all the items you mentioned yet, but will try my best to finish them and document the functions before your talk tomorrow. Thanks!

[yihui]

All done now. A few messages need a little bit improvement. I'll do that tomorrow morning.