Citations

The template makes citing and maintaining large lists of publications easy. You can also fill in your own citation data when you need to.

Manubot

Citations in this template are made possible by Manubot, a suite of tools that (among many other things) lets you automatically generate a citation with full details from just a short identifier for a publication.

https://manubot.org/

Basic Use

The template comes with a basic setup for citations that should meet the needs of most people. If you just want to get started as quickly as possible, follow these instructions.

1. For each source you want to cite, just provide an id in /_data/sources.yaml, and some other details if you want (see below).
2. Push the new file to GitHub.
3. The template will automatically fill in the authors, publisher, date, etc. (using Manubot), and save the details to /_data/citations.yaml.
4. Citation(s) in this file can then be displayed with the citation or list component anywhere on your site.

sources.yaml

Basic example with just id:

# a source
- id: doi:10.12345
  # author/date/publisher/etc filled in automatically by Manubot

# another source
...

Example of providing extra details:

# a source
- id: arxiv:1806.05726
  # extra details that template can display nicely (can't be filled in by Manubot)
  image: https://publisher.com/striking-image-for-your-paper.jpg
  tags:
    - biology
    - big data
    - medicine
  repo: your-lab/some-repo
  extra-links:
    - type: source
      link: https://github.com/your-lab/some-repo
    - type: website
      text: My Personal Website
      link: http://some-website.com/

Example of overriding certain Manubot citation details:

# a source
- id: pmc:PMC5640425
  publisher: Manually Corrected Publisher Name

Example of ignoring Manubot and providing everything manually:

# a source (no id field provided)
- title: Some Publication Title
  authors:
    - Steve McQueen
  date: 2021-01-01
  publisher: bioRxiv
  link: biorxiv.org/1234

id

Identifier for the source that Manubot can understand and cite.

An identifier type (like doi, url, isbn, pmc, pmcid, pubmed, arxiv, etc.), then a :, then the id itself, e.g. doi:10.1098/rsif.2017.0387, pubmed:29424689, pmc:PMC5640425, arxiv:1806.05726, etc.

See here for a full list of identifier types that Manubot supports.

If you omit this field or leave it blank, the template will skip running Manubot on it. Do this if you want to manually provide all of the citation details for a source yourself (see the "pass through" feature below).

image

Url to a striking image for the source. Highly recommended.

tags

List of tags for the source.

See the tags component.

repo

GitHub repository to automatically fetch additional tags from.

See the tags component.

extra-links

List of supplementary links for the source, aside from the one Manubot generates for the citation.

See the link component.

date / authors / publisher / other

Any other field you put on a source will always be passed through untouched to the output citation.

You may want to do this if Manubot generates some faulty information for a particular source† and you want to override it, or if Manubot can't generate any citation info for a source†† and you need to manually fill it in yourself.

When doing this, just make sure to format the info in the way that the template expects. See /_data/citations.yaml for reference. In particular, authors should be an array/list of full names, and dates should be in the format "YYYY-MM-DD".

† Very rare and usually due to upstream issues out of our control.
†† Maybe the source is too new or doesn't have readily-accessible metadata (e.g. a PDF).

citations.yaml

DO NOT EDIT THIS FILE! It is generated automatically from sources.yaml (and potentially other files). See the explanation above, and the pipeline diagram below.

Advanced Use

Definitions

To make things easier to explain, here are some definitions:

• source - A book, article, web page, film, or any other published item you want to cite.
• metasource - A single item that lists multiple sources, like how an author's ORCID number can be used to get a list of their published works.
• citation - Detailed information about a source, like author(s), publisher, publish date, url, issue number, journal, etc.

Pipeline

This diagram explains how automatic citations work in the template.

It may seem a bit complicated, but the most important thing to know is that you provide the input (on the left), the template automatically processes the input (in the middle), and outputs complete citations (on the right).

The pipeline works via plugins so it can be extended to support more types of metasources in the future. Currently the only metasource plugin we provide is for ORCID numbers. In the future, we plan to add others, like NCBI and Google Scholar. If you know a bit about programming in Python, you can write your own plugin. For example, perhaps you want to automatically get Professors' publications from a University database.

In more detail, the basic steps of the pipeline are:

1. You create as many source and metasource .yaml input files as you need under /_data. For example, you might want to split up your sources by year, like sources-2020.yaml, sources-2021.yaml, etc. Or you may want to split up your metasources by type, like orcid-current-members.yaml and orcid-alumni.yaml.
2. In _config.yaml, you specify the names of the input files and which plugins they get passed to. By default, the template just reads regular sources as described in the basic use section above.
3. The template uses the plugins compile all of your inputs into a master list of sources.
4. The template will automatically fill in the authors, publisher, date, etc. (using Manubot), and save the details to /_data/citations.yaml.
5. Citation(s) in this file can then be displayed with the citation or list component anywhere on your site.

_config.yaml

Example:

... basic settings

auto-cite:
  plugins:
    - name: orcid
      input:
        - ../_data/orcid.yaml
    - name: sources
      input:
        - ../_data/sources.yaml
  output: ../_data/citations.yaml

orcid.yaml

Example:

# an author
- orcid: 0000-0002-0208-3730
  page: tim-member

# another author
...

orcid

An ORCID number for an author. The plugin fetches all known sources associated with the author in the ORCID database.

page or any other field

You can provide any other field besides the orcid field, and it will be attached to each citation generated from that metasource.

One good use of this is to show certain citations on certain pages using the list component. For example:

You have a list of only your lab's most important papers in sources.yaml. You also put each lab member's ORCID in orcid.yaml, along with their bio page filename, like page: tim-member. Then, on your research page, you display only citations without a page field like {% include list.html data="citations" component="citation" filter="page: " %} Then, on another page, you display all ORCID citations from a specific team member like {% include list.html data="citations" component="citation" filter="page: tim-member" %}.

Cache

If you have hundreds of sources, generating the citations for all of them can take a while. To save time, when going through the list of source, the template skips† ones that are already in /_data/citations.yaml††.

To clear this "cache", simply delete the output file and it will be generated from scratch the next time the citation process runs. Or, if you want to re-generate the citation for a particular source, find its entry in citations.yaml and delete it.

† Note that only the Manubot part of the process is skipped, because it is the part that takes significant time. The pass-through of extra/overridden properties will still occur regardless.
†† Matched by the _cache field, which is a hash of the original input source object.