OpenPhysica

A collaborative physics documentation platform built with Astro, featuring real-time editing capabilities and GitHub-powered collaboration.

🌟 Features

• 📝 Collaborative Editing: Edit physics documentation directly in your browser with live preview
• 🔧 GitHub Integration: Seamless integration with GitHub for version control and collaboration
• 🌍 Multilingual Support: Full internationalization support (English and Italian)
• ⚡ Modern Tech Stack: Built with Astro 5, React 19, and TailwindCSS 4
• 🎨 Beautiful UI: Styled with daisyUI for consistent, accessible design
• 📱 Responsive Design: Works perfectly on desktop, tablet, and mobile devices
• 🔍 Search Functionality: Find physics concepts and documentation quickly
• 🖼️ Image Management: Upload and manage images directly through the editor
• 📊 Math Support: KaTeX integration for mathematical expressions
• 🎯 Custom Components: Specialized MDX components for educational content

🚀 Quick Start

Prerequisites

• Node.js 18.20.8+ or 20.3.0+ or 22.0.0+
• pnpm (recommended) or npm

Installation

1. Clone the repository

   git clone https://github.com/your-username/OpenPhysica.git
   cd OpenPhysica

2. Install dependencies

   pnpm install

3. Start the development server

   pnpm dev

4. Open your browser Navigate to http://localhost:4321

Environment Setup

Create a .env file in the root directory:

# GitHub OAuth Configuration (for editing features)
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret

# Repository Configuration
GITHUB_REPO_OWNER=your-username
GITHUB_REPO_NAME=OpenPhysica

# Optional: Analytics
ANALYTICS_ID=your_analytics_id

📖 Project Structure

OpenPhysica/
├── content/docs/           # Documentation content (MDX files)
├── public/                 # Static assets
├── src/
│   ├── components/         # Reusable components
│   │   ├── mdx/           # Custom MDX components
│   │   ├── react/         # React components
│   │   └── pages/         # Page components
│   ├── layouts/           # Page layouts
│   ├── lib/               # Utility functions
│   ├── pages/             # Astro pages/routes
│   └── types/             # TypeScript type definitions
├── astro.config.mjs       # Astro configuration
├── package.json           # Dependencies and scripts
└── tailwind.config.js     # TailwindCSS configuration

🛠️ Tech Stack

Core Technologies

• Astro 5 - Modern web framework
• React 19 - Interactive components
• TypeScript - Type safety
• MDX - Markdown with JSX components

Styling & UI

• TailwindCSS 4 - Utility-first CSS framework
• daisyUI 5 - Component library
• Lucide Icons - Beautiful icons

Collaboration & Content

• GitHub API - Repository management
• Octokit - GitHub API client
• KaTeX - Math rendering
• Shiki - Syntax highlighting

Development Tools

• Prettier - Code formatting
• ESLint - Code linting
• Vercel - Deployment platform

📝 Content Creation

Basic Markdown Syntax

OpenPhysica supports all standard Markdown features:

Text Formatting

**Bold text**
_Italic text_
~~Strikethrough~~
`Inline code`

Headings

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6

Lists

- Unordered list item 1
- Unordered list item 2
  - Nested item
  - Another nested item

1. Ordered list item 1
2. Ordered list item 2
   1. Nested numbered item
   2. Another nested numbered item

Links and Images

[Link text](https://example.com)
[Link with title](https://example.com "Title")

![Alt text](image.jpg)
![Image with title](image.jpg "Image title")

Code Blocks

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

def calculate_force(mass, acceleration):
    return mass * acceleration

E = mc^2

#### Blockquotes
```markdown
> This is a blockquote
>
> It can span multiple lines
>
> > And can be nested

Tables

| Property     | Symbol | Unit | Description             |
| ------------ | ------ | ---- | ----------------------- |
| Force        | F      | N    | Newton's second law     |
| Mass         | m      | kg   | Amount of matter        |
| Acceleration | a      | m/s² | Rate of velocity change |

Horizontal Rules

---
---

---

Mathematical Expressions

OpenPhysica supports LaTeX math rendering through KaTeX:

Inline Math

The speed of light is $c = 3 \times 10^8$ m/s.

Display Math

$$
F = ma
$$

$$
E = \frac{1}{2}mv^2 + mgh
$$

Physics Formulas

$$
\begin{align}
v &= v_0 + at \\
x &= x_0 + v_0t + \frac{1}{2}at^2 \\
v^2 &= v_0^2 + 2a(x - x_0)
\end{align}
$$

Custom MDX Components

OpenPhysica provides specialized components for educational content:

Callouts

Use callouts to highlight important information:

<Callout type="info">
  This is an informational callout with helpful context.
</Callout>

<Callout type="success">Great job! You've mastered this concept.</Callout>

<Callout type="warning">
  Be careful with this calculation - it's easy to make mistakes.
</Callout>

<Callout type="error">
  This is a common misconception that should be avoided.
</Callout>

<Callout type="note">Here's an interesting fact related to this topic.</Callout>

Custom Titles:

<Callout type="info" title="Physics Insight">
  Custom callout with a specific title.
</Callout>

Tabs

Organize content into tabbed sections:

<Tabs labels={["Theory", "Example", "Practice"]}>
  <div slot="tab-0">
    ## Theoretical Foundation Here's the theoretical explanation of the concept.
  </div>

<div slot="tab-1">## Worked Example Let's solve a problem step by step.</div>

  <div slot="tab-2">
    ## Practice Problems Try these exercises to test your understanding.
  </div>
</Tabs>

Multiple Tabs:

<Tabs labels={["Kinematics", "Dynamics", "Energy", "Momentum", "Waves"]}>
  <div slot="tab-0">Content about kinematics equations and motion.</div>

<div slot="tab-1">Content about forces and Newton's laws.</div>

<div slot="tab-2">Content about kinetic and potential energy.</div>

<div slot="tab-3">Content about conservation of momentum.</div>

  <div slot="tab-4">Content about wave properties and behavior.</div>
</Tabs>

Details (Expandable Sections)

Create collapsible content sections:

<Details summary="Click to see the detailed solution">
Here's the step-by-step solution that was hidden:

1. First, identify the given values
2. Choose the appropriate equation
3. Substitute the values
4. Solve for the unknown
5. Check units and reasonableness
   </Details>

<Details summary="Advanced Topics" open={true}>
  This section starts expanded and covers advanced concepts that build upon the
  basic material.
</Details>

Advanced MDX Features

Combining Components

<Callout type="info" title="Multi-Step Problem">
This problem requires several physics concepts.

<Details summary="Hint 1">Start by drawing a free body diagram.</Details>

<Details summary="Hint 2">
  Apply Newton's second law in both x and y directions.
</Details>

<Tabs labels={["Method 1", "Method 2"]}>
  <div slot="tab-0">
    ## Energy Approach
    Use conservation of energy to solve.
  </div>
  
  <div slot="tab-1">
    ## Force Approach
    Use Newton's laws directly.
  </div>
</Tabs>
</Callout>

Interactive Examples

<Callout type="note" title="Interactive Simulation">
Try adjusting the parameters in this simulation:

<Details summary="Simulation Controls">
- Mass: Use slider to change from 1-10 kg
- Force: Adjust from 0-50 N
- Friction: Toggle on/off
</Details>
</Callout>

🤝 Contributing

We welcome contributions from the physics and education community! Here's how you can help:

Ways to Contribute

1. Content Creation: Add new physics topics, improve explanations
2. Translation: Help translate content to other languages
3. Bug Reports: Report issues with the platform or content
4. Feature Requests: Suggest new features or improvements
5. Code Contributions: Improve the platform itself

Getting Started with Contributions

1. Fork the repository on GitHub
2. Clone your fork locally
3. Create a feature branch: git checkout -b feature/new-physics-topic
4. Make your changes using the built-in editor or locally
5. Test your changes with pnpm dev
6. Commit your changes: git commit -m "Add quantum mechanics section"
7. Push to your fork: git push origin feature/new-physics-topic
8. Create a Pull Request on GitHub

Using the Built-in Editor

For content contributions, you can use the built-in editor:

1. Navigate to any page you want to edit
2. Click the "Edit Page" button (requires GitHub login)
3. Make your changes in the editor with live preview
4. Submit a pull request directly from the interface

Content Guidelines

• Accuracy: Ensure all physics content is scientifically accurate
• Clarity: Write for students at the appropriate level
• Examples: Include worked examples and practice problems
• Visuals: Add diagrams and illustrations where helpful
• Citations: Reference authoritative sources

Code Style

• Use Prettier for code formatting
• Follow TypeScript best practices
• Write meaningful commit messages
• Add tests for new functionality

🌍 Internationalization

OpenPhysica supports multiple languages:

Supported Languages

• English (en) - Primary language
• Italian (it) - Secondary language

Adding Translations

1. Create language files in the appropriate directory:

   content/docs/topic-name.en.mdx
   content/docs/topic-name.it.mdx
   

2. Update navigation in src/lib/translations.json

3. Test translations with the language switcher

Translation Guidelines

• Maintain the same structure across languages
• Adapt examples to local contexts when appropriate
• Ensure mathematical notation remains consistent
• Preserve component usage and formatting

🚀 Deployment

Vercel (Recommended)

1. Connect your GitHub repository to Vercel
2. Configure environment variables in the Vercel dashboard
3. Deploy automatically on every push to main

Manual Deployment

1. Build the project:

   pnpm build

2. Deploy the dist folder to your hosting provider

Environment Variables

For production deployment, set these environment variables:

GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GITHUB_REPO_OWNER=your-username
GITHUB_REPO_NAME=OpenPhysica
SITE_URL=https://your-domain.com

📚 API Reference

GitHub Integration

The platform integrates with GitHub for:

• Authentication: OAuth login for contributors
• Content Management: Reading and writing MDX files
• Version Control: Creating pull requests for changes
• Image Storage: Uploading images to the repository

Editor Features

• Real-time Preview: See changes instantly
• Syntax Highlighting: MDX and code block highlighting
• Error Detection: Catch syntax errors before submission
• Diff View: Compare changes with original content
• Image Upload: Drag-and-drop image support

🔧 Configuration

Astro Configuration

Key configuration options in astro.config.mjs:

export default defineConfig({
  integrations: [react(), mdx(), vercel()],
  markdown: {
    shikiConfig: {
      theme: "dracula",
      langs: ["javascript", "python", "latex"],
    },
  },
});

TailwindCSS Configuration

Custom configuration for educational content:

module.exports = {
  content: ["./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}"],
  plugins: [require("@tailwindcss/typography"), require("daisyui")],
  daisyui: {
    themes: ["light", "dark"],
  },
};

🤔 FAQ

General Questions

Q: Is OpenPhysica free to use? A: Yes, OpenPhysica is completely free and open source.

Q: Do I need GitHub to view content? A: No, GitHub is only required for editing and contributing content.

Q: Can I use OpenPhysica offline? A: The site requires an internet connection, but content can be downloaded for offline reading.

Technical Questions

Q: What browsers are supported? A: Modern browsers including Chrome, Firefox, Safari, and Edge.

Q: Can I self-host OpenPhysica? A: Yes, follow the deployment instructions above.

Q: How do I report a bug? A: Create an issue on the GitHub repository with detailed information.

Content Questions

Q: How do I add mathematical equations? A: Use LaTeX syntax with KaTeX for inline ($...$) or display ($$...$$) math.

Q: Can I add interactive simulations? A: Currently, simulations must be embedded as external content or images.

Q: How do I upload images? A: Use the image upload feature in the editor or add images to the public folder.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Astro Team for the amazing web framework
• React Team for the powerful UI library
• TailwindCSS Team for the utility-first CSS framework
• daisyUI Team for the beautiful component library
• KaTeX Team for mathematical typesetting
• GitHub for hosting and collaboration tools
• Physics Education Community for inspiration and content

📞 Support

• Documentation: Visit our documentation site
• GitHub Issues: Report bugs and request features
• Community: Join our discussions in GitHub Discussions
• Email: Contact us at support@your-domain.com

---

Made with ❤️ for the physics education community