blogdown archetype (template)
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.
In a recent blog post I wrote about having a template for blogdown posts. I wanted to know if it was possible to do this and make my life (and others hopefully) easier for writing new blog posts that are ready to go with the features I frequently re-use.
In my case, I like using BiocStyle (Oleś, Morgan, and Huber, 2017) for functions such as CRANpkg(), Biocpkg() and Githubpkg(). I also like using knitcitations (Boettiger, 2017) for citing with citep() packages or papers; I use citation() and bib_metadata() to get the necessary information, respectively. Furthermore, I prefer devtools::session_info() (Wickham, Hester, and Chang, 2018) over sessionInfo() since it provides information of where you got the package, which becomes specially relevant when using packages from GitHub. Finally, I like thanking the creators of the tools I use, which in this case is blogdown (Xie, Hill, and Thomas, 2017).
I also like reminding myself how to do some common tasks. Basically, the equivalent of the new R Markdown file you get when using RStudio. In my case, I want to remind myself of the YAML options I frequently use (toc, fig height and width) or how to add screenshots.
My first post on this topic is actually rather messy. That’s because at that time:
- I didn’t know about hugo archetypes which are template files,
- I hadn’t even thought of making the Insert Image addin.
I went down the rabbit hole of archetypes and blogdown, reported an issue resulated to this topic that was in the way of using archetypes for .Rmd posts. After some encouragement by Yihui Xie, I ended up fixing this issues in my first pull request ever to an RStudio package. The PR also added the Archetype option to the New Post RStudio addin (which I used right now ^^).
Creating my blogdown archetype (template)
To make my archetype (template) for blog posts I looked at the GitHub repo for the theme I’m using. It contains an archetypes directory with several files. I just looked at the one called post.md (check it here) and copied it from themes/hugo-academic/archetypes/post.md to archetypes/post.md. Next I added my favorite R code below the last +++ mark. You can check out the final version here. Below I display the version at the time of writing this blog post (I’m using a .txt extension otherwise the embedded gist doesn’t look good, but you want it to end in .md).
| +++ | |
| title = "{{ replace .TranslationBaseName "-" " " | title }}" | |
| date = {{ .Date }} | |
| draft = false | |
| # Tags and categories | |
| # For example, use `tags = []` for no tags, or the form `tags = ["A Tag", "Another Tag"]` for one or more tags. | |
| tags = [] | |
| categories = [] | |
| # Featured image | |
| # Place your image in the `static/img/` folder and reference its filename below, e.g. `image = "example.jpg"`. | |
| # Use `caption` to display an image caption. | |
| # Markdown linking is allowed, e.g. `caption = "[Image credit](http://example.org)"`. | |
| # Set `preview` to `false` to disable the thumbnail in listings. | |
| [header] | |
| image = "" | |
| caption = "" | |
| preview = true | |
| +++ | |
| ```{r setup, echo = FALSE, message = FALSE, warning = FALSE} | |
| ## Load frequently used packages for blog posts | |
| library('knitcitations') # for citations | |
| library('BiocStyle') # for CRANpkg() Biocpkg() Githubpkg() | |
| library('devtools') # for session_info() | |
| ## Load knitcitations with a clean bibliography | |
| cleanbib() | |
| cite_options(hyperlink = 'to.doc', citation_format = 'text', style = 'html') | |
| bib <- c( | |
| 'BiocStyle' = citation('BiocStyle'), | |
| 'blogdown' = citation('blogdown')[2], | |
| 'devtools' = citation('devtools'), | |
| 'knitcitations' = citation('knitcitations') | |
| ) | |
| ``` | |
| ### Post content | |
| Typical location to start editing since the bibliography chunk is hidden. Make sure that you selected `R Markdown (.Rmd)` as the _format_ option of the post when using the `New Post` `r CRANpkg('blogdown')` addin. | |
| ### R image | |
| ```{r 'plot', echo = TRUE, fig.width = 6, fig.height = 6, eval = FALSE} | |
| ## This imaged will be saved in the /post/*_files/ directory | |
| ## Use echo = FALSE if you want to hide the code for making the plot | |
| plot(1:10, 10:1) | |
| ``` | |
| If you prefer not to use the `fig.width` and `fig.height` options in every plot chunk, edit the YAML (the part at the top of the post) with: | |
| ``` | |
| output: | |
| blogdown::html_page: | |
| toc: no | |
| fig_width: 5 | |
| fig_height: 5 | |
| ``` | |
| The spaces are important. | |
| ### Custom image | |
| The easiest option is to use the `r CRANpkg('blogdown')` _Insert Image_ RStudio addin to add an external image described in this [blog post](http://lcolladotor.github.io/2018/03/07/blogdown-insert-image-addin). You need to use version 0.5.7 or newer to have access to this plugin. | |
| If you want to add images manually, check this [blog post](http://lcolladotor.github.io/2018/02/17/r-markdown-blog-template/#.WqChJZPwa50) for more details on the image syntax. | |
| ### Acknowledgements | |
| This blog post was made possible thanks to: | |
| * `r Biocpkg('BiocStyle')` `r citep(bib[['BiocStyle']])` | |
| * `r CRANpkg('blogdown')` `r citep(bib[['blogdown']])` | |
| * `r CRANpkg('devtools')` `r citep(bib[['devtools']])` | |
| * `r CRANpkg('knitcitations')` `r citep(bib[['knitcitations']])` | |
| ### References | |
| ```{r bibliography, results = 'asis', echo = FALSE, cache = FALSE} | |
| ## Print bibliography | |
| bibliography(style = 'html') | |
| ``` | |
| ### Reproducibility | |
| ```{r reproducibility, echo = FALSE} | |
| ## Reproducibility info | |
| options(width = 120) | |
| session_info() | |
| ``` |
I couldn’t get the archetype to respect some of the YAML that blogdown adds, but well, that’s a single copy-paste I have to do now (if I actually decide to use the custom YAML options which are only for .Rmd posts).
I encourage you to make your own blogdown archetype (template). At least it should remind you to include reproducibility information which matters whenever any R code is involved.
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)
Yihui Xie also talked about my first PR in his blog.
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.