Skip to content
All-in-One

Aggregated resource

All-in-One

This page combines the lesson into one continuous view.

1 episode
20 min total
Best for teaching from one tab

Lesson controls

Jump between episodes, filter the page, or reveal every hint and solution when you need the full teaching flow.

Getting started

Episode

Getting started

Teaching 10 min
Exercises 10 min
Estimated 20 min

Questions

  • How do I start a lesson from this template?

Objectives

  • Follow a reliable first-run order: setup, metadata update, then content replacement.
  • Update the key hugo.toml fields so links, branding, and deployment targets are correct.

Use this order for a clean start:

  1. complete local setup checks
  2. update lesson metadata in hugo.toml
  3. replace sample pages with your own lesson material
  4. use the shared docs when you need deeper authoring or deployment detail

For module refresh and _vendor/ maintenance details, see Reference.

1. Run setup checks first

Before editing content, confirm your toolchain from the Setup page.

Then run:

hugo version
hugo server

This works without Go because the template commits a vendored module tree in _vendor/.

If setup is unclear, use the shared docs:

2. Update hugo.toml early

Edit these fields before replacing episode content:

FieldWhy it matters
baseURLProduction URL for deployed pages and canonical links, for example https://<account>.github.io/<repo>/.
top-level titleSite title used in browser/title surfaces.
[params.lesson].titleLesson title shown in theme components.
[params.lesson].tagline and descriptionHomepage framing and metadata summary.
[params.lesson].contactContact shown in lesson metadata contexts.
[params.lesson].repoFooter source link target in the UI.
[params.lesson].editBranchBranch used for “Edit this page” links.
[params.versioning]Controls whether the deployment workflow publishes only Latest or also archived branch/tag builds.
[[menus.main]] GitHub urlTop-nav GitHub link target.

If you plan to deploy on GitHub Pages, enable Pages in the repository settings and choose GitHub Actions as the source before the first push to main. The included workflow deploys on pushes to main, so that first push should already have a configured Pages target.

Keep these as-is unless you know why
Do not remove the module.imports block that points to github.com/oer-particle-physics/hugo-styles. That import is what provides the shared layouts, shortcodes, and supporting behavior.

3. Replace template content with your lesson

After metadata is set:

  • replace this sample episode with your first real episode
  • set episode order with front matter weight values (10, 20, 30, …) rather than filename prefixes
  • update content/_index.md homepage copy
  • add or rename glossary/profile pages if needed

For structure and conventions, use:

Challenge

Local vs shared

List two things that should stay in this lesson repository and two things that should stay in the shared module.

Need a hint?
Think about what is specific to your lesson topic versus what should stay reusable across many lessons.
Show solution
Lesson prose, schedule, glossary/profile content, and local branding should stay in this repository. Shared layouts, pedagogy shortcodes, CSS/JS behavior, and validation tooling should stay upstream in hugo-styles.
Instructor
Point maintainers to the update guide early so they know updates should arrive through module version bumps: Updating Downstream Lessons.

Key Points

  • Start with learners/setup, then update hugo.toml before writing lesson content.
  • Keep lesson prose local and framework behavior in the shared hugo-styles module.
  • Use the shared hugo-styles docs after the local lesson skeleton is running.