mdbook-quiz：Markdown交互式测验

在线演示

此存储库提供了一个 mdBook 预处理器，允许您将交互式测验添加到Markdown书籍中。一个测验看起来像这样

目录

• 安装
  • 从crates.io安装
  • 从源安装
• 使用方法
• 测验模式
  • 简答题
  • 多项选择题
  • 追踪
• 测验配置

安装

这些说明假设您已经设置了mdBook。不熟悉mdBook？请阅读mdBook指南！

从crates.io安装

cargo install mdbook-quiz --locked

注意：此工具正在积极开发中。我建议指定一个版本以避免损坏，例如通过运行

cargo install mdbook-quiz --locked --version <YOUR_VERSION>

并且您可以通过运行 mdbook-quiz -V 来检查您的版本。此存储库使用语义版本控制对测验数据格式进行版本控制，因此如果您更新到更新的补丁版本，您的测验不应损坏。

从源安装

您需要安装Cargo、cargo-make 和 Depot。然后运行

git clone https://github.com/cognitive-engineering-lab/mdbook-quiz
cd mdbook-quiz
cargo make init-bindings
cargo install --path crates/mdbook-quiz

使用方法

首先，创建一个测验文件。测验编码为TOML文件（见测验模式）。例如

# quizzes/rust-variables.toml
[[questions]]
type = "ShortAnswer"
prompt.prompt = "What is the keyword for declaring a variable in Rust?"
answer.answer = "let"
context = "For example, you can write: `let x = 1`"

然后在您的Markdown文件中，添加对测验文件的引用

<!-- src/your-chapter.md -->

And now, a _quiz_:

{{#quiz ../quizzes/rust-variables.toml}}

配置您的 book.toml 以激活 mdbook-quiz。

# book.toml
[preprocessor.quiz]

然后 mdbook build 应正确嵌入测验。

注意：由于mdBook的限制（见mdBook#1087），mdbook-quiz 预处理器将文件复制到您的书籍源目录下的名为 mdbook-quiz 的子目录中。我建议将此目录添加到您的 .gitignore。

测验模式

测验是一系列问题。

export interface Quiz {
  questions: Question[];
}

问题是一组预定义问题类型之一。

export type Question = ShortAnswer | Tracing | MultipleChoice;

每种问题类型都是此TypeScript接口的实例化

export interface QuestionFields<Type extends string, Prompt, Answer> {
  type: Type;
  prompt: Prompt;
  answer: Answer;
  context?: Markdown;
}

它有一个区分性的字符串名称 type，然后是一个 prompt 和 answer，以及解释答案的附加 context。

请注意，Markdown 类型只是一个字符串，但将被测验渲染器解释为 Markdown。

目前，mdbook-quiz 支持以下问题类型

• 简答题
• 多项选择题
• 追踪

简答题

答案为单行字符串的问题。

示例

[[questions]]
type = "ShortAnswer"
prompt.prompt = "What is the keyword for declaring a variable in Rust?"
answer.answer = "let"
context = "For example, you can write: `let x = 1`"

接口

export interface ShortAnswerPrompt {
  /** The text of the prompt. */
  prompt: Markdown;
}

export interface ShortAnswerAnswer {
  /** The exact string that answers the question. */
  answer: string;

  /** Other acceptable strings answers. */
  alternatives?: string[];
}

export type ShortAnswer = QuestionFields<"ShortAnswer", ShortAnswerPrompt, ShortAnswerAnswer>;

多项选择题

用户从多个选项中选择的问题。

示例

[[questions]]
type = "MultipleChoice"
prompt.prompt = "What does it mean if a variable `x` is immutable?"
prompt.distractors = [
  "`x` is stored in the immutable region of memory.",
  "After being defined, `x` can be changed at most once.",
  "You cannot create a reference to `x`."
]
answer.answer = "`x` cannot be changed after being assigned to a value."
context = """
Immutable means "not mutable", or not changeable.
"""

接口

export interface MultipleChoicePrompt {
  /** The text of the prompt. */
  prompt: Markdown;

  /** An array of incorrect answers. */
  distractors: Markdown[];

  /** If defined, don't randomize distractors and put answer at this index. */
  answerIndex?: number;
}

export interface MultipleChoiceAnswer {
  /** The text of the correct answer. */
  answer: Markdown;
}

追踪

用户需要预测程序如何执行（或编译失败）的问题。

示例

[[questions]]
type = "Tracing"
prompt.program = """
fn main() {
  let x = 1;
  println!("{x}");
  x += 1;
  println!("{x}");
}
"""
answer.doesCompile = false
context = """
This is a compiler error because line 4 tries to mutate `x` when `x` is not marked as `mut`.
"""

接口

export interface TracingPrompt {
  /** The contents of the program to trace */
  program: string;
}

export interface TracingAnswer {
  /** True if the program should pass the compiler */
  doesCompile: boolean;

  /** If doesCompile=true, then the contents of stdout after running the program */
  stdout?: string;  
}

export type Tracing = QuestionFields<"Tracing", TracingPrompt, TracingAnswer>;

测验配置

您可以通过向 [preprocessor.quiz] 部分添加选项来配置 mdbook-quiz。选项有：

• fullscreen（布尔值）：如果为 true，则测验将占用网页的全屏。
• cache-answers（布尔值）：如果为 true，则用户的答案将保存在其浏览器的 localStorage 中。然后测验将显示用户在重新加载页面后的答案。
• spellcheck（布尔值）：如果为 true，则在所有 Markdown 字符串上运行拼写检查器。
• more-words（路径）：一个可选的路径，指向一个 .dic 文件，该文件向拼写检查器添加有效单词。您可以在 wooorm/dictionaries 中找到每种语言的基字典。您可以在 这篇博客文章 中找到有关如何编写 .dic 文件的说明。