Using challenge and solution blocks
Episode
Using challenge and solution blocks
Teaching 15 min
Exercises 10 min
Estimated 25 min
Questions
- How should active-learning blocks behave in a Hugo-based lesson?
Objectives
- Use challenge, hint, and solution shortcodes in a way that feels natural to authors.
- Show how learner and instructor context can coexist in the same episode.
Shortcodes should help the author express teaching intent, not force them to think about page mechanics.
Challenge
Draft a reusable exercise block
Write a short prompt that asks contributors to identify which parts of a lesson framework should remain shared across repositories.
Need a hint?
Think about pieces that change rarely and are expensive to copy around.
Show solution
Reusable framework elements usually include layouts, shortcodes, shared CSS, small interaction scripts, and validation logic. Lesson-specific prose and branding should normally stay local to each tutorial repository.
Review checklist
- Does the activity ask learners to do something concrete?
- Is the expected answer small enough for a workshop?
- Could an instructor reveal the solution only when needed?
Why not keep legacy fenced-attribute syntax?
It is harder to teach to new contributors, less portable, and more awkward to validate than a small set of explicit shortcodes.
Instructor
If you need to pace the room, ask learners to compare answers in pairs before expanding the solution.
Callout gallery
The older styles lessons relied heavily on recognisable teaching boxes. In this stack, they are still first-class teaching components, but their presentation stays closer to Hextra’s overall visual system.
Expand the Show code toggles to see the shortcode syntax for each box without making the page much longer.
Note
Use this for side context or reminders that support the main narrative.Show code (note)
{{< callout type="note" title="Note" >}}
Use this for side context or reminders that support the main narrative.
{{< /callout >}}Prerequisite
Use this when learners need knowledge or setup in place before continuing.Show code (prereq)
{{< callout type="prereq" title="Prerequisite" >}}
Use this when learners need knowledge or setup in place before continuing.
{{< /callout >}}Checklist
- Confirm the prompt is concrete.
- Keep the exercise small enough for a workshop.
- Make the reveal optional.
Show code (checklist)
{{< callout type="checklist" title="Checklist" >}}
- Confirm the prompt is concrete.
- Keep the exercise small enough for a workshop.
- Make the reveal optional.
{{< /callout >}}Discussion
Ask learners to compare trade-offs before showing a canonical answer.Show code (discussion)
{{< callout type="discussion" title="Discussion" >}}
Ask learners to compare trade-offs before showing a canonical answer.
{{< /callout >}}Instructor perspective
“This kind of box is useful when I want to signal facilitation intent without breaking the flow of the lesson.”Show code (testimonial)
{{< callout type="testimonial" title="Instructor perspective" >}}
“This kind of box is useful when I want to signal facilitation intent without breaking the flow of the lesson.”
{{< /callout >}}Common trap
Avoid using a generic callout when the content is actually an exercise or a solution. Those need their own behaviour.Show code (warning)
{{< callout type="warning" title="Common trap" >}}
Avoid using a generic callout when the content is actually an exercise or a solution. Those need their own behaviour.
{{< /callout >}}Migration caution
Legacy lessons may contain nested blockquote syntax that should be migrated automatically, but unusual customisations still deserve a quick manual pass.Show code (caution)
{{< callout type="caution" title="Migration caution" >}}
Legacy lessons may contain nested blockquote syntax that should be migrated automatically, but unusual customisations still deserve a quick manual pass.
{{< /callout >}}Learner
As a learner, you should mostly see activities, guidance, and supporting notes.
Instructor
As an instructor, this page can also surface pacing advice, debrief prompts, and workshop-specific facilitation notes without requiring a separate fork of the lesson.
Key Points
- Challenge blocks should be easy to read in source form and easy to scan on the page.
- Hints and solutions should stay collapsible but also support bulk expansion in the all-in-one page.