Open Source

Contribute to Physics

Help us build the most beautiful interactive physics library. Whether it's a new concept, a bug fix, or a better explanation, your contribution matters.

Find an Issue

How to Contribute

The most common way to contribute is by adding a new interactive concept page. Follow these steps to get started:

STEP 01

Fork & Setup

Clone the repository and start a local server. No complex build tools or bundlers are required—it's just pure HTML/JS.

git clone https://github.com/CasberryIndia/Physics-Notebook.git
cd Physics-Notebook
python3 -m http.server 8000  # or npx http-server

STEP 02

Create a Concept

Create a new file in Concepts/ (e.g., doppler-effect.html). Use our structure:

• Use standard HTML5 structure with our head section boilerplate.
• Implement 3 sections: Theory, Application, and Real-world Context.
• Write a visual class extending BaseVisual for the canvas animation.

STEP 03

Register Module

Add your new concept to the DATA array within index.html so it appears on the home page grid.

{
    id: 'doppler',
    title: 'Doppler Effect',
    domain: 'Waves',
    desc: 'Change in frequency based on relative motion.',
    href: 'Concepts/doppler-effect.html',
    type: 'doppler' // You'll adding a new visual class in index.html for the card preview
}

Quality Checklist

Before submitting your Pull Request, ensure your contribution meets these standards:

HTML structure follows the CONCEPT_PATTERN.md template.

Visualizations are interactive (sliders/inputs) and run smoothly at 60fps.

Equations are rendered correctly using MathJax (if applicable).

Design works perfectly in both Light and Dark modes.

Page is responsive and layouts adapt to mobile devices.

Code is clean, commented, and properly indented.

AI Agent Workflow

Have an AI agent create a new concept page for you — fully automatically. Clone the repo, point your AI assistant to the runbook, and it will research, code, verify, and register the new concept from start to finish.

STEP 01

Clone & Start the Server

Get the project running locally. No build step needed — it's plain HTML & JS.

git clone https://github.com/CasberryIndia/Physics-Notebook.git
cd Physics-Notebook
python3 -m http.server 8000

STEP 02

Ask Your AI Agent

Open the runbook in your AI coding assistant (Antigravity, Claude, Copilot, Cursor, etc.) and give it this prompt. The agent reads the checklist, searches the web for accuracy, generates the concept page, registers it, and runs verification checks.

Paste this into your AI agent

Please read CREATE_CONCEPT.md and add the next unchecked concept from CONCEPTS_CHECKLIST.md to the Physics Notebook. Follow every instruction in the runbook exactly.

STEP 03

Or Run the Python Script Directly

Alternatively, run the automation script. With a Gemini API key it operates fully autonomously — without one, it prints a ready-to-paste prompt for your AI assistant.

# Without API key — prints the prompt for you:
python3 scripts/add_concept.py

# With Gemini API key — runs end-to-end autonomously:
export GEMINI_API_KEY="your_key_here"
python3 scripts/add_concept.py

STEP 04

Review & Submit a PR

The agent will run accessibility checks automatically. Review the generated concept page in your browser at http://localhost:8000, then open a Pull Request.

git add .
git commit -m "feat: add [Concept Name] concept page"
git push origin your-branch

Runbook

Step-by-step instructions for AI agents in CREATE_CONCEPT.md

Automation Script

Python script that handles everything: scripts/add_concept.py

Concept Checklist

Track what's been done and what's next: CONCEPTS_CHECKLIST.md

Pattern Template

The canonical HTML structure all pages must follow: CONCEPT_PATTERN.md

Ready to submit your changes?

Make a Pull Request