1. Adding a table of contents
Let's discuss how to add a table of contents to a report.
2. Table of contents
Including a table of contents provides the audience with an overview of the report. To add a table of contents, we add toc and true as a new key value pair in the YAML header.
The file won't knit unless the correct indentation is used in the YAML header. We include the toc field with an added indentation, and nest it within the html_document field.
3. TOC depth
We can specify which headers will appear in the table of contents by adding the toc-underscore-depth field. The number we list after toc_depth specifies the size of headers that will be listed in the table of contents.
For example, a toc depth of two means that headers that use two hashes, and larger headers that use one hash, will appear in the table of contents. When we knit the file, only the Datasets header is shown, since it is the only header that uses two hashes and there are no headers with one hash.
By default, the depth is three for HTML documents and two for PDF documents.
4. Number sections
We can also add section numbering to the headers in the table of contents by adding number-underscore-sections colon true.
If we include number sections, and want the decimal numbering to start with one, the largest headers in the report should use one hash.
5. Number sections
If the largest headers in the report start with two hashes, the section numbering will start with zero.
In the Markdown file shown, Datasets is the largest header and uses two hashes, so the number next to the Datasets header in the table of contents is zero-point-one-point-one.
6. TOC float
When creating HTML documents, we have some additional options for the table of contents.
When toc-underscore-float is set to true in the YAML header, the table of contents will appear on the left side of the document and will continue to remain visible while the reader scrolls through the document.
7. TOC float: collapsed
Within toc float, we can also use the collapsed and smooth scroll options. The previous table of contents options we've discussed, toc and toc_depth, are separate attributes, while the collapsed and smooth scroll options are nested within the toc_float field. Since these options are nested, we remove true from toc_float when specifying either collapsed or smooth scroll.
The collapsed option is true by default, and it determines whether or not the table of contents only displays the largest headers. When collapsed is used, the table of contents expands as someone is reading through the report or navigating to another section. When collapsed is set to false, the full table of contents remains visible.
8. TOC float: smooth scroll
The smooth-underscore-scroll option is also true by default. This option animates page scrolls when a reader clicks on an item in the table of contents to navigate to another section of the report. When smooth scroll is set to false in the YAML header, clicking on an item in the table of contents will navigate the reader to that section of the article without animation.
9. Summary
We've discussed a number of options for the YAML header. To summarize, we discussed the toc, toc_depth, and number_sections options for HTML and PDF files. Recall that the default toc_depth is three for HTML documents and two for PDF documents.
Then, we discussed toc_float for HTML documents, and the collapsed and smooth_scroll options within that field that can be used to further customize the knit report.
10. Let's practice!
Let's practice!