Skip to content

Borrowing chapters between courses

Candace Savonen edited this page Feb 18, 2022 · 10 revisions

Table of Contents generated with DocToc

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:

```{r, echo = FALSE, results='asis'}
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.

Borrowing from a local file

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:

```{r, echo = FALSE, results='asis'}
cow::borrow_chapter(
  doc_path = "02-chapter_of_course.Rmd"
)
```

Borrowing from a private repository

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:

```{r, echo = FALSE, results='asis'}
cow::borrow_chapter(
  doc_path = "02-chapter_of_course.Rmd",
  repo_name = "jhudsl/Private_Repo",
  git_pat = "12345"
)
```

Removing an h1 header

If you want to change the title you can use an option remove_h1 to remove the title from the incoming borrowed chapter.


# A new title

Some new words before the borrowed chapter content.

```{r, echo = FALSE, results='asis'}
cow::borrow_chapter(
  doc_path = "02-chapter_of_course.Rmd",
  remove_h1 = TRUE
)
```

Some new words after the borrowed chapter content.

Linking between chapters

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:

![](https://jhudatascience.org/OTTR_Template/a-new-chapter.html)
Clone this wiki locally