9.4 On The Line Style Guide for Bookdown + RMarkdown

NOTE: View this file and the code used to create the examples directly on the GitHub repo at https://github.com/OnTheLine/otl-bookdown/blob/master/09.4-style-guide.Rmd.

Also, this style guide was created primarily for the web edition http://OnTheLine.trincoll.edu, and may require additional modifications for the final PDF print edition.

Use HTML-style code comments to insert notes that are invisible to most readers, yet visible to authors (or anyone) viewing the public GitHub repo

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

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 tags to create link that opens in a new page

Preface and Footers

In this book, index.Rmd begins with a non-numbered first-level header # Preface {-}, followed by non-numbered second-level headers such as ## Authors and Contributors {-} and ## Acknowledgements {-}. All of this content is placed in the index.Rmd file because creating zero-numbered files (such as 0.1-about.Rmd) generated Bookdown errors.

Also, at the end of each section in the main text, a footer has been manually pasted that includes HTML links to sections in the Preface. The purpose of the footer is to ensure that each long web page contains author and copyright information, in case readers print out individual web pages from their browsers. Also, manually inserting a footer is not ideal, but we have not yet created a custom-script that performs the same function.

Formatting and Footnotes

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:

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

A text-only footnote.222

To create a footnote with citations only, separate BibTeX citation keys with semi-colons:223

Since footnotes also may include text and punctionation in Markdown syntax, always insert a caret symbol prior to the brackets to demarcate a footnote:224

Figures: Interactive Content and Static Images

In body of the book, avoid inserting images with simple Markdown syntax, because it lacks auto-numbering. 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:

Overview of steps
  • Define a text reference for captions, because this method accepts complex syntax, such as RMarkdown cites and links, as shown below. For details, see Bookdown sections on Figures https://bookdown.org/yihui/bookdown/figures.html and Markdown extensions https://bookdown.org/yihui/bookdown/markdown-extensions-by-bookdown.html.
  • Insert a BLANK LINE between the text reference and the R code chunk coming up.
  • Insert an R code chunk https://bookdown.org/yihui/bookdown/r-code.html, with NO SPACES between ref:chunk-label, as shown below.
  • To reduce the width (or height) of the output, add out.width="30%" to the code chunk, which works for Web edition and also PDF edition. If width is less than full, also insert fig.align="center".
  • To display interactive content in the Web edition and a static image in the PDF edition, create both elements and insert an if-else statement in the R code chunk to display these elements in different outputs, as shown below. (Thanks to Michael Dorman for this tip.)
  • If the interactive content includes an iframe (for a map or chart), the default height will be 400 pixels. To adjust the iframe height (or width), insert a line of code in custom-scripts.html and add a code comment to the text to serve as a reminder, as shown below. Also, make sure that the index.Rmd file includes the custom script in the header, as described in the section above.
    • Optional: In the body text, insert a dynamic reference to the figure in the same file, because PDF engine creates floating images that may be placed on the next page. Sample dynamic reference to a figure further below: … as shown in Figure 9.3.
  • Reminders:
    • If the image appears a second time in the book, in a separate chapter, be sure to relabel the text ref: year-title2.
    • Bookdown does not auto-number figures in the index.Rmd file, which serves as a preface or introduction.
  • STILL TODO
    • Decide if ‘out.width’ and ‘out.height’ is preferable in all cases to "fig_height=7"
    • Accessibility: use alt="" for brief image description? Or do the detailed captions replace this need?
    • About auto_pdf: “include_graphics() can be smart enough to use PDF graphics automatically when the output format is LaTeX and the PDF graphics files exist, e.g., an image path foo/bar.png can be automatically replaced with foo/bar.pdf if the latter exists. PDF images often have better qualities than raster images in LaTeX/PDF output. To make use of this feature, set the argument auto_pdf = TRUE, or set the global option options(knitr.graphics.auto_pdf = TRUE) to enable this feature globally in an R session.” from https://bookdown.org/yihui/bookdown/figures.html
Example: Static image in all editions, half-size output, no interactive version
Caption for sample static image, with Markdown formatting, links, citation.

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

Example: Interactive iframe in web edition (with adjusted height), static image in PDF edition

Figure 9.3: Caption for all versions here, with link to full-screen interactive map with its own caption, and link to sources and the code View map historical sources, known issues, and the code, developed by Ilya Ilyankou and Jack Dougherty, with footnote.225

Example: YouTube video clip in web edition, static image in PDF edition

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

Example: Vimeo video clip in web edition, static image in PDF edition

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

Example: CTDA video clip in web edition, static image in PDF edition

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

Example: Kaltura video clip in web edition, static image in PDF edition

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

Example: Scrollable PDF in web edition, static screenshot in PDF edition

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

Tables

For now, use Markdown table formatting, with header above and caption (in italicized text) below. See http://www.tablesgenerator.com/ with Markdown output. TODO: Decide on Bookdown-recommended kable package for tables, link to CSV in GitHub repo, and so on.

Sample table
Header 1 Header 2 Header 3
Security Grade Second Third
Location Hartford Hartford
Trend Next Decade Stable Stable

In the table above, insert a caption in italics, with optional links and footnote.226

References for above

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 International 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-08-13


  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

  5. Ilyankou and Dougherty, “Leaflet Map of HOLC "Redlining" Security Map for Hartford CT Area, 1937.”