Open Review Toolkit: Better books, Higher sales, Increased access to knowledge
HTML Ruby CSS Makefile JavaScript Shell Other
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
figures
output
provisioning
scripts
support
tests
website
.gitignore
.travis.yml
01-introduction.md
02-another-chapter.md
99-references.md
Gemfile
Gemfile.lock
LICENSE
Makefile
README.md
Vagrantfile
_01-acknowledgements.md
_02-preface.md

README.md

Open Review Toolkit Build Status

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

  1. Download and install Vagrant.
  2. Download the soure code by either cloning the git repository or downloading the latest release.
  3. 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 call Vagrantfile.
  4. 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.
  5. Once the previous command has completed, run vagrant ssh. You are now inside the Vagrant VM, which includes all the dependencies for the project.
  6. make book will create a PDF file of the book and place it in the output/ directory.
  7. 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.

The Open Review websites are build for to be integrated with Google Analytics. In order configure the your Open Review website to use your Google Analytics account, you must update the ga_code configuration item in website/config.rb.

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:

  1. Create a new blank Google Form.
  2. Give the form a title.
  3. Create a question named "Email" that accepts a "Short answer".
  4. Click the "Preview" link for the form (eye icon).
  5. Copy URL of the form preview.
  6. Inside the Vagrant VM (via vagrant ssh), execute ./scripts/google-form-details.rb.
  7. 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
    
  8. Update the config[:google_form_action] setting in website/config.rb with the "Form action" URL specified in the output.
  9. 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.

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.