Publishing on Leanpub

The _Quizzes template repository includes all of the files that you need to convert your Bookdown course that was set up from a OTTR_Template to a Leanpub course with quizzes. These repositories are separate so that the quizzes and answers can be kept private.

The leanbuild package does the handling and automatic conversion from your main OTTR_Template repository to a rendered version that is ready for Leanpub.

If you haven't created a OTTR_Template course repository for your course template repository's getting started section Wiki and start there.

If you encounter any problems or have ideas for improvements to this template repository or this getting started Wiki, please file an issue here! Your feedback is very much appreciated.

How to use these repositories:

If you don't wish to have quizzes with your material or publish on Leanpub then you do not need the _Quizzes repository template, and the OTTR_Template course repository should be sufficient for your needs.

The Leanpub repository is where quizzes are stored because it is meant to be kept private so answers are hidden.

Keep in mind that in order to keep your Leanpub and Bookdown versions of your course concurrent, you should not make chapter edits in this repository! Only quiz edits should be in your _Quizzes repository. Chapter changes should be made in your OTTR_Template course repository and the transfer-rendered_files.yml Github action should be used to copy over the changes here.

Setting up your OTTR_Quizzes Github repository

Go to the OTTR_Quizzes repository and click Use this template. You must name this repository identical to your main OTTR repository but ending in _Quizzes if you would like them to be linked. For example, the jhudsl/Documentation_and_Usability course has a corresponding quiz repository named jhudsl/Documentation_and_Usability_Quizzes.

Make sure to set your new repository to Private so your quiz answers will be hidden.

Set up branches

*These settings are the same as we used in the Bookdown repository so we will need to set them up in the same way.

Go to Settings > Branches and click Add rule. For Branch name pattern, put main.

Protect the main branch:
Then check the box that says Require pull request reviews before merging.

Make sure branches are updated:

• Check the box that says Require status checks to pass before merging.
• Underneath this also check the box that says Require branches to be up to date before merging.

Use automatic spell and URL checks:
After the first pull request, a couple of checks will automatically happen and then appear here in settings. Then, you can require these checks to pass before merging pull requests by returning here and selecting them - they are url_check and sp-check they will check that the urls work and that the quizzes do not have spelling errors. See the Github Actions section in the Bookdown repository for more details on these.

After setting up these new branch items, click Create and Save changes.

Linking to your OTTR_Template course Github repository

In order to link your _Quizzes and OTTR_Template course repositories (so you only have to edit material in one place), you need to name your GitHub repository with an identical name to your OTTR_Template course repository except end it in _Quizzes. So for example, if your Bookdown repository is called: Cool_Course; it's Leanpub quiz repository must be called Cool_Course_Quizzes.

The GitHub actions that are responsible for content transfer is in the .gihub/workflows/ folder and called transfer-rendered-files.yml

Once build-all is run, the docs/ folder where the rendered files are place are copied over to the Leanpub repository and filed as a pull request. When you are sure that you want the changes from your main OTTR_Template repository, you can merge that pull request.

Note if you haven't set a GH_PAT git secret and you are not a part of jhudsl organization, you will need to set that by following these instructions.

_Note that any content changes to non-quiz material needs to be done your course's Bookdown repository! Do NOT change them in your Quizzes repository, otherwise your OTTR_Template course will not be updated.

Setting up quizzes

Quizzes should only live and be edited in a repository made from the OTTR_Quizzes repository.

As a general rule, don't edit files in manuscript folder. This folder should be autogenerated by leanbuild and you in general shouldn't make edits to it.

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.

Quiz formatting 'rules' from Leanpub

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. 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

• 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.

Upon merging to the main branch, a GitHub action will automatically run that will use the leanbuild package to check that your quiz conforms to these rules. It will fail if any of these are broken. To check if the rendering happened successfully, go to the main page of your _Quizzes repository, go to Actions and the Render and publish Leanpub workflow. It will show a green check mark on the most recent run if it ran successfully. If there's a red x you can click on the title of the run to investigate what went wrong.

Leanpub rendering

The leanbuild 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 leanbuild::bookdown_to_leanpub() function at the top of the repository. To check if the rendering happened successfully, go to the main page of your _Quizzes repository, go to Actions and the Render and publish Leanpub workflow. It will show a green check mark on the most recent run if it ran successfully. If there's a red x you can click on the title of the run to investigate what went wrong.

If you encounter issues with the leanbuild 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

3. 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.

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

leanbuild::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 leanbuild package has a leanbuild::convert_quizzes() function if you choose to create quizzes and publish on both Leanpub and Coursera.

Setting up the _Quizzes repository checklist:

• A GH_PAT has been set in the _Quizzes repository's GithHub secrets.

• Your Leanpub course as been created on Leanpub

  • Writing mode in this course is set to GitHub and your main OTTR_Template repository is linked.

• Repository is created and set to private.

• main branch has been set up:

  • Require pull request reviews before merging box is checked.
  • Require status checks to pass before merging box is checked.
    • Underneath that Require branches to be up to date before merging box is checked.

• This repo has been enrolled in automatic updates from the original template.

• Your Book.txt file is up to date.

• The leanbuild::bookdown_to_leanpub() ran successfully.