pandoc-wikicite
Pandoc filter to use Wikidata as reference manager
This Pandoc filter supports using Pandoc citation syntax to reference bibliographic records from Wikidata. Bibliographic data is extracted from Wikidata with citation.js and it can be stored locally in a CSL JSON file.
Table of Contents
Background
The knowledge base Wikidata contains statements about all kinds of entities such as people, places, and publications. The WikiCite initiative promotes using Wikidata as collaboratively curated bibliography. To cite a document it only needs methods to reference a corresponding Wikidata item and to extract its bibliographic data.
Install
Install latest release
$ npm install -g pandoc-wikicite
Install from source
$ git clone https://github.com/wikicite/pandoc-wikicite.git
$ cd pandoc-wikicite
$ npm install -g . # or `npm link`
Tested with NodeJs version 6 and above.
Usage
pandoc-wikicite consists of two scripts that can be used independently:
- pwcite to use Wikidata identifiers in Pandoc citation keys
- wcite to get and locally store bibliographic data from Wikidata
pwcite
Write your documents in Markdown with Pandoc citation syntax. In short,
reference publications via citation keys prepended by @
:
Blah blah [@doe95; @doe99], disputed by @alice07.
Publications listed in Wikidata can be referenced by their item identifier:
Wikidata is a collaborative knowledge base [@Q18507561].
As these identifiers are ugly to read you can map them from more readable
citekeys in the citekeys
field of your document metadata:
---
citekeys:
Vrand04: Q18507561
...
Wikidata is a collaborative knowledge base [@Vrand04].
To process this file, call pandoc with two filters (-F
):
$ pandoc -F pwcite -F pandoc-citeproc examples/example-1.md
The first filter pwcite
detects and maps Wikidata identifiers used as
citation keys, downloads the corresponding bibliographic data from Wikidata,
and adds it to the document. The second filter pandoc-citeproc
creates
nicely references using the Citation Stylesheet Language (CSL).
Bibliography files
Bibliographic data is downloaded and converted from Wikipedia on each call of
the filter script pwcite
. This has limitations for two reasons:
- performance: network access is slow
- reproducability: the data could have been been changed on Wikidata
You should therefore store bibliographic data in a local file. The file can be
specified via document metadata field bibliography
and it must have file
extension .json
:
---
bibliography: references.json
...
Wikidata is a collaborative knowledge base [@Q18507561].
The filter script pwcite
detects a JSON bibliography file, looks up referenced
Wikidata items in this file, and adds missing entries by lookup in Wikidata.
The filter pwcite
use the bibliography file for caching. Wikidata identifiers
are first looked up in the file. If an identifier is not found, its data is
queried from Wikidata and written to the file, so each existing Wikidata
identifier is only queried once. Use wcite or delete the file for updates.
If multiple bibliography files are specified then pwcite
only uses the first
file with extension .json
, so bibliographic data from Wikidata and from other
sources, for instance BibTeX files, can be mixed.
It is also possible to pass the filename with pandoc option --bibliography
.
This overrides bibliography files in the document metadata and automatically
enables filter pandoc-citeproc
, but the file must exist in advance (an empty
file is ok):
$ touch references.json
$ pandoc -F pwcite --bibliography references.json examples/example-1.md
wcite
The wcite
script can be used to list or add/update bibliographic data from
Wikidata in a JSON file:
wcite wikicite.json # list Wikidata citekeys
wcite update wikicite.json Q18507561 # update/add selected
wcite update wikicite.json # update all
wcite Q18507561 # get and format from Wikidata
The file is always sorted by citekey and serialized as pretty-printed, sorted JSON so facilitate comparing versions.
Linking to Wikidata
The bibliography generated in HTML format includes Wikidata identifiers for
each reference. Setting document metadata field wikidata-links
to true
or
to an URL prefix (e.g. https://tools.wmflabs.org/scholia/work/
) will inject
two snippets of JavaScript and CSS to add links from references back to Wikidata.
License
MIT license
Contains parts of pandoc-filter-node.