The challenge of using vignettes/ as a blog

[maurolepore]

Now we use the tab News of r2dii's website as a blog. We use it for example to make announcements that depend on a specific version of a package (example). This comes with an unanticipated challenge.

Here I explain the problem, my solution, and I open the discussion in search for a better alternative -- maybe bite the bullet and build a blog then link it from r2dii packages.

The problem is that the announced package may change in a way that changes the output of the announcement, or brakes it. This is not a problem when using vignettes/ for its intended purpose -- you usually want a vignette (or pkgdown article) to reflect the latest state of the package. Instead we use vignettes/ in a mixed way, sometimes for its intended purpose and sometimes as a blog where an article should reflect not the latest state but a state at the time we wrote the article.

The solution I found for now is to build the website at master in docs/, add docs/ to the git repository, and remote the source from vignettes/*.Rmd. We can always explore find the source by noticing the file name from the website then searching the log. For example, this article points to the file vignettes/r2dii-data-0-0-3.Rmd, which no longer exists but can be found with

git log -- vignettes/r2dii-data-0-0-3.Rmd

--

FYI @jdhoffa

[jdhoffa]

If I understand this correctly, the problem:

• We want old blog posts to faithfully reflect the state of the package at the time the post is written
• By default, using vignettes as we do will knit the .Rmd using the latest installation of the package?

I like your idea to link to older versions of the package by git ref, but it also seems to be a lot of overhead to solve this problem.

Is there a way to specify the package version directly in the vignette.Rmd preamble? ie.

require(devtools)
install_version("r2dii.match", version = "0.0.3", repos = "http://cran.us.r-project.org")

and ensure that this links to the correct package version?

Since most (actually all) blog posts should correlate to a specific CRAN release, we should always be able to revert to a state that faithfully reflects the state of that package at the time of the post, and I think there is less chance for errors using this method (if possible). (We can define a default blog vignette format, and ensure that the preamble is required, also that the version numbers are consistent)

[maurolepore]

Thanks a lot for your thoughts. You really help me articularte the problem, brainstorm solutions and clarify my ideas.

--

Yes, you understand the problem correctly.

My solution, however, is simpler than you think. The blog is "frozen" because the .html file that you read online won't be overwritten by its source .Rmd because I removed the source .Rmd. Git plays no role other than allowing you to travel the commit history back to recover the original .Rmd -- should you ever need to do so, which is unlikely.

Your idea is clever, but I see two problems:

1. It scales up poorly. Imagine we have 100 announcements. Each announcement will install its own version of a package during the process triggered by pkgdown::biuld_site(). It could take too long.
2. It seems error prone. Installations fail too often and might leave the developer's system in bad shape.

These problems could be mitigated by renv but still seems like too hacky and more complex than maintaining a blog with no hacks.

Last time I experimented with blogdown I experienced some friction. I hope that got better. What was you experience in building your personal site? Was it smooth? Is that tool something you would trust to "put in production"?

[jdhoffa]

Understood and agreed, my solutions scales poorly and introduces chance for error. Let me see if I understand yours again by describing an example:

1. We release r2dii 0.0.1 on CRAN
2. The following commit, we write a blog vignette, illustrating examples of the package by writing an .Rmd and using pkgdown to generate the static .html (in docs/)
3. We manually move this docs/ folder to the git repo and delete the source .Rmd
4. We update r2dii 0.0.2 on CRAN
5. Write a .Rmd, build site using pkgdown and then manually add the "new" .html files to the ./docs/? or manually add the "old" .html files to the newly generated docs/ and then add that to the git repo?

Because as I understand it, if we generate a "new" docs/ folder, after deleting the old .Rmd files, we will have to somehow manually include those corresponding .html files?

--

As for my website, I use jekyll (built on ruby) which is more or less the standard for all simple .github.io pages. I haven't tried rendering any R code or anything like this, but it is a relatively simple infrastructure for a static blog.

[jdhoffa]

To directly answer your question, I would absolutely trust putting it in production, many already have! Example jekyll blog in production

Spotify, netflix, etc. also build sites off of jekyll

[maurolepore]

Following a call on slack we decided to build the announcements as "reprexes". The workflow looks like this (example):

* [ ] `use_article("r2dii.match-0-0-3.Rmd")` to add the article's yaml header and setup chunk.
* [ ] Write the article.
* [ ] `rmarkdown::render("vignettes/r2dii.match-0-0-3.Rmd", "md_document")`
* [ ] Commit
* [ ] In the .Rmd file, replace the source with the output from the .md file. 
* [ ] Remove the .md
* [ ] Ensure the article is added to buildignore and R CMD check passes.
* [ ] Link the article to News in _pkgdown.yml, e.g.:

• text: "News" menu:
  • text: "Release notes"
  • text: "r2dii.data 0.0.3" href: articles/r2dii-data-0-0-3.html