[This article was first published on rOpenSci - open tools for open science, and kindly contributed to R-bloggers]. (You can report issue about the content on this page here)
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

Whilst working on the blog guide, Stefanie Butland and I consolidated knowledge we had already gained, but it was also the opportunity to up our Rmd/Hugo technical game. Our website uses Hugo but not blogdown1 to render posts: every post is based on an .md file that is either written directly or knit from an .Rmd file. We wanted to provide clear guidance for both options, and to stick to the well-documented Hugo way of e.g. inserting figures. We also wanted to provide post contributors with an as smooth as possible workflow to create a new post. Working on this mission, unsurprisingly we learned a lot, and why not share our newly acquired technical know-how? In this post I shall go through four things we learned about Rmd/Hugo, while trying to provide context about the why of our using them.

### knitr hooks

Problem: Hugo has a nice figure shortcode with options such as width. How do we make R Markdown output these shortcodes from a code chunk, instead of the usual figure syntax? I.e. how to get2

{{< figure src="chunkname-1.png” alt="alternative text please make it informative” caption="this is what this image shows, write it here or in the paragraph after the image as you prefer” width="300” >}}

not

![alternative text please make it informative ](chunkname-1.png)

to appear – as the result of a chunk producing a figure – in the .md after knitting the .Rmd?

I asked this question in the friendly French-speaking R Slack workspace3 and got an answer from both Romain Lesur and Christophe Dervieux: the solution was to use a knitr plot hook!

knitr hooks are “Customizable functions to run before / after a code chunk, tweak the output, and manipulate chunk options”.

In the setup chunk4 of the .Rmd file, there should be this code

knitr::knit_hooks$set( plot = function(x, options) { hugoopts <- options$hugoopts
paste0(
"{", "{}}\n"
)
}
)


that reads options from the chunk, and uses options from the hugoopts named list if it exists.

The chunk

{r chunkname, hugoopts=list(alt="alternative text please make it informative", caption="this is what this image shows, write it here or in the paragraph after the image as you prefer", width=300)}
plot(1:10)



produces

{{< figure src="chunkname-1.png” alt="alternative text please make it informative” caption="this is what this image shows, write it here or in the paragraph after the image as you prefer” width="300” >}}

in the .md file which is what we wanted.

Now, a bit later in our website journey, I had a quite similar question: Hugo has nice highlighting options for code fences. How to make R Markdown show R source code with such options? This time there was no need to ask anyone, searching the internet for the name of the right knitr hook was enough: our .Rmd has to feature a knitr source hook. More on that highlighting chapter another time, but in the meantime refer to our standard .Rmd.

Note that when writing a .md post instead of knitting an .Rmd file, authors can use Hugo syntax directly. And when adding figures in an .Rmd file that come from say a stock photos website rather than a code chunk, authors can also use Hugo syntax, granted they write the shortcode between html_preserve markers, see below the lines I used to add the crochet hook picture in the .Rmd producing this post.

{{< figure src ="person-holding-purple-crochet-hook-and-white-yarn-3945638.jpg” alt = “Person holding a purple crochet hook and white yarn” link = “https://www.pexels.com/photo/person-holding-purple-crochet-hook-and-white-yarn-3945638/” caption = “Castorly Stock on Pexels” width = “300” class = “center” >}}

### “One post = one folder”: Hugo leaf bundles

Problem: Our advice to contributors including ourselves was to add their post under content/ but its images under themes/ropensci/static/img/ which is… not smooth. How do we change that?

Thanks to Alison Hill’s blog post about page bundles I learned you can use a folder to add both a post and its related images to a Hugo website. What an improvement over adding the post in one place, the images in another place like we used to! It’s much smoother to explain to new contributors5. In Hugo speak, each post source is a leaf bundle.

We did not have to “convert” old posts since both systems can peacefully coexist.

Below is the directory tree of this very tech note, added as a leaf bundle.

/home/maelle/Documents/ropensci/roweb2/content/technotes/2020-04-23-rmd-learnings
├── index.Rmd
├── index.md
├── orange-mug-near-macbook-3219546.jpg
├── person-holding-purple-crochet-hook-and-white-yarn-3945638.jpg
└── richard-dykes-SPuHHjbSso8-unsplash.jpg




### Conclusion

In this post I reported on a few things our website work taught us about R Markdown (knitr hooks), Hugo (ignoreFiles, leaf bundles, archetypes) and blogdown (New Post Addin). We’re still learning important concepts and tricks thanks to new questions by blog authors and to updates in the ecosystem8, we shall keep publishing such posts, stay tuned if that’s your jam!

1. But as you’ll see later we actually take advantage of that cool package: we recommend using blogdown’s New Post Addin; and we also mention blogdown::install_hugo() in the blog guide. ↩︎

2. Yes you can escape Hugo shortcodes in your site content! ↩︎

4. I recently asked and received references to define the setup chunk. ↩︎

5. I can also credit this smoother workflow for making me like adding more images, hence the stock pictures in this post! ↩︎

6. At the time of writing blogdown 1.18.1 has to be installed from GitHub via remotes::install_github("rstudio/blogdown"). ↩︎

7. I actually wrote a post around maintaining Hugo websites in my personal blog. ↩︎

R-bloggers.com offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.