Questions and quizzes

Basic usage

If you want to manage your questions independently of the main book text, and make your multiple-choice questions interactive and self-marking, then each question should be its own file. Questions should be separate files in either the book’s text folder or in _items.

Include a question in your book file with the include question tag:

{% include question file="question-01" %}

Multiple-choice questions

You can add MCQs to your book like this:

{% include mcq file="question-01" %}

You can also just use the usual question include like this:

{% include question file="question-01" %}

and if the question file includes a correct value in its YAML frontmatter, it will be rendered as an interactive multiple-choice question.

MCQ files must include the correct answer option(s) in their YAML frontmatter to be rendered as interactive MCQs in web and app output. They should include feedback for each answer option. Here is an example of an MCQ markdown file:

correct: 1, 4

Which of the following is true?

- You should not pick a fight with a Wookiee.
- Picking fights with Wookiees is safe.
- Wookiees love being laughed at.
- Wookiees make loyal companions.

* Wookiees can tear your arm off.
* Wookiees don't shy away from a fight.
* Wookiees are proud and sensitive.
* Wookiees have been known to stick by their friends even in the worst circumstances.

You can have more than one correct answer.



You can gather several questions into a quiz using the include quiz tag:

{% include quiz questions="question-01, question-02, question-03" %}

If each question file has a marks value in its YAML frontmatter, a quiz will add up those marks and show the total.

Applying classes to quizzes

You can apply a class to a quiz in the include quiz tag. For example, to make a quiz your ‘featured quiz’, you might use a featured-quiz class:

{% include quiz questions="question-01, question-02, question-03" class="featured-quiz" %}

Also, if you want all the questions inside a quiz to have a particular class, you can set that, too, like this:

{% include quiz questions="question-01, question-02, question-03" question-class="my-featured-questions" %}

Quiz groups

You can collect quizzes into quiz-groups, for instance to create exam papers. To create a quiz-group, wrap quizzes in a <div class="quiz-group"></div>. A quiz group treats each quiz as a section, and numbers their questions consecutively across all quizzes in the quiz-group. This is useful for creating exam papers, where questions must numbered consecutively across sections (which are quiz-groups).

You can create a quiz group in one of two ways:

  1. If an entire markdown file represents a quiz group (e.g. it’s a single exam paper), add quiz-group to the style: values in the file’s YAML frontmatter. For instance:

    style: quiz-group

    (Technically, the values in style become classes of your output HTML’s body element.)

  2. If only a part of a markdown file represents a quiz-group, wrap the quizzes in a div element with a quiz-group class. Also add a markdown="1" attribute so that markdown in the div is processed into HTML as usual:

    <div class="quiz-group" markdown="1">
    ## Section 1
    {% include quiz questions="question-01, question-02, question-03" %}
    ## Section 2
    {% include quiz questions="question-04, question-05, question-06" %}