20.2-structure.Rmd

## File Structure and Headers {- #structure}
To understand our file structure, see the GitHub repository for this book at <https://github.com/handsondataviz/book>.

In general, each chapter is a separate .Rmd file. As co-authors, we are careful to work on different chapters of the book, and to regularly push our commits to the repo. Only one of us regularly builds the book with Bookdown to avoid code merge conflicts.

Here is a simplified outline of the root file structure in the GitHub repo for this book:

- Preface of the book with non-numbered sections: `index.Rmd`
- Chapters with first-level headers in this format: `01-chapter.Rmd`
- Occasionally, we use some subchapters with second-level headers in this format: `01.1-subchapter.Rmd`. While Bookdown refers to these as sections, we call them subchapters.
- The `images` folder, where PNG, JPG, and PDF images to display in chapters are located.
- The `docs` folder, which contains the published book products, such as Web edition (`index.html`, `introduction.html`, etc.), the PDF edition (`HandsOnDataViz.pdf`), etc.
- Additional helper files described further below.

When you change the names of chapters/sections, Bookdown builds new HMTL pages based on those new names, but old HMTL pages based on old chapter/section names may still exist in the same subfolder. To avoid confusion, you may wish to carefully delete old HTML pages in `docs` whenever you significantly alter names and build a new version of the book.

Bookdown assigns a default ID to each header, which can be used for cross-references. The default ID for `# Topic` is `{#topic}`, and the default ID for `## Section Name` is `{#section-name}`, where spaces are replaced by dashes. But we do *not* rely on default IDs because they might change due to editing or contain duplicates across the book.

Instead, we *manually assign a unique ID* to each first- and second-level header in the following way. Note that the `{-}` symbol, used alone or in combination *with a space* and a unique ID, prevents auto-numbering in the second- thru fourth-level headers:

```
# Top-level chapter title {#unique-name}
## Second-level section title {- #unique-name}
### Third-level subhead {-}
#### Fourth-level subhead {-}
```

Also, we match the unique ID keyword to the file name for top-level chapters this way: `01-keyword.Rmd` to keep our work organized. Unique names should contain only _alphanumeric_ characters (a-z, A-Z, 0-9) or dashes (-).

Subheaders must have unique names or IDs to avoid Bookdown errors about duplicated references. To avoid this issue for repeated subheaders (such as “Summary”), at the end of each chapter insert a third-level summary subhead, but use a unique ID that matches each chapter number, like this: `### Summary {- #summary17}`

A special header in this book is the unnumbered header beginning with `(APPENDIX)`, which indicates that all chapters appearing afterwards are appendices. According to [Bookdown](https://bookdown.org/yihui/bookdown/markdown-extensions-by-bookdown.html), the numbering style will appear correctly in HTML and LaTeX/PDF output, but not in Word or ebooks.

```
# Chapter One

# Chapter Two

# (APPENDIX) Appendix {-}

# Appendix A

# Appendix B
```

In the Bookdown `index.Rmd` for the HTML book output and the PDF output, the `toc_depth: 2` setting displays chapter and section headers down to the second level in the Table of Contents.

The `split_by: section` setting divides the HTML pages at the second-level header, which creates shorter web pages with reduced scrolling for readers. For each web page, the unique ID becomes the file name, and is stored in the `docs` subfolder.

The `number_sections` setting is true for the HTML and PDF editions, and given the `toc_depth: 2`, this means that they will display two-level chapter-section numbering (1.1, 1.2, etc.) in the Table of Contents. Note that `number_sections` must be true to display Figure and Table numbers in x.x format, which is desired for this book. See relevant settings in this excerpt from `index.Rmd`:

```
output:
  bookdown::gitbook:
    ...
    toc_depth: 2
    split_by: section
    number_sections: true
    split_bib: false
    ...
bookdown::pdf_book:
  toc_depth: 2
  number_sections: true
```

Note that chapter and section numbering do *not* appear automatically in the MS Word output unless you supply a reference.docx file, as described in the [RMarkdown guide](https://bookdown.org/yihui/rmarkdown/word-document.html) and this [Stack Overflow question](https://stackoverflow.com/questions/52924766/numbering-and-referring-sections-in-bookdown).

In the `_bookdown.yml` settings, all book outputs are built into the `docs` subfolder of our GitHub repo, as shown in this excerpt:

```
output_dir: "docs"
delete_merged_file: true
book_filename: "HandsOnDataViz"
language:
  label:
    fig: "Figure "
    tab: "Table "
chapter_name: "Chapter "
```
In our GitHub repo, we set GitHub Pages to publish to the web using `main/docs`, which means that visitors can browse the source files at the root level, and view the HTML web pages hosted in the `docs` subfolder. We use the GitHub Pages custom domain setting so that the HTML edition is available at https://HandsOnDataViz.org.

The `docs` subfolder also may contain the following items, which are *not* generated by Bookdown and need to be manually created:

- `CNAME` file for the custom domain, generated by GitHub Pages.
- `.nojekyll` invisible empty file to ensure speedy processing of HTML files by GitHub Pages.
- Note: Bookdown now generates a `404.html` redirect file, which replaces the prior need to create and manually transfer a custom version.

One more option is to copy the Google Analytics code for the web book, paste it into an HTML file in the book repo, and include this reference in the `index.Rmd` code:

```
output:
  bookdown::gitbook:
  ...
  includes:
    in_header: google-analytics.html
```