Intro to ottrpal

ottrpal converts a Bookdown repository into a Leanpub-ready set of files. The output rendered files from this package can be published using the Github writing mode on Leanpub.

Read the full documentation here.

Required files:

Before you are ready to run ottrpal, you will need the following files (which are standard in a Bookdown repository):

• a _bookdown.yml file which lists the .Rmd files that are to be rendered in a rmd: category (see example file).
• .Rmd files which contain the chapter content (including your index.Rmd file which Bookdown has).
• an images directory that contains any images that are referenced in the chapters.
• .bib file(s) to complete any citation renders (see example file).

Optionally:

• a Book.txt file which lists the order of the chapters/quiz files (this can be autogenerated with ottrpal) (see example file).
• a directory containing quizzes in the form of .md files which have been written using the Markua formatting specifications (see example folder).

Here’s an example of what the Bookdown file set up (which ottrpal will look for) might be set up like:

A_Bookdown_Repo
├── _bookdown.yml
├── index.Rmd
├── 01-chapter_one.Rmd
├── docs
│   └── ...
├── references.bib
├── quizzes
│   ├── quiz_1.md
│   └── ...
├── resources/images
│   ├── some-figures.png
│   └── ...
└── Book.txt

Using the example repository:

If you’d like to use our example repository you can fork it on Github and clone it to your own computer Follow these instructions to fork and then you can clone it using a command like:

git clone https://github.com/{organization}/OTTR_Quizzes.git

But replace {organization} with the location of your forked repository.

Installing ottrpal:

You can install ottrpal from GitHub with:

You will need to use the remotes package (and will need to install it if you don’t have it).

if (!("remotes" %in% installed.packages())) {
  install.packages("remotes")
}
remotes::install_github("jhudsl/ottrpal")

Setting up the Rmds and images folder:

Each of your Rmds needs to have this chunk of code in the beginning of the file:

```{r, include = FALSE}
ottrpal::set_knitr_image_path()
```

This will ensure that the images are stored in the correct place and will be rendered correctly both in Bookdown and in Leanpub.

Running ottrpal

The ottrpal package converts your files using this main function:

ottrpal::bookdown_to_leanpub()

By default, ottrpal will re-run a bookdown::render_book("index.Rmd") rendering of your chapters first before converting the files to the Leanpub ready format. However, if you wish to skip this step, you can set render = FALSE when running the ottrpal::bookdown_to_leanpub() function.

About the Book.txt file:

Leanpub requires a Book.txt file to know what order the chapters/quizzes should be published.

By default, your Book.txt file will not be autogenerated but ottrpal will look in your given directory for an existing Book.txt file which it will copy over to the output directory.

You can create a Book.txt file manually, or if your quizzes and chapters are numbered, ottrpal can create the Book.txt file based on the numbers going from low to high and quizzes following chapters of the same number. (e.g. quiz_03.md will be placed after 03-some_chapter_file.Rmd).

To have ottrpal attempt to autogenerate this file, set make_book_txt to TRUE.

ottrpal::bookdown_to_leanpub(make_book_txt = TRUE)

If no Book.txt file is found and make_book_txt is set to FALSE (this is the default setting), ottrpal will fail.

A ottrpal autogenerated Book.txt file might look something like this:

index.Rmd
01-chapter.Rmd
quiz_1.md
02-chapter.Rmd
quiz_2.md
about.Rmd

Also note that any index.Rmd will always be placed first and any about.Rmd file will be placed last.

Setting up quizzes:

By default, ottrpal will look for a folder called quizzes/ to find your quiz .md files. If your quizzes are located somewhere else, you will need to use the quiz_dir argument to specify that:

ottrpal::bookdown_to_leanpub(quiz_dir = "some_directory")

About the output files

Leanpub’s Github writing mode will look for a directory called manuscript to publish from. You should not edit the files in manuscript/ by hand since a re-run of ottrpal will cause your changes to be overwritten.

Adding footer text:

If there is text you would like added to the end of each chapter (like a link to a feedback survey for example), you can supply a character string to the footer_textargument in the main ottrpal::bookdown_to_leanpub() function.

# Set up a character string
survey_link <- "Please provide any feedback you have in [this survey](www.some_link.org)"

# Supply the footer text in the main function
ottrpal::bookdown_to_leanpub(footer_text = survey_link)