The Open Review Toolkit 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 your manuscript and help make it better, and you can collect valuable feedback to improve the manuscript and help launch your book.
You can view a sample site generated by this repository.
The Open Review Toolkit contains 1) a template for a book written in Markdown and 2) a virtual machine with all the neccesary open-source software pre-installed. The template includes a few files that contain the content of the book, a few supporting files (e.g., figures, bibtex files), and a make file that converts your manuscript into either a PDF or a website. You can drop your book's content into this template, and you can even extend the template's basic structure to suit your needs. If you follow the same basic structure as the template, then the make file should continue to work.
The virtual machine is basically a standard Linux box pre-installed with the open-source software that is needed to power the make file (e.g., pandoc, LaTeX). This virtual machine ensures that the Open Review Toolkit works in the same way on different computers. This virtual machine is roughly 1.5 GB in size and will be downloaded during the first time through the steps below. If you're interested to see how this virtual machine is built and what software is installed, take a look at the vagrant-build repository.
Unfortunately, at the moment, the Open Review Toolkit only supports manuscripts in Markdown. If your book is currently in LaTeX, Word, or some other format, you can convert it to Markdown. Or, you can contact us. We're interested in developing the codebase to support LaTeX and Word.
- Download and install Vagrant.
- Download the soure code by either cloning the git repository or downloading the latest release.
- Once you've cloned the git repository or extracted the release source code, open your favorite terminal and navigate to the directory the holds the source code. You should see several files and directories in this directory, including a file called
- From your terminal, run:
vagrant up. The very first time you run this command it will download the virtual machine image, roughly 1.5GB of data, so it may take a few minutes or more depending on the speed of your internet connection.
- Once the previous command has completed, run
vagrant ssh. You are now inside the Vagrant VM, which includes all the dependencies for the project.
make bookwill create a PDF file of the book and place it in the
make sitewill build an Open Review site from the book. After building the site, you can view it in your browser by visiting: http://0.0.0.0:17278/. This link only works on your local machine. See the Hosting Your Site section before for how to publish your site publicly.
As you make changes to the Markdown files that contain the content of your book, you will need to re-run the relevant
make command above in order to re-build the PDF and/or site. Once you're done working with the Vagrant VM, it's a good idea to shut it down with
vagrant halt. The next time you want to start again, you can run
vagrant up and
Reminder: after you make any improvements to your book (by editing the Markdown files), you'll need to re-run the appropriate
make command to re-build the PDF or site.
The sample site includes some details on how to customize your site.
The Open Review websites are built to be integrated with Google Analytics. In order to configure your Open Review website to use your Google Analytics account, you must update the
ga_code configuration item in
Setting up email collection with Google Forms
The sample site includes some email collection forms, which can interact with Google Forms. Here are the steps for setting that up:
- Create a new blank Google Form.
- Give the form a title.
- Create a question named "Email" that accepts a "Short answer".
- Click the "Preview" link for the form (eye icon).
- Copy URL of the form preview.
- Inside the Vagrant VM (via
vagrant ssh), execute
- Paste URL from the form preview page when the script asks for it and press enter. You should see something like this:
vagrant@vagrant:~/open-review-toolkit$ ./scripts/google-form-details.rb Enter public Google Form URL: https://docs.google.com/forms/d/e/1FAIpQLSdEFEOnkR_JeKdEIK-9MwG-5zP78qpiQSSBeM2DIKUYYqGyUw/viewform Form action: https://docs.google.com/forms/d/e/1FAIpQLSdEFEOnkR_JeKdEIK-9MwG-5zP78qpiQSSBeM2DIKUYYqGyUw/formResponse Email: entry.398259910
- Update the
website/config.rbwith the "Form action" URL specified in the output.
- Update the
website/config.rbwith the value associated with your email field from the script output (
entry.398259910in the sample above).
make site, you should be able to test that everything is working and see your email address show up in the "Responses" tab of your Google Form. You can also download the responses as a CSV.
Hosting Your Site
make site, the complete website is available as static HTML pages and assets in the
website/build/ directory. These can be copied over to the web host of your choice. You can also use a static web site host like GitHub Pages.
Open Review Toolkit supports having multiple editions for a book. For example, you may want to first publish an "open-review" edition and then later publish the first edition of the book. To add an additional edition:
EDITIONvariable in the
Makefileto have the URL slug you want to use for your new edition.
Add this same slug to the beginning of the list of editions in
Feel free to join our mailing list and ask questions or see how other folks are using the project.
The Open Review Toolkit is supported by a grant from the Alfred P. Sloan Foundation.