Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.
Have you ever tried inserting an image into a blogdown post? Maybe you have, or maybe you tried and gave up. Lets first review the hard way before getting to the solution I contributed.
The hard way
The process involves copying the target image to the static directory that corresponds to the blogdown post. Lets say that your post is called 2018-03-07-my-new-post.Rmd and lives at content/post/, so it’s full path is content/post/2018-03-07-my-new-post.Rmd. When you run the RStudio blogdown addin Serve Site, behind curtains the directory static/post/2018-03-07-my-new-post_files is created and inside it you can find the images made by your R code: likely at static/post/2018-03-07-my-new-post_files/figure_html.
So far everything is working! But now you want to add a screenshot or some other image to your blog post. Lets say that your image is ~/Desktop/screenshot.jpg. Your ~/Desktop directory is not part of your blogdown directory and well, simply put, your website won’t find the image. We need to put it in a location that will be made public by hugo. That is, we need to put it inside static/post/2018-03-07-my-new-post_files (or anywhere inside static, but we like to keep things tidy!).
Ok, so we copy our screenshot file ~/Desktop/screenshot.jpg and save it as static/post/2018-03-07-my-new-post_files/screenshot.jpg. The next time we render our site and publish it, the figure will be available in the web. But it’s still not part of our blogdown post.
So we need to use either the Markdown or HTML syntax for adding the image. Maybe your initial thought is to use:
Except that will not work. We need to use almost all the path (just remove static) as shown below:
If you want to edit the height or width, then you need to use the HTML syntax. Something like:
<img alt = 'my new screenshot' width='200' src='/post/2018-03-07-my-new-post_files/screenshot.jpg' />
hard way notes
You could have also used knitr::include_graphics() and let blogdown copy it to the final location in static and link to it appropriately. However, you would have to keep your original images organized in a way that won’t bother hugo.
Another option that I used for a while, even in the days when my blog was based on Jekyll, is to render the figures yourself and copy the directory with the figures, plus mess around with how they are linked from R. Details here. Not something I recommend doing now.
Insert Image addin: aka, the easy way
If you are using blogdown, you most likely (you should if you can) are using RStudio and the great blogdown addins: New Post and Serve Site. I just recently started using them in the past few days and looking at the code I realized that it should be possible to make an addin that lets you:
- select a target image,
- copies the target image to the appropriate location under
static, - gives you the correct code for linking the image.
Yihui Xie loved the idea (I think it’s fair to say that ^^) and helped me polish it in the pull request that implements it. He then refined the code even more!
Features of the Insert Image addin
The final features, at least as implemented in blogdown version 0.5.7 are:
- Select an image from anywhere in your computer.
- Automatically generate a candidate final location for your image under
static, which you can edit. Useful if you want to rename the final figure. - Allow specifying the alternate description of the image (
alt), height and width. - If the target image file exists, a dynamic menu shows up that asks you whether to overwrite it or not.
- The final syntax is Markdown unless a width or height are used, in which case it uses HTML code.
Yihui Xie hinted at other possible future features, which maybe you can help implement.
Using the Insert Image addin
Step 1: install appropriate blogdown version
First of all, at the time of writing this post, you need the development version of blogdown. You can install it with:
## Check if you have version 0.5.7 or newer
## I actually used version 0.5.9 for this blog post
packageVersion('blogdown')
## If not, then get it!
##### If necessary:
## install.packages('devtools')
devtools::install_github('rstudio/blogdown')
You also need an up to date version of RStudio and I recommend also using R 3.4.x (or newer if you are reading this in the future). Re-start RStudio so it loads the new version of blogdown.
Step 2: open the Insert Image addin
Second, go to the Addins menu in the top section of the RStudio window and select the Insert Image blogdown addin.
Step 3: choose figure and inputs
So far the Insert Image addin looks like this:
So lets go head and select an image we want to upload. In my case, I chose an image that already exists.
You can rename the figure if you want, and if it doesn’t exist, the overwrite option goes away.
Step 4: hit done!
Lets go ahead and click done! Our text window in RStudio will insert the appropriate code for linking the image. In this case, it’s the following code:
<img src="/post/2018-03-07-blogdown-insert-image-addin_files/screenshot.png" alt="final image" width="400"/>
and this is the image:
Optional step 5
Now use the Serve Site addin and check if you like your images. You might want to change the height/widths or alternate text. You could also wrap the HTML/Markdown code around it for linking to a website.
You can also delete your original images, if for example, they are cluttering your ~/Desktop.
Conclusions
I hope that you will find this new addin as useful as I’m finding it, or even more. Plus hopefully this blog post gives you an idea of the difficulties before this addin existed. Also, I want to thank Yihui Xie for guiding me, I’ve learnt quite a bit recently. Though I will still use <- assignment operator for my own code hehe.
Acknowledgements
This blog post was made possible thanks to:
- BiocStyle (Oleś, Morgan, and Huber, 2017)
- blogdown (Xie, Hill, and Thomas, 2017)
- devtools (Wickham, Hester, and Chang, 2018)
- knitcitations (Boettiger, 2017)
as well as Yihui Xie’s help and encouragement in the form of a signed sticker and the Great Hacker title ^^. He also wrote a blog post about the Insert Image addin.
References
[1] C. Boettiger. knitcitations: Citations for ‘Knitr’ Markdown Files. R package version 1.0.8. 2017. URL: https://CRAN.R-project.org/package=knitcitations.
[2] A. Oleś, M. Morgan and W. Huber. BiocStyle: Standard styles for vignettes and other Bioconductor documents. R package version 2.6.1. 2017. URL: https://github.com/Bioconductor/BiocStyle.
[3] H. Wickham, J. Hester and W. Chang. devtools: Tools to Make Developing R Packages Easier. R package version 1.13.5. 2018. URL: https://CRAN.R-project.org/package=devtools.
[4] Y. Xie, A. P. Hill and A. Thomas. blogdown: Creating Websites with R Markdown. ISBN 978-0815363729. Boca Raton, Florida: Chapman and Hall/CRC, 2017. URL: https://github.com/rstudio/blogdown.
Reproducibility
## Session info ---------------------------------------------------------------------------------------------------------- ## setting value ## version R version 3.4.3 (2017-11-30) ## system x86_64, darwin15.6.0 ## ui X11 ## language (EN) ## collate en_US.UTF-8 ## tz America/New_York ## date 2018-03-10 ## Packages -------------------------------------------------------------------------------------------------------------- ## package * version date source ## backports 1.1.2 2017-12-13 CRAN (R 3.4.3) ## base * 3.4.3 2017-12-07 local ## bibtex 0.4.2 2017-06-30 CRAN (R 3.4.1) ## BiocStyle * 2.6.1 2017-11-30 Bioconductor ## blogdown 0.5.9 2018-03-08 Github (rstudio/blogdown@dc1f41c) ## bookdown 0.7 2018-02-18 cran (@0.7) ## colorout * 1.2-0 2018-02-19 Github (jalvesaq/colorout@2f01173) ## compiler 3.4.3 2017-12-07 local ## datasets * 3.4.3 2017-12-07 local ## devtools * 1.13.5 2018-02-18 CRAN (R 3.4.3) ## digest 0.6.15 2018-01-28 CRAN (R 3.4.3) ## evaluate 0.10.1 2017-06-24 CRAN (R 3.4.1) ## graphics * 3.4.3 2017-12-07 local ## grDevices * 3.4.3 2017-12-07 local ## htmltools 0.3.6 2017-04-28 CRAN (R 3.4.0) ## httr 1.3.1 2017-08-20 CRAN (R 3.4.1) ## jsonlite 1.5 2017-06-01 CRAN (R 3.4.0) ## knitcitations * 1.0.8 2017-07-04 CRAN (R 3.4.1) ## knitr 1.20 2018-02-20 cran (@1.20) ## lubridate 1.7.3 2018-02-27 CRAN (R 3.4.3) ## magrittr 1.5 2014-11-22 CRAN (R 3.4.0) ## memoise 1.1.0 2017-04-21 CRAN (R 3.4.0) ## methods * 3.4.3 2017-12-07 local ## plyr 1.8.4 2016-06-08 CRAN (R 3.4.0) ## R6 2.2.2 2017-06-17 CRAN (R 3.4.0) ## Rcpp 0.12.15 2018-01-20 CRAN (R 3.4.3) ## RefManageR 0.14.20 2017-08-17 CRAN (R 3.4.1) ## rmarkdown 1.9 2018-03-01 cran (@1.9) ## rprojroot 1.3-2 2018-01-03 CRAN (R 3.4.3) ## stats * 3.4.3 2017-12-07 local ## stringi 1.1.6 2017-11-17 CRAN (R 3.4.2) ## stringr 1.3.0 2018-02-19 cran (@1.3.0) ## tools 3.4.3 2017-12-07 local ## utils * 3.4.3 2017-12-07 local ## withr 2.1.1 2017-12-19 CRAN (R 3.4.3) ## xfun 0.1 2018-01-22 CRAN (R 3.4.3) ## xml2 1.2.0 2018-01-24 CRAN (R 3.4.3) ## yaml 2.1.17 2018-02-27 cran (@2.1.17)
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.