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:

  1. Pandoc converts the book manuscript into a single HTML file.
  2. 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.
  3. 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.

Next steps