🐍 The Python Ledger Engine

The technical core of The Python Ledger, an interactive, browser-based learning platform. This project combines the static site power of Docusaurus with the client-side Python execution of Skulpt.

🚀 The Tech Stack

• Framework: Docusaurus v3 (React-based SSG)
• Engine: Skulpt (In-browser Python 3 execution)
• Editor: @uiw/react-codemirror (Python syntax highlighting)
• Deployment: CI/CD via GitHub Actions

🌍 Visit the site

Visit the site hosted by GitHub Pages

⚙️ How the Engine Works

Unlike standard documentation, this project uses a custom React component, InteractivePython, to turn static code blocks into live environments.

The Suspension Logic

To support interactive input() calls without freezing the browser's UI thread or hitting TimeLimitErrors, the engine uses a Promise-based Suspension architecture:

1. When Python hits input(), Skulpt triggers a custom inputfun.
2. The engine returns a Promise and captures the resolve function in a React useRef.
3. Skulpt "suspends" execution while the promise is pending.
4. Once the user submits the HTML form, the promise resolves, and the Python state resumes exactly where it left off.

🛠️ Getting Started

Prerequisites

• Node.js (v18 or higher)
• npm or yarn

Installation

1. Clone the repository:

   git clone https://github.com/ThePythonLedger/Curriculum.git
   git clone https://github.com/ThePythonLedger/Docusaurus-engine.git
   cd Docusaurus-engine

2. Install dependencies:

   npm install

3. Start the development server:

   npm start

   The site will be available at http://localhost:3000.

📂 Project Structure

• /src/components/InteractivePython/: The React logic for the Skulpt engine and terminal UI.

🤝 Contributing

We are looking for contributors to help with both Engine Polish and Lesson Content.

• Engine: Improving the terminal UI or optimizing Skulpt's output handling.
• Content: Drafting new lessons in Markdown and improving existing lessons (tracked separately)

See CONTRIBUTING.md for our full guidelines and the Discord community for real-time discussion.

📄 License

This project is licensed under the MIT License.

Community

You can join our community on Discord