Skip to content
Examples
Physics notation, diagrams, and richer docs

Episode

Physics notation, diagrams, and richer docs

Teaching 20 min
Exercises 10 min
Estimated 30 min

Questions

  • How can we communicate a particle-physics analysis workflow clearly without custom frontend code?

Objectives

  • Use LaTeX and Mermaid to express analysis logic and notation directly in lesson content.
  • Use Hextra components to keep setup, navigation, and optional depth structured and maintainable.

This episode demonstrates documentation-focused Hextra features in a particle-physics context. The goal is to keep source files readable for authors while giving learners clear visual structure.

LaTeX for physics notation

Inline notation is useful for compact expressions like pT>25 GeVp_T > 25\,\mathrm{GeV}, ∣η∣<2.4|\eta| < 2.4, and ΔR<0.4\Delta R < 0.4.

A standalone equation block can communicate selection logic and uncertainty estimates more clearly:

Nsig=Nobs−NbkgZ≈NsigNbkg+(δNbkg)2 \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}
Notation scope
Keep first-pass equations close to the learning objective. Move detailed derivations to optional details blocks.

Mermaid for analysis flow 

    flowchart LR
  A[Detector data] --> B[Reconstruction]
  B --> C[Quality filters]
  C --> D[Object selection]
  D --> E[Signal region]
  D --> F[Control region]
  E --> G[Fit and inference]
  F --> G
  
    sequenceDiagram
  participant C as Collaborator
  participant CI as CI checks
  participant R as Reviewers
  C->>CI: Push selection update
  CI-->>C: Validation and build report
  C->>R: Open PR with plots and notes
  R-->>C: Request uncertainty clarification

Synced tabs for command variants

Use repeated tab labels to keep shell choices synced across blocks.

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

FileTree and Cards for orientation

      • 01-introduction/index.md
      • 04-physics-doc-features/index.md
      • setup.md
  • hugo.toml
Authoring Guide
Structure and pedagogy conventions.
core
Hextra Features
Curated feature usage for lesson authors.
core
Update workflow
How to pull shared module updates safely.
maintenance
Reference links
Upstream docs for deeper options.
upstream

Steps plus optional deep dive

Write the question and objective first

Anchor the episode around one concrete analysis skill.

Add one core equation and one core diagram

Use LaTeX and Mermaid to keep explanation compact and precise.

Keep setup variants in tabs

Avoid long repeated command blocks in linear prose.

Hide advanced context in details blocks

Keep the default reading path short, then let motivated learners expand.

Optional: invariant-mass reminder
For two reconstructed leptons, mℓℓ2=(E1+E2)2−∥p⃗1+p⃗2∥2m_{\ell\ell}^2 = (E_1 + E_2)^2 - \lVert \vec{p}_1 + \vec{p}_2 \rVert^2.
Use this as context when explaining mass-window selection.
Challenge

Document a toy signal-selection flow

Add one Mermaid flowchart and one LaTeX equation to a new episode page that explains a toy signal-vs-background workflow.

Need a hint?
Start with only four stages: reconstruction, quality filters, signal region, control region.
Show solution
Keep the first version minimal: one flowchart, one equation for ZZ or a counting estimate, and one optional details block for background theory.

Key Points

  • Prefer built-in Hextra features over custom templates for diagrams and notation.
  • Use tabs, details, steps, cards, and filetree to separate core path from optional depth.
Setup choices, profiles, and native embeds