Style Guide

View the source code to better understand how this page was composed at: https://github.com/HandsOnDataViz/bookdown-template/blob/master/01-bookdown.Rmd

This book is composed in R-flavored Markdown (.Rmd), and each paragraph begins on a separate line. O’Reilly style guide prefers italics rather than bold. Use single back tics to display a monospaced code word.

Insert an embedded link to O’Reilly. This appears as a colored clickable link in HTML and Word editions, and a non-colored but clickable link in the PDF edition. According to O’Reilly Atlas documentation, the AsciiDoc version should automatically unfurl for the printed edition.

For lists, always insert a blank line before the items, unless they appear directly after hashtag header.

• unordered
• list

1. ordered
2. list

Dashes:

• Use a hyphen (1 dash) for hyphenated words, such as two-thirds or dog-friendly hotel.
• Use an en-dash (2 dashes) for ranges, such as the May–September magazine issue.
• Use an em-dash (3 dashes) to insert an additional thought—like this—in a sentence.

Insert TODO to note items to finish or review with co-author or editor.

Insert three back tics to insert a code block. Check character line length limits in O’Reilly style guide:

<link rel="stylesheet" href="https://unpkg.com/leaflet@1.6.0/dist/leaflet.css" />
<script src="https://unpkg.com/leaflet@1.6.0/dist/leaflet.js"></script>

Conditional Formatting

Conditional formatting offers the option to display text or images in some editions, but not other editions. Options:

1. Insert a HTML code comment <!-- Comment --> in the .Rmd file to hide a few lines of text. This appears as commented-out text in the HTML and .md formats, is not displayed in the HTML browser, and does not appear in any way in the PDF, MS Word or AsciiDoc formats.

Demo:

2. R package function is_[html/latex]_output allows conditional output for different book products, such as text that should appear in the HTML edition but not the PDF edition, or vice versa.

Demos:

This line appears in the HTML, Word, Markdown, and AsciiDoc versions, and is commented-out in the PDF version.

TODO: Create conditional formatting that displays only in the HTML edition, and allows the inclusion of R code-chunks to conditionally display images. See links for more complex conditional formatting:

• https://stackoverflow.com/questions/56808355/how-to-conditionally-process-sections-in-rmarkdown
• https://bookdown.org/yihui/rmarkdown-cookbook/latex-html.html
• https://blog.earo.me/2019/10/26/reduce-frictions-rmd/
• https://stackoverflow.com/questions/53861244/html-specific-section-in-bookdown
• https://stackoverflow.com/questions/41084020/add-a-html-block-above-each-chapter-header
• https://stackoverflow.com/questions/45360998/code-folding-in-bookdown

3. Option to customize the style.css code for the HTML book.

4. Option to add headers, footers, preambles to the HTML or LaTeX versions.

5. Build different versions of the HTML and LaTeX (PDF) books using different chapters by listing them in order in the _bookdown.yml file:

rmd_files:
  html: ["index.Rmd", "abstract.Rmd", "intro.Rmd"]
  latex: ["abstract.Rmd", "intro.Rmd"]

Cross-references

In order to cross-reference in Bookdown, assign a unique name or R code-chunk label to each chapter, section, figure, and table. Unique names and labels should contain only alphanumeric characters (a-z, A-Z, 0-9) or dashes (-).

To cross-reference any chapter or section, and allow readers to jump there, use a HTML link with the unique name, such as index.html or style-guide.html. Demos:

• See Preface
• See “Style Guide” in Chapter x.

Contrary to the Bookdown manual, avoid using Bookdown unique ID links to cross-reference chapters or sections, because these create extraneous and imprecise URLs, such as this example: Chapter 1 “Style Guide”

To cross-reference figures and tables, and display their auto-number and allow readers to jump there, write a call-out with a Bookdown reference to a code-chunk label, such as See Figure \@ref(fig:sample-map) or See Table \@ref(tab:left-table). Demos:

• See Figure 1.1.
• See Table 1.1.

Cross-reference interactivity varies by output:

• In HTML, all cross-refs are clickable.
• In PDF, all cross-refs are clickable (except chapter-level HTML links).
• In Word, no cross-refs are clickable (unless this varies with reference.docx).
• TBA with Markdown (.md) and AsciiDoc.

When writing cross-references in the text, the O’Reilly Style Guide prefers live cross references (e.g., “see Figure 2-1”), but if not feasible, use “preceding” or “following” because physical placement of elements may vary across print and digital formats. Avoid using “above” or “below.”