Citations

The template makes citing and maintaining large lists of publications easy. You can automatically generate full citation details for a paper from just a short identifier. 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 identifier 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

Example of providing "rich" details:

# a source
- id: arxiv:1806.05726
  # extra "rich" details that the 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 a Manubot citation detail:

# 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
    - Lightning McQueen
  publisher: bioRxiv
  date: 2021-01-01
  link: biorxiv.org/1234

For Manubot

id

Identifier for the source that Manubot can understand and cite.

Put 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.

If Manubot is unable to generate a citation for this ID, the template will log an error message and will exit with an error code.

Citation details

These details should ideally be generated automatically by Manubot, but you can still provide some of them to manually override Manubot's details, or provide all of them when bypassing Manubot all-together.

title

Title of the source.

authors

List of in-order author full names.

publisher

Publisher of the source.

date

Publication date (or any notable date) for the source, in the format YYYY-MM-DD.

link

Main link for the source, when clicking on the citation title or thumbnail image.

"Rich" details

Extra "rich" details that the template can display nicely with the citation component. These are things that couldn't be generated automatically by Manubot because they require human discretion.

image

Url to a striking image for the source. Highly recommended. Shows up as a square thumbnail next to the citation details.

tags

List of tags to show underneath the citation details.

See the tags component.

repo

GitHub repository to automatically fetch additional tags from.

See the tags component.

extra-links

List of supplementary links to show underneath the citation details.

See the link component.

Other details

Any other fields you put in sources.yaml will always be passed through, untouched, to the output in citations.yaml. The ability to override citation details is just a result of this simple behavior; it is not handled as a special case.

Of course, if you attach a custom field, it won't be visible on your site unless it is a field that's supported by the component you are using to display the citation.

However, it can still be useful to do this for filtering with the list component. For example, you could put a significant: true field on certain papers, then always show those papers at the top of your page.

citations.yaml

DO NOT EDIT THIS FILE! It is generated automatically from sources.yaml (and potentially other files). See the explanations 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.

Sometimes an ORCID number for an author will return source IDs that Manubot does not know how to cite, e.g. eid:123345. In this case, the template will log an error message, but will NOT exit with an error code.

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/significant papers in sources.yaml.
• You also put each lab member's ORCID in orcid.yaml, which (hopefully) captures all the work your lab has done in a comprehensive list.
• Alongside their ORCIDs, you put their member page on the site, like page: tim-member.
• citations.yaml gets generated with hundreds of publications, and the ones without a page field are the ones from sources.yaml, and the ones with a page field are from orcid.yaml.
• On your research page, you display your important (sources.yaml) papers like {% include list.html data="citations" component="citation" filter="page: " %}
• 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 citations.yaml and it will be generated from scratch the next time the citation process runs.

† 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.