📚 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 34 chapters and 241 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 service worker (sw.js) caches core assets and visited pages for offline access.
• 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

On GitHub Pages, chapter and section pages have a PDF download button in the upper right corner. Chapter pages link to the complete chapter; section pages link to individual sections.

The complete-book PDF is generated by the quarterly/manual PDF workflow and published to the pdfs GitHub Release. The Preface and Summary buttons point to a local complete-book.pdf, which the Pages deployment does not currently generate. Vercel builds do not generate PDFs; use GitHub Pages for chapter downloads and the release for the complete book.

Automated PDF Generation

PDFs are not stored in git. Each GitHub Pages deployment generates chapter and section PDFs using Playwright parallel processing:

• 309 PDFs with beautifully rendered mathematical equations
• All figures and diagrams included
• Clean, print-optimized formatting
• A recovery step retries a fixed list of historically troublesome combined chapters

A quarterly workflow (January, April, July, and October 1 at 00:00 UTC) also publishes individual PDFs, including the complete book, to the pdfs GitHub Release. It can be triggered manually from GitHub Actions.

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: Includes the preface, all chapters, and both appendices; published separately through the quarterly/manual release workflow

Manual Generation

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

# Generate chapter and section PDFs (complete book is a separate command)
npm run generate:pdf:install  # First time only
npm run serve                 # Terminal 1
node scripts/generate-pdf-parallel.js  # Terminal 2
npm run generate:pdf:book           # Optional: complete textbook

📖 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.10 or higher (optional, for physics calculation verification)
• Git for version control

Setup & Execution

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

# 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-book/

Useful Development Commands

The project includes a suite of Node.js scripts for quality assurance and content management. Many 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

# Audit links, assets, figures, YAML, accessibility, math, content, and references
npm run audit

# Add physics verification and JavaScript/Python unit tests
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 # Manually rebuild search index (automatic during build/serve)

# 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 AGENTS.md.

For the build architecture, see roadmap.md. Historical changes, including the Eleventy migration, are recorded in CHANGELOG.md.

📝 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.