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.

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 (and some extra details like a thumbnail and tags, if you want) in /_data/sources.yaml
2. Push the new file to GitHub. If working from a fork, enable GitHub actions on the FORK, BEFORE opening the pull request, otherwise automatic citations might not work
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

Example:

# a source
- id: doi:10.12345
  image: https://image-database.com/some-image
  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/

# another source
...

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.

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

If you're familiar with JavaScript, this analogy might help to explain the difference between the two files: sources.yaml is like your package.json file and citations.yaml is like your package-lock.json/yarn.lock file.

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 id field). To clear this "cache", simply delete the output file. Or if you want to re-generate the citation for a particular source, find its entry in citations.yaml and delete it.

Note: Even if a source is skipped, any field you manually put in the input will still be copied over.