This chapter explains the technical details of submitting a blog post or tech note (referred to collectively as “posts”) for publication on the rOpenSci website - from drafting in an (R) Markdown template, to submitting for review using GitHub Pull Request infrastructure.
We include advice on commonly used elements like adding an image, a citation, or embedding a social media post in case you need them.
Briefly, the process is:
This chapter links to templates for posts and checklists that you can also find in the Appendix.
roweb3 repositoryFork the rOpenSci website repository and create a new branch to work on your post. For help with this aspect of git/GitHub, we recommend happygitwithr and the pull request helpers of the usethis package.
If you plan to use R Markdown to write your post (using index.Rmd as opposed to directly writing it in Markdown with index.md and not executing any code), please install or update blogdown.
install.packages("blogdown")Start your post from a template. If you use RStudio, refer to the instructions to create your draft with blogdown’s New Post Addin. If not, refer to the instructions to create your draft manually.
The blogdown New Post RStudio addin creates the post draft in the correct location and fills the post YAML based on metadata you’ll have entered.1
whoami and blogdown (install.packages(c("whoami", "blogdown"))) (blogdown version should be at least 1.6.0).blogdown::install_hugo("0.133.0") (version recorded in netlify.toml of the roweb3 repository).roweb3 project.blogdown:::new_post_addin().
whoami wasn’t able to guess it.Create a folder YYYY-MM-DD-slug/ (e.g. 2020-01-20-rorcid/) under /content/blog/ Your post source and its images should live in /content/blog/YYYY-MM-DD-slug/.2
R Markdown template is to be saved as /content/blog/YYYY-MM-DD-slug/index.Rmd. It will need to be knit (RStudio knit button, or blogdown::build_site(build_rmd = <path_to_file>)). Add both index.Rmd and index.mdto your PR.
Quarto template is to be saved as /content/blog/YYYY-MM-DD-slug/index.qmd. It will need to be rendered. Add both index.qmd and index.mdto your PR.
Markdown template is to be saved as /content/blog/YYYY-MM-DD-slug/index.md.
The YAML sets the metadata for a post. This is the YAML from our post template, with comments to explain some components.
Note: The New Post Addin automatically creates a
categoriescomponent, but you should ignore or remove this and usetagsinstead.
slug: post-template
title: Post Title in Title Case
package_version: 0.1.0
author:
- Author Name1
- Author Name2
date: '2020-03-10'
tags:
- Software Peer Review
- packages
- R
- community
description: A very short summary of your post (~ 100 characters)
socialImg: blog/2019/06/04/post-template/name-of-image.png
socialAlt: Alternative description of the image
social: A post about blabla by @[email protected]!
editor: ~If you need to add an alert box at the beginning of the post, use the preface field with the Markdown syntax. See for instance this post with a preface about a series of post (source)
preface: "some alert"Images can either be external or created in rmarkdown. Regardless of how images are included, they should all contain alt text and consider the following features.
Alt text
Every image should be accompanied by alternative text to make it more accessible and provide a better user experience. The alternative text should convey the meaning or content that is displayed in the image. Refer to this tutorial for details on what should go in alternative text, and see the following sections for how to include alt text.
If you include a picture with text (like a comment on a post or a phrase on a wall), include the text you want to highlight from that image in the alt-text.
Image features
This section refers to images that are not generated from R Markdown. If you want to generate images from R Markdown use our R Markdown template and see next subsection.
File location
All images go in the same folder as your post source (/content/blog/YYYY-MM-DD-slug/) (do not link to external services like imgur). To reference them in your post, use name-of-image.png.
Insert an image
figure or imgtxt short codes
alt = to specify alt text
{{< figure src = "image-name.png" alt = "informative description" >}}{{< imgtxt src = "image-name.png" alt = "informative description">}}
Text to right
{{< /imgtxt >}}Image placement
Basic positioning with {{< figure >}} and class
{{< figure src = "image-name.png" alt = "informative description" class = "center" >}}
pull-left - Left-align the picture and wrap text around itcenter - Center the picture (no text wrapping)pull-right - Right-align the picture and wrap text around it
Specific text next to image with {{< imgtxt >}}
{{< imgtxt src = "image-name.png">}} Text to right {{</ imgtxt >}} Text below
{{< imgtxt >}} and {{</ imgtxt >}} is to the right of the figure
Other details
Control image size with width{{< figure src = "image-name.png" width = "400" alt = "informative description">}}
Make the image a hyperlink with link{{< figure src = "image-name.png" alt = "informative description" link = "http://hyperlink">}}
Important! In R Markdown (i.e. in *.Rmd files but NOT *.md files), these Hugo shortcodes need to be escaped:
<!--html_preserve-->{{}}<!--/html_preserve-->
File location
When using our R Markdown template the knitr hook in the setup chunk actually creates the necessary Hugo shortcodes. Therefore you don’t need to worry about paths.
Image details
In the chunk producing a figure, use the hugoopts chunk option to control the alt text and other elements. hugoopts is a named list that can have all elements described in the documentation of the Hugo figure shortcode except for title.
```{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)
```This chunk above produces a figure with “alternative text please make it informative” as alternative text, “title of the image” as title, “this is what this image shows, write it here or in the paragraph after the image as you prefer” as caption, and a width of 300 pixels.
To add citations, refer to them in the body of your post as footnotes:
Citation of the primary literature[^1].
Citation of an R package[^2].
Citation of a website[^3].And list your sources at the bottom of your post:
[^1]: Sciaini, M., Fritsch, M., Scherer, C., & Simpkins, C. E. (2018). NLMR and landscapetools: An integrated environment for simulating and modifying neutral landscape models in R. Methods in Ecology and Evolution, 9(11), 2240-2248. <https://doi.org/10.1111/2041-210X.13076>
[^2]: Elin Waring, Michael Quinn, Amelia McNamara, Eduardo Arino de la Rubia, Hao Zhu and Shannon Ellis (2019). skimr: Compact and Flexible Summaries of Data. R package version 2.0.2. https://CRAN.R-project.org/package=skimr
[^3]: Hugo static site generator. https://gohugo.io/To get the citation for an R package, run citation("packagename").
To get the citation for an article, you can use the RStudio Addin for rcrossref, or get the citation from a paper’s DOI by running e.g.
rcrossref::cr_cn("10.1111/2041-210X.13076", format="text", style="apa")
[1] "Sciaini, M., Fritsch, M., Scherer, C., & Simpkins, C. E. (2018). NLMRandlandscapetools: An integrated environment for simulating and modifying neutral landscape models inR. Methods in Ecology and Evolution, 9(11), 2240–2248. doi:10.1111/2041-210x.13076"To get the citation for an article in Google Scholar, find the article, click the quote symbol (in search results under the article) to open the “Cite” window, and copy the APA style text.
E.g. if you want to highlight a sentence from the post itself.
Block quotes are paragraphs starting with >.
If you want to have them right-align add {.blockquote .text-right} right after the paragraph e.g.
> blabla
blabla
blabla
{.blockquote .text-right}If you want to have them centered add {.blockquote .text-center} right after the paragraph e.g.
> blabla
blabla
blabla
{.blockquote .text-center}If you want to add a block quote with an author name, use:
{{< quote footer="Author Name">}}
Blablablabla
{{< /quote >}}If you want to add a block quote with an author name and a source, use:
{{< quote footer="Author Name" cite="[good book](url)">}}
Blablablabla
{{< /quote >}}If you want to center the block quote add the align variable:
{{< quote footer="Author Name" cite="[good book](url)" align="center">}}
Blablablabla
{{< /quote >}}If you want to right-align the block quote add the align variable:
{{< quote footer="Author Name" cite="[good book](url)" align="right">}}
Blablablabla
{{< /quote >}}Note that this syntax also work for quotes without attribution!
{{< quote align="center">}}
Blablablabla
{{< /quote >}}If you want to use e.g. striped tables, add {.table .table-responsive .table-striped} right after the last line of the table.
Header | Other Header | Another Header
---------|----------------|-------------------
Value 11 | Value 12 | Value 13
Value 21 | Value 22 | Value 23
Value 31 | Value 32 | Value 33
{.table .table-responsive .table-striped}Comparing the raw Markdown to the live posts in these examples might be helpful.
A blog post about a package that has passed software peer review. Compare raw markdown with the live post.
A tech note. Compare raw markdown with the live tech note.
Please discuss your post’s language with blog editors!
index.md.index.<two-letter-language-code>.md, for instance index.es.md. Translate tags, title, description too.index.md file and only use the index.XX.md file using the appropriate language code (e.g., index.es.md for a Spanish-only post).content/author/author-name/_index.<two-letter-language-code>.md even if it only duplicates content/author/author-name/_index.md./blog/ instead of https://ropensci.org/blog/.DT, leaflet, etc.), include a screenshot and use the link option of the Hugo figure shortcode to direct readers to an online version of the widget.If using the R Markdown template, knitting index.Rmd (RStudio knit button, or blogdown::build_site(build_rmd = <path_to_file>)) will generate index.md. Commit both index.Rmd and index.md.
roblog
You can use functions in the roblog package to do some automated checks on your post.
ro_lint_md() to check and enforce use of complete alternative descriptions for image, of relative links to rOpenSci website, of Hugo shortcodes.ro_check_urls() to check for URLs that might be brokenPick the appropriate checklist for your post and ensure you checked everything off. Notice the copy-paste button at the top-right corner of the list.
* [ ] I have read the Content Guidelines.
* [ ] I have read the Technical Guidelines.
* [ ] I used or followed the R Markdown or Markdown template.
* [ ] I have followed the Style Guide.
* [ ] I created or updated my author metadata with correct folder name.
* [ ] I have added relevant tags after browsing existing tags (including "community" tag).
* [ ] I have added the "tech notes" tag if this is a technote.
* [ ] I ran `roblog::ro_lint_md()` on index.md (optional).
* [ ] I ran `roblog::ro_check_urls()` on index.md (optional).
* [ ] I ran a spell-check on index.md.
* [ ] I have added the tags - Software Peer Review, my-packagename.
* [ ] I have added the package-version YAML tag.
* [ ] I have added acknowledgement of the reviewers' work (with links to reviewers).
* [ ] I have added a link to the software peer review thread.* [ ] I have read the Content Guidelines.
* [ ] I have read the Technical Guidelines.
* [ ] I used or followed the R Markdown or Markdown template.
* [ ] I have followed the Style Guide.
* [ ] I created or updated my author metadata with correct folder name.
* [ ] I have added relevant tags after browsing existing tags (including "community" tag).
* [ ] I have added the "tech notes" tag if this is a technote.
* [ ] I ran `roblog::ro_lint_md()` on index.md (optional).
* [ ] I ran `roblog::ro_check_urls()` on index.md (optional).
* [ ] I ran a spell-check on index.md.If you wish to preview your post locally, as it will appear in our site, you must install Hugo. To install, refer to Hugo docs or run blogdown::install_hugo() using the version recorded in netlify.toml.
Note: You can also preview your blog post online through the pull request before the final submission.
Then run hugo serve or blogdown::serve_site() in the repo directory to start a local server on http://localhost:1313 (or another one indicated by blogdown).
Note: If you are used to using hugodown you can use it instead to serve the website.
The version of Hugo used by the rOpenSci web server is defined in netlify.toml.
When this preview looks good to you, you should submit your post as a pull request.
Open a draft pull request (PR) from your fork (using the web interface, see step 8 for creating a draft), or usethis::pr_push() that will save you some work and that will in the end open the same web interface where you can choose Draft PR in the last step)
If you opened a PR instead of a draft PR, you can convert it to a draft by clicking on “Still in progress? Convert to draft” on the right panel under “Reviewers”.
In the first comment of your pull request submitting a post, please copy-paste the checklist corresponding to your post and check off the items.
From the PR, Netlify will start building the new version of the site within seconds and you can preview your changes to make sure everything looks as intended. Otherwise push additional fixes till things look right.
If you don’t use RStudio you can still use the addin, but the new post will be opened in the editor returned by getOption("editor"), that you might need to configure.↩︎
In Hugo speak, we’d say your post is a leaf bundle.↩︎
3.5.1.2 Social media metadata (optional)
Delete
description,socialImgandsocialAltYAML fields if you don’t use them.