Chapter 9 Mapping and Publishing On The Line

This chapter details our design process and web technologies we used to create this open-access digital book. Our interactive web maps, built with open-source Leaflet code, help broader audiences to visualize spatial and historical change over time. The chapter also describes our publishing workflow, based on the open-source Bookdown package for RStudio, which produces both HTML web pages and PDF print pages. We share our knowledge about these tools so that others may innovate and build more digital books to tell their own stories.

List of Interactive Maps and Charts

by Jack Dougherty and Ilya Ilyankou

Interactive Map of Home Value Index in Hartford County, CT, from 1910-2010, https://ontheline.github.io/otl-home-value/index-caption.html

Interactive Storymap of Town Borders in Hartford County, CT, from 1600s to Present, https://ontheline.github.io/otl-town-borders/

Interactive Map of Federal Home Owners’ Loan Corporation “Redlining” in Hartford area, 1937, https://ontheline.github.io/otl-redlining/index-caption.html

Interactive Map of Restrictive Covenants in Hartford area, 1940s, https://ontheline.github.io/otl-covenants/index-caption.html

Interactive Storymap of Hartford Public High School locations, 1847-present, https://ontheline.github.io/otl-hphs/

Publishing On the Line with Bookdown, GitHub, and Zotero

by Jack Dougherty and Ilya Ilyankou

This open-access book is published using open-source tools, featuring Bookdown, GitHub, and Zotero. Publishing with Bookdown allows authors to compose in Markdown (an easy-to-read-and-write computer syntax that works on multiple platforms) and publish in multiple formats (static HTML web edition, PDF edition, ePUB ebook edition, and Microsoft Word documents). Hosting the book in a public GitHub repository, and publishing it with GitHub Pages, easily makes the original text of the book, as well as the published products, available on the public web. Zotero is an open-source bibliography manager that matches the workflow described below to organize citations. For a technical guide to publishing with Bookdown, see Yihui Xie, Bookdown: Authoring Books and Technical Documents with R Markdown, 2018, https://bookdown.org/yihui/bookdown/.

An alternative book publishing platform to consider is Pressbooks. This open-source modification of WordPress multisite also supports multiple publication formats (HMTL web edition, PDF edition, ePUB ebook edition. Authors can use the http://Pressbooks.com paid hosting service. Or, users with advanced WordPress and some system admin skills can download the code from http://github.com/pressbooks and run their own self-hosted book publishing site.

Setup RStudio, Bookdown, and a Latex Engine

Below are steps we followed to setup the publishing platform for this book, using our Macintosh OS 10.14 computers. The same general principles also should apply to Windows computers. No special knowledge is required, but these steps will be easier if users are adventurous or already familiar with R Studio, GitHub, or editing code.

  • Install R Project statistical programming language https://www.r-project.org to build your book with Bookdown. (Yes, we too were surprised to use a statistics package to publish a book, but it works!). See screenshot
  • Install the free RStudio Desktop to make R easier to use with a visual editor. See screenshot
  • Inside RStudio, select the Packages tab, and select Install. See screenshot
  • Inside RStudio, install the “bookdown” package to build your book, and select Install Dependencies. See screenshot
  • Bookdown now should be successfully installed in RStudio. See screenshot
  • Inside RStudio, install the “tinytex” package for Bookdown to create a PDF edition of your book (and see more about PDF edition below) See screenshot
  • Don’t forget: in RStudio console, type tinytex::install_tinytex() and press return to finish the installation. See screenshot

Sidenote: If tinytex installation error

  • In the section above, we received this error message on our Mac computers: /usr/local/bin not writeable. We resolved by reading the software developer’s GitHub issue https://github.com/yihui/tinytex/issues/24 and following these steps:
  • In the Mac Applications > Utilities folder, open the Terminal application.
  • Carefully type sudo chown -Rwhoami:admin /usr/local/bin and press return.
  • Carefully type (without “sudo”) ~/Library/TinyTeX/bin/x86_64-darwin/tlmgr path add and press return.
  • Close the Terminal application.
  • In the RStudio console, type tinytex::install_tinytex(force = TRUE) and press return.

Sidenote: Tinytex vs Xelatex

  • this book currently uses xelatex intstead of tinytex, to avoid some error messages. Modify this in your index.Rmd settings:
    • latex_engine: xelatex

Download and Build a Sample Book

  • Create a free GitHub account https://github.com to share code repositories and publish book editions online.
  • In your web browser, log into your GitHub account, go to the software developer’s bookdown-minimal repo https://github.com/yihui/bookdown-minimal, and fork a copy to your GitHub account. To learn about forking in GitHub, see this chapter http://datavizforall.org/github.html in the Data Visualization for All book.
  • Install GitHub Desktop https://desktop.github.com to transfer files between your online GitHub repo and local computer
  • In your web browser, go to your forked copy of bookdown-minimal and click the green Clone or Download button and select Open in Desktop. This should automatically open the GitHub Desktop application, and you can navigate to copy the code repo to a folder on your local computer.
  • In RStudio in the upper-right corner, select Project > Open Project to open the bookdown-minimal folder on your local computer. See screenshot
  • In RStudio, open the index.Rmd file and make some simple edits to the text of this minimal book. For example, remove the hashtag # comment symbol in line 8 to “uncomment” and activate the PDF book option. Save your edits. See screenshot
  • Optional: Use your preferred text editor, such as Atom editor https://atom.io, to modify the text.
  • In RStudio, upper-right corner, select the Build tab, select Build Book, and choose All Formats to build both the gitbook-style static web edition and PDF edition.
  • If RStudio successfully builds both editions of your minimal book, the output will be saved into your bookdown-minimal folder, in a subfolder named _book, because that’s how this sample is configured. The RStudio internal browser should automatically open your web edition (and it’s not a very good browser, so feel free to close it). Also, open the subfolder and inspect the PDF edition. If RStudio found any errors, they will appear in the Build viewer. See screenshot
  • Hint: In future sessions with RStudio, you may need to select Packages tab and click Update to keep bookdown and other software packages up to date. See screenshot
  • Close RStudio.

Publish your Book with GitHub Pages

  • Open GitHub Desktop and navigate to the bookdown-minimal folder on your local computer. Write a summary to commit (save) the changes you made above to your master branch, and push this version to your online GitHub repo.
  • In your web browser, go to your online GitHub repo, with a web address similar to https://github.com/USERNAME/bookdown-minimal (insert your GitHub username).
  • In your GitHub repo, select Settings, scroll down to the GitHub Pages section (which is a free web hosting service to publish your code and book editions on the public web). Select Master Branch as your source, and Save.
  • Scroll down to this section again, and the web address of your published site should appear. Copy this address.
  • In a new browser tab, paste the web address from above, and at the end add _book/index.html because this sample is configured to store the web edition of your book in this subfolder. Your web address should be similar to: https://USERNAME.github.io/bookdown-minimal/_book/index.html

Customize your Bookdown and GitHub settings

  • To see customized settings for this book, go to its online repository https://github.com/ontheline/ontheline-bookdown
  • In the _bookdown.yml file, the output directory is set to build all book formats into the docs folder.
  • The GitHub Pages settings for this repo (which you cannot view) is set to publish from the master/docs folder, to match the output directory above. This simplifies the published web address to this format: https://USERNAME.github.com/REPONAME
  • Most of the Bookdown configuration settings appear in the index.Rmd file. Read more about these options in the software developer’s technical guide, https://bookdown.org/yihui/bookdown/.
  • In addition, this GitHub Pages repo is published with a custom domain name https://OnTheLine.trincoll.edu. Learn more about custom domain names at https://help.github.com/articles/using-a-custom-domain-with-github-pages/, which usually requires purchasing a domain name from a web hosting service (such as http://ReclaimHosting.com). Adding a GitHub Pages custom domain name creates an additional CNAME file in the docs subfolder. Be careful not to delete it (or place a copy in a subfolder for safekeeping).
  • This book also includes a custom 404.html file that was manually transferred into the docs subfolder, since it is not automatically built by Bookdown.
  • This book also includes a custom google-analytics-otl.html file in the root-level of repo (where bookdown looks for it) and also is manually transferred to the docs subfolder (since bookdown does not appear to copy it to there on each build). This tracks web traffic with Google Analytics.

9.0.0.1 About PDF edition

The Bookdown-generated PDF edition is still a work-in-progress. Read more about various options at https://bookdown.org/yihui/rmarkdown/pdf-document.html. Currently using xelatex engine (see bookdown.yml settings) to avoid unicode errors, but images are not ideal.

On The Line Style Guide with Bookdown-flavored Markdown

Code comments

<!-- this comment appears in the source code, but not the book outputs -->

Use brackets and parentheses for an embedded link

Use parentheses only for a non-embedded link (http://example.com)

Similarly, display URL with angle brackets: http://example.com

If necessary, use HTML to create link that opens in a new page

Zotero Settings and Footnotes

This workflow uses open-source Zotero bibliography manager (http://zotero.org) with Better BibTeX extension (https://retorque.re/zotero-better-bibtex/). See Better BibTeX installation. This allows the author to insert footnote codes (example: @tyackOneBestSystem1974) and configure bookdown settings (such as Chicago note format) that pull footnotes from a recently downloaded Zotero collection, rather than typing each note directly into the book.

Zotero preferences > Better BibTeX

  • add URLs to BibTeX export > in a note field
  • when ref has both DOI and URL, export > both

To export from Zotero:

  • select library > right-click to export collection
  • select format > Better BibLaTeX (IMPORTANT I switched to this format to include full dates in newspaper citations, and urls) and leave checkboxes blank (I do not use “keep updated”)
  • save output as ontheline.bib (or whatever matches your config settings) and save into book repo

Chicago full-note appears to be working exactly as it was designed, meaning that the second instance of a citation currently appears as an abbreviated note (Author, title when appropriate). Ideally, modify the CSL to show full note in every instance in the web version.

These Zotero types appear correctly with this Bookdown workflow:

  • book
  • book chapter
  • journal
  • newspaper
  • thesis
  • report
  • blog post
  • web page
  • document (use this in place of: law case, presentation, interview, video recording, television broadcast; insert details, such as archival location, in the Publisher field)

A text-only footnote.190

BibText footnote with semi-colons to separate cites:191

Markdown caret-footnote, which can accept multiple references with complex punctuation.192

Subheadings need four hashtags and no-number symbol

Note: Using three hashtags makes the subheader appear in the TOC because I have not found way to control toc_depth in web output. Use the no-number symbol to prevent automatic number of subheaders.

Figures: Static Images and Interactive Content

In body of the book, avoid inserting images with simple Markdown syntax, because it lacks auto-numbering. (In the preface, use simple Markdown syntax for static images, because Bookdown does not auto-number figures in the index.Rmd file.)

Instead, follow this R code chunk method, especially to display interactive content on the HTML web edition, with static screenshot images in the PDF edition:

  • Define a text reference for captions with complex formatting, because this method accepts RMarkdown cites and links. See Bookdown section 2.2.4
  • Leave a BLANK LINE between the text reference and the code chunk coming up
  • Insert an R code chunk https://bookdown.org/yihui/bookdown/r-code.html, with NO SPACES between ref:chunk-label, and follow with an if-else statement from Michael Dorman, to display interactive version in HTML and static version in PDF.
  • STILL TO DO:
    • Find code fix to gain control over HTML iframe height (> 400px) and also width (ideally 90%)
    • Find code fix to insert a formatted title or header immediately above the image. Ideally, Use equivalent of 5 hashtags for digital image headers, and imperative verbs to hint interactive use (eg. Explore the Map….)
    • Decide whether to insert fig.align="center"
    • Decide if auto.PDF=TRUE is necessary

REMINDER: If the image/map/video appears a second time in the book (in a separate chapter), be sure to relabel ref: year-title2

Example: Static image, with no interactive version
Caption for sample static image, with Markdown formatting, links, citation.

Figure 9.1: Caption for sample static image, with Markdown formatting, links, citation.

Example: Interactive map

Figure 9.2: Scroll down the narrative (or click and use arrow keys) in this interactive map to see how Hartford County, Connecticut was divided into 29 separate towns from the early 1600s to the late 1800s. Boundaries shown here are not exact, but approximated from the best available digital sources: UConn Libraries MAGIC historical maps, Atlas of Historical County Boundaries at Newberry Library, and the Connecticut State Register and Manual. View map historical sources, known issues, and the code, developed by Ilya Ilyankou and Jack Dougherty.193

Example: Vimeo video clip

Figure 9.3: Here’s a sample Vimeo caption, with option to add Markdown link and footnote.

Example: YouTube video clip

Figure 9.4: Here’s a sample YouTube caption, with option to add Markdown link and footnote.

Example: CTDA video clip

Figure 9.5: Here’s a sample CTDA video caption, with option to add Markdown link and footnote.

Example: Kaltura video clip

Figure 9.6: Here’s a sample Kaltura video caption, with option to add Markdown link and footnote.

Example: Scrollable local PDF

Figure 9.7: Here’s a sample local scrollable PDF caption, with option to add Markdown link and footnote.

9.0.0.2 Tables

For now, use Markdown table formatting, with header above and text (as caption) below

About this book

On The Line is an open-access, born-digital, book-in-progress by Jack Dougherty and contributors at Trinity College, Hartford CT, USA. This work is copyrighted by the authors and freely distributed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 Interational License. Learn about our open-access policy and code repository and how to read and cite our work.

This book-in-progress was last updated on: 2019-07-15


  1. This is a footnote, with no reference

  2. Hirsch, Making the Second Ghetto; Jackson, Crabgrass Frontier; Tyack, The One Best System.

  3. On this theme, see Jack Dougherty, “Review of ’Connecticut’s Public Schools: A History, 1650-2000’ by Christopher Collier,” Connecticut History 50, no. 1 (2011): 120–22, http://digitalrepository.trincoll.edu/cssp_papers/41. On a different theme, see Dougherty et al., “School Choice in Suburbia.”, pp. 33-35

  4. Ilyankou and Dougherty, “Map,” 2017