Setup choices, profiles, and native embeds

Teaching 15 min

Exercises 5 min

Estimated 20 min

Questions

How do we document setup and learner variation without overloading the main narrative?

Objectives

Show how profile pages and glossary pages support lesson navigation.
Use Hugo-native embed syntax instead of hand-written iframe HTML when a provider shortcode exists.

Profiles make it easier to explain why a lesson exists for different audiences. In this example, the Workshop Host profile cares most about pacing, while the Self Paced Maintainer profile cares more about update flow and repo ownership.

For terminology, content can link to short definitions like Audience Toggle without interrupting the main narrative.

A facilitation sketch showing where setup decisions and audience mode intersect.

Tabs for local setup choices

This page opts out of synced tabs so the examples can stay local to this episode. That is useful when one tab set is about operating systems and another is about shells, but you do not want changing one to affect the other.

Tell learners where a tool lives in Finder or which package manager you expect them to use.

export LESSON_ENV=workshop

Because this page disables sync, the second shell tab group below starts independently instead of following the choice above.

echo $LESSON_ENV

Below is a native Hugo video embed example:

Migration expectation

The migration helper should cover the common path well, but highly customised legacy sites should still expect a short manual pass.

Key Points

Profiles and glossary entries are easier to maintain as real content pages.
Supported video providers should use Hugo shortcodes rather than raw iframe HTML.

Using challenge and solution blocks Physics notation, diagrams, and richer docs