npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

wcite

v0.4.4

Published

Use Wikidata as reference manager

Downloads

23

Readme

wcite

Use Wikidata as reference manager

NPM Version Build Status Open Issues JavaScript Style Guide license Maintainability Coverage Status

This JavaScript package provides a command line client to fetch and manage bibliographic records from Wikidata and a Pandoc filter to use Wikidata item identifiers and aliases as citation keys.

Table of Contents

Overview

Wikidata contains statements about all kinds of entities such as people, places, and publications. The WikiCite initiative promotes using Wikidata as collaboratively curated bibliography. The JavaScript package wcite provides:

  • the command line client wcite to fetch bibliographic records from Wikidata and to manage them locally in bibliography files for writing system such as Pandoc and LaTeX.

  • the Pandoc filter pwcite to use Wikidata item identifiers as citation keys in Pandoc citation syntax to automatically fetch records from Wikidata.

See usage for details and examples.

Installation

Install latest release:

$ npm install -g wcite

or install from source:

$ git clone https://github.com/wikicite/wcite.git
$ cd wcite
$ npm install -g .  # or `npm link`

Tested with NodeJs version 8 and above.

Usage

Bibliographic entities in Wikidata are referenced by their item identifier. For instance Q55239420 identifies the first edition of Mary Shelley's novel Frankenstein. Its bibliographic data can be shown by calling wcite with the identifier:

$ wcite Q55239420
Q55239420: Shelley, M. (1818). Frankenstein (1st ed.). London

To locally save the bibliographic data in a bibliography file pass its name as argument or with option -b/--bibliography:

$ wcite refs.json add Q55239420
Q55239420 added

Records from the file can be listed in multiple formats:

$ wcite refs.json
Q55239420

$ wcite refs.json -f bibtex
@book{Q55239420,
  author={Shelley, Mary},
  title={Frankenstein},
  edition=1,
  ...

All this is done automatically with Pandoc filter pwcite.

Command wcite

Command line script wcite can fetch and transform bibliographic data from Wikidata and locally manage it in a bibliography file. In addition to bibliography files the script can read and write document files with YAML header.

Usage: wcite [options] [command] [file] [ids...]

Manage bibliographic data from Wikidata. Bibliography CSL JSON file
can be specified explicitly or via YAML header field 'bibliography'.

Options:
  -V, --version              output the version number
  -b, --bibliography <file>  Bibliography file (CSL JSON)
  -d, --document <file>      Document file with YAML header
  -f, --format <name>        Output format (text|html|bibtex|bibtxt|json|ndjson)
  -o, --output <file>        Output file. Format can be guessed from extension
  -t, --template <name>      Citation template (apa|vancouver|harvard1)
  -l, --language <lang>      Language codes (separate with space or comma)
  -i, --ids <file>           Read ids from (use `-` for stdin)
  -q, --quiet                Avoid status output
  -h, --help                 output usage information

Commands:
  add <ids...>               add records specified by Wikidata identifiers
  remove <ids...>            remove records by Wikidata identifiers or aliases
  get [ids...]               show bibliographic records
  update [ids...]            update bibliographic records
  list                       list Wikidata identifiers and aliases
  help                       display this usage help

Examples:
  $ wcite refs.json          # list Wikidata ids in refs.json
  $ wcite update refs.json   # update all entries in refs.json
  $ wcite Q18507561          # get bibliographic data from Wikidata

Filter pwcite

The Pandoc filter pwcite processes a document to detect citation keys that use Wikidata item identifiers. Simply write your documents in Markdown and use Pandoc citation syntax to reference publications:

Blah blah [@doe95; @doe99], disputed by @alice07.

Publications from Wikidata can be referenced using their identifiers like this:

Wikidata is a collaborative knowledge base [@Q18507561].

Wikidata identifiers are hard to remember and to distinguish so you can define aliases with the citekeys field of your document metadata:

---
citekeys:
  Vrand04: Q18507561
...

Wikidata is a collaborative knowledge base [@Vrand04].

To process this file, call pandoc with filter pwcite followed by filter pandoc-citeproc:

$ pandoc -F pwcite -F pandoc-citeproc example.md

The first filter detects referenced Wikidata items, downloads the corresponding bibliographic records from Wikidata, and adds them to the document. The second filter creates nicely formatted references using the Citation Style Language (CSL).

A local bibliography file can be specified in metadata field bibliography for caching:

---
citekeys:
  Vrand04: Q18507561
bibliography: refs.json 
...

Wikidata is a collaborative knowledge base [@Vrand04].

If multiple bibliography files are specified then all are used for referencing but only the first file with extension .json is to store records fetched from Wikidata. This way it is possible to get some references from Wikidata and use other sources as well for instance BibTeX files.

Pandoc option --bibliography overrides an existing metadata field and automatically enables filter pandoc-citeproc but in this case the file must exist in advance.

Linking bibliography entries to Wikidata

Each bibliography entry in HTML format includes the Wikidata item identifier in its id attribute (e.g. <div id="ref-Q55239420">...). This identifier can be used to add a link to the corresponding Wikidata item or to other services such as Scholia. The filter pwcite can inject snippets of JavaScript and CSS to add links from bibliography entries to Wikidata. To to do set document metadata field link-wikidata-references to true or to an URL prefix (e.g. https://tools.wmflabs.org/scholia/work/). This feature is based on Pandoc metadata variable include-after, so don't set it via Pandoc command line option -A/--include-after-body and don't remove the variable in custom HTML templates!

Bibliography files

Bibliographic records fetched from Wikidata should be stored locally for several reasons:

  • performance: network access is slow
  • reproducibility: the data could have been been changed on Wikidata

Both wcite and pwcite store records in a normalized CSL JSON file. Records in this file are sorted by Wikidata item identifier and serialized as pretty-printed JSON with sorted keys to facilitate comparing changes.

Bibliography files must have file extension .json. A file can be specified:

  • via document metadata field bibliography (see example at pwcite)
  • as command line argument to wcite
  • as existing file wcite.json (not implemented yet)

Both wcite and pwcite use bibliography files for caching: records are first looked up by their Wikidata item identifier in the file and queried from Wikidata only if not found locally. Use wcite to delete or update records if needed.

API

The JavaScript API to use this package as module is not finished yet. Stable parts include:

Bibliography

This class implements a bibliography file that stores CSL JSON records from Wikidata.

const { Bibliography } = require('wcite')

var refs = new Bibliography('refs.json')

refs.add(item)
let record = refs.get(id, citekeys) 

if (refs.modified) {
  refs.save()
}

wcite

Provides the implementation of command [wcite-cli]

const { wcite } = require('wcite')

wcite({ bibliography: 'refs.json' }).list()

License

MIT license

Contains parts of pandoc-filter-node originally created by Mike Henderson.

Acknowledgements

Fetching and converting data from Wikidata and to BibTeX is implemented with citation.js created by Lars Willighagen.

References

A bibliography of some publications relevant to wcite is included in the source code repository following here for the purpose of demonstration at http://wikicite.org/wcite/#references.