Skip to content

Commit 040d401

Browse files
staredclaude
andcommitted
Update README: add inspirations and improve clarity
Added inspiration credits: - BetterExplained's colorized equations - Stuart Riffle's Fourier transform visualization (2011) Improvements: - More concise features list highlighting key capabilities - Simplified "How It Works" section - Updated file structure and examples to reflect current codebase - Clearer instructions for creating new equations - Removed redundant content 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
1 parent 7752c8b commit 040d401

File tree

1 file changed

+43
-56
lines changed

1 file changed

+43
-56
lines changed

README.md

Lines changed: 43 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,18 @@ A minimal framework for creating interactive mathematical explanations with colo
44

55
**Demo:** [https://p.migdal.pl/equations-explained-colorfully/](https://p.migdal.pl/equations-explained-colorfully/)
66

7-
Inspired by the concept of [explorable explanations](https://p.migdal.pl/blog/2024/05/science-games-explorable-explanations/), this framework makes mathematical equations more accessible through color-coding and interactive hover effects.
7+
**Inspired by:**
8+
- [Explorable explanations](https://p.migdal.pl/blog/2024/05/science-games-explorable-explanations/) as a learning medium
9+
- [BetterExplained's colorized equations](https://betterexplained.com/articles/colorized-math-equations/)
10+
- Stuart Riffle's [color-coded Fourier transform](https://web.archive.org/web/20130318211259/http://www.altdevblogaday.com/2011/05/17/understanding-the-fourier-transform) (2011)
811

912
## Features
1013

11-
- Simple markdown-based content format
12-
- Color-coded equation terms with hover interactions
13-
- Multiple color schemes (including accessibility options)
14-
- Minimal dependencies
15-
- Reusable across different equations
14+
- **Markdown-based**: Write equations in simple markdown format
15+
- **Interactive**: Hover over colored terms to see definitions
16+
- **Accessible**: Multiple color schemes including color-blind friendly options
17+
- **Minimal**: Built with KaTeX, CodeJar, and Prism (~10KB total)
18+
- **Editable**: Real-time editor for creating and modifying equations
1619

1720
## Content Format
1821

@@ -56,39 +59,23 @@ Fundamental constant connecting energy and frequency.
5659
**Value:** $\hbar \approx 1.055 \times 10^{-34}$ J·s
5760
```
5861

59-
## Color Schemes
60-
61-
Colors are automatically assigned based on the order terms appear in the document:
62-
63-
```typescript
64-
colorSchemes = {
65-
vibrant: ['#8b5cf6', '#10b981', '#ec4899', ...],
66-
accessible: ['#0072B2', '#E69F00', '#009E73', ...], // Wong palette
67-
contrast: ['#0066CC', '#FF6600', '#9933CC', ...],
68-
nocolor: ['#000000', '#000000', '#000000', ...]
69-
}
70-
```
71-
72-
The first term gets `colors[0]`, second gets `colors[1]`, etc.
73-
7462
## How It Works
7563

76-
1. **Parse** markdown content to extract:
77-
- LaTeX equation (converting `\mark` to `\htmlClass`)
78-
- Description text (converting `{.class}` to `<span>`)
79-
- Definitions from heading sections
64+
1. **Parse** markdown: Convert `\mark[label]{content}` to `\htmlClass{term-label}{content}` for KaTeX
65+
2. **Render** equation using KaTeX, description and definitions as HTML
66+
3. **Color** terms based on order of appearance in equation (first term → first color, etc.)
67+
4. **Interact**: Hover over colored terms to see definitions, click to lock
8068

81-
2. **Render** using KaTeX for math and HTML for text
69+
**Color schemes available:** Vibrant (default), Accessible (Wong palette), High Contrast, No Color
8270

83-
3. **Color** terms dynamically using CSS variables:
84-
- `.imaginary``--color-imaginary``colors[0]`
85-
- `.planck``--color-planck``colors[1]`
71+
## Examples
8672

87-
4. **Interact** with hover effects showing definitions
88-
89-
## Example
90-
91-
See [content.md](content.md) for a complete example (Schrödinger equation).
73+
See `public/examples/` for complete examples:
74+
- `new.md` - Simple starter template (E = mc²)
75+
- `schrodinger.md` - Schrödinger equation
76+
- `maxwell.md` - Maxwell's equations
77+
- `navier-stokes.md` - Navier-Stokes equation
78+
- `euler.md` - Euler's identity
9279

9380
## Usage
9481

@@ -103,36 +90,36 @@ pnpm dev
10390
pnpm build
10491
```
10592

106-
## Creating New Interactive Equations
107-
108-
1. Create a new markdown file following the format above
109-
2. Update `loadContent('/your-file.md')` in `main.ts`
110-
3. Adjust color scheme arrays if you need more/fewer colors
93+
## Creating New Equations
11194

112-
## Design Philosophy
95+
1. Create a markdown file in `public/examples/` (e.g., `my-equation.md`)
96+
2. Add entry to `public/examples/equations.json`:
97+
```json
98+
{
99+
"id": "my-equation",
100+
"title": "My Equation",
101+
"category": "Physics",
102+
"file": "my-equation.md"
103+
}
104+
```
105+
3. Use the in-browser editor to refine your equation interactively
113106

114-
- **Minimal syntax**: Natural markdown with simple annotations
115-
- **Separation of concerns**: Content (markdown) separate from styling (CSS) and logic (TypeScript)
116-
- **Accessibility**: Multiple color schemes including color-blind friendly options
117-
- **Tufte-inspired**: Clean, minimal design focusing on content
118-
119-
## File Structure
107+
## Key Files
120108

121109
```
122-
├── content.md # Equation content in markdown
123-
├── src/
124-
│ ├── main.ts # Main application logic
125-
│ ├── parser.ts # Markdown parser
126-
│ └── style.css # Styles
127-
├── index.html # HTML entry point
128-
└── README.md # This file
110+
public/examples/ # Equation markdown files
111+
├── equations.json # List of available equations
112+
└── *.md # Individual equation files
113+
src/
114+
├── main.ts # Main app logic & editor
115+
├── parser.ts # Markdown → KaTeX/HTML parser
116+
├── prism-custom.ts # Syntax highlighting for editor
117+
└── style.css # Tufte-inspired minimal styles
129118
```
130119

131120
## Author
132121

133-
Created by [Piotr Migdał](https://p.migdal.pl).
134-
135-
For more on interactive explanations and science communication, see: [Science, games, and explorable explanations](https://p.migdal.pl/blog/2024/05/science-games-explorable-explanations/).
122+
Created by [Piotr Migdał](https://p.migdal.pl)
136123

137124
## License
138125

0 commit comments

Comments
 (0)