Introduction

As mentioned in a previous post, it is important for an academic researcher or scientist to have an online presence and especially to share their research works and achievements with global audience. On simple solution is to use academic social networks and scholarly literature databases, such as Orcid, Clarivate (web-of-science), Google Scholar, Scopus, Academia, ResearchGate… However, it may be preferable to share one’s contributions on one’s own website.
I create my website using Quarto (see the history page). If you don’t have a Quarto website, you can find many blogs that explain how to create a blog or personal website with Quarto. This guide is for anyone interested in learning how to create a references page like mine.

A previous post shows how to use Quarto listing to create a publication list. This method is “quite” simple, but may be tedious if you have a lot of publications.

Another simple solution, is to use Pandoc to render citations with citeproc ¹. Put all references in a bibliographic data file (e.g., a .bib file), and to include nocite in the metadata front end, and add div block with id refs in your references documents.
One disadvantage of this approach is that the references are not clearly distinguished or organized.

Problem statement

Most editors only support BibTeX (regretfully), but I want the reference manager to support BibLaTeX.
I want to organize the references in different categories.
Render formatted references in Markdown or in HTML (body only).
Manage the bibliography entries style and rendering.

There are many methods for managing bibliography references, particularly if you already use BibLaTeX or BibTeX. In particular, Quarto is a multi-language program that can use Knitr to run R code (such as with R-markdown) and also supports Python, Juia and Observable JS code blocks. I initially used R-markdown when writing my HDR, so I sought a solution with R code and discovered the RefManageR package. With this package, I manage my references page.

Note

Quarto supports Python code blocks, and there are many BibTeX Python parsers out there. I will investigate this solution later. For more information, see the blog of Marcel Bollmann.

Parsing Bib(La)TeX with RefManageR

RefManageR provides tools for importing and working with bibliographic references. It can load BibTeX and BibLaTeX .bib files, and even connect to NCBI, CrossRef, and Zotero to import references.

Once a .bib file is create or imported, it is then straightforward to import them in a R code:

if(!require(RefManageR))
  remotes::install_github("ropensci/RefManageR") 

RefManageR::BibOptions(check.entries = FALSE, 
                       style = "markdown",
                       bib.style = "numeric",
                       sorting = "ydnt",
                       max.names=99)
bib <- RefManageR::ReadBib("references.bib", .Encoding = "UTF-8", 
                           check = 'warn')

1: The printing style here set to markdown.
2: Specifying BibLaTeX style to use for formatting references.
3: Set references sorting.

bib contains all entries of the .bib files, and with a print(bib) all entries are printed (here in markdown style ). It is quite easy to separate the bibliography entries, for example:

# All Article entries type
bibArticle <- bib[bibtype="Article"] 
# All InProceeding entries of the year 2022
bibInProceeding2022 <- bib[c(bibtype="InProceeding", year=2022)]

and the include print(bibArticle), print(bibInProceeding2022) properly in your references document, such as:

## Articles

```{r bibArticle}
#| results: asis
#| echo: false
print(bibArticle)
```

Tip

It is worth noting that it is possible to update certain statistical data on references in a dynamic manner.

Example 1 To illustrate, the following sentence will be updated dynamically (i.e. each time you update your .bib files and render your website)

My scientific activities have led to  `{r} length(bib)` publications
including `{r} length(bibArticle)` articles.

Bibliography style

RefManager offers five natives bibliography styles : numeric, authoryear, authortitle, alphabetic and draft. These options may be suitable for those seeking a basic bibliography style. However, if a specific style is desired, it may be somewhat cumbersome to get it with RefManager.

Custom bibliography style

To create a custom bibliography style, with RefManager, use the bibstyle function from the tools package (native in R). This function uses an environment to hold the functions implementing the style. RefManager has the MakeBibLaTeX and MakeAuthorYear (internal) functions that manage its native bibliography styles:

my_style <- RefManageR:::MakeBibLaTeX()
#
# <<Put here your customization>>
#
tools::bibstyle("my", my_style)

Add link to journal article’s title using URL

To manage journall article’s title RefManageR use the fmtJTitle function. Just modify it according your taste, such as:

refs$fmtJTitle=my_style$fmtJTitle
with(my_style,
     my_style$fmtJTitle <- function(t, st=NULL, url=NULL, class="title", quote=TRUE) {
       if (length(t)){
         res <- cleanupLatex(t)
         if (length(st))
           res <- paste0(addColon(res), (cleanupLatex(st)), collapse =' ')
         if (quote)
           res<-refs$fmtJTitle(res)
         else
           res<-addPeriod(res)
         if (length(url))
           fmtURI(label=res, uri=url, class=class)
         else
           fmtSetClass(res,class)
       }
     })

Next, RefManageR use the formatArticle function to render article entries:

with(my_style,
     my_style$formatArticle <- function(paper){
       collapse(c(fmtPrefix(paper), fmtBAuthor(paper), 
                  fmtJTitle(paper$title, paper$subtitle, url=paper$url),
                  fmtAddOn(paper$titleaddon), fmtLanguage(paper$language),
                  fmtTranslator(paper), fmtCommentator(paper$commentator),
                  fmtAnnotator(paper$annotator), fmtVersion(paper$version),
                  sentenceP(paste0(c(fmtJournal(paper), fmtSeries(paper$series),
                                     fmtVolume(paper$volume, paper$number),
                                     fmtPages(paper$pages, paper$pagination),
                                     fmtEditor(paper, suffix = NULL, prefix = '. ')),
                                   collapse =' ', sep = ', '),
                            fmtJournDate(paper),
                            fmtBTitle(paper$issuetitle, paper$issuesubtitle, paper$url),
                            fmtEditor(paper, suffix = NULL, prefix = '. '),
                            sep = ''),
                  fmtISSN(paper$issn), fmtDOI(paper$doi), fmtEprint(paper),
                  fmtURL(paper), 
                  fmtHAL(paper$hal_id),
                  fmtAddendum(paper$addendum), fmtNote(paper$note),
                  fmtPubstate(paper$pubstate)
                  ))
     })

1: Adapt fmtJTitle to use url field.
2: The non-original Bib(La)TeX fields can be maintained and handled.

It should be noted that any function fmtXXXX can be tailored to suit specific requirements. Moreover, a careful observer may notice that the order of the fields in the above my_style$formatArticle function differes from that proposed by RefManageR. Oviously, it is possible to rearrange the order of the fields to align with the desired bibliography style. It is also possible to add or remove fields that are deemed unnecessary.

Warning

If one really want to define a fully tailored bibliography style, it is then necessary to customize each entry, including formatBook, formatInBook, formatInCollection, formatInProceedings, and so on. This process can be somewhat tedious.

Make DOI a link

RefManageR renders DOI field as a simple string. To create a link, customize the fmtDOI function, for example, by adding the following code:

with(my_style,
     my_style$fmtDOI <- function(doi){
       if (length(doi)){
         enc.doi <- gsub("%", "\\\\%", URLencode(doi, reserved = TRUE))
         fmtURI(label=doi, uri=paste0("https://doi.org/", enc.doi), 
                prefix="\\{\\{< ai doi >\\}\\} ", class="doi")
       }
     })

Note

In the example above the icon from Academicons is used. Then, the Academicons Extension for Quarto is here needed.

Auxilliary functions

Here some functions which are not part of RefManageR and may be useful.

addColon <- function(s){
  if (!.is_not_nonempty_text(s) && grepl("([^.?!])$", s, useBytes = FALSE))
    paste0(s, ":")
  else
    s
}
# Span a class arround a string
fmtSetClass <- function(s, class, prefix="bib-"){
  if (length(s))
    paste0("[", s, "]\\{.",prefix, class,"\\}")
}
# Format an URI 
fmtURI <- function(label, uri, prefix="", uri_prefix="", class="uri"){
  if (length(uri))
    fmtSetClass(paste0("[", prefix, label, "](",uri, ")\\{rel='noopener noreferrer'\\}."),class)
}

Note

It is my hope that this simple tutorial will prove useful in the creation of your own references page. Should this be the case, I would be grateful if you would share your feedback in the comments section below.

Additionally, the above tutorial is a simplified version of the one used on my website. If you would like to have supplementary tips, ask below.

Footnotes

CiteProc is the generic name for programs that produce formatted bibliographies and citations based on the metadata of the cited objects and the formatting instructions provided by Citation Style Language (CSL) styles (from Wikipedia).↩︎