There are a lot of additional features and tools of OTTR that are discussed here!
You can generally follow the Bookdown instructions about citations, but you don’t need to add the additional bibliography argument at the top of the Rmds.
To add a new reference source, add to the book.bib
file, keeping your new entry in alphabetical order.
For articles (or anything with a DOI), go to doi2bib.org or ZoteroBib to get a BibTex-formatted reference that you can copy and paste the reference to the book.bib
file.
You can also use programs like Zotero or Endnote to export a .bib file and either combine with the book.bib
or manage your references from there.
Other sources can be added using this template:
@website{citekey,
author = {First Last},
title = {Title},
url = {www.website.com},
}
To reference the citations in your writing follow the bookdown instructions:
Items can be cited directly within the documentation using the syntax @key where key is the citation key in the first line of the entry, e.g., @R-base. To put citations in parentheses, use [@key]. To cite multiple entries, separate the keys by semicolons, e.g., [@key-1; @key-2; @key-3]. To suppress the mention of the author, add a minus sign before @, e.g., [-@R-base].
See Chapter 2 of this template course for examples.
This will automatically list references at the bottom of each chapter included in your course, as well as at the end of your course. Thus it is important to keep the References.Rmd
file and to keep this as the last part of the _bookdown.yml
file as it is in the template, so that this full list of references will be listed in a place that makes sense.
_bookdown.yml file showing the references file as the last file
Alternatively, you can add a header for this list of references as the last header in any other Rmd file that is listed as the final file of the _bookdown.yml
file.
If you would like to suppress having references listed at the end of each chapter, you can add a line that says split_bib: false
to your _output.yml
file.
_output.yml file showing the split.bibset to false
Since so many individuals contribute to our courses in so many ways. Thus, we decided to make a table of credits to make it clear who did what.
Here is an example:
Credit section from a course that used this template
Please see the about section of the template for descriptions of how credits should be attributed for the course.
This is generated from the About.Rmd file. An About.Rmd file will already be in your course from using our template. You will need to do the following steps to update it for your course:
Example Table:
The first row and additional rows based on this table should be added and filled in using markdown table format.
|Credits|Names|
|-------|-----|
|Lead Content Instructor|FirstName LastName|
Links to personal websites can be added below the table to make it easier to read.
|Credits|Names|
|-------|-----|
|Lead Content Instructor|[FirstName LastName]|
<!-- Author information -->
[FirstName LastName]: link to personal website
These rows should be included for all courses:
|Template Publishing Engineers|[Candace Savonen], [Carrie Wright]|
|Publishing Maintenance Engineer|[Candace Savonen]|
|Technical Publishing Stylists|[Carrie Wright], [Candace Savonen]|
|Package Developers[ottrpal]|[John Muschelli], [Candace Savonen], [Carrie Wright]|
<!-- Author information -->
[John Muschelli]: https://johnmuschelli.com/
[Candace Savonen]: https://www.cansavvy.com/
[Carrie Wright]: https://carriewright11.github.io/
<!-- Links -->
[ottrpal]: https://github.com/jhudsl/ottrpal
These rows should be added to all Johns Hopkins courses:
|Content Publisher|[Ira Gooding]|
|Content Publishing Reviewer|Ira Gooding]|
<!-- Author information -->
[Ira Gooding]: https://publichealth.jhu.edu/faculty/4130/ira-gooding
Additionally, this row should be added for all ITCR Courses:
|Content Directors|[Jeff Leek]|
<!-- Author information -->
[Jeff Leek]: https://jtleek.com/
In Coursera, you can add the credits table URL as an ungraded plugin (the same as described here for adding chapter content). This should be added at the beginning of your course, right after the introduction.
In Leanpub, make sure that your About.md file in your manuscript folder is listed in your Book.txt file and this Credits table will automatically be incorporated into your Leanpub course.
If you have two courses that the content and topics overlap, you may want to share written material between the two.
But, if you copy and paste to share material this would create a maintenance problem because if you update one you will need to remember to copy over the other! 😱
In OTTR, we try to minimize maintenance pains so to get around this, we use cow::borrow_chapter()
from the jhudsl/cow package. The cow
package is already on the jhudsl/course_template
docker image so you do not need to install it if you are using the docker image or if you are have GitHub actions do all the rendering for you.
To borrow a chapter from another course, create an .Rmd
as you normally would, with a ottrpal::set_knitr_image_path()
in a chunk at the beginning of the file and a H1
title.
Then, wherever you would like the borrowed chapter to appear, put an R chunk with this; where {r, echo = FALSE, results='asis'}
is included in your chunk arguments.
cow::borrow_chapter(
doc_path = "02-chapter_of_course.Rmd",
repo_name = "jhudsl/OTTR_Template"
)
The magic of this function is that whenever the course is re-rendered it will knit the latest version of the chapter you are borrowing. Note that this chunk cannot be run interactively, just include it in your Rmd and render your course as usual.
If for some reason you would like a local file incorporated, just leave off the repo_name argument and cow::borrow_chapter()
will look for the chapter locally: Have your chunk arguments include: {r, echo = FALSE, results='asis'}
.
cow::borrow_chapter(
doc_path = "02-chapter_of_course.Rmd"
)
If you are borrowing from a course in a private repository, you will need to supply GitHub personal access token using a git_pat
argument like this: Have your chunk arguments include:{r, echo = FALSE, results='asis'}
cow::borrow_chapter(
doc_path = "02-chapter_of_course.Rmd",
repo_name = "jhudsl/Private_Repo",
git_pat = "12345"
)
If you want to change the title you can use an option remove_h1
to remove the title from the incoming borrowed chapter.
If you don’t want the material from another chapter completely copied over, you might instead just want to put a link to the Bookdown chapter. You can just use the full url. A link would look something like this:

You might want your course available for download as a docx. For example, you might be running a “train-the-trainer” workshop where trainees don’t feel comfortable using Github to edit the lessons for their own use.
The following yml in index.Rmd
allows you to render the docx with a table of contents:
output:
bookdown::word_document2:
toc: true
You can also incorporate a template docx if you have headers and logos you want to use. To incorporate a template, make sure you add the reference_docx
argument:
output:
bookdown::word_document2:
reference_docx: <path/to/template>.docx
toc: true
Learn more about templates here.
Google Docs can be a great way to get feedback from collaborators who aren’t comfortable developing in the GitHub environment. docx versions of the course are automatically rendered in pull requests and can be downloaded from the autogenerated comment.
+ New
in the left corner and then File Upload
. Choose the docx file you downloaded.main
content branch.