Skip to content
Slate Slate Docs

ASSESSMENT.md

v1.6

An ASSESSMENT.md file is a scored assessment: a graded quiz with an attempt limit and a passing score. It is a LESSON.md file with a restricted block set and its own frontmatter. Added in LESSON.md v1.6, it imports into Slate as a course’s assessment section.

How an assessment file differs from a lesson

Section titled “How an assessment file differs from a lesson”

A regular LESSON.md file is one lesson. An ASSESSMENT.md file is the course’s scored test. The difference is two restrictions plus extra frontmatter:

  • It carries attempts, pass, and randomize settings in its frontmatter.
  • It allows only three block types: text, image, and knowledge-check.
  • Each knowledge-check block is one scored question.

Frontmatter

Section titled “Frontmatter”

The title is required, the same as any lesson. The rest are optional and control how the assessment is scored.

KeyRequiredValuesDefault
titleYesText—
attemptsNoA whole number, or unlimited3
passNoA percentage like 80%, or a whole number of correct answers like 870%
randomizeNotrue, falsefalse
---
title: Final Assessment
attempts: 2
pass: 80%
randomize: true
---
  • attempts - how many times a learner can take the assessment before it locks. Use unlimited for no limit.
  • pass - the score needed to pass. A percentage (80%) is scored against the total; a plain number (8) is a count of correct answers.
  • randomize - when true, the question order is shuffled per learner.

Content rules

Section titled “Content rules”
  • Only text, image, and knowledge-check blocks are allowed. Any other block type is skipped on import with a warning.
  • At least one knowledge-check block is required. An assessment with no questions fails to import.
  • Each knowledge-check block is one scored question. All three question types work: multiple choice, multiple select, and fill in the blank. Use a leading text block for instructions if you need them.
  • Per-question attempt properties do not apply. Properties like maxAttempts and revealCorrectAnswer are ignored inside an assessment - the whole-assessment attempts and pass from the frontmatter govern instead. Leave them off assessment questions.

See the LESSON.md block reference for the full knowledge-check syntax.

Example

Section titled “Example”
---
title: Feedback Skills Assessment
attempts: 2
pass: 80%
randomize: true
---


::: text
# Feedback Skills Assessment


Answer every question to complete the module. You have two attempts, and
80% earns a pass.
:::


::: knowledge-check
type: multiple-choice
question: What are the three parts of the feedback model in order?
correct-feedback: Correct. Situation, then Behaviour, then Impact.
incorrect-feedback: Revisit the model - it moves from context to action to effect.


- [x] Situation, Behaviour, Impact
- [ ] Behaviour, Impact, Situation
- [ ] Impact, Situation, Behaviour
:::


::: knowledge-check
type: multiple-select
question: Which statements are specific, behavioural feedback? (Select all that apply)
correct-feedback: Correct. Each names an observable action.
incorrect-feedback: Look for the statements that describe an action, not a trait.


- [x] "You answered every demo question with a concrete example."
- [ ] "You're a natural presenter."
- [x] "You spoke over the customer twice during pricing."
- [ ] "Your attitude needs work."
:::


::: knowledge-check
type: fill-in-the-blank
question: Feedback should describe _____, not character.
correct-feedback: Correct. Describe observable behaviour.
incorrect-feedback: Think about what the person actually did.


- [x] behaviour
- [x] behavior
:::

Two ways to import an assessment

Section titled “Two ways to import an assessment”

Inside a course bundle

Section titled “Inside a course bundle”

Place a file named ASSESSMENT.md at the root of a LESSON.md course zip. Slate adds it as the course’s assessment, always as the final section.

customer-service.zip
├── 01-introduction/
│   ├── 01-welcome.md
│   └── 02-why-it-matters.md
├── 02-during-the-call/
│   └── 01-handling-uncertainty.md
├── ASSESSMENT.md
└── media/
    └── diagram.png
  • The name ASSESSMENT.md is reserved and matched case-insensitively.
  • A bundle may have at most one assessment file.
  • It sits at the zip root alongside section folders without affecting the flat-versus-foldered layout choice.
  • A zip containing only ASSESSMENT.md and no lessons is valid - that is an assessment-only course.

On its own

Section titled “On its own”

A single ASSESSMENT.md file can be imported directly into an existing course:

  1. In Course Overview, click Add Assessment.
  2. In the dialog, choose Import ASSESSMENT.md instead of a question-count preset.
  3. Select your .md file. The questions and the scoring settings both come from the file, so the assessment opens ready to edit.

The dialog also offers a downloadable ASSESSMENT.md template to start from.

Error handling

Section titled “Error handling”

The parser reports issues in two categories:

Errors (prevent import):

  • Missing title in frontmatter
  • No knowledge-check block (an assessment with no questions)
  • Unclosed ::: fence

Warnings (the item is skipped or adjusted):

  • A disallowed block type (anything other than text, image, or knowledge-check) is dropped
  • An attempts, pass, or randomize value that can’t be read falls back to its default

When you import a standalone assessment, Slate shows a toast noting how many items were adjusted to fit the assessment format.

Section titled “Related”