14.6 Adding the main content… the code in a single “.Rmd” file
…and how it translates into content
Video guides
In the video: intro to rmd and bookdown - template HERE I introduce the basics of the Bookdown setup and folder structure, using the bookdown template repo files as an example.
I further discuss the elements of the .Rmd (and associated) files, and how they translate into html output in the video: rmarkdown content from template HERE
A final video that focuses a bit more on adding citations is HERE – this latter video has a very large file size, sorry.
My apologies: In these videos my dumb head is blocking an important part of the screen share. It may help you to have the original files up to see the missing bits. I hope to redo these when I have a chance.
Note: The key files and settings for my bookdown projects are maintained in my repo here, along with a minimal example. This is (or should be) synchronised with all the other repos.
A tip: ‘find in files’
‘Find in files’ is a nice tool when working in Rstudio for a project combining many files.
In menu bar, select: - Edit - Find in files…
Or use the (built in?) shortcut (in Mac) <Shift>-<cmd>-f
14.6.1 Basic (R-)Markdown
The Markdown format offers a simple plain-text notation for specifying
the elements of documents, reports, web sites, etc. (It is much simpler
and easier to read than html, latex, etc.) It is widely used by
programmers, on comment boards/forums, and throughout the internet. For
example, GitHub.com automatically renders markdown code, particularly in
readme.md files.
Actually there are several varieties of markdown, but they mainly share key elements.
Markdown documents are usually saved as plain text files with the
extension .md, e.g., report.md. These allow for an easy way to
create a variety of outputs, particularly reports and text-focused web
pages. The markdown format is converted into other formats (html,
latex, etc.) with a variety of tools, particularly something called
Pandoc.
What is Pandoc?
Pandoc is a tool (a program) for converting from one document format to another. It is incredibly powerful. The great thing about a format like markdown, or r-markdown, is that it is simple to write and peruse, and, with the help of Pandoc, it can convert into many many other useful formats for web pages, documents, presentations, etc.
Pandoc is built into other tools including the RMarkdown package (see discussion on Stackexchange here).
You can also install and use Pandoc directly in the command line, or try it out (in a limited but still useful way) on the web here
For more on Pandoc visit pandoc.orgIn the R (statistically focused) language there are tools such as
knitR that allow R users to produce reports combining text,
statistical output, and interactive content. These are generally written
in “R-markdown” documents, saved as .Rmd rather than .md files. The
R-studio interface, and several “add-ins,” also help facilitate this.
This interface is very useful; in fact, it may be convenient to build
web books and other content using this even if you are not planning to
extensively integrate R code and data. (As in the present book, although
I’m hoping to build this in).
Using R-markdown and Knitr (and other tools and add-ins like ‘Bookdown’) content from multiple sources can easily be embedded into these documents allowing users to easily display objects such as plots or regression output.
14.6.2 Some simple markdown rules
Text can be made italic using single asterisks *italic or bold
by using asterisks **bold**.
Hashtags/pound signs (#) specify headers and subheaders, e.g., this
third-level subsection header was created with the code:
### Some simple markdown rules {#simple-md-rules}
Where the bit in the curly braces allows us to link-back with the code
[link back text whatever](#simple-md-rules) … rendering as link
back text whatever.
Other key features are ordered lists and unordered lists:
- unordered first entry
- unordered second entry
- subelement of second entryWhile basic markdown has a limited set of rules, there are many more formatting and content options for documents produced in (R)-Markdown, far too many to detail here. These may combine markdown code, html code, latex code, and more. The following cheatsheets are very useful for writing (R)-markdown documents:
Markdown documents allow for an easy way to write reports. Content from multiple sources can easily be embedded into these documents allowing users to easily display objects such as plots or tables of data.
Text can be made italic using single asterisks *italic* and bold
by using double asterisks **bold**.
There are various text formatting options in Markdown, far too many to detail here… The following cheatsheets are very useful for writing markdown documents:
See also (most useful, but highly detailed):
Code chunks provide an easy way to embed code into your R Markdown files. The code language is not just limited to R either, as other languages can be used. This means that there is a wide variety of content which can be displayed in a chunk. Such as tables of data:
| Sepal.Length | Sepal.Width | Petal.Length | Petal.Width | Species |
|---|---|---|---|---|
| 5.1 | 3.5 | 1.4 | 0.2 | setosa |
| 4.9 | 3 | 1.4 | 0.2 | setosa |
| 4.7 | 3.2 | 1.3 | 0.2 | setosa |
| 4.6 | 3.1 | 1.5 | 0.2 | setosa |
| 5 | 3.6 | 1.4 | 0.2 | setosa |
| 5.4 | 3.9 | 1.7 | 0.4 | setosa |
Code chunks are defined by wrapping text inside ``` ```. The above example was coded using:
```{r}
head(iris)Options can be specified inside of the curly brackets {} More information is provided here
14.6.3 Inline code
Inline code is a quick and easy way to put snippets of R code. As an
alternative to using code chunks, R code can simply be placed inside of
`r `. For example, this can be used as an easy way to insert the
value of a variable into a paragraph without inserting a chunk.
14.6.4 Latex/maths
R Markdown also can make use of the LaTeX document preparation system, which is popular for writing technical documents with mathematical content. This allows us to publish documents which include equations such as:
\[y = \beta_0+\beta_1x_1 +\beta_2x_2+...+\beta_kx_k+u\]
Which is written using
$$y = \beta_0+\beta_1x_1 +\beta_2x_2+...+\beta_kx_k+u.$$. Using $$
means that the equation will be centered on the page. Alternatively $
can be used in the same way, without the centering.
A very useful guide to maths in R Markdown provides a detailed outline of the various mathematical symbols which can be used.
14.6.5 Custom styles
Bookdown allows for users to build their own custom styles in order to change the appearance of documents. To create styles for HTML projects a custom css file is used. For these projects, styles are contained in support/tufte_plus.css. To use a defined style, the user can specify options at the start of a chunk, or using a HTML wrapper as show below for margin notes.
More on creating styles here. Below will outline several key styles used throughout these projects:
‘Notes’
{block2, type ='note'} can be specified at the start of the block, or a HTML wrapper can be used. This assigns the .note formatting from the tufte_plus.css file to the chunk.
- Margin notes Margin notes are used throughout these projects as a way of displaying information in an organised and aesthetically pleasing way. To add a margin note, text is placed inside the following HTML wrapper:
The margin notes used in this project are inspired by the Tufte handout style developed by American statistician Edward Tufte.
<div class="marginnote">
Your margin note goes here.
</div>Or margin notes can be added by using chunk options.
- Folding boxes
{block2, type='fold'} at the start of a chunk, or using a HTML wrapper.
14.6.6 Adding references/citations
As with any academic work, it is always important to reference sourced material. Across these projects the following software is used:
- Setup
Pandoc provides a way to generate formatted references as well as a bibliography in R-Markdown.
The bibliography file to be sourced is specified within ‘YAML’ content,
which guides the processing of these documents. (YAML content is
generally enclosed with a three-dash --- break at top and bottom.)
I generally specify the bibliography source in the YAML at the top of the .Rmd file, or for Bookdown projects in the the YAML content in index.Rmd.
- BibTeX
The BibTeX format refers to a stylized file format which is used predomoninantly for lists of references, mainly and originally for working with latex.. BibTeX bibliographies use the .bib extension. For example the bibliography for this project is giving_keywords.bib. For more information on BibTeX see here
- Zotero
Zotero is a free open source reference manager, which enables users to sync their library of references across multiple devices. Similarly to other reference managers, Zotero offers plugins for popular browsers such as Chrome and Safari. This project makes use of a shared reference library in Zotero, contact daaronr AT gmail.com to be added. Download Zotero
- Better BibTeX for Zotero
Better BibTeX for Zotero is a add-on for Zotero. Among other things it allows the Zotero library to be exported from Zotero for use in Markdown. Installation instructions are provided here.
- Citr package (addin) for RStudio
The Citr package provides functions to search Zotero and BibTeX libraries in order to insert references into Markdown files. Citr also features a plugin for RStudio which makes the referencing process even easier. Instructions for download, as well as a demonstration of the Rstudio plugin are provided here. When using the Citr package to add citations to projects such as this one, make sure to have Citr update the correct Bibtex file.
Citr Settings for Ea_giving_barriers
The Bibtex file to “Add references to” is the bibliography file specified in the YAML header of index.Rmd.
14.6.7 Specific system for adding references in this project
Method 1 (recommended): Rstudio citr plugin linked to Zotero
Install Zotero software, Rstudio, and
citrpackage (an ‘Add-in’). Make sure all are running.Join the Zotero reinstein_research_and_impact_collabs group
Make sure the group library is syncronised with your Zotero
R-Studio ‘Addins (see bar at top),’ (Citr) ‘insert citation,’ settings (brings up the screen shown above)
Make sure ‘add references to’ specifies the “…
ea_giving_barriers/support/reinstein_bibtex.bib” folder.Make sure Zotero ‘reinstein_research_and_impact_collabs’ library is loaded
- Try to add the citation/reference.
Note that
[(at symbol) reference]gives a different format than(at symbol) reference(see below test).If the reference is not present, add it to the Zotero library (there are various methods, from Google Scholar etc) and synchronise your library, and try it again.
If you are not sure what the reference is, consult the Airtable, use context, and consult other survey papers. If you are still not sure ask on Github.
Method 2: Dropbox-syncronised Zotero to bibtex
(I’ll explain this later)
Adding a shortcut key for ‘insert citations’ in R-Studio
You may be able to save time in adding citations (via the CitR add-in in R-Studio) if you use a shortcut key.
Select (menu bar):
- Tools
- Addins
- Browse addins
Click in box “keyboard shortcuts”
Click the addin “Insert Citations” under ‘shortcuts,’ and enter a keyboard shortcut of your choice.
14.6.8 A test of adding references
Test a reference from reinstein_bibtex.bib: (fongTruthGivingExperimental2010?) no brackets (fongTruthGivingExperimental2010?) with brackets
Comments/notifications
In a variety of places within a repo when you are adding comments or content you can refer to a collaborator who will then receive a “notification” linking this content. (These are also called “callouts” in some systems.) These may come as as emails to that collaborator if they set a setting to get email notifications, but they will definitely appear as a notification, again that bell thing in the upper right hand corner.