-
Notifications
You must be signed in to change notification settings - Fork 1
Posts
In this section we provide guidelines for people interested in writing a blog post.
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.
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.
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 madepublic
, 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 theurl
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 ourr-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,
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.
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.
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 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:
- adding a DOI in
dois.csv
, - adding a package name directly in
createRefList.R
, - 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 ifpkg = ""
); -
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
.
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:
-
the post is rebuilt one more time with
.Rmarkdown
, so that a.markdown
file is generated (see this explanation for further details); -
the
.Rmarkdown
should be moved tostatic/oldsouce
and the extension should be switched to.Rmarkdown.origin
to avoidblogdown
attempts to build the post; -
the YAML header of the
.markdown
should includearchived: YYYY-MM-DD
so that a badge could be added to indicate when the post was archived. Note that as we add asessionInfo()
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.