Hextra Features for Physics Lessons

Use this page for practical, lesson-author-focused Hextra features that are especially useful in particle-physics tutorials. It complements upstream Hextra docs with domain-shaped examples instead of re-documenting every option.

Scope

This page covers the high-value defaults for lesson authors. For full option matrices and edge cases, use the linked upstream Hextra pages.

High-value feature map

Feature	Good fit in physics lessons	Upstream
LaTeX	equations, symbols, uncertainty notation	LaTeX
Mermaid	selection flow and collaboration diagrams	Diagrams
Tabs	OS/shell/package-manager variants	Tabs
Details	optional derivations and deep dives	Details
FileTree	repository and data layout orientation	FileTree
Cards	quick links to key lesson resources	Cards
Steps	short procedural workflows	Steps
Syntax highlighting	line numbers and highlighted snippets	Syntax Highlighting

LaTeX for analysis notation

Inline notation works well for terms like $p_T$ , $\eta$ , and $\Delta R$ .

For standalone equations:

\begin{aligned} N_{\text{sig}} &= N_{\text{obs}} - N_{\text{bkg}} \\ Z &\approx \frac{N_{\text{sig}}}{\sqrt{N_{\text{bkg}} + (\delta N_{\text{bkg}})^2}} \end{aligned}

hugo-styles enables Goldmark passthrough delimiters so $...$ and $$...$$ render correctly.

Mermaid for analysis and teaching flow

    flowchart LR
  A[Raw events] --> B[Reconstruction]
  B --> C[Object selection]
  C --> D[Signal region]
  C --> E[Control region]
  D --> F[Histogram + fit]
  E --> F

    sequenceDiagram
  participant DAQ as Data acquisition
  participant RECO as Reconstruction
  participant ANA as Analysis team
  participant REV as Internal review
  DAQ->>RECO: Calibrated data stream
  RECO->>ANA: Ntuples + metadata
  ANA->>REV: Selection + uncertainty model
  REV-->>ANA: Feedback and sign-off

Tabs for setup variants

Use the same labels across tab groups when you want sync behavior.

python -m venv .venv
source .venv/bin/activate

File orientation with FileTree and Cards

- - 01-introduction/index.md
  - 04-physics-doc-features/index.md
- - setup.md
hugo.toml

Authoring model

Where pedagogy conventions live.

core

Component reference

Lesson shortcodes and examples.

core

Update workflow

How downstream lessons consume module releases.

maintenance

External references

Hextra and Hugo upstream docs.

upstream

Steps and optional depth

Define the learning objective

Write the specific analysis skill the learner should gain.

Show the minimal reproducible command path

Keep platform-specific command variants in short tab groups.

Add one visual summary

Use Mermaid for workflow shape before detailed prose.

Add one optional deep-dive block

Use details for derivations that are useful but not required for first pass.

Optional derivation: Poisson counting uncertainty

For quick estimates in counting analyses,

\sigma_N \approx \sqrt{N}

is often enough to explain uncertainty propagation in early lesson stages.

Syntax-highlighted snippets

selection.py

1
2
3
4
5
events = load_events("events.parquet")
selected = events[(events.pt > 25) & (abs(events.eta) < 2.4)]
control = selected[selected.m_ll.between(70, 110)]
signal = selected[selected.m_ll.between(110, 160)]
plot_mass(control, signal)

For badge/PDF/video and other utility shortcodes, see Other Shortcodes.

Glossary & Profiles Deployment