Publishing on Leanpub - jhudsl/OTTR_Template GitHub Wiki

Table of Contents generated with DocToc

OTTR contains all the files you need to publish your course to Leanpub. The ottrpal package does the handling and automatic conversion to a rendered version that is ready for Leanpub.

These converted files are stored in the manuscript folder. As a general rule, don't edit files in manuscript folder. This folder should be autogenerated by the render ottrpalGitHub action (in file.github/workflows/render-leanpub.yml`) and you in general shouldn't make edits to it.

Note that if you wish your quizzes and their answers to remain hidden, there is a bit more set up involved with this process and you will need to create a separate private OTTR_Quizzes repository to store these quizzes. Start with these instructions first if you want your quizzes and answers to be hidden.

Leanpub rendering

The ottrpal package can do most of the formatting of links and etc for you (so long as you followed the formatting prescribed by the Setting up images section of this Wiki.

Github actions in this repository will attempt to do the Bookdown to Leanpub conversions for you by running ottrpal::bookdown_to_leanpub() function at the top of the repository.

Setting up Leanpub-related GitHub actions

When you are ready to begin publishing to Leanpub, you will want to turn on a few Github Actions that are included in the template but by default, turned off.

In your config_automation.yml file, you will need to turn on two actions in particular:

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

File a pull request with these changes and merge these to main. When you file a pull request, the quiz formatting will be checked automatically and reported on in a link on a comment in your pull request.

If you encounter issues with the ottrpal package, please file an issue on its Github repository.

Hosting your course on Leanpub

To host your course on Leanpub follow these steps:

  1. Make a Leanpub account here: https://leanpub.com/ if you don't already have one.

  2. Start a course

  • Click on the 3 line menu button
  • Click the author tab on the far left
  • Click Courses
  • Click the text that says create a new course
  • Fill out all the necessary information
  • Select using Git and GitHub (if you work with us at JHU there is a different protocol and additional settings you need to set which you should follow - see this document )
  • press the add to plan button
  1. Preview a new version
  • Click on the 3 line menu button
  • Click the author tab on the far left
  • Click Courses
  • Click on your course name/icon
  • Click "Preview New Version"
  • Click Create Preview button

If you have errors in your course (typically from a quiz formatting issue) the render will fail and you will need to fix your quizzes. Also note, that occasionally the preview might fail and you should just try again, as it will work the second time. This might be due to a lag in GitHub and Leanpub communicating.

Setting up quizzes

Quizzes need to be stored in the quizzes/ directory. Edit and add quizzes to this directory. See and copy this template quiz to get started. All quizzes need to be written in the Markua format. Refer to their documentation (but note that it is sometimes vague or out of date). The example question types in the template are ones that are verified to work.

After you add each new quiz to the quizzes/ directory, it's filename needs to be added in its respective spot in the Book.txt file (remember do not edit the one in manuscript but the one at the top of the repository); this ensures its incorporated by Leanpub in the correct order.

If you wanted two quizzes (one called quiz_1.md and one called quiz_2.md) you could duplicate and modify quiz_1.md for your needs and then you could make the Book.txt file look like this (assuming you created a chapter called "03-chapter_of_course.Rmd" and you wanted quiz_1 to be after 02-chapter-of_course and quiz_2 to be after 03_chapter_of_course:

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

Note that any .md files with an # in front of the name in the Book.txt file will be ignored by Leanpub. We have included an example of this in the Book.txt file.

See an example quiz here Note that you cannot have two quizzes with the same quiz_id.

Leanpub quizzes

Leanpub is specific about how quizzes should be formatted and it won't create a preview if any question or quiz doesn't follow these rules. Our GitHub action for checking quizzes (In file, .github/workflows/pull-request.yml underneath check-quizzes section) will print out a list of errors for you which you can retrieve from a pull request comment that is automatically printed. This check is only run when changes are made to the quizzes/. At this time, two types of questions are supported. (Short answers are not yet supported by our checks but will be added in the future).

Standard multiple choice:

The answer choices are not randomized. And it looks like this:

? 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

You can use choose-answers option which will randomize the multiple choices or you can use a standard quiz question that doesn't randomize. The notation for the answer choices are: C) for correct answers m) for mandatory incorrect answers and o) for optional incorrect answers.

Note that the number given for the number of answers has to be at least equal to the number of correct and mandatory incorrect answers listed.

Here's an example:

{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 the main branch, a GitHub action will automatically run check-quizzes.yml that will use the ottrpal package to check that your quiz conforms to these rules. It will report the quiz formatting errors on your pull request should there be any problems.

Leanpub quiz formatting 'rules'

  • Quizzes start and end with the {quiz} and {\quiz} tags.
  • Don't have exclamation points or colons in answers.
  • Make sure there's at least one right answer.
  • Check that the question and quiz attributes used are attributes recognized by Leanpub. -
  • Make sure all quizzes are listed in Book.txt
  • The number of choose answers is at least as big as the number of mandatory and correct answers listed.
  • For choose-answers questions, use C) for correct answers m) for mandatory incorrect answers and o) for optional incorrect answers.
  • Check that the question and quiz attributes used are attributes recognized by Leanpub.

Converting quizzes from Leanpub to Coursera format

See more instructions on how to port a course made from these templates to Coursera.

You can convert your quizzes to a nicely upload-able yaml file in this repository by running this command in the docker image

ottrpal::convert_quizzes()

Note that currently images and links are not supported and if your quizzes contain those, you will have to manually add them at this time.

You can run this same command locally if you wish to test something. This render the chapters without the table of Contents. If you do not wish to publish to Coursera and prefer this do not run, you may delete this section (but it shouldn't hurt anything to keep as is -- unless for some reason it causes you some troubles).

Additionally, the ottrpal package has a ottrpal::convert_quizzes() function if you choose to create quizzes and publish on both Leanpub and Coursera.

Setting up the _Quizzes repository checklist: