📚 General Physics Open Textbook

✨ Welcome to the Open Physics Textbook Project!

This open-source textbook aims to make physics education accessible to everyone. Whether you're a student, educator, or just curious about physics, this resource is for you!

Comprehensive Coverage: An introductory, algebra-based college physics textbook covering mechanics, thermodynamics, waves, electricity, magnetism, optics, and modern physics across 280+ sections.

⚡ Features

• Rich Mathematical Notation: Powered by MathJax v4 for beautifully rendered equations.
• Interactive & Responsive: Works seamlessly on desktop, tablet, and mobile devices.
• Offline Support: A root-level service worker (sw.js) enables offline access after the first visit.
• Dual Deployment: Automatically deployed to both Vercel and GitHub Pages.
• Fully Customizable: Fork and modify to suit your teaching needs.
• PDF Export: Generate PDF versions of individual chapters or the complete book.
• Free & Open: Licensed under CC BY-NC-SA 4.0 for educational use.

📥 PDF Downloads

Each page features a convenient PDF download button in the upper right corner:

• Chapter Pages: Download the complete chapter with all sections
• Section Pages: Download individual sections
• Preface & Summary: Download the entire book as a single PDF

Automated PDF Generation

PDFs are not stored in git (~587 MB). They are generated automatically during each GitHub Pages deployment using Playwright parallel processing (~60 minutes):

• 309 PDFs with beautifully rendered mathematical equations
• All figures and diagrams included
• Clean, print-optimized formatting
• Automatic failure recovery and regeneration

A quarterly workflow also publishes PDFs to the pdfs GitHub Release as a downloadable archive.

Available PDFs

• Section PDFs: 241 individual section documents
• Chapter Intro PDFs: 34 chapter introduction pages
• Combined Chapter PDFs: 34 complete chapters with all sections
• Complete Book PDF: Single PDF with entire textbook

Manual Generation

For local PDF generation with parallel processing, see the PDF generation section in the scripts documentation.

# Quick method (30 minutes for all PDFs)
npm run generate:pdf:install  # First time only
npm run serve                 # Terminal 1
node scripts/generate-pdf-parallel.js  # Terminal 2

📖 About the Project

This modern, interactive textbook is built with:

• Eleventy (11ty) v4: A fast, Node-based static site generator.
• markdown-it: The Markdown renderer (with custom math/typography plugins).
• MathJax v4: For advanced mathematical and scientific notation.
• Vercel & GitHub Pages: For seamless publishing and distribution.

The entire book is stored directly in GitHub and automatically regenerated whenever changes are made, making contributions easy!

🚀 Local Development

Want to contribute or run a local copy? It's easy!

Getting Started

Prerequisites

• Node.js 22.15 or higher (runs Eleventy v4 and all tooling)
• Python 3.x (optional, for physics calculation verification)
• Git for version control

Setup & Execution

# 1. Clone or fork the repository
git clone https://github.com/veillette/physics-book2.git
cd physics-book2

# 2. Install Node.js dependencies
npm install

# 3. Start the local dev server (or build for production)
npm run serve
# npm run build

# 4. View your local copy at http://localhost:4000/physics-book2/

Useful Development Commands

The project includes a suite of Node.js scripts for quality assurance and content management. All scripts use a shared utilities library (scripts/lib/) for consistent output formatting and CLI handling. See the scripts README for full details.

# Build the site
npm run build

# Run a full audit (links, orphans, figures, YAML, accessibility, content)
npm run audit

# Run ALL checks including math delimiter validation
npm run check:all

# Verify physics calculations (requires Python 3)
npm run check:physics

# Individual quality checks
npm run check:links           # Internal & external links
npm run check:orphans         # Unreferenced files
npm run check:figures         # Figure references
npm run check:yaml            # YAML front matter
npm run check:accessibility   # Alt text, headings
npm run check:math            # LaTeX delimiter balance
npm run check:content         # Content quality validation
npm run check:equations       # Equation validation

# Content fixes
npm run fix:content           # Fix content issues
npm run fix:equations         # Fix equation issues

# Generate assets
npm run generate:icons        # Generate PWA icons
npm run generate:pdf          # Generate PDF chapters (requires the dev server)
npm run generate:search-index # Build search index

# Code quality
npm run lint                  # ESLint check
npm run format                # Prettier formatting
npm run test:unit             # Run unit tests

Deployment

This project is automatically deployed to two platforms:

• Vercel: The primary, production-ready version of the book. Deploys from the main branch.
• GitHub Pages: A secondary version for redundancy and testing. Deploys from the main branch.

Configuration for each platform (vercel.json for Vercel, eleventy.config.js for the build) manages the specific build settings required.

👥 Contributing

We welcome contributions from the physics education community! Your help makes this resource better for everyone.

How to Contribute

1. Fork the repository to your own GitHub account.
2. Create a feature branch for your changes (git checkout -b feature/your-improvement).
3. Make your changes, following the existing style and formatting.
4. Test your changes locally by running npm run serve and using the quality assurance scripts (e.g., npm run audit).
5. Commit your changes with a clear and descriptive message.
6. Push your branch to your fork (git push origin feature/your-improvement).
7. Submit a pull request to the main repository.

Contribution Ideas

• Fix Errors: Correct typos, formatting issues, or scientific inaccuracies.
• Add Examples: Provide real-world examples to clarify concepts.
• Improve Explanations: Make complex topics more accessible.
• Add Solutions: Contribute worked solutions to end-of-chapter problems.
• Enhance Visuals: Create or improve diagrams, illustrations, and figures.
• Report Issues: Found a bug or broken link? Open an issue.

For detailed project conventions, see claude.md.

🎉 Recent Improvements

July 2026 Updates

Eleventy Migration:

• Replaced Jekyll/Kramdown with Eleventy v4 and markdown-it
• Node-only build (npm run build / npm run serve); Ruby/Bundler no longer required
• Nunjucks templates replace Liquid layouts
• Root-relative links replace {{ site.baseurl }} patterns

December 2025 Updates

Performance & Accessibility:

• Removed Font Awesome dependency (~200KB savings)
• Replaced icon fonts with Unicode symbols and CSS2
• Added comprehensive ARIA labels and semantic HTML
• Implemented skip navigation for keyboard users
• Enhanced screen reader support

PDF Generation:

• Implemented parallel PDF generation (4x-8x faster)
• Automated weekly regeneration via GitHub Actions
• 309 PDFs generated in ~60 minutes
• Automatic failure recovery system
• Smart commits (only when PDFs change)

Infrastructure:

• Enhanced GitHub Actions workflows
• Improved service worker caching
• Better offline support
• Automated quality checks (links, accessibility, content)

See claude.md for complete details on recent improvements.

📝 License

This project is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

You are free to:

• Share and adapt the material for non-commercial educational purposes.
• Customize the content for your courses.

Under the following terms:

• Attribution is required.
• Non-commercial use only.
• Share derivatives under the same license.

See the full license text for details.