Citations

The "main event" of this template is citations that are generated automatically for you. It makes citing and maintaining large lists of publications easy. You can also fill in your own citation data when you need to.

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.
   1. If you want, you can also provide extra details like a thumbnail image and tags.
   2. If you need to, you can also manually input any citation details -- like author, publisher, date, etc. -- which will override the ones generated automatically.
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 manually adding extra details (optional):

# a source
- id: arxiv:1806.05726
  # extra details
  image: https://image-database.com/some-image.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 citation details:

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

id

Identifier for the source that Manubot can understand and cite. Required.

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.

image

Url to a striking image for the source. Optional, but highly recommended.

tags

List of tags for the source. Optional.

See the tags component.

repo

GitHub repo for the source to automatically fetch additional tags (aka "topics") from. Optional.

extra-links

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

See the link component.

date / authors / publisher / other

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

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 (that have the same _cache field).

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.