Publishing with Leanpub

OTTR includes everything needed to publish to Leanpub. The ottrpal package handles converting content into a Leanpub-ready format, storing output in the manuscript folder.

Warning

Do not manually edit files in the manuscript folder. It is auto-generated by ottrpal and will be overwritten.

If you want quizzes and answers hidden, you will need a separate private OTTR_Quizzes repository. Start with these instructions before proceeding.

Leanpub Rendering

The ottrpal package handles most formatting for links and other elements, as long as you have followed the image formatting instructions.

GitHub Actions will attempt to convert Bookdown to Leanpub by running ottrpal::bookdown_to_leanpub() at the top of the repository.

Setting up Leanpub-related GitHub Actions

When ready to publish to Leanpub, enable the following in your config_automation.yml:

• render-leanpub: yes
• check-quizzes: yes

You may also configure chapter and quiz ordering. By default, make-book-txt: TRUE orders content by filename numbering. Set make-book-txt: FALSE if you want to specify ordering manually via a Book.txt file. Read more in the quizzes section.

After updating config_automation.yml, file and merge a pull request. Quiz formatting will be checked automatically and reported in a pull request comment.

File issues with the ottrpal package in its GitHub repository.

Hosting your course on Leanpub

Finalizing a course on Leanpub can be tricky. The Using Leanpub guide provides detailed help.

1. Create a Leanpub account if you do not have one.

2. Start a course:

   • Click the three-line button at the far right of the top bar.
   • Click the Author tab, then Courses.
   • Verify your email address if prompted.
   • Click create a new course, then A Course.
   • Provide a title (the Course URL fills automatically).
   • Select Using Git and GitHub.
     • JHU developers: follow this additional setup document.
   • Press add to plan.

3. Preview a new version:

   • Click the three-line menu, then the Author tab, then Courses.
   • Click your course name or icon.
   • Click Preview New Version, then Create Preview.

If the render fails, it is typically due to a quiz formatting error. Occasional failures may also occur due to sync lag between GitHub and Leanpub — try again if it fails once.

Setting up quizzes

Store quizzes in the quizzes/ directory. Use the template quiz as a starting point. All quizzes must be written in Markua format.

After adding each quiz, add its filename to the Book.txt file at the top of the repository (not the one in manuscript) in the correct position. For example, with two quizzes interleaved between three chapters:

01-intro.md
02-chapter_of_course.md
quiz_1.md
03-chapter_of_course.md
quiz_2.md
about.md

Files listed with a # prefix in Book.txt are ignored by Leanpub.

You cannot have two quizzes with the same quiz_id. See an example quiz here.

Leanpub quiz question types

Standard multiple choice — answer choices are not randomized:

? A question is here
a) A wrong answer
B) A correct answer has a capital letter
c) A wrong answer
d) A wrong answer

Choose answers — randomizes choices using C) for correct, m) for mandatory incorrect, and o) for optional incorrect. The number of answers must be at least equal to the count of correct and mandatory incorrect answers.

{choose-answers: 4}
? A question is here
C) The correct answer is signified with a capital C
m) A mandatory incorrect answer
m) A mandatory incorrect answer
o) An optional incorrect answer
o) An optional incorrect answer

Upon merging to main, the check-quizzes.yml GitHub Action validates quiz formatting and reports errors on the pull request.

Leanpub quiz format rules

• Quizzes start and end with {quiz} and {\quiz} tags.
• No exclamation points or colons in answers.
• At least one correct answer per question.
• All question and quiz attributes must be recognized by Leanpub.
• All quizzes must be listed in Book.txt.
• The choose-answers count must be at least as large as the number of mandatory and correct answers.

Converting quizzes from Leanpub to Coursera format

Convert quizzes to a Coursera-uploadable YAML file by running:

ottrpal::convert_quizzes()

Note that images and links are not currently supported by the conversion script and must be added manually. Colons (:) are not allowed in prompts or answers.

See full Coursera publishing instructions.

_Quizzes repository checklist

• A GH_PAT has been set in both the main Template and the _Quizzes repository.
• Leanpub course has been created.
  • Writing mode is set to GitHub and linked to your main OTTR_Template repository.
• _Quizzes repository is set to private.
  • main branch protection is configured:
    • Require pull request reviews before merging is checked.
    • Require status checks to pass before merging is checked.
    • Require branches to be up to date before merging is checked.
• Repository is enrolled in automatic updates.
• Book.txt is up to date.
• ottrpal::bookdown_to_leanpub() ran successfully.

Examples

Below are some examples of courses created using the OTTR Template and published:

Introduction to Reproducibility in Cancer Informatics:

• GitHub repository and source code
  • Leanpub course

Computing for Cancer Informatics:

• GitHub repository and source code
  • Leanpub course