README.md

sphinxcontrib-quizdown

A sphinx extension for writing quizzes with a markdown-like syntax, called quizdown.

🚀 See the demo or try the interactive quizdown live editor.

• supports markdown text formatting, images and syntax highlighting.
• different quiz-types: single-choice, multiple-choice, sequence.
• support for hints and explanations.
• options for color theme, question shuffling, localization.
• mobile friendly with touch support for all question types.

Installation

First, install the library with:

pip install git+git://github.com/bonartm/sphinxcontrib-quizdown

Then change the conf.py of your Sphinx project:

extensions = [
    ...,
    'sphinxcontrib.quizdown',
    ...
]

Usage

A new directive is added that let's you write markdown-like quizdown inside your .rst documents:

.. quizdown::

    ---
    primary_color: orange
    secondary_color: lightgray
    text_color: black
    shuffle_questions: false
    ---

   ## What is the capital of Germany?

   > It's the largest city in Germany.  

   - [x] Berlin
   - [ ] Cologne
   - [ ] Frankfurt
   - [ ] Munich

   ## Put the [days](https://en.wikipedia.org/wiki/Day) in order!

    > Monday is the *first* day of the week.

    1. Monday
    2. Tuesday
    3. Wednesday
    4. Friday
    5. Saturday  

You can also write you quiz in an external markdown file and reference it like so:

.. quizdown:: quiz.md

The HTML builder will wrap a <div class="quizdown"></div> around the text and includes the quizdown.js library in the build.

To use another version of quizdown or to set global options you can place a dictionary quizdown_config in your project's conf.py and change some of the values (quizdown uses the default option of not specified):

# global options passed to the quizdown library
quizdown_config = {
    'quizdown_js': 'https://cdn.jsdelivr.net/gh/bonartm/quizdown-js@latest/public/build/quizdown.js' # quizdown javascript
    'start_on_load': True,			# detect and convert all divs with class quizdown
    'shuffle_answers': True,		# shuffle answers for each question
    'shuffle_questions': False,     # shuffle questsions for each quiz
    'primary_color': '#FF851B',     # primary CSS color
    'secondary_color': '#DDDDDD',   # secondary CSS color
    'text_color': 'black',          # text color of interactive elements
    'locale': 'en'                  # language of text in user interface
}

📚 Documentation

The quizzes are for fun and not for serious assessment. Since everything is rendered on the client side, the hints and solutions to the questions become visible once javascript is disabled in the browser.

Check out the documentation on the main project page. You might be interested in:

• different quiz-types: single-choice, multiple-choice, sequence.
• support for hints and explanations.
• options for color theme, question shuffling, localization.

Credits

sphinxcontrib-mermaid and the sphinx-contrib template served as a reference for this project. Thank you for the inspiration!