For my current project, the Open Digital Archaeology Textbook Environment (ODATE for short; I’m rubbish at a) names and b) acronyms) Neha, Michael, Beth and I are trying to use Slack to manage our conversations, and writing instead in a series of markdown files, and use a repo to manage the collaboration, resolve conflicts, etc. Right now this is going swimmingly because for various reasons the rest of the gang can’t devote any time to this project. For my part, I’m trying to get the infrastructure and preliminary writing set up so we can hit the ground running in around mid march.

Given our requirements outlined above, I looked around at a couple of different platforms, settling eventually on Bookdown . I like Bookdown because I can write in whatever editor strikes my fancy (switching into R to do the build) and it will give me a complete flat website (with search), an epub, and a PDF, grabbing my citations from a Bibtext file and formatting appropriately (we have a collaborative Zotero library for adding to while we write/research; export to Bibtext, boom!). Right now, I’m writing within RStudio. With some minimal tweaking, it also allows me to build in Hypothes.is collaborative annotation (and via the Hypothesis API, I plan on collating annotations periodically to guid revisioning and also perhaps to build into the book user appendices, but that idea is still nebulous at the moment). I’ve also run the resulting website from Bookdown through various web accessibility tools, and the report comes back fairly positive. With some more tweaking, I think I can make the final product super-accessible, or at the very least, produce PDFs that screenreaders and so on can work with.

Getting Bookdown set up was not without its idiosyncracies. The RStudio version has to be the preview release. Then:

create a new project in RStudio (do this in a brand new folder) run the following script to install Bookdown: install.packages("devtools") devtools::install_github("rstudio/bookdown")

create a new textfile with metadata that describe how the book will be built. The metadata is in a format called YAML (‘yet another markup language’) that uses keys and values that get passed into other parts of Bookdown: title: "The archaeology of spoons" author: "Graham, Gupta, Carter, & Compton" date: "July 1 2017" description: "A book about cocleararchaeology." github-repo: "my-github-account/my-project" cover-image: "images/cover.png" url: 'https\://my-domain-ex/my-project/' bibliography: myproject.bib biblio-style: apa-like link-citations: yes This is the only thing you need to have in this file, which is saved in the project folder as index.Rmd.

Write! We write the content of this book as text files, saving the parts in order. Each file should be numbered 01-introduction.Rmd, 02-a-history-of-spoons.Rmd, 03-the-spoons-of-site-x.Rmd and so on. Build the book. With Bookdown installed, there will be a ‘Build Book’ button in the R Studio build pane. This will generate the static html files for the book, the pdf, and the epub. All of these will be found in a new folder in your project, _book. There are many more customizations that can be done, but that is sufficient to get one started. To get Hypothesis working, we have to modify the _output.yml file:

bookdown::gitbook:
  includes:
      in_header: hypothesis.html

That html file is just a file with a single line, where you add the script src line for embedding hypothesis (see this guidance).

You end up with a Gitbook-looking site.