Citations
Last updated
Last updated
Arguably the most important feature of this template is its ability to automatically generate citations from simple identifiers. This makes it easy to cite and maintain large lists of publications.
The template is able to do this thanks to , a suite of tools that (among many other things) lets you automatically generate a citation with full details from just a short identifier, like doi, url, isbn, pmc, pmcid, pubmed, arxiv, and .
First let's define some consistent terminology to make things easier to explain:
source - A paper, book, article, web page, film, or any other published item you want to cite.
citation - Full, detailed information about a source, like title, author(s), publisher, publish date, URL, etc.
For most content on your site, you just need change the contents of the appropriate file. Citations have a special additional step. When you add new sources or metasources to be cited, the template has to run a special "cite process" to generate your full citations.
At a high level, here's how it all works:
Input your sources and metasources in /_data files, e.g. sources-2020.yaml, orcid-students.yaml, etc.
The cite process outputs a single citations.yaml file in /_data.
Filename must start with sources.
id
Optionally, you can manually pass extra "rich" details that the template can display nicely. Manubot can't automatically determine these.
type
The type of the source. Determines the icon to show.
See /_data/types.yaml for what types are built-in or to add your own.
description
Brief description of the source. Can contain Markdown.
image
URL to a striking image for the source. Highly recommended. Displays as a thumbnail next to the citation details.
buttons
tags
repo
All fields you attach to a source (or metasource, see below) get passed through to the generated citation untouched. This allows you to manually input or correct details of a citation.
title / authors / publisher / date / link
If you don't provide an id, Manubot has nothing to cite and so doesn't run. You'd only want to do this if manually providing all the citation details manually. This defeats the main benefit of the template, but is sometimes necessary.
Filename must start with orcid.
Each ORCID gets expanded into a full list of regular sources with ids. Any fields you put in the original entry get copied to each source in the expanded list. This applies to the other types of metasources below as well.
See ORCID above for general metasource functionality.
Filename must start with pubmed.
See ORCID above for general metasource functionality.
Filename must start with google-scholar.
Metasources like ORCID update over time as you publish new sources. To accommodate this, the template tries to automatically re-run the cite process periodically. In your repo's "▶️ Actions", see the "on schedule" workflow.
When the workflow runs, it will get the latest sources associated with your metasources, generate citations like normal, and open a pull request to let you review the changes before publishing them.
If you have many sources, generating the citations for all of them can take a while. To save time, the cite process keeps a time-to-live cache for Manubot/ORCID/etc. network requests. If a cached response hasn't expired, it is used instead of making a new request. To clear this, simply delete the cache directory _cite/.cache. You can also customize the default expire times in the Python code in _cite.
metasource - A single item that lists multiple sources, like how an author's can be used to get a list of their published works.
The cite process runs – either or – to convert your sources and metasources to full citations.
Display and filter citations on your site with the and components.
You can mix and match as many sources and metasources as you want, and display them however and wherever you'd like! For example, you may want to have a "CV" page that lists all of the papers under your 's ORCID, then reserve your "Research" page for just a few special papers by various members in your lab that you want to highlight.
Identifier for the source that . If Manubot is unable to generate a citation for this ID, the template will log an error message and exit with an error code.
List of to show underneath the citation details.
List of to show underneath the citation details.
GitHub repository to automatically fetch additional from.
Always provide a good thumbnail for your publications. Use a figure from the source, or if there are none, a journal logo or issue cover. .
Basic citation information normally returned from Manubot and displayed by the component. Date should be in YYYY-MM-DD format. Authors can contain Markdown.
You can also attach arbitrary fields. The template won't explicitly use them, but you could use them to filter citations with the component.
is the recommended way to retrieve a complete set of published works for an author.
To conveniently and explicitly associate an ORCID with a person for filtering with the , you can add a unique field for that person like in the example above and use a filter like this:
Because the cite process merges duplicate sources by id, you can also use the above to manually correct sources returned from metasources. You can also use the special remove field to ignore a source returned from a metasource, discarding it from the citations output. Example:
Uses to search for terms. This is a brittle way to select an author's papers, very vulnerable to false positives. ORCID is recommended.
Unfortunately, Google does not provide APIs for many of its services, and that includes Scholar. Luckily there is a 3rd-party API to access it, . First you'll have to sign up and get an API key. Then, if , make a named GOOGLE_SCHOLAR_API_KEY with your API key as its value, or if , put the same name/value in a .env file.
. You may have to manually enable the workflow, or re-enable it after a while.
Due to another , if you want to see a for this pull request, you'll have to close (not merge) and reopen it. That should trigger the "build preview" workflow.
