Citations

Referencing other works and creating citeable articles

Table of Contents


Radix articles support including citations and a corresponding bibliography using standard R Markdown citation syntax. Radix also provides tools for making your articles more easily citeable, as well as for generating Google Scholar compatible citation metadata.

Citing other works

BibTeX is the supported way of making academic citations. To include citations, first create a BibTeX file and refer to it from the bibliography field of the YAML front-matter. For example:


---
title: "Radix for R Markdown"
description: | 
  Scientific and technical writing, native to the web
output: radix::radix_article
date: May 4, 2018
author:
  - name: Nora Jones 
    url: https://example.com/norajones
    affiliation: Spacely Sprockets
    affiliation_url: https://example.com/spacelysprokets
bibliography: biblio.bib
---

Here’s an example of what one of the entries in your BibTeX file might look like:


@Book{xie2015,
  title = {Dynamic Documents with R and knitr},
  author = {Yihui Xie},
  publisher = {Chapman and Hall/CRC},
  address = {Boca Raton, Florida},
  year = {2015},
  edition = {2nd},
  note = {ISBN 978-1498716963},
  url = {http://yihui.name/knitr/},
}

To cite this within your article, use standard R Markdown notation, for example: [@xie2015] (referencing an id provided in the bibliography). Note that multiple ids (separated by semicolons) can be provided.

The citation is presented inline like this: (Xie 2015) (a number that displays more information on hover). If you have an appendix, a bibliography is automatically created and populated within it.

Radix chose a numerical inline citation style to improve readability of citation dense articles and because many of the benefits of longer citations are obviated by displaying more information on hover. However, we consider it good style to mention author last names if you discuss something at length and it fits into the flow well—the authors are human and it’s nice for them to have the community associate them with their work.

Also note that you are strongly encouraged you to populate the url BibTeX field where possible so that links can be provided for citations.

Creating citeable articles

You can make it easier for others to cite your work by providing additional metadata with the YAML front-matter of your article. Citations can be provided for both articles published to the web or for articles published in journals (with or without a DOI).

Web articles

To provide a citation for an article published to the web, include author and date metadata as well as a citation_url. For example:


---
title: "Radix for R Markdown"
description: | 
  Scientific and technical writing, native to the web
date: May 4, 2018
author:
  - name: Nora Jones 
    url: https://example.com/norajones
    affiliation: Spacely Sprockets
    affiliation_url: https://example.com/spacelysprokets
citation_url: https://radixpub.github.io/radix-r
slug: jones2018radix
bibliography: biblio.bib
---

Note that the citation_url field is not required for blog articles (in that case it’s computed automatically using the site’s base_url field).

When this metadata is available, a citation appendix is automatically added to the article which looks like this:

Note that we also included a slug field (in this case jones2018radix) which affects the abbreviated version of the citation included in the BibTeX entry. If you don’t provide a slug then one will be automatically generated.

Journal articles

If your article is published within a Journal, you can add the following the additional fields to generate the appropriate citation entry:

Metadata Description
journal Name of Journal published within
doi Digital Object Identifier (DOI)

Here’s our previous examples amended with these fields:


---
title: "Radix for R Markdown"
description: | 
  Scientific and technical writing, native to the web
date: May 4, 2018
author:
  - name: Nora Jones 
    url: https://example.com/norajones
    affiliation: Spacely Sprockets
    affiliation_url: https://example.com/spacelysprokets
journal: "Journal of Data Science Software"
doi: "10.23915/distill.00010"
slug: jones2018radix
citation_url: https://radixpub.github.io/radix-r
bibliography: biblio.bib
---

This is how the citation is presented in the appendix:

For Journal articles, the citation_url is included in the BibTeX entry within the note field.

Google Scholar

Radix articles automatically include metadata compatible with the format indexed by Google Scholar. This makes it easy for indexing engines (Google Scholar or otherwise) to extract not only a citation for your article but also information on other sources which you cited.

For example, here is the Google Scholar metadata automatically included for the home page of the Radix website:


<!--  https://scholar.google.com/intl/en/scholar/inclusion.html#indexing -->
<meta name="citation_title" content="Radix for R Markdown"/>
<meta name="citation_fulltext_html_url" content="https://rstudio.github.io/radix"/>
<meta name="citation_fulltext_world_readable" content=""/>
<meta name="citation_online_date" content="2018/05/04"/>
<meta name="citation_publication_date" content="2018/05/04"/>
<meta name="citation_author" content="JJ Allaire"/>
<meta name="citation_author_institution" content="RStudio"/>
<meta name="citation_author" content="Rich Iannone"/>
<meta name="citation_author_institution" content="RStudio"/>
<meta name="citation_author" content="Yihui Xie"/>
<meta name="citation_author_institution" content="RStudio"/>
<meta name="citation_reference" content="citation_title=Distill;
citation_publication_date=2016;citation_publisher=Distill Working
Group;citation_doi=10.23915/distill;citation_author=Shan Carter;
citation_author=Chirs Olah;citation_author=Arvind Satyanarayan"/>
<meta name="citation_reference" content="citation_title=Literate
programming;citation_publication_date=1984;
citation_publisher=British Computer Society;citation_volume=27;
citation_author=Donald E. Knuth"/>
<meta name="citation_reference" content="citation_title=Dynamic
documents with r and knitr;citation_publication_date=2015;
citation_publisher=Chapman; Hall/CRC;citation_author=Yihui Xie"/>

Note that the citation_reference fields provide information on which works your article cited.

The code above is HTML so don’t worry if you aren’t familiar with the syntax. The important thing to know is that citation data is provided in a way that machines can easily read and index.

If you are publishing a Journal article, there are some additional metadata fields you can provide to enhance the Google Scholar metadata generated by Radix. These include additional fields describing the Journal (title, issn, and publisher) as well fields describing the volume and issue in which your article was published. For example:


---
title: "Radix for R Markdown"
description: | 
  Scientific and technical writing, native to the web
date: May 4, 2018
author:
  - name: Nora Jones 
    url: https://example.com/norajones
    affiliation: Spacely Sprockets
    affiliation_url: https://example.com/spacelysprokets
journal: 
  title: "Journal of Data Science Software"
  issn: 2490-1752
  publisher: Data Science Press
volume: 10
issue: 4
doi: "10.23915/distill.00010"
slug: jones2018radix
citation_url: https://radixpub.github.io/radix-r
bibliography: biblio.bib
---

Xie, Yihui. 2015. Dynamic Documents with R and Knitr. 2nd ed. Boca Raton, Florida: Chapman; Hall/CRC. http://yihui.name/knitr/.

Corrections

If you see mistakes or want to suggest changes, please create an issue on the source repository.

Reuse

Text and figures are licensed under Creative Commons Attribution CC BY 4.0. Source code is available at https://github.com/radixpub/radix-r, unless otherwise noted. The figures that have been reused from other sources don't fall under this license and can be recognized by a note in their caption: "Figure from ...".