Skip to content

Changelog

Version 1.0.0 (2025-11-13)

v1.0.0 of mkdocs-quiz is a complete rewrite of the original plugin. It modernises the codebase, changes the quiz markdown syntax, and adds a lot of new functionality.

The plugin was originally written by @skyface753, who has graciously passed the repository over to @ewels for future development after this rewrite. @skyface753 will stay on as a maintainer.

🚨 Breaking Changes

New Quiz Syntax

The quiz syntax has been completely redesigned to use a cleaner, markdown-style format. The old question:, answer:, answer-correct:, and content: syntax is no longer supported. The opening and closing tags no longer have the ? characters.

Old Syntax (v1.x):

<?quiz?>
question: Are you ready?
answer-correct: Yes!
answer: No!
answer: Maybe!
content:
<h2>Some additional content</h2>
<?/quiz?>

New Syntax (v2.0):

<quiz>
Are you ready?
- [x] Yes!
- [ ] No!
- [ ] Maybe!

Some additional content here
</quiz>

Migration:

  • A CLI migration tool is provided: mkdocs-quiz migrate
  • Run: mkdocs-quiz migrate docs/ to automatically convert all quiz blocks
  • Use --dry-run flag to preview changes without modifying files
  • Use git tracked changes to review before committing

✨ Added Features

Core Functionality

  • Markdown support in questions and answers - Full markdown parsing including bold, italic, code, links, images, etc.
  • Optional content section - No longer required to include content when there's nothing additional to show
  • Full markdown in content section - Content area now supports complete markdown syntax, not just HTML
  • Plugin configuragion - Both site-wise in mkdocs.yml or page-specific in the YAML frontmatter.
  • Auto-submit answers - No need to press 'Submit' for single-choice questions
  • Quiz header IDs - Each quiz gets a unique ID (quiz-0, quiz-1, etc.) with hover anchor link for direct navigation. Optionally also include a numbered heading for each question.
  • Global progress tracking - Tracks answered/correct status across all quizzes on the page. Progress trackers in the sidebar (desktop) or top of page (mobile) show progress.
  • LocalStorage persistence - Progress automatically saved per-page and restored on reload
  • Reset button - Ability to clear localStorage and current answers, to start again
  • Results panel - Add a placeholder to the page to show results and fire confetti when the quiz is complete 🎉
  • and many more small additions..

Pre-1.0.0

Previous versions 0.1 to 0.41 were all written by the original plugin author Sebastian Jörz. See original GitHub history for details: https://github.com/skyface753/mkdocs-quiz/