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.
You can use a tool like Pandoc to convert a
.docx book into
markdown. This generated markdown file should then be separated into chapters and saved into the root of the project. You can take a look at some of the sample files within this repository's source code for naming conventions, and how these files should be structured.
.md files have been created,
make book will read these files and generate the eBook. In addition to the PDF file of the book in the
/output directory, an html file will be generated within
website/book-html. This html file will be used to serve the site locally with
Navbar linked pages can be modified from within the
website/source/localizable directory. You will also need to create the appropriate
<li> nav item from within the
base.erb layout file to get these links to appear in the navbar. Notice cards and email collection forms can be modified within
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
You may run into a situation where the generated html build in the browser doesn't exactly match the expectation, based on the markdown chapter copy. For instance, certain chapters or subheadings may be incorrectly nested, or some body paragraphs may get omitted.
If there are no apparent errors in the markdown files, one way to address this is to manually modify the generated html file in
webiste/book-html. This should only be done sparingly, in order to address edge cases. The eBook build should instead, rely mainly on markdown files in order to maintain the integrity of the automated parser functionality. Should you decide that a manual change in the html output file is necessary, it is recommended to catalog these changes so that they can be referred to when proof-reading, or finalizing eBook copy.
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.