Weekend Project: Convert WordPress into a Scholarly Publishing Platform with Annotum


There’s publishing, and then there’s publishing. A general-purpose CMS often needs tweaking to meet the demands of a professional publication — such as a magazine or news organization. But that’s where the open source CMSes shine, and Annotum is a prime example of what they can do. It is an add-on that turns vanilla WordPress into a scholarly publication platform suitable for use at an academic or scientific journal.

The impetus for Annotum came about in mid-2011, when Google announced that it would slowly close the doors on its Knol academic publishing service. The Knol phase-out is gradual — everything will remain fully accessible through April of 2012, and authors and editors using will be able access their own works (in order to export them) until October 2012.

Building a replacement — specifically, one to which existing Knol users could easily export their works — was a key concern. WordPress was certainly a high-profile option from the start, but it, like many other open source CMSes, is designed with blog publishing in mind. That meant some missing features critical to scholarly publishing, would need to be replicated. In order to make migration from Knol simple, though, there would also need to be a way to serve authors who were unable or uninterested in running their own private WordPress server.

The main differences that Annotum brings to WordPress are changes to the post authoring workflow &mndash; to support multiple authors and to enable separate editors, publishers, and reviewers — and changes to the content formatting. Blog posts can be pretty free-form, but scholarly journals need more structure. For example, it is important to have tables and illustrations with semantically-attached labels, rather than captions in <div> tags that are dropped in place at render-time by CSS rules.

Introducing Annotum 1.0

Annotum is the product of a collaborative development project between Solvitor LLC and Crowd Favorite, with some critical assistance provided by WordPress’s core sponsor Automattic. The 1.0 release was unveiled on November 23. The source code is hosted at GitHub, as are self-contained .ZIP archives — although WordPress users may find it easier to install the package by searching for it through the WordPress dashboard’s theme installer.

Annotum is implemented as a theme, rather than as a plug-in, largely because it changes core WordPress components. WordPress 3.3 is required, as is PHP 5.2.4 or newer, and libxml 2.6.29 or later. Another option is to sign up for an account at WordPress.com, which now offers Annotum as one of its user-selectable themes.

The package integrates into the WordPress dashboard back-end, but introduces several new ideas. First, “Articles” appears as a separate option in the sidebar, distinct from both Posts and Pages. Articles can also have multiple co-authors, which Posts and Pages cannot. You can start writing your own article, and invite other users to participate as collaborators.

You’ll also notice that Articles have a “Submit for Review” button in place of the usual “Publish” button. This is where Annotum hooks into the peer-review workflow used by most scholarly publications. Whenever an article is submitted, those users with “editor” privileges can read it and assign it to “reviewer” users. The reviewers can make comments, notes, and corrections, which are then sent back to the editor. Only when the editor decides that the corrected and updated version of the article passes muster is it tagged for publication.

The workflow changes are not the only alterations to the codebase, however. Annotum adds several new capabilities to the Article editor component as well. First, you can insert proper sections (complete with section titles), and add captions to all illustrations or tables. These are semantic markup tags that will be preserved in the final copy. Annotum uses XML to store articles, in the Kipling DTD, a subset of the journal-publishing format specified by the Nation Library of Medicine. There is also a proper equation editor built in — you can use the toolbar buttons or directly type in LaTeX commands, and you can write equations in-line or for display as figures. Finally, you can insert quotations and other references, and have them linked to accurate bibliographic entries that are automatically tracked by Annotum.

All of these changes required changed to the WordPress story editor — as well as to the WYSIWYG HTML editing component that it uses, TinyMCE. But they also required changing how articles are stored. Annotum articles are stored as Kipling DTD XML — the HTML that you see when you visit the page is generated from that. Likewise, whenever you “print” an Annotum article, the PDF it generates comes directly from the XML copy saved, preserving important features, regardless of the output format.

The developers included several other features that journal publishers were interested in, including the ability to do comparisons between revisions of an article, a way to log changes (and to view the change log), and a mechanism for authors and editors to leave back-end-only comments for each other over the life of an article.

Finally, the Annotum team worked with Automattic to have the package thoroughly reviewed and security tested, then added to the WordPress.com site. In case you have always run your own WordPress blog, WordPress.com is a public blogging service that alleviates the need for users to run and maintain their own server. By offering Annotum at WordPress.com, the team gives Knol users and other interested authors and journal projects a simple destination to head to when getting started.

For Future Reference

Frankly, a lot of Annotum’s features may prove themselves useful to other types of WordPress site manager. After all, news sites also need editorial review, many commercial blogs could use a change-log and back-end comment system, and who wouldn’t want a revision-history comparison tool? This is what’s great about open source: one groups of interested users builds a tool that they need, and lo and behold, other people find it valuable, too. If you are starting a journal, or building a peer-reviewed publishing outfit at your college, school, or university — or for that matter, at your company or project — you may find that Annotum fits the bill. Sure, from the outside, visitors will just see HTML, like they would on any other site — but the behind-the-scenes tools make all the difference in this case. They may for other publishing projects as well.