Merge pull request #16 from vsoch/add/quiz

Adding quiz element

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)

VERSION

@@ -1 +1 @@
-0.0.11
+0.0.12

_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!

_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"

_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' %}

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

_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 %}<h2>{{ quiz.title }}</h2>{% endif %}{% for item in questions %}
+{% if item.type == "multiple-choice" %}{% include quiz/multiple-choice.html item=item count=forloop.index %}{% endif %}<br>{% endfor %}

_includes/quiz/multiple-choice.html

@@ -0,0 +1,5 @@
+<div class="admonition question">
+<p class="admonition-title">{% if include.item.question %}{{ include.item.question }}{% else %}Question {{ include.count }}{% endif %}</p>
+<p>{% for choice in include.item.items %}{% if choice.correct == true %}<span class="correct-{{ include.count }}">{% endif %}{{ forloop.index }}. {{ choice.choice }}{% if choice.correct == true %}</span>{% endif %}<br>{% endfor %}</p>
+</div><button class="btn btn-success" onclick='$(".correct-{{ include.count }}").css("font-weight", 600);$(".correct-more-{{ include.count }}").css("display", "inline")'>Show Answer</button>
+{% if include.item.followup %}<p class="well correct-more-{{ include.count }}" style="display:none">{{ include.item.followup }}</p>{% endif %}