Skip to content

Progress Tracking

MkDocs Quiz includes a progress tracking system that helps users monitor their quiz completion status. Progress is automatically saved to the browser's local storage.

Progress Sidebar

When a page has two or more quizzes, a progress tracker automatically appears in the right sidebar (on Material theme). It shows:

  • Answered count: How many quizzes have been completed
  • Progress bar: Visual representation of completion
  • Score breakdown: Correct and incorrect answer counts
  • Reset link: Clear all progress on the page
Progress sidebar Progress sidebar

Mobile Progress Bar

On mobile devices, a sticky progress bar appears at the top of the page instead of the sidebar:

Mobile progress bar Mobile progress bar

Local Storage Persistence

Quiz progress is automatically saved to the browser's local storage. This means:

  • Progress persists across page reloads and browser sessions
  • Per-page storage: Each page tracks its own quiz state independently
  • Answer restoration: Previously submitted answers are restored when returning to a page

Privacy Note

Quiz data is stored locally in the user's browser only. No data is sent to any server.

Resetting Progress

Users can reset quiz progress in several ways:

From the Progress Sidebar

Click the "Reset" link in the progress sidebar to clear all quiz progress on the current page.

Using Intro Text

Add the intro text comment to provide users with a reset button:

<!-- mkdocs-quiz intro -->

This displays an info panel explaining that progress is saved, along with a reset button. See Intro Text for more details.

Programmatically

For advanced use cases, you can reset progress via JavaScript:

// Clear progress for current page
localStorage.removeItem("quizProgress_" + window.location.pathname);
location.reload();

Configuration

Hiding the Progress Tracker

To hide the progress sidebar and mobile bar on specific pages:

page.md frontmatter
---
quiz:
  show_progress: false
---

Or disable site-wide:

mkdocs.yml
plugins:
  - mkdocs_quiz:
      show_progress: false

Control where the progress tracker appears in the sidebar:

mkdocs.yml
plugins:
  - mkdocs_quiz:
      progress_sidebar_position: bottom # or "top" (default)
  • top (default): Progress tracker appears above the Table of Contents
  • bottom: Progress tracker appears below the Table of Contents

This is useful for pages with substantial content where quizzes appear at the end.

Try It Out

Answer the quizzes below to see the progress tracker in action:

#

What color is the sky on a clear day?

#

How many continents are there?

#

What is 10 + 5?

Look at the sidebar (desktop) or top of the page (mobile) to see your progress!

Events for Integration

The quiz system dispatches custom events that you can use for integration:

document.addEventListener("quizProgressUpdate", function (e) {
  console.log("Quiz progress updated:", e.detail);
  // e.detail contains: { answered, total, correct, incorrect }
});

This allows you to build custom progress displays or integrate with analytics.

Next Steps