Skip to content
This documentation is a live feature demo. See the feature guide.
Documentation
Authoring Guide

Authoring Guide

This is the shortest path from an empty template to a checked lesson. Keep the Front Matter and Components references open when you need field or shortcode details.

1. Create an episode 

hugo new content --kind episode episodes/05-your-topic/index.md

Put the teaching sequence in content/episodes/. Use content/learners/ for learner setup or reference material and content/instructors/ for facilitation notes. Keep glossary entries and audience profiles in their matching content/glossary/ and content/profiles/ sections.

2. Complete the episode metadata

Every episode needs a non-empty string title, an integer weight, and non-empty lists of non-empty questions, objectives, and keypoints. Optional teaching and exercises values are non-negative integer minutes.

See Front Matter for a copyable example and TOML math guidance.

3. Add teaching components

Use project-owned components for pedagogy and audience-specific content, then Hextra components for general documentation UI. The live references place copyable source beside every example:

  • Components: challenge, hint, solution, callouts, audience blocks, links, images, and lesson metadata
  • Hextra Features: math, Mermaid, tabs, details, steps, cards, code, PDF, Jupyter, search, theme, and other theme features
  • Glossary & Profiles: reusable glossary and profile pages

Episode and All-in-One pages add the learner/instructor selector automatically. On another page that contains learner or instructor blocks, place {{< lesson/audience-toggle >}} above them.

4. Preview both audiences 

hugo server

Open an episode and the All-in-One page, switch between learner and instructor, and check any local links or page-bundle images. Add ?view=learner or ?view=instructor to test a direct audience URL.

5. Validate and build 

go run github.com/oer-particle-physics/hugo-styles/cmd/hugo-styles-migrate@latest check .
hugo --gc --minify --panicOnWarning

The validator checks episode metadata types and values, unique weights, glossary/profile targets, image alt text, and unsupported legacy syntax. The Hugo build catches rendering warnings. Maintainers can run the full browser and rendered-link suite from hugo-styles Maintenance.

Live lesson examples

QuickstartFront Matter