Publishing DataVizForAll with Bookdown

by Jack Dougherty and Ilya Ilyankou, last updated February 13, 2019

This open-access book is published using open-source tools, featuring Bookdown with RStudio and GitHub. 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. 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 TinyTeX

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. See screenshot
  • Don’t forget: in RStudio console, type tinytex::install_tinytex() and press return to finish the installation. See screenshot

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.

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 this 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/datavizforall/dataviz-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://DataVizForAll.org. Learn more about custom domain names at https://help.github.com/articles/using-a-custom-domain-with-github-pages/, which 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-datavizforall.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.

DataVizForAll Style Guide with Bookdown-flavored Markdown

Bookdown-flavored Markdown Syntax

For an em-dash, use three hyphens—like this—rather than two hyphens.

For a block quote, start each line with a caret AND add two spaces to insert a line break:

Code:

> I thoroughly disapprove of duels. If a man should challenge me, I would take him kindly and forgivingly by the hand and lead him to a quiet place and kill him.    
> --- Mark Twain  
> --- notable American author

Demo: > I thoroughly disapprove of duels. If a man should challenge me, I would take him kindly and forgivingly by the hand and lead him to a quiet place and kill him.
> — Mark Twain
> — notable American author

Simple footnote

Code:

A text-only footnote.^[This is a footnote, with no reference]

Demo: A text-only footnote.1

See On The Line book (http://OnTheLine.trincoll.edu) for more details about footnotes using Zotero and Better BibTeX.

Embed images and iframes

Insert image using Markdown syntax:

Code:

![Caption using markdown: auto-number does not appear in web, but appears in pdf, text *with italics*, no center-alignment on web, but centered in PDF, with [source link](https://google.com)](images/sample.jpg)

Demo:

Caption using markdown: auto-number does not appear in web, but appears in pdf, text with italics, no center-alignment on web, but centered in PDF, with source link

Caption using markdown: auto-number does not appear in web, but appears in pdf, text with italics, no center-alignment on web, but centered in PDF, with source link

Explore the Chart: embedded HTML iframe

Code:

<iframe src="https://datavizforall.github.io/highcharts-scatter-csv-instructor-sample/" width="90%" height="420px"></iframe>
Recommended: Insert caption and link to view the full-screen version.

Demo:

Recommended: Insert caption and link to view the full-screen version.

Scroll the Map: embedded HTML iframe

Code:

<iframe src="https://ontheline.github.io/otl-town-borders/" width="90%" height="525px"></iframe>
Recommended: Insert caption and link to view the full-screen version.

Demo:

Recommended: Insert caption and link to view the full-screen version.

Watch the YouTube Video: embedded HTML iframe from secure https

Code:

<iframe width="560" height="315" src="https://www.youtube.com/embed/Gl3uIRYYUmI?rel=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
Recommended: Insert caption and link to view the full-screen version.

Demo:

Recommended: Insert caption and link to view the full-screen version.

Output in other formats

This book is being built primarily for the web edition, and will require more work to create formatted PDF and EPUB versions.

Add this later to index.Rmd, and correctly place and indent it

      download: [pdf, epub, mobi, docx]

And also add this to index.Rmd, and correctly place and indent it

bookdown::pdf_book: default

bookdown::epub_book:
  dev: svglite
  stylesheet: css/style.css

bookdown::word_document2:
  default

  1. This is a footnote, with no reference