Chapter 9 Dress it up!
Once you have the website in place, it’s likely that you will want to update it periodically or add new pages. The key to updating is that you must build your site or use
rmarkdown::render_site() each time before you push to GitHub–otherwise your changes wouldn’t make it into your
docs/ folder. And if it’s not in the
docs/ then GitHub pages will not be able to find it.
9.1 Use a bootswatch theme
For a single R Markdown document, knitted to the HTML output format, adding a theme is so dead simple that you have no good excuses for not using one. You have 15 theme options:
nullfor no theme)
You can preview them all here.
--- name: YUM-101 output: html_document: theme: flatly ---
9.2 Add a floating table of contents
_site.yml file, you can add a table of contents either as a static list of links at the top of the page, or a floating sidebar. We recommend adding a floating TOC, which means adding two lines to your document’s YAML.
--- name: YUM-101 output: html_document: toc: true toc_float: true ---
By default, the following “nice things” happen when you use a floating TOC.
- First, the TOC “explodes” the subsections when you click on the top-level (H2) headers (i.e.,
## My big header).
- The TOC also animates, so that when you click on a top-level header, your document appears to “scroll” to the right section.
###headers will be included because the default
We encourage you to leave these default settings, but know that you can change them.
You can also number your sections, but we find it easier to stick to good top-level headers as the TOC organizing principle.
9.3 Customize code highlighter
--- output: html_document: highlight: tango ---
9.4 Add images
9.4.1 Markdown images
include_graphics gives you figure captions
can also play with out.width
That would be great re: narrative/code. I realized they are two diff lenses, because your exposition is for the educator who is sitting down and assessing their learners, their time, their task etc- so their question is, what should I make? Then, next in the process is where I am sitting! I want to write up something for educators who have decided what to make and help them navigate the dizzying array of YAML/knitr options. But for that I want a clear typology of who needs what and when from the educators’ standpoint (not from the learners’ necessarily). Does that make sense?
9.6 Upgrade your output format
So we know we told you to use HTML document as our preferred output format. That hasn’t changed- but there are ways to significantly upgrade your HTML output from R Markdown with additional packages, and you can keep all your content as is. The only changes are to install these packages and change the output format in your YAML. We’ll show you four options.
What you get:
- cross references to other documents
- numbered figures (plus cross-references)
::gotcha Warning! This output format means more surgery is needed to your content. But if you want to make your code interactive and hands-on, it may be worth it to you (and your learners!) :::