Skip to content

Posts

Jump to bottom
Kevin Cazelles edited this page Jul 17, 2023 · 12 revisions

In this section we provide guidelines for people interested in writing a blog post.

Subject matter

The blog is geared towards computational ecology at large. This means that it can be directly related to computational ecology, but does not have to be explicitly expanding on the subject. For example, it may also deal with ecology, your experience as an ecologist and computational tools. It may include code, but it may also be an opinion piece or even a short concise literature review on a specific subject you may wish to expand on.

How to create and add a new post

File format

A new post is a Markdown or an R Markdown file added in the content/post/current_year folder. Importantly enough, blogdown offers two main ways to render R Markdown files (see https://bookdown.org/yihui/blogdown/output-format.html). Our posts should use the chroma' syntax highlighting with (set in static/css/syntax.css) and thus, .Rmarkdown and .markdown file extensions should be used (unless specific features not supported by Goldmark are required).

There are no limitation in terms of number of character per post. We should however be aware that readers rarely (if ever) spend hours reading the same post. The table of content is generated using the Hugo built-in .TableOfContents and only records title of level 2. Level 1 should be used only for the title of the posts.

YAML front matter

The author of the post must take advantage of the yaml front matter to edit the meta-data associated with his post. Below is a description of the different fields to be used.

  • author: who wrote the post (a single author or a list of co-authors);
  • date: when the post was written (YYYY-MM-DD format);
  • draft: if true the post will not be made public, i.e. not available on the online version of the website; the post will however be rendered locally and a badge "underDevelopment" will be added;
  • edits: a list of maps of two elements: date and comment that are used to describe edits on the post;
  • estime: estimate of the reading time;
  • layout: which layout must be used; note the default layout is the one required for posts;
  • license: by default, content is licensed under CC-BY-4.0, if you need another license, please specify its name in the sub-field name and a link to the description of the license under the url sub-field. If you are fine with CC-BY-4.0, do not add this field!
  • output: rmarkdown options;
  • review: if true a badge will be added to indicate that the post is under review. Posts may also be public (author's choice);
  • reviewer: reviewer(s) of the post;
  • tags: keywords used to index posts the author(s) should carefully select the tags associated to their post , so the reader easily access posts with similar content.
  • title: title of the blog post;
  • rbloggers: if true then the post will be added to our r-bloggers/index.xml rss flux, shared on r-bloggers and a badge will be added;
  • tweet: text associated with the tweet button.

Given the kind of posts found of the blog (that could be tricky), the estimated time to read the post (estime) should better be estimated roughly by ourselves. 300 words read per minute for a post that is not too complex. Also, the author(s) of the post should take the time to read the code, figures, etc. Finally,

Writing guidelines

Adding build environment information

In order to make your post as reproducible as possible, it is important to add information pertaining to the build environment. At the end of a post about R, we strongly encourage to include your session info. We have a specific script that does so and included in the archetype post.Rmarkdown, the following code chunk ne copy

```{R sessionInfo, child = path_session_info}
```

This is actually mandatory for posts that are archived and thus no longer build by Travis CI.

Images, figures, video

Format

Figures can use any formats (see https://bookdown.org/yihui/rmarkdown-cookbook/graphical-device.html) PNG and SVG are however preferred. For SVG, dev:svg must be avoided and dev:svglite should be used instead (see https://stackoverflow.com/questions/50767445/how-to-fix-failed-to-load-cairo-dll-in-r).

For videos, either Advanced Video Coding or WebM are recommended.

Shortcodes

Hugo shortcodes simplify the addition of chunk of HTML, this is very useful to add images, video, etc. We have custom shortcodes to add image (see layouts/shortcodes/imgcenter.html) and figures (see layouts/shortcodes/figcenter.html), both centered. A figure is an image with a caption.

Centered images are added like so

{{< imgcenter "path/myfig.png" 90 >}}

90 will be used as a percentage of the width, so the image width will be 90% of the parent element. There is an extra argument for centered figures:

{{< figcenter "path/myfig.png" "The caption to be added below the image." 90 >}}

Alternatively, if you are using R Markdown, use knitr::include_graphics("path/file.png"), and the chunk option fig.wdith to adjust the width of the figure and fig.cap to add a caption (see https://yihui.org/knitr/options/):

```{R myfig, fig.width}
knitr::include_graphics("path/myfig.png")
```

Hugo natively includes shortcodes to embed videos hosted on vimeo and youtube.

Citations and reference list

Citations are handled in R Markdown files (see https://bookdown.org/yihui/rmarkdown-cookbook/bibliography.html) but not in Markdown files. You can use your own bib file for your post, or you can use the common reference management system that has been set up for the blog.

The common reference list is a .bib file: ~/data/bib/inSileco.bib. inSileco.bib that is built via the following script: static/ref/createRefList.R that can be executed with using the makefile (should work on Linux and MacOS):

make biblio

There are three ways to add a reference to the reference list:

  1. adding a DOI in dois.csv,
  2. adding a package name directly in createRefList.R,
  3. adding a bib entry directly in inSileco_nodoi.bib

Once the reference has been added, to use is, you can use the following fields in the yaml front-matter:

bibliography: "`r path_ref_bib`"
csl: "`r path_ref_csl`"
link-citations: yes

Note that by default the references will be appended at the end of your post, and we recommend using a header # References at the end of the post. In some cases, you might want to decide where the reference list should be placed. To do so, use the following tag where the list should be added:

<div id="refs"></div>

Also, three helper functions to add links to R packages are available:

  • url_cran("pkg"): add the canonical link to the CRAN main page of "pkg" (or the main page of the CRAN if pkg = "");
  • url_bioc(): similar function, but for Bioconductor packages;
  • url_gh(): similar function, but for GitHub repositories;

These functions are available in our inSilecoRef package that is loaded in .Rprofile and thus available for all posts. These functions can also be used in inline code. For instance, `r url_cran("ps")` will add the link to the CRAN for the package ps.

Archiving a post

There are posts that are heavy, either because it is computationally-intensive (e.g. benchmarks, data retrieval) or because of its dependency tree. After a while it may be better to avoid re-building such posts. In this case, the post should be archived, which simply means the post is no longer rebuilt on deployment and therefore the code is no longer been checked for newer released of packages. This is also a strategy that should be adopted when a post cannot be build on a newer R version.

The process to archive a post is as follows:

  1. the post is rebuilt one more time with .Rmarkdown, so that a .markdown file is generated (see this explanation for further details);

  2. the .Rmarkdown should be moved to static/oldsouce and the extension should be switched to .Rmarkdown.origin to avoid blogdown attempts to build the post;

  3. the YAML header of the .markdown should include archived: YYYY-MM-DD so that a badge could be added to indicate when the post was archived. Note that as we add a sessionInfo() at the end of all posts, the reader will always be able to check the versions of R and packages that were used to generate the post.

Clone this wiki locally