Open Review Toolkit

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.

Overview

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.

Getting Started

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 Vagrantfile.
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 book will create a PDF file of the book and place it in the output/ directory.
make site will 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 vagrant ssh.

Modification Tips

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.

Once these .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 make site.

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 book.erb.

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 website/config.rb.

Troubleshooting

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 ./scripts/google-form-details.rb.
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 config[:google_form_action] setting in website/config.rb with the "Form action" URL specified in the output.
Update the config[:google_form_email_field] setting in website/config.rb with the value associated with your email field from the script output (entry.398259910 in the sample above).

After running 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

After running 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.

Multiple Editions

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:

Update the EDITION variable in the Makefile to 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 website/config.rb.

Need Help?

Feel free to join our mailing list and ask questions or see how other folks are using the project.

Acknowledgements

The Open Review Toolkit is supported by a grant from the Alfred P. Sloan Foundation.

nktoan / open-review-toolkit