GitHub - stared/equations-explained-colorfully: KaTeX + coloring + interactivity to make equations explained well (prototype)

A minimal framework for creating interactive mathematical explanations with colored, annotated equations.

Demo: https://p.migdal.pl/equations-explained-colorfully/

Inspired by:

• Explorable explanations and science-based games
• BetterExplained's colorized equations
• Stuart Riffle's color-coded Fourier transform

I am grateful to Amit Patel (Red Blob Games) for valuable feedback on an early draft.

Features

• Markdown-based: Write equations in simple markdown format
• Interactive: Hover over colored terms to see definitions
• Accessible: Multiple color schemes including color-blind friendly options
• Minimal: Built with Vue 3, KaTeX, CodeJar, and Prism
• Export: Generate standalone HTML, LaTeX, Beamer, or Typst output
• Editable: Real-time editor for creating and modifying equations

Content Format

Create a markdown file with three sections:

1. Equation (LaTeX with annotations)

Use \mark[classname]{formula} to annotate terms:

$$
\mark[imaginary]{i}\mark[planck]{\hbar}\mark[timederiv]{\frac{\partial\psi}{\partial t}} = ...
$$

2. Description (Markdown with term references)

Use [text]{.classname} to reference terms with the same color:

## Description

Multiply the [imaginary unit]{.imaginary} by [Planck constant]{.planck}...

3. Definitions (Heading-based)

Use ## .classname headings for detailed explanations:

## .imaginary

Indicates the quantum nature of the equation and ensures unitary time evolution.

The imaginary unit $i$ is fundamental to quantum mechanics.

## .planck

Fundamental constant connecting energy and frequency.

**Value:** $\hbar \approx 1.055 \times 10^{-34}$ J·s

How It Works

1. Parse markdown: Convert \mark[label]{content} to \htmlClass{term-label}{content} for KaTeX
2. Render equation using KaTeX, description and definitions as HTML
3. Color terms based on order of appearance in equation (first term → first color, etc.)
4. Interact: Hover over colored terms to see definitions, click to lock

Color schemes available: Vibrant (default), Accessible (Wong palette), High Contrast, No Color

Examples

See src/examples/ for complete examples:

• new.md - Simple starter template (E = mc²)
• schrodinger.md - Schrödinger equation
• maxwell.md - Maxwell's equations
• navier-stokes.md - Navier-Stokes equation
• euler.md - Euler's identity

Usage

# Install dependencies
pnpm install

# Run dev server
pnpm dev

# Build for production
pnpm build

Creating New Equations

1. Create a markdown file in src/examples/ (e.g., my-equation.md)
2. Use the in-browser editor to refine your equation interactively

Key Files

src/examples/            # Equation markdown files
  └── *.md               # Individual equation files
src/
  ├── main.ts            # Vue app entry point
  ├── App.vue            # Main app layout with three-panel design
  ├── components/
  │   ├── CentralPanel.vue       # Equation display with hover interactions
  │   ├── MarkdownEditor.vue     # CodeJar editor with Prism highlighting
  │   ├── controls/              # EquationSelector, ColorSchemeSwitcher, ExportControls
  │   └── equation/              # EquationDisplay, DescriptionPanel, DefinitionPopup
  ├── export/            # Export formats (HTML, LaTeX, Beamer, Typst)
  └── utils/             # parser.ts, colorSchemes.ts, termDom.ts

Author

Created by Piotr Migdał

License

MIT