Distill articles support including citations and a corresponding bibliography using standard R Markdown citation syntax. Distill also provides tools for making your articles more easily citeable, as well as for generating Google Scholar compatible citation metadata.
Citing other works
Use standard R Markdown bibliographies for citing other works. To do this, first create a bibliography file using a supported format (e.g. CSL or BibTeX) and refer to it from the bibliography field of the YAML front-matter. For example:
---
title: "Distill for R Markdown"
description: |
Scientific and technical writing, native to the web
output: distill::distill_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.yaml
---Here’s an example of what a CSL bibliography might look like:
---
references:
- type: article-journal
id: WatsonCrick1953
author:
- family: Watson
given: J. D.
- family: Crick
given: F. H. C.
issued:
date-parts:
- - 1953
- 4
- 25
title: 'Molecular structure of nucleic acids: a structure for
deoxyribose nucleic acid'
title-short: Molecular structure of nucleic acids
container-title: Nature
volume: 171
issue: 4356
page: 737-738
DOI: 10.1038/171737a0
URL: https://www.nature.com/articles/171737a0
language: en-GB
...To cite this within your article, use standard R Markdown notation, for example: [@WatsonCrick1953] (referencing an id provided in the bibliography). See the documentation on Pandoc Citations for details on in-text citations, citing multiple works, etc.
Note that both CSL and BibTeX bibliographies are supported. See the Pandoc Bibliographies documentation for addional details on creating a bibliography for use with Pandoc.
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: "Distill 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://rstudio.github.io/distill
slug: jones2018distill
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 jones2018distill) 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: "Distill 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: jones2018distill
citation_url: https://rstudio.github.io/distill
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
Distill 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 Distill for R Markdown website:
<!-- https://scholar.google.com/intl/en/scholar/inclusion.html#indexing -->
<meta name="citation_title" content="Distill for R Markdown"/>
<meta name="citation_fulltext_html_url" content="https://rstudio.github.io/distill"/>
<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 Distill. 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: "Distill for R Markdown"
description: |
Scientific and technical writing, native to the web
date: May 4, 2018
author:
- name: Norah Jones
url: https://example.com/norahjones
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: jones2018distill
citation_url: https://rstudio.github.io/distill
bibliography: biblio.bib
---