I’m happy to announce the release of the Open Review Toolkit, open source software that enables you to convert your book manuscript into a website that can be used for Open Review. During the Open Review process everyone can read and annotate your manuscript, and you can collect valuable data to help launch your book. The goals of the Open Review process are better books, higher sales, and increased access to knowledge. In an earlier post, I described some of the helpful feedback that I’ve received during the Open Review of my book Bit by Bit: Social Research in the Digital Age. Now, in this post I’ll describe more about the Open Review Toolkit—which has been generously supported by a grant from the Alfred P. Sloan Foundation—and how you can use it for your book.
As described on the project’s website, the Open Review Toolkit is a set of open source scripts that you can download and use to convert your manuscript to an Open Review website. One way to think about it is that the Open Review Toolkit is the plumbing that ties together four outstanding projects: Hypothes.is, Pandoc, Google Analytics, and Google Forms. Full technical details and all the code are available from the Open Review Toolkit GitHub repository, but here’s an overview.
The build process that converts a manuscript into an Open Review website is codified in a single Makefile and has three primary steps:
- Pandoc converts the book manuscript into a single HTML file.
- A set of custom scripts enrich the single HTML (e.g., with richer information about each citation) and then split the single HTML file into a bunch of different HTML files, one for each section of the book.
- Middleman uses those HTML files and some custom templates to create the Open Review website, which is a static HTML website.
Step 1
Pandoc converts the book manuscript into a single HTML file. Currently, the only supported input format for this first step is Markdown. In other words, at this time, your manuscript must be written in Markdown. However, Pandoc supports a variety of formats as inputs, and in the future we hope to add support for additional input formats, such as LaTeX and Word. If you’d like to help build support for additional input formats, please get in touch.
Step 2
The custom scripts enrich and split the HTML output from Pandoc. First, an enrichment script adds information to each citation. In the future, additional enrichments could also be added at this step. Next, the splitting script splits the single HTML file into one file for each section of the book. These sections are then placed in directory structure that reflects to hierarchy of the sections in the manuscript. This splitting script also creates a JSON file that includes metadata about the manuscript structure. This JSON metadata file that allows the Middleman build process to create things such as the table of contents and previous / next page links between sections.
Step 3
Middleman builds the Open Review website, which is a static HTML website. The Middleman project lives inside the website/ directory. This project is pre-populated with existing layouts that include Google Analytics, Hypothes.is, and navigational elements for the site. This is also where pages that are part of the Open Review website but are not part of the manuscript reside (e.g., an About page). The HTML files from step 2 are used as the primary content for each book page on the site. These HTML files should not be manually modified as they will be overwritten the next time the site is built.
This entire build process takes place inside of a virtual machine we created that comes pre-installed with all the open-source software that you will need. By using this virtual machine, we hope to ensure that the Open Review Toolkit will work right the first time no matter what operating system you are using.
Once those three steps are complete, you have a set of static html files that you can host anywhere that you want (for my book, we are using GitHub pages). On the Open Review Toolkit website, I also describe additional features of the Open Review websites.
We’ve tried to make it as easy as possible to convert your manuscript into a modern and functional Open Review website. All of our code is open source, but if you’d like to hire a developer to help you do the conversion, the Open Review Toolkit has a recommend list of Preferred Partners.
The Open Review Toolkit, which was inspired by earlier innovations in academic publishing, would not have been possible without the help of many people. I would like to thank the folks at the the Agathon Group, particularly Luke Baker (coding) and Paul Yuen (design) who built the Open Review website for my book Bit by Bit: Social Research in the Digital Age. The Open Review Toolkit grew out of that initial code and design. I would also like to thank Meagan Levinson and Princeton University Press for their support during the first Open Review process. Further, I would like to thank the Alfred P. Sloan Foundation for their support of the Open Review Toolkit. Finally, the Open Review Toolkit builds on some amazing open source software. I’d like to thank everyone who contributed to the project we used in the Open Review Toolkit: Pandoc, LaTeX, hypothes.is, Vagrant, Ansible, Middleman, Bootstrap, Nokogiri, GNU Make, and Bundler.
