From bcdae2d5b86f436441ff9ec273662445d49b78c9 Mon Sep 17 00:00:00 2001 From: Vanessa Sochat Date: Mon, 22 Jul 2019 11:10:40 -0400 Subject: [PATCH] adding quiz element Signed-off-by: Vanessa Sochat --- CHANGELOG.md | 1 + VERSION | 2 +- _data/quizzes/example-quiz.yml | 25 ++++++++++++ _data/toc.yml | 5 +++ _docs/extras/example-quiz.md | 62 +++++++++++++++++++++++++++++ _docs/extras/index.md | 15 +++++++ _includes/quiz.html | 3 ++ _includes/quiz/multiple-choice.html | 5 +++ 8 files changed, 117 insertions(+), 1 deletion(-) create mode 100644 _data/quizzes/example-quiz.yml create mode 100644 _docs/extras/example-quiz.md create mode 100644 _docs/extras/index.md create mode 100644 _includes/quiz.html create mode 100644 _includes/quiz/multiple-choice.html diff --git a/CHANGELOG.md b/CHANGELOG.md index c0313ac..d05c3ab 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ Critical items to know are: - changed behaviour ## [master](https://github.com/vsoch/mkdocs-jekyll/tree/master) + - basic support for multiple choice quizzes (0.0.12) - adding colored buttons, various fixed to navigation (0.0.11) - getting search working (0.0.1) - start of theme (0.0.0) diff --git a/VERSION b/VERSION index 2cfabea..8cbf02c 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.0.11 +0.0.12 diff --git a/_data/quizzes/example-quiz.yml b/_data/quizzes/example-quiz.yml new file mode 100644 index 0000000..c81a523 --- /dev/null +++ b/_data/quizzes/example-quiz.yml @@ -0,0 +1,25 @@ +title: This is the Quiz Title +randomized: false +questions: + + - type: "multiple-choice" + question: "What is your favorite color?" + items: + - choice: Red + correct: null + - choice: Blue + correct: null + - choice: Green + correct: null + followup: There is no correct answer to asking your favorite color! All choices would be good. + + - type: "multiple-choice" + question: "True or False, Pittsburgh is West of Philadelphia" + items: + - choice: True + correct: true + - choice: False + correct: false + followup: | + The answer is True! Pittsburgh is 304.9 miles West of Philadelphia, or approximately + a car ride of 4 hours and 52 minutes. Buckle up! diff --git a/_data/toc.yml b/_data/toc.yml index 38d686c..22f4837 100644 --- a/_data/toc.yml +++ b/_data/toc.yml @@ -7,6 +7,11 @@ url: "docs/getting-started#development" - title: Customization url: "docs/getting-started#customization" +- title: "Extras" + url: "docs/extras" + children: + - title: Quizzes + url: "docs/extras/example-quiz" - title: "About" url: "about" - title: "News" diff --git a/_docs/extras/example-quiz.md b/_docs/extras/example-quiz.md new file mode 100644 index 0000000..7ba78b4 --- /dev/null +++ b/_docs/extras/example-quiz.md @@ -0,0 +1,62 @@ +--- +title: Quiz +--- + +# Quizzes + +As of version 0.0.12, mkdocs-jekyll has support for basic quizzes! These are +intended to help educate your users about the content of your documentation. +For a quiz, you can add a new file to the folder `_data/quizzes`, and write a +questions file based on the format shown in `_data/quizzes/example-quiz.yml`. +Here is a simple example of a multiple choice question (which can also serve as +True/False): + +```yaml +title: This is the Quiz Title +randomized: false +questions: + + - type: "multiple-choice" + question: "True or False, Pittsburgh is West of Philadelphia" + items: + - choice: True + correct: true + - choice: False + correct: false + followup: | + The answer is True! Pittsburgh is 304.9 miles West of + Philadelphia, or approximately a car ride of + 4 hours and 52 minutes. Buckle up! +``` + +The quiz is rendered with a "Show Answer" button below each question, and when +the user clicks it, any questions that are flagged with `correct: true` will be +bolded, and if a followup section is included, it will be displayed. +See the live example at the end of this page. + +## Options + +#### Title + +If you include a title, it will be rendered at the top of the quiz. This is +optional - you can leave it out and add it before the include on the page. + +#### Random + +If you want your questions to be presented randomly, just add randomized: true +to the data. + + +## Example Quiz + +If I want to include the quiz located at `_data/quizzes/example-quiz.yml`, I +can do so like this: + +``` +{% raw %}{% include quiz.html file='example-quiz' %}{% endraw %} +``` + +The rendered quiz is shown here: + + +{% include quiz.html file='example-quiz' %} diff --git a/_docs/extras/index.md b/_docs/extras/index.md new file mode 100644 index 0000000..c2cff42 --- /dev/null +++ b/_docs/extras/index.md @@ -0,0 +1,15 @@ +--- +title: Extras +--- + +# Extras + +Extras include other integrations that aren't relevant to style or customization, +but can further enhance your documentation pages. Currently, we have support +for adding interactive quizzes. + + - [Quizzes](example-quiz) + + +Would you like to see another question type, or another kind of extra? Please +[open an issue])({{ site.repo }}/issues/new). diff --git a/_includes/quiz.html b/_includes/quiz.html new file mode 100644 index 0000000..f80fa73 --- /dev/null +++ b/_includes/quiz.html @@ -0,0 +1,3 @@ +{% assign quiz = site.data.quizzes[include.file] %} +{% if quiz.randomize == true %}{% assign questions = quiz.questions | sample %}{% else %}{% assign questions = quiz.questions %}{% endif %}{% if quiz.title %}

{{ quiz.title }}

{% endif %}{% for item in questions %} +{% if item.type == "multiple-choice" %}{% include quiz/multiple-choice.html item=item count=forloop.index %}{% endif %}
{% endfor %} diff --git a/_includes/quiz/multiple-choice.html b/_includes/quiz/multiple-choice.html new file mode 100644 index 0000000..aceb0c0 --- /dev/null +++ b/_includes/quiz/multiple-choice.html @@ -0,0 +1,5 @@ +
+

{% if include.item.question %}{{ include.item.question }}{% else %}Question {{ include.count }}{% endif %}

+

{% for choice in include.item.items %}{% if choice.correct == true %}{% endif %}{{ forloop.index }}. {{ choice.choice }}{% if choice.correct == true %}{% endif %}
{% endfor %}

+
+{% if include.item.followup %}{% endif %}