{"id":20929381,"url":"https://github.com/cognitive-engineering-lab/mdbook-quiz","last_synced_at":"2025-05-16T06:06:40.701Z","repository":{"id":37973842,"uuid":"501779085","full_name":"cognitive-engineering-lab/mdbook-quiz","owner":"cognitive-engineering-lab","description":"Interactive quizzes for Markdown","archived":false,"fork":false,"pushed_at":"2025-05-01T22:28:29.000Z","size":7074,"stargazers_count":124,"open_issues_count":13,"forks_count":24,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-05-01T22:32:41.249Z","etag":null,"topics":["learning","mdbook","quiz","rust"],"latest_commit_sha":null,"homepage":"http://cel.cs.brown.edu/mdbook-quiz/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cognitive-engineering-lab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-09T19:11:43.000Z","updated_at":"2025-05-01T22:28:33.000Z","dependencies_parsed_at":"2023-09-21T22:49:18.561Z","dependency_job_id":"f1b82fc9-cce8-4a58-9010-2161f7e4b337","html_url":"https://github.com/cognitive-engineering-lab/mdbook-quiz","commit_stats":{"total_commits":195,"total_committers":2,"mean_commits":97.5,"dds":0.01538461538461533,"last_synced_commit":"836e9b9fc56600d4c7fdd1ed4397d57df5afe7e2"},"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cognitive-engineering-lab%2Fmdbook-quiz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cognitive-engineering-lab%2Fmdbook-quiz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cognitive-engineering-lab%2Fmdbook-quiz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cognitive-engineering-lab%2Fmdbook-quiz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cognitive-engineering-lab","download_url":"https://codeload.github.com/cognitive-engineering-lab/mdbook-quiz/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254478190,"owners_count":22077676,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["learning","mdbook","quiz","rust"],"created_at":"2024-11-18T21:19:13.384Z","updated_at":"2025-05-16T06:06:35.693Z","avatar_url":"https://github.com/cognitive-engineering-lab.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mdbook-quiz: interactive quizzes for Markdown\n\n[![tests](https://github.com/cognitive-engineering-lab/mdbook-quiz/actions/workflows/main.yml/badge.svg)](https://github.com/cognitive-engineering-lab/mdbook-quiz/actions/workflows/main.yml)\n[![crates.io](https://img.shields.io/crates/v/mdbook-quiz.svg)](https://crates.io/crates/mdbook-quiz)\n\n_[live demo](https://cognitive-engineering-lab.github.io/mdbook-quiz/)_\n\nThis repository provides an [mdBook](https://github.com/rust-lang/mdBook) [preprocessor](https://rust-lang.github.io/mdBook/format/configuration/preprocessors.html) that allows you to add interactive quizzes to your Markdown books. A quiz looks like this:\n\n\u003cimg width=\"521\" alt=\"Screenshot of mdbook-quiz embedded in a web page\" src=\"https://user-images.githubusercontent.com/663326/178065062-73542533-a1d7-479e-975b-cb0bf03658b2.png\"\u003e\n\nTable of contents:\n * [Installation](#installation)\n   + [From crates.io](#from-cratesio)\n   + [From source](#from-source)\n * [Usage](#usage)\n * [Quiz schema](#quiz-schema)\n   + [Short answer](#short-answer)\n   + [Multiple choice](#multiple-choice)\n   + [Tracing](#tracing)\n * [Quiz configuration](#quiz-configuration)\n\n\n## Installation\n\n*These instructions assume you have an mdBook already set up. Unfamiliar with mdBook? Read the [mdBook guide!](https://rust-lang.github.io/mdBook/)*\n\n### From crates.io\n\n```\ncargo install mdbook-quiz --locked\n```\n\nNote: this tool is under active development. I recommend pinning to a specific version to avoid breakage, e.g. by running\n\n```\ncargo install mdbook-quiz --locked --version \u003cYOUR_VERSION\u003e\n```\n\nAnd you can check your version by running `mdbook-quiz -V`. This repository uses semantic versioning for the quiz data format, so your quizzes should not break if you update to a more recent patch.\n\n### From source\n\nYou need Cargo, [cargo-make](https://github.com/sagiegurari/cargo-make), and [Depot](https://github.com/cognitive-engineering-lab/depot) installed. Then run:\n\n```\ngit clone https://github.com/cognitive-engineering-lab/mdbook-quiz\ncd mdbook-quiz\ncargo make init-bindings\ncargo install --path crates/mdbook-quiz\n```\n\n## Usage\n\nFirst, create a quiz file. Quizzes are encoded as TOML files (see [Quiz schema](#quiz-schema)). For example:\n\n```toml\n# quizzes/rust-variables.toml\n[[questions]]\ntype = \"ShortAnswer\"\nprompt.prompt = \"What is the keyword for declaring a variable in Rust?\"\nanswer.answer = \"let\"\ncontext = \"For example, you can write: `let x = 1`\"\n```\n \nThen in your Markdown file, add a reference to the quiz file:\n\n```markdown\n\u003c!-- src/your-chapter.md --\u003e\n\nAnd now, a _quiz_:\n\n{{#quiz ../quizzes/rust-variables.toml}}\n```\n\nConfigure your `book.toml` to activate `mdbook-quiz`.\n```toml\n# book.toml\n[preprocessor.quiz]\n```\n\nThen `mdbook build` should correctly embed the quiz.\n\n\u003e Note: due to limitations of mdBook (see [mdBook#1087](https://github.com/rust-lang/mdBook/issues/1087)), the `mdbook-quiz` preprocessor will copy files into your book's source directory under a subdirectory named `mdbook-quiz`. I recommend adding this directory to your `.gitignore`.\n\n## Quiz schema\n\nA quiz is an array of questions.\n\n```ts\nexport interface Quiz {\n  questions: Question[];\n}\n```\n\nA question is one of a set of predefined question types.\n\n```ts\nexport type Question = ShortAnswer | Tracing | MultipleChoice;\n```\n\nEach question type is an instantiation of this Typescript interface:\n\n```ts\nexport interface QuestionFields\u003cType extends string, Prompt, Answer\u003e {\n  type: Type;\n  prompt: Prompt;\n  answer: Answer;\n  context?: Markdown;\n}\n```\n\nIt has a discriminating string name `type` and then a `prompt` and `answer`, along with additional `context` for explaining the answer.\n\n\u003e Note that the `Markdown` type is just a string, but will be interpreted as Markdown by the quiz renderer.\n\nCurrently, mdbook-quiz supports these question types:\n* [Short answer](#short-answer)\n* [Multiple choice](#multiple-choice)\n* [Tracing](#tracing)\n\n\u003chr /\u003e\n\n### Short answer\n\nA question where the answer is a one-line string.\n\n#### Example\n\n```toml\n[[questions]]\ntype = \"ShortAnswer\"\nprompt.prompt = \"What is the keyword for declaring a variable in Rust?\"\nanswer.answer = \"let\"\ncontext = \"For example, you can write: `let x = 1`\"\n```\n\n#### Interface\n\n```ts\nexport interface ShortAnswerPrompt {\n  /** The text of the prompt. */\n  prompt: Markdown;\n}\n\nexport interface ShortAnswerAnswer {\n  /** The exact string that answers the question. */\n  answer: string;\n\n  /** Other acceptable strings answers. */\n  alternatives?: string[];\n}\n\nexport type ShortAnswer = QuestionFields\u003c\"ShortAnswer\", ShortAnswerPrompt, ShortAnswerAnswer\u003e;\n```\n\n\u003chr /\u003e\n\n### Multiple choice\n\nA question with multiple options that the user selects from.\n\n#### Example\n\n```toml\n[[questions]]\ntype = \"MultipleChoice\"\nprompt.prompt = \"What does it mean if a variable `x` is immutable?\"\nprompt.distractors = [\n  \"`x` is stored in the immutable region of memory.\",\n  \"After being defined, `x` can be changed at most once.\",\n  \"You cannot create a reference to `x`.\"\n]\nanswer.answer = \"`x` cannot be changed after being assigned to a value.\"\ncontext = \"\"\"\nImmutable means \"not mutable\", or not changeable.\n\"\"\"\n```\n\n#### Interface\n\n```ts\nexport interface MultipleChoicePrompt {\n  /** The text of the prompt. */\n  prompt: Markdown;\n\n  /** An array of incorrect answers. */\n  distractors: Markdown[];\n\n  /** If defined, don't randomize distractors and put answer at this index. */\n  answerIndex?: number;\n}\n\nexport interface MultipleChoiceAnswer {\n  /** The text of the correct answer. */\n  answer: Markdown;\n}\n```\n\n\u003chr /\u003e\n\n### Tracing\n\nA question where the user has to predict how a program will execute (or fail to compile).\n\n#### Example\n\n```toml\n[[questions]]\ntype = \"Tracing\"\nprompt.program = \"\"\"\nfn main() {\n  let x = 1;\n  println!(\"{x}\");\n  x += 1;\n  println!(\"{x}\");\n}\n\"\"\"\nanswer.doesCompile = false\ncontext = \"\"\"\nThis is a compiler error because line 4 tries to mutate `x` when `x` is not marked as `mut`.\n\"\"\"\n```\n\n#### Interface\n\n```ts\nexport interface TracingPrompt {\n  /** The contents of the program to trace */\n  program: string;\n}\n\nexport interface TracingAnswer {\n  /** True if the program should pass the compiler */\n  doesCompile: boolean;\n\n  /** If doesCompile=true, then the contents of stdout after running the program */\n  stdout?: string;  \n}\n\nexport type Tracing = QuestionFields\u003c\"Tracing\", TracingPrompt, TracingAnswer\u003e;\n```\n\n## Quiz configuration\n\nYou can configure mdbook-quiz by adding options to the `[preprocessor.quiz]` section of `book.toml`. The options are:\n\n* `fullscreen` (boolean): If true, then a quiz will take up the web page's full screen during use.\n* `cache-answers` (boolean): If true, then the user's answers will be saved in their browser's `localStorage`. Then the quiz will show the user's answers even after they reload the page.\n* `spellcheck` (boolean): If true, then run a spellchecker on all Markdown strings.\n* `more-words` (path): An optional path to a `.dic` file that adds valid words to the spellchecker. You can find a base dictionary for each language in [wooorm/dictionaries](https://github.com/wooorm/dictionaries/tree/main/dictionaries). You can find documentation about how to write a `.dic` file in [this blog post](https://typethinker.blogspot.com/2008/02/fun-with-aspell-word-lists.html).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcognitive-engineering-lab%2Fmdbook-quiz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcognitive-engineering-lab%2Fmdbook-quiz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcognitive-engineering-lab%2Fmdbook-quiz/lists"}