Build beginner-first Jekyll course website

Author: iBalajiShanmugam

.github/workflows/pages.yml

@@ -1,4 +1,4 @@
-name: Deploy course website
+name: Deploy Jekyll course website
 
 on:
   push:
@@ -15,20 +15,37 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - name: Configure Pages
+        id: pages
+        uses: actions/configure-pages@v6
+
+      - name: Build website
+        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
+        env:
+          JEKYLL_ENV: production
+
+      - name: Upload website
+        uses: actions/upload-pages-artifact@v4
+
   deploy:
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-      - name: Configure Pages
-        uses: actions/configure-pages@v5
-      - name: Upload website
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: .
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

00-setup/README.md

@@ -1,93 +1,248 @@
-# Setup: Run Python on Your Computer
+---
+layout: default
+title: Setup
+nav_order: 4
+has_children: true
+permalink: /setup/
+course_lesson: true
+course_index: "00"
+next_page: /lessons/fundamentals/
+next_title: Python Fundamentals
+---
+
+# Setup: Run Your First Python Program
+
+This page helps you install Python, create one file, and see your first successful output. Complete the quick start before learning about virtual environments.
+
+## Before installing anything
+
+If you use a school or office computer, ask a parent, teacher, or administrator before installing software. Do not remove a Python installation that already belongs to the operating system.
+
+You need:
+
+- a computer running Windows, macOS, or Linux;
+- permission to install software;
+- a text editor;
+- a terminal, which is a window where you type commands.
+
+Choose only the section for your operating system.
+
+## Windows quick start
+
+### Step 1 — install Python
+
+Use the official [Python Install Manager instructions](https://docs.python.org/3/using/windows.html). It can be installed from Python.org or the Microsoft Store.
+
+After installation, open **PowerShell** from the Start menu and type:
+
+```powershell
+python --version
+```
 
-## Goal
+If your installation uses the `py` command, this also works:
 
-By the end of this section you can install Python, open a terminal, run Python code, create a project folder, and use an isolated virtual environment.
+```powershell
+py --version
+```
 
-## Which Python should I install?
+You should see a Python 3 version. The exact numbers may be newer than examples in this course.
 
-Use a current stable Python 3 release from [python.org/downloads](https://www.python.org/downloads/). Do not install a pre-release for this course.
+### Step 2 — create a learning folder
 
-## macOS
+```powershell
+mkdir python-learning
+cd python-learning
+```
+
+- `mkdir` creates a folder.
+- `cd` moves the terminal into that folder.
+
+### Step 3 — create and run `hello.py`
+
+Open the `python-learning` folder in your editor. Create a file named `hello.py` and type:
 
-1. Download the macOS installer from [Python Releases for macOS](https://www.python.org/downloads/macos/).
-2. Run the installer and complete the prompts.
-3. Open Terminal and verify:
+```python
+print("Hello, Python!")
+```
+
+Save the file. Return to PowerShell and run:
+
+```powershell
+python hello.py
+```
+
+If `python` does not work but `py` does, run:
+
+```powershell
+py hello.py
+```
+
+Expected output:
+
+```text
+Hello, Python!
+```
+
+## macOS quick start
+
+### Step 1 — install Python
+
+Download the current supported Python 3 installer from [Python Releases for macOS](https://www.python.org/downloads/macos/). Use the normal `.pkg` installer and complete its instructions.
+
+Open **Terminal** and type:
 
 ```bash
 python3 --version
 ```
 
-4. Create a workspace:
+You should see a Python 3 version. Do not delete or modify Python supplied by macOS or Apple development tools.
+
+### Step 2 — create a learning folder
 
 ```bash
 mkdir python-learning
 cd python-learning
-python3 -m venv .venv
-source .venv/bin/activate
-python --version
 ```
 
-## Linux
+### Step 3 — create and run `hello.py`
+
+Open the `python-learning` folder in your editor. Create `hello.py`:
+
+```python
+print("Hello, Python!")
+```
 
-Python is already available on many distributions. Use your distribution's package manager and prefer Python 3. On Debian or Ubuntu:
+Save it and run:
+
+```bash
+python3 hello.py
+```
+
+Expected output:
+
+```text
+Hello, Python!
+```
+
+## Linux quick start
+
+Python 3 is already available on many Linux distributions. First try:
+
+```bash
+python3 --version
+```
+
+If Python is unavailable on Debian or Ubuntu, use:
 
 ```bash
 sudo apt update
 sudo apt install python3 python3-venv python3-pip
-python3 --version
+```
+
+For Fedora, Arch, or another distribution, use its package manager and the [official Python Unix guide](https://docs.python.org/3/using/unix.html).
+
+Create the learning folder:
+
+```bash
 mkdir python-learning
 cd python-learning
+```
+
+Create `hello.py` in your editor:
+
+```python
+print("Hello, Python!")
+```
+
+Save it and run:
+
+```bash
+python3 hello.py
+```
+
+## What just happened?
+
+```text
+hello.py -> Python reads the file -> print() displays text -> terminal shows output
+```
+
+- `hello.py` is a Python source file.
+- `.py` is the usual filename ending for Python code.
+- `python`, `py`, or `python3` starts the Python interpreter.
+- An **interpreter** is the program that reads and runs Python instructions.
+
+If you saw `Hello, Python!`, pause and enjoy that small win. Your computer has successfully run your code.
+
+## Recommended next step: a virtual environment
+
+A virtual environment is a private project box for Python tools and installed packages. One project's packages will not interfere with another project's packages.
+
+```text
+computer Python
+├── project A .venv -> project A packages
+└── project B .venv -> project B packages
+```
+
+The Basic examples use the standard library and can run without extra packages. Creating `.venv` now is still a useful habit.
+
+### macOS and Linux
+
+From inside `python-learning`:
+
+```bash
 python3 -m venv .venv
 source .venv/bin/activate
 python --version
 ```
 
-For Fedora, Arch, and other distributions, follow the distribution-specific instructions in the [official Unix guide](https://docs.python.org/3/using/unix.html).
+### Windows PowerShell
 
-## Windows
-
-1. Install Python using the official [Windows installation guide](https://docs.python.org/3/using/windows.html) or the Python Install Manager from [python.org/downloads](https://www.python.org/downloads/).
-2. Open PowerShell and verify:
+From inside `python-learning`:
 
 ```powershell
-py --version
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+python --version
 ```
 
-3. Create a workspace and virtual environment:
+If you normally use `py`, create it with:
 
 ```powershell
-mkdir python-learning
-cd python-learning
 py -m venv .venv
-.venv\Scripts\Activate.ps1
-python --version
 ```
 
-If PowerShell blocks activation, use the Python interpreter directly with `.venv\Scripts\python.exe`, or ask an administrator to review the execution-policy setting. Do not randomly change system security settings.
-
-## First program
+When activation succeeds, the terminal prompt normally begins with `(.venv)`. Activation makes the plain `python` command select the environment's interpreter.
 
-Create a file named `hello.py`:
+To leave the environment later:
 
-```python
-print("Hello, Python!")
+```text
+deactivate
 ```
 
-Run it from the activated environment:
+If PowerShell blocks activation, do not randomly weaken computer security. You may run the environment directly:
 
-```bash
-python hello.py
+```powershell
+.venv\Scripts\python.exe hello.py
 ```
 
+## Choose an editor
+
+Read [Editor Setup](editor-setup.md). Any editor that saves plain `.py` files is acceptable. IDLE, which is included with many Python installations, is enough for this course.
+
+## Learn six terminal commands
+
+Read [Terminal Basics](terminal-basics.md). You only need a few commands to move between folders and run files.
+
 ## Setup checkpoint
 
-- [ ] Python 3 is installed.
-- [ ] The version command works.
-- [ ] A virtual environment was created.
-- [ ] The environment was activated.
-- [ ] `hello.py` runs successfully.
-- [ ] You know how to deactivate it with `deactivate`.
+- [ ] A Python 3 version command works.
+- [ ] The `python-learning` folder exists.
+- [ ] `hello.py` contains the one-line program.
+- [ ] Running the file displays `Hello, Python!`.
+- [ ] I know which command works on my computer: `python`, `py`, or `python3`.
+- [ ] I either created `.venv` or understand that I can return to that optional step.
+
+If a checkpoint fails, open [Setup Troubleshooting](troubleshooting.md).
 
 ---
 

00-setup/editor-setup.md

@@ -1,11 +1,37 @@
+---
+layout: default
+title: Editor Setup
+parent: Setup
+nav_order: 1
+permalink: /setup/editor/
+---
+
 # Editor Setup
 
 Use any editor that supports Python syntax. Visual Studio Code is a convenient option, but the course does not depend on a particular editor.
 
+## Easiest choice: IDLE
+
+IDLE is included with many official Python installations. Open IDLE, choose **File → New File**, type your program, save it with a `.py` ending, and choose **Run → Run Module**.
+
+## Visual Studio Code choice
+
+1. Install Visual Studio Code from its official website.
+2. Open the complete `python-learning` folder.
+3. Install Microsoft's official Python extension when prompted.
+4. Select the Python interpreter from `.venv` if you created one.
+5. Open the integrated terminal and run the file with the command from Setup.
+
+An **editor** is where you write and save code. A **terminal** is where you type commands that run the saved code. They may appear in one application, but they have different jobs.
+
 Recommended habits:
 
 - Open the repository folder, not just one file.
 - Install the editor's official Python extension if available.
 - Select the `.venv` interpreter.
 - Keep one experiment per file while learning.
 - Run programs from the terminal so the command is familiar.
+
+---
+
+[Back to Setup](README.md) · [Terminal Basics](terminal-basics.md) · [Troubleshooting](troubleshooting.md)