https://github.com/stared/equations-explained-colorfully
KaTeX + coloring + interactivity to make equations explained well (prototype)
https://github.com/stared/equations-explained-colorfully
Last synced: about 1 month ago
JSON representation
KaTeX + coloring + interactivity to make equations explained well (prototype)
- Host: GitHub
- URL: https://github.com/stared/equations-explained-colorfully
- Owner: stared
- License: mit
- Created: 2025-11-03T11:11:49.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-12-31T20:12:39.000Z (4 months ago)
- Last Synced: 2026-01-05T07:23:14.693Z (4 months ago)
- Language: TypeScript
- Homepage: http://p.migdal.pl/equations-explained-colorfully/
- Size: 985 KB
- Stars: 16
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Equations Explained Colorfully
A minimal framework for creating interactive mathematical explanations with colored, annotated equations.
**Demo:** [https://p.migdal.pl/equations-explained-colorfully/](https://p.migdal.pl/equations-explained-colorfully/)
**Inspired by:**
- [Explorable explanations and science-based games](https://p.migdal.pl/blog/2024/05/science-games-explorable-explanations/)
- [BetterExplained's colorized equations](https://betterexplained.com/articles/colorized-math-equations/)
- [Stuart Riffle's color-coded Fourier transform](https://web.archive.org/web/20130318211259/http://www.altdevblogaday.com/2011/05/17/understanding-the-fourier-transform)
I am grateful to [Amit Patel (Red Blob Games)](https://www.redblobgames.com/) 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:
```latex
$$
\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:
```markdown
## Description
Multiply the [imaginary unit]{.imaginary} by [Planck constant]{.planck}...
```
### 3. Definitions (Heading-based)
Use `## .classname` headings for detailed explanations:
```markdown
## .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
```bash
# 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ł](https://p.migdal.pl)
## License
MIT