Generating citations and bibliographies with CSL and citeproc-java

I was recently writing a scientific document with AsciiDoc. As usual, my toolchain was AsciiDoc → DocBook → FO → PDF. It really worked quite well until I came to the point where manually adding citations and editing the bibliography by hand became really complex and I suddenly found myself yearning for more automation.

I asked Google what I could do and Google told me about BibTeX and all these things. There even was a tool called asciidoc-bib by Peter Lane that was able to read BibTeX files to generate citations and bibliographies and then put them into an AsciiDoc source file. I tested this tool for a while and contributed one or two commits via GitHub. However, I was not yet convinced by the flexibility and maturity of asciidoc-bib by that time, so I started looking for ways how to extend it.

Enter the Citation Style Language (CSL). CSL is an XML-based description of citation styles and bibliographies that’s maintained by a number of people from the scientific community. They say it’s “by academics, for academics”. I really loved the idea of having a more modern alternative to BibTeX and natbib, which I never found particularly mind-blowing by the way.

I started with extending asciidoc-bib with support for a library called citeproc-ruby by Sylvester Keil. citeproc-ruby is a so-called CSL processor, which means it reads CSL styles and transforms them to citations and bibliographies. However, I still found asciidoc-bib too cumbersome to use, in particular since it was written in Ruby and my toolchain was based on Java.

So I asked Google again, if they could tell me something about CSL and Java, but they said they didn’t know very much about that. That was when I finally decided to write my own CSL processor for Java.


Today I’m pleased to announce the first release of citeproc-java, a CSL processor for Java! An (almost) complete documentation is available at the following site:

I have to be honest with you guys. I didn’t implement the whole CSL specification myself. Instead, I tried to incorporate existing code as much as possible. citeproc-java uses the great citeproc-js by Frank G. Bennett, Jr. internally. It is therefore fully CSL 1.0.1-compliant. Apart from that, it offers some cool additional features such as BibTeX import as well as export to AsciiDoc and FO.

For convenience, I uploaded citeproc-java and the CSL styles and locales to Maven central. Please see the installation instructions for more information:

citeproc-java’s BibTeX to CSL mapping is based on the one used in Docear. It has been converted to Java by permission from the Docear authors, in particular Joeran Beel. The BibTeX converter imports author names using the name parser from the citeproc-ruby project. It has been converted to Java by permission from Sylvester Keil. Thank you very much for that!

Although citeproc-java is a very young project and this is the very first release, I consider it rather stable already—not least because it uses citeproc-js under the hood. Nevertheless, development of citeproc-java has just begun and I’m sure there are great features to come. If you want to participate, don’t hesitate to fork my GitHub repository and send me pull requests:

Finally, big thanks go to the CSL community for the great work and support!


citeproc-java is licensed under the Apache License, Version 2.0.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Profile image of Michel Krämer

Posted by Michel Krämer
on 16 September 2013

Next post

Command line tool for citations and bibliographies

Version 0.6 of citeproc-java introduces a command line tool that can be used to generate citations and bibliographies without setting up a complete development environment.

Previous post

bson4jackson 2.2 has just been released!

The latest release 2.2 of bson4jackson, which has just been released, now supports Jackson 2.2. Thanks to contributions from the community, dependencies have also been updated.

Related posts

citeproc-java 2.0.0 has just been released

The new major version offers support for Java 11 and is able to import YAML files. To improve performance, a GraalVM-based JavaScript runner has been added. The update also fixes a few minor bugs.

Binary JSON with bson4jackson

This post introduces the open-source library bson4jackson, which is an extension to the Jackson JSON processor. It enables you to parse and generate documents in a binary JSON format called BSON.

Actson: a reactive (or non-blocking, or asynchronous) JSON parser

I’m thrilled to announce the first release of Actson, a reactive JSON parser. Actson is event-based and can be used together with reactive frameworks such as Vert.x to create highly responsive applications.