Components

These are the supported lesson-specific components on top of Hextra. This page focuses on the Carpentries-style layer added by hugo-styles. For the broader Hextra and Hugo feature set, use the Reference page and the linked upstream docs. For a particle-physics-focused Hextra feature walkthrough, see Hextra Features for Physics Lessons.

Challenge, hint, and solution

{{< challenge title="Warm-up exercise" subtitle="Try the prompt on your own before the group debrief." >}}
Prompt the learner to do something concrete.

{{< hint >}}
Offer a small nudge.
{{< /hint >}}

{{< solution >}}
Provide the worked answer.
{{< /solution >}}
{{< /challenge >}}

Use these for real learning activities, not just decorative emphasis. The subtitle parameter is optional, so leave it out when the challenge title already does enough work on its own.

Callouts

Use the callout shortcode for the common Carpentries-style boxes:

note
prereq
checklist
testimonial
discussion
warning
caution

{{< callout type="discussion" title="Compare approaches" >}}
Ask learners to compare trade-offs before you reveal an answer.
{{< /callout >}}

Audience-aware content

{{< learner >}}
Learner-facing support text.
{{< /learner >}}

{{< instructor >}}
Facilitation guidance for instructors.
{{< /instructor >}}

The top-bar learner/instructor switch controls these blocks.

Details blocks

{{< details title="Why this matters" >}}
Expanded explanation or optional background.
{{< /details >}}

Tabs

Use Hextra-native tabs for OS, shell, or package-manager variants:

{{< tabs >}}
{{< tab name="bash" selected=true >}}
```bash
echo hello

echo hello


Tabs sync by default. Disable sync per page with:

```toml
+++
[tabs]
  sync = false
+++

For the full Hextra tab behavior and additional examples, see Hextra Tabs.

Videos

Use Hugo-native shortcodes when supported:

{{< youtube aqz-KE-bpKQ >}}

Avoid raw iframe HTML for providers that Hugo already supports directly. For the full list of embedded providers, see Hugo Embedded Shortcodes.

Lesson homepage snippets

The lesson landing page is usually content/_index.md with layout = "hextra-home". The shared module provides a few small shortcodes that make that page carry the same lesson metadata as the episode pages without introducing a custom layout.

+++
title = "My Lesson"
layout = "hextra-home"
+++

{{< lesson/overview >}}

{{< lesson/schedule title="Schedule" >}}

{{< lesson/authors title="Authors and Contributors" >}}

lesson/overview renders a compact table built from the objectives lists of all episode pages. lesson/schedule renders a timetable with an optional untimed setup row, a cumulative start-time column, the episode title, and the episode questions. lesson/authors renders a compact table of contributors from the repository root AUTHORS file on the homepage. lesson/meta reuses lesson metadata from hugo.toml directly inside Markdown body content.

Use lesson/meta when the homepage or another content page should echo the configured lesson title, tagline, or description without duplicating that text:

{{< lesson/meta "title" >}}
{{< lesson/meta "tagline" >}}
{{< lesson/meta "description" >}}
{{< lesson/meta "siteTitle" >}}

Supported keys:

title: params.lesson.title, falling back to title
tagline: params.lesson.tagline, falling back to params.lesson.description
description: params.lesson.description, falling back to params.lesson.tagline
siteTitle: the site-level title

Unsupported keys fail the build clearly so typos do not silently render empty content.

The authors file is intentionally lightweight. One contributor per line is enough:

# Comments are ignored
@alice
Ada Lovelace <ada-lovelace>
Grace Hopper <https://github.com/gracehopper>

That keeps the convention explicit while avoiding custom HTML includes.

Hextra home components

For landing pages, overview sections, or documentation marketing surfaces, you can also use Hextra’s own home components directly:

hextra/hero-badge
hextra/hero-headline
hextra/hero-subtitle
hextra/hero-button
hextra/feature-grid
hextra/feature-card

These are a good fit for non-pedagogy UI such as homepage highlights, getting-started links, or overview cards. The homepage of hugo-styles now uses them as the default pattern. For more theme-level homepage guidance, see Hextra Getting Started.

If you want the same overall homepage structure that Hextra uses, set:

+++
layout = "hextra-home"
+++

and compose the page from hextra/hero-badge, hextra/hero-headline, hextra/hero-subtitle, hextra/hero-button, and hextra/feature-grid.

For most downstream lesson repositories, the easiest customization path is:

Keep layout = "hextra-home" in content/_index.md.
Edit the copy, links, and cards in that file.
Prefer Hextra shortcodes over custom layout overrides.

A minimal starting point looks like this:

+++
title = "My Lesson"
layout = "hextra-home"
+++

{{< hextra/hero-badge link="docs/quickstart/" >}}
Workshop-ready lesson materials
{{< /hextra/hero-badge >}}

<div class="hx:mt-6 hx:mb-6">
{{< hextra/hero-headline >}}
Teach particle physics with a Carpentries-style lesson
{{< /hextra/hero-headline >}}
</div>

<div class="hx:mb-12">
{{< hextra/hero-subtitle >}}
Reuse the familiar teaching structure while keeping the site easy to maintain with Hugo.
{{< /hextra/hero-subtitle >}}
</div>

<div class="hx:mb-6">
{{< hextra/hero-button text="Start Learning" link="episodes/01-introduction/" >}}
</div>

<div class="hx:mt-6"></div>

{{< hextra/feature-grid cols="3" >}}
{{< hextra/feature-card title="Episodes" subtitle="Step-by-step lesson flow." icon="book-open" link="episodes/" class="hx:min-h-[220px]" >}}
{{< hextra/feature-card title="Setup" subtitle="Environment and data requirements." icon="cog" link="learners/setup/" class="hx:min-h-[220px]" >}}
{{< hextra/feature-card title="Teaching Notes" subtitle="Support for instructors and helpers." icon="academic-cap" link="instructors/" class="hx:min-h-[220px]" >}}
{{< /hextra/feature-grid >}}

Recommended customization boundaries:

Change the homepage content in content/_index.md.
Change site-wide metadata such as the title, repository URL, and menu entries in hugo.toml.
Add more hextra/feature-card entries or additional content sections if the lesson needs more orientation material.
Avoid copying layouts/hextra-home.html, navbar.html, or other theme templates unless you need a structural change that content cannot express.
Reach for custom CSS only after the built-in Hextra shortcodes and utilities stop being enough.

That keeps downstream lesson repositories thin and makes future Hextra or hugo-styles updates much easier to adopt.

For text-only homepages, adding small wrapper divs with Hextra utility classes like hx:mt-6, hx:mb-6, and hx:mb-12 is often enough to create better breathing room between the hero badge, headline, subtitle, button, and card grid.

Front Matter Glossary & Profiles