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:

complete local setup checks
update lesson metadata in hugo.toml
replace sample pages with your own lesson material
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:

Field	Why it matters
`baseURL`	Production URL for deployed pages and canonical links, for example `https://<account>.github.io/<repo>/`.
top-level `title`	Site title used in browser/title surfaces.
`[params.lesson].title`	Lesson title shown in theme components.
`[params.lesson].tagline` and `description`	Homepage framing and metadata summary.
`[params.lesson].contact`	Contact shown in lesson metadata contexts.
`[params.lesson].repo`	Footer source link target in the UI.
`[params.lesson].editBranch`	Branch 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 `url`	Top-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.