gatsby-source-publications
Gatsby source plugin to pull publications from bibtex, DOIs, or ORCID and format them using Citation.js. The key features:
- Pull publications from multiple sources: BibTex, DOIs and ORCID.
- Formatted bibliography using custom citation styles
- Query publications in GraphQL
- Easily filter which publications are added to the graph
Minimal example
// In your gatsby-config.js
plugins: [
{
resolve: "gatsby-source-publications",
options: {
sources: [
{
type: "bibtex"
name: "my-publication",
path: path.resolve('./src/my-bibliography.bib')
}
]
},
},
];
More elaborate example
The only required option is a list of sources, but you can find a list of all options below.
// In your gatsby-config.js
plugins: [
{
resolve: "gatsby-source-publications",
options: {
sources: [
{
// Fetch all works from a given ORCIDiD
type: "orcid",
name: "bcornelissen",
orcidId: "0000-0002-0766-7305",
// You can exclude some of them using a filter...
filter: (item) => item.year > 2020,
// ...or by passing a list of DOIs to exlucde
excludeDOIs: ['10.1177/10298649221149109'],
},
{
// And another one...
type: "orcid",
name: "jaburgoyne",
orcidId: "0000-0001-6854-5646"
},
{
// Or you can pass a list of DOIs to load
type: "doi",
name: "some-dois",
DOIs: [
"10.31234/osf.io/qjfpe",
"10.1177/10298649221149109",
"10.1007/s10071-023-01763-4"
]
},
{
// Or read out a bibtex file
type: "bibtex"
name: "my-bibtex-pubs",
path: path.resolve('./src/my-bibliography.bib')
}
],
style: "apa", // harvard1 or vancouver
// ... or pick your favourite citation style
template: 'https://.../my-style.csl',
// See below for all options
},
},
];
You can then query your publications as follows.
query MyQuery {
allPublication {
nodes {
year
citation # an inline citation, e.g. (Author, 2023)
bibtex # a bibtex reference
html # formatted html reference
text # plain text reference
sources # list of source names
# The Cite object is exported to bibjson, and all its fields
# are added to the graph under props:
props {
DOI
title
author {
given
family
}
abstract
issued {
date_parts
}
# And more...
}
}
}
}
Sources
The plugin fetches and combines publications from multiple sources. Three types of sources are currently supported: BibTex, DOIs and ORCID.
You can pass as many sources as you like to plugins.options.sources
using dictionaries of the following form:
{
// Required options
type: 'orcid', // one of 'orcid', 'bibtex' or 'doi'
name: 'my_name' // required
// Required when type == 'bibtex', either one of these:
path: '' // path to a bibtex file
bibtex: '' // or, alternatively the contents of a bibtex file
// Required when type == 'orcid'
orcidId: '0000-0001-6854-5646' // an ORCIDiD
// Required when type == 'doi'
DOIs: [...] // a list of dois
// Optional: excludes items for which the filter returns false
filter: (item) => true
// Optional: exlude certain DOIs (a shorthand filter)
excludeDOIs: [...] // A list of DOIs that are excluded
}
Plugin options
sources
(required list of strings). A list of all source objects, see section on sources.style
(optional string, default'apa'
). Name of the citation style. The styles that are included by default in Citation.js are'apa'
,'vancouver'
, and'harvard1'
. This field is ignored if you also specify a custom CSL templatetemplate
(optional string). A custom CSL template, passed as an url or an XML string.locale
(optional string, default'en-US'
). The locale, used by Citation.js. Supported values are'en-US'
,'es-ES'
,'de-DE'
,'fr-FR'
, and'nl-NL'
.skipWithoutBibtexOrDoi
(optional boolean, defaultfalse
). Iftrue
, all works without bibtex or doi are skipped. It is possible to construct Cite objects for such works from the information returned by ORCID, but they maybe turn out to be incomplete.replaceDOIsByAnchors
(optional boolean, defaulttrue
). If this is enabled and the style is'apa'
, then the DOIs at the end of the formatted HTML reference are replaced by anchors.nodeType
(optional string, default'Publication'
). Name of the nodes.orcidEndpoint
(optional string, default'https://pub.orcid.org/v3.0'
). The ORCID endpoint from which to fetch all data.delayAfterFetch
(optional int, default25
ms). The delay in ms after every request to ORCID.
Custom citation styles
You can use custom citation styles by passing a CSL template to the plugin options. You can find many citation styles in this Github repository. Pass the XML template to the plugin as a url or as an XML string:
// In your gatsby-config.js
module.exports = {
// ...
plugins: [
{
resolve: "gatsby-source-orcid-publications",
options: {
sources: [
// ...
],
// Option 1: pass an url"
template: 'https://raw.githubusercontent.com/citation-style-language/styles/master/chicago-author-date-16th-edition.csl',
// Option 2: pass the CLS style directly
template: '<?xml version="1.0" encoding="utf-8"?><style ...';
// ...
},
},
//...
],
};
Resolving duplicate publications
The same publication could appear in multiple sources. The plugin first tries to identify and remove duplicates using (normalized) DOIs. If no DOI can be found, the plugin uses the year and title, but this may not always work well. If problems arise, edit the source data so that the works in question all have the same DOI, or otherwise have identical titles. You can also write a custom filter to remove duplicates.
The plugin tracks from which source each publication was retrieved using the source.name
field. If a publication is for example found in sources with names source_1
and source_2
then one node will be created, and it will have Publication.sources = ['source_1', 'source_2']
.
Filtering publications
You can of course filter publications using GraphQL queries, but you can also prevent certain publications from being added to the graph altogether. (This may for example reduce build time for ORCID sources in particular). To filter publications before nodes are created, pass a source.filter
function, that takes a SourceItem
and returns true
if the item is to be included:
{
type: 'orcid',
name: 'my_source'
//...
filter: (item) => {
// Your fancy filtering function
return item.year > 2020
}
}
The item
is a SourceItem
instance, and does not yet contain all information about the publication: this is fetched only when it is really needed, when nodes are finally created. Which data is available depends on the source type:
- DOI. With
DOISourceItems
you can useitem.doi
anditem.id
- ORCID. With
OrcidSourceItem
you can use the propertiesid
,lastModified
,created
,putCode
,path
,doi
,type
,title
,journal
,year
. - BibTex. With
BibTexSourceItem
you can useid
,doi
,citationKey
,title
,year
, or other fields by accessingitem.data
directly.
(N.B.: If you really need all data, you can hack the filter by accessing item.export
. This will fetch and cache all data for that item.)
Linking publications
One way you can use the sources
field, is to associate publications to other nodes, such as users. The specifics will vary depending on the setup, but suppose you have a node type Users
with a username
field. If the names of your publication sources correspond to usernames, then the following schema customization should do the trick:
// In your gatsby-node.js
exports.createSchemaCustomization = ({ actions }) => {
actions.createTypes(`
type User implements Node @infer {
username: String
}
type Publication implements Node @infer {
users: [User] @link(from: "sources", by: "username")
}
`);
};
License
MIT License, Copyright (c) 2023 Bas Cornelissen