Development

docs/classes.md

@@ -6,6 +6,8 @@ description: >-
 
 # :material-package-variant:{ .lg .middle } Classes
 
+<div class="pfg-section" markdown="block">
+
 A **class** bundles related data together with the behavior (methods) that acts on it, instead of keeping them separate. A [dictionary](collections.md#dictionaries) can already hold a snake's data as key-value pairs — a class goes one step further, pairing that data with the functions that work on it. Structuring code this way is called **object-oriented programming (OOP)**.
 
 | Concept | Example | What it is |
@@ -16,6 +18,8 @@ A **class** bundles related data together with the behavior (methods) that acts
 | Method | `def describe(self):` | A function that belongs to a class and acts on a specific object |
 | Inheritance | `class Boa(Snake):` | A new class that reuses — and can extend or override — another class's attributes and methods |
 
+</div>
+
 <div class="pfg-section" markdown="block">
 
 ## Defining a class

docs/collections.md

@@ -6,6 +6,8 @@ description: >-
 
 # :material-basket-outline:{ .lg .middle } Collection Data Types
 
+<div class="pfg-section" markdown="block">
+
 A **collection** is a single object that groups multiple values (like [basic types](types.md)) together and so they can be stored in one variable together and worked with as a unit. 
 
 <div class="pt-jump-table" markdown="block">
@@ -33,7 +35,9 @@ A **collection** is a single object that groups multiple values (like [basic typ
     isinstance(weights, list)  # True
     isinstance(weights, dict)  # False
     ```
-
+
+</div>
+
 <div class="pfg-section" markdown="block">
 
 ## Lists

docs/conditionals.md

@@ -6,6 +6,8 @@ description: >-
 
 # :material-source-branch:{ .lg .middle } Conditionals
 
+<div class="pfg-section" markdown="block">
+
 A **conditional** lets a program make decisions by running a **block** of code only when a [condition](#boolean-expressions) is `True`. 
 
 The condition ends with a colon `:`, and the block is the lines indented underneath it, treated as a single unit. 
@@ -21,6 +23,8 @@ The condition ends with a colon `:`, and the block is the lines indented underne
 
 </div>
 
+</div>
+
 <div class="pfg-section" markdown="block">
 
 ## If / elif / else

docs/errors.md

@@ -6,6 +6,8 @@ description: >-
 
 # :material-bug-outline:{ .lg .middle } Errors
 
+<div class="pfg-section" markdown="block">
+
 **"Errors"** occur when a line of code is impossible to run, so the program stops and displays a message with information on what went wrong and where. 
 
 **"Bugs"** are the general term for errors or *any mistake* in your code, like logic errors. 
@@ -26,6 +28,8 @@ They are part of programming, and happen constantly. Based on the kind of error,
 
 ## Kinds of errors:
 
+</div>
+
 <div class="pfg-section" markdown="block">
 
 ### Syntax errors { .pt-fake-h2 }

docs/files.md

@@ -6,6 +6,8 @@ description: >-
 
 # :material-file-document-outline:{ .lg .middle } File Read/Write
 
+<div class="pfg-section" markdown="block">
+
 Instead of only printing output to the terminal, you can have the program save data to a file on your computer so data stays after the program ends, or read data from a file.
 
 For how to pull code **from another `.py` file** into your program, that's in [Modules & Imports](modules.md#importing-modules).
@@ -25,6 +27,8 @@ flowchart LR
 
 </div>
 
+</div>
+
 <div class="pfg-section" markdown="block">
 
 ## Opening and closing files

docs/functions.md

@@ -6,6 +6,8 @@ description: >-
 
 # :material-function-variant:{ .lg .middle } Functions
 
+<div class="pfg-section" markdown="block">
+
 A **function** packages a block of code under a name, so it can be run again — with different inputs — instead of copying and pasting the same lines every time you need them. 
 
 Python already has some built in (`print()`, `len()`, `input()`), but `def` lets you write your own.
@@ -95,6 +97,8 @@ message = describe("ball")        # "a ball python" is the return value, so now
     print(is_unusually_long("ball python", 6))
     ```
 
+</div>
+
 <div class="pfg-section" markdown="block">
 
 ## Defining a function

docs/javascripts/essentials_toggle.js

@@ -63,11 +63,19 @@
     });
   }
 
-  // Disappearing confirmation toast for the Essentials/Advanced toggle —
-  // the toggle itself only shows the current state, not what just changed,
-  // so a click gives no feedback about its actual effect otherwise.
+  // Disappearing confirmation toast, shared by the Essentials/Advanced
+  // toggle and the light/dark toggle — neither toggle's own button shows
+  // what just changed, only the current state, so a click otherwise gives
+  // no feedback about its actual effect.
+  //
+  // `iconAttrs` is the dataset to put on the icon span, e.g. {mode:
+  // "simplified"} or {scheme: "slate"} — matched in extra.css by
+  // .pt-mode-icon[data-mode] / [data-scheme] to the same icons the
+  // triggering toggle itself uses. `body` is optional; pass "" to show a
+  // one-line toast (the light/dark toggle's own message is self-
+  // explanatory, unlike the Essentials/Advanced one).
   let toastTimer = null;
-  function showToast(active) {
+  function showToast(label, iconAttrs, body) {
     let toast = document.getElementById("pt-toast");
     if (!toast) {
       toast = document.createElement("div");
@@ -87,17 +95,19 @@
     title.className = "pt-toast__title";
     const icon = document.createElement("span");
     icon.className = "pt-mode-icon";
-    icon.dataset.mode = active ? "simplified" : "advanced";
+    Object.keys(iconAttrs).forEach(function (key) {
+      icon.dataset[key] = iconAttrs[key];
+    });
     icon.setAttribute("aria-hidden", "true");
-    title.append(active ? "Essentials " : "Advanced ", icon);
-
-    const body = document.createElement("div");
-    body.className = "pt-toast__body";
-    body.textContent = active
-      ? "Just the basics, start here!"
-      : "Viewing all content.";
-
-    toast.append(title, body);
+    title.append(label + " ", icon);
+    toast.append(title);
+
+    if (body) {
+      const bodyEl = document.createElement("div");
+      bodyEl.className = "pt-toast__body";
+      bodyEl.textContent = body;
+      toast.append(bodyEl);
+    }
 
     // The header's own height isn't fixed across breakpoints (taller with
     // the tab bar on tablet/desktop) or over time (Material can hide/reveal
@@ -108,8 +118,9 @@
     toast.style.top = Math.max(headerBottom, 0) + 12 + "px";
 
     // Retrigger the transition even if a toast is already showing (rapid
-    // clicks between the two options): drop the class, force layout, then
-    // re-add it, instead of just extending the existing timer.
+    // clicks between the two options, or switching from one toggle to the
+    // other): drop the class, force layout, then re-add it, instead of
+    // just extending the existing timer.
     toast.classList.remove("pt-toast--visible");
     void toast.offsetWidth;
     toast.classList.add("pt-toast--visible");
@@ -180,7 +191,11 @@
       if (next === wasActive) return;
       localStorage.setItem(STORAGE_KEY, String(next));
       applyState(container, next);
-      showToast(next);
+      showToast(
+        next ? "Essentials" : "Advanced",
+        { mode: next ? "simplified" : "advanced" },
+        next ? "Just the basics, start here!" : "Viewing all content."
+      );
     });
 
     return container;
@@ -233,12 +248,13 @@
     container.addEventListener("click", function (event) {
       const option = event.target.closest(".pt-theme-option");
       if (!option) return;
-      const radio = option.dataset.scheme === "slate" ? darkRadio : lightRadio;
-      if (!radio.checked) {
-        radio.checked = true;
-        radio.dispatchEvent(new Event("change", { bubbles: true }));
-      }
+      const scheme = option.dataset.scheme;
+      const radio = scheme === "slate" ? darkRadio : lightRadio;
+      if (radio.checked) return;
+      radio.checked = true;
+      radio.dispatchEvent(new Event("change", { bubbles: true }));
       applyThemeState(container);
+      showToast(scheme === "slate" ? "Lights off" : "Lights on", { scheme: scheme }, "");
     });
 
     // Sync to whatever scheme Material's own JS actually lands on, not

docs/libraries/beautifulsoup.md

@@ -6,12 +6,16 @@ description: >-
 
 # :material-pot-steam-outline:{ .lg .middle } BeautifulSoup library
 
+<div class="pfg-section" markdown="block">
+
 [BeautifulSoup documentation :material-open-in-new:](https://www.crummy.com/software/BeautifulSoup/bs4/doc/){ .md-button target="_blank" }
 
 BeautifulSoup is an open-source project maintained by volunteer contributors.
 
 **BeautifulSoup** (imported from `bs4`) is a popular library for parsing HTML — turning a page's raw markup into something you can search by tag, class, or attribute instead of scanning raw text by hand. It's a third-party package, not part of the standard library, but it's the de facto standard for this in Python.
 
+</div>
+
 <div class="pfg-section" markdown="block">
 
 ## Setup { data-card-link="skip" }

docs/libraries/collections.md

@@ -6,6 +6,8 @@ description: >-
 
 # :material-format-list-group:{ .lg .middle } collections library
 
+<div class="pfg-section" markdown="block">
+
 [collections documentation :material-open-in-new:](https://docs.python.org/3/library/collections.html){ .md-button target="_blank" }
 
 !!! note "Not the same as the Collections page"
@@ -32,6 +34,8 @@ built-in [`str`](../types.md#strings) [`list`](../collections.md#lists) [`dict`]
 
 </div>
 
+</div>
+
 <div class="pfg-section" markdown="block">
 
 ## Setup { data-card-link="skip" }

docs/libraries/csv.md

@@ -6,10 +6,14 @@ description: >-
 
 # :material-file-delimited-outline:{ .lg .middle } csv library
 
+<div class="pfg-section" markdown="block">
+
 [csv documentation :material-open-in-new:](https://docs.python.org/3/library/csv.html){ .md-button target="_blank" }
 
 The **`csv`** module reads and writes CSV ("comma-separated values") files — a plain-text table format that spreadsheets and databases can both open. Every example below actually runs in your browser: Pyodide gives each page its own in-memory filesystem, so `open()` works exactly like it would on a real computer, just without anything being saved outside this page.
 
+</div>
+
 <div class="pfg-section" markdown="block">
 
 ## Setup { data-card-link="skip" }

docs/libraries/datetime.md

@@ -6,6 +6,8 @@ description: >-
 
 # :material-calendar-clock:{ .lg .middle } datetime library
 
+<div class="pfg-section" markdown="block">
+
 [datetime documentation :material-open-in-new:](https://docs.python.org/3/library/datetime.html){ .md-button target="_blank" }
 
 The **`datetime`** module is Python's standard library for working with dates and times — logging when an observation happened, measuring how long ago it was, or formatting a date for display.
@@ -17,6 +19,8 @@ The **`datetime`** module is Python's standard library for working with dates an
 | Timezone support | Full — handles timezone-aware dates and conversions. | Limited — relies on the system's local time. |
 | Common uses | <ul><li>Logging when something happened</li><li>Calculating an age or a deadline</li><li>Date arithmetic</li></ul> | <ul><li>Benchmarking how long code takes to run</li><li>Pausing a program with `sleep()`</li></ul> |
 
+</div>
+
 <div class="pfg-section" markdown="block">
 
 ## Setup { data-card-link="skip" }

docs/libraries/json.md

@@ -6,10 +6,14 @@ description: >-
 
 # :material-code-json:{ .lg .middle } json library
 
+<div class="pfg-section" markdown="block">
+
 [json documentation :material-open-in-new:](https://docs.python.org/3/library/json.html){ .md-button target="_blank" }
 
 The **`json`** module reads and writes JSON ("JavaScript Object Notation") data — a plain-text format for structured data, whose objects and arrays map naturally to Python dicts and lists, which makes it the standard way structured data moves between programs, files, and web APIs. Every example below actually runs in your browser: Pyodide gives each page its own in-memory filesystem, so `open()` works exactly like it would on a real computer, just without anything being saved outside this page.
 
+</div>
+
 <div class="pfg-section" markdown="block">
 
 ## Setup { data-card-link="skip" }

docs/libraries/math.md

@@ -6,10 +6,14 @@ description: >-
 
 # :material-square-root-box:{ .lg .middle } math library
 
+<div class="pfg-section" markdown="block">
+
 [math documentation :material-open-in-new:](https://docs.python.org/3/library/math.html){ .md-button target="_blank" }
 
 The **`math`** module extends Python's built-in arithmetic with functions it doesn't provide directly — square roots, rounding modes, constants like pi, and logarithms.
 
+</div>
+
 <div class="pfg-section" markdown="block">
 
 ## Setup { data-card-link="skip" }

docs/libraries/matplotlib.md

@@ -6,12 +6,16 @@ description: >-
 
 # :material-chart-line:{ .lg .middle } matplotlib library
 
+<div class="pfg-section" markdown="block">
+
 [matplotlib documentation :material-open-in-new:](https://matplotlib.org/stable/){ .md-button target="_blank" }
 
 matplotlib is an open-source project, funded by nonprofit [NumFOCUS](https://numfocus.org/).
 
 **matplotlib** (its plotting interface imported as `plt`) is Python's foundational library for creating charts — line plots, bar charts, scatter plots — directly from plain Python data. It's a third-party package, not part of the standard library, but it's a foundational Python plotting library that many other Python tools integrate with or build upon. Like [Pillow](pillow.md) and [OpenCV](opencv.md), matplotlib produces visual output — a chart shown in a window or saved to a file — which can't be shown inside this site's browser sandbox, so the examples below aren't runnable here. Copy them into a local `.py` file and run them with `python` to see the results.
 
+</div>
+
 <div class="pfg-section" markdown="block">
 
 ## Setup { data-card-link="skip" }

docs/libraries/numpy.md

@@ -6,12 +6,16 @@ description: >-
 
 # :material-matrix:{ .lg .middle } NumPy library
 
+<div class="pfg-section" markdown="block">
+
 [NumPy documentation :material-open-in-new:](https://numpy.org/doc/stable/){ .md-button target="_blank" }
 
 NumPy is an open-source project, with fiscal sponsorship from the nonprofit [NumFOCUS](https://numfocus.org/).
 
 **NumPy** (imported as `np`) is a widely used library for fast numeric arrays — the foundation nearly every other data or scientific library in Python is built on. It's a third-party package, not part of the standard library. A NumPy `ndarray` looks similar to a `list`, but every element is the same type and math operations apply to the whole array at once, instead of one item at a time.
 
+</div>
+
 <div class="pfg-section" markdown="block">
 
 ## Setup { data-card-link="skip" }

docs/libraries/opencv.md

@@ -6,12 +6,16 @@ description: >-
 
 # :material-face-recognition:{ .lg .middle } OpenCV library
 
+<div class="pfg-section" markdown="block">
+
 [OpenCV documentation :material-open-in-new:](https://docs.opencv.org/4.x/d6/d00/tutorial_py_root.html){ .md-button target="_blank" }
 
 OpenCV is stewarded by nonprofit [OpenCV.org](https://opencv.org/).
 
 **OpenCV** (imported as `cv2`) is a popular library for computer vision — real-time image and video analysis, rather than the straightforward photo editing [Pillow](pillow.md) is built for. It's a third-party package, originally written in C++ with a thin Python wrapper over it, which shows up in a couple of its API choices: images load as plain NumPy arrays instead of a dedicated `Image` class, and in **BGR** (blue-green-red) channel order rather than the RGB most other tools expect. Like Pillow and [Tkinter](tkinter.md), OpenCV produces visual, often interactive output — a window showing an image or a live camera feed — that can't run inside this site's browser sandbox, so the examples below aren't runnable here. Copy them into a local `.py` file alongside an image and run them with `python` to see the results.
 
+</div>
+
 <div class="pfg-section" markdown="block">
 
 ## Setup { data-card-link="skip" }

docs/libraries/pandas.md

@@ -6,12 +6,16 @@ description: >-
 
 # :material-table:{ .lg .middle } pandas library
 
+<div class="pfg-section" markdown="block">
+
 [pandas documentation :material-open-in-new:](https://pandas.pydata.org/docs/){ .md-button target="_blank" }
 
 pandas is an open-source project, funded by nonprofit [NumFOCUS](https://numfocus.org/).
 
 **pandas** (imported as `pd`) is a widely used library for tabular data — rows and columns, like a spreadsheet, with tools for filtering, sorting, and summarizing built in. It's a third-party package, not part of the standard library, and is built on top of [NumPy](numpy.md).
 
+</div>
+
 <div class="pfg-section" markdown="block">
 
 ## Setup { data-card-link="skip" }

docs/libraries/pillow.md

@@ -6,12 +6,16 @@ description: >-
 
 # :material-image-outline:{ .lg .middle } Pillow library
 
+<div class="pfg-section" markdown="block">
+
 [Pillow documentation :material-open-in-new:](https://pillow.readthedocs.io/en/stable/){ .md-button target="_blank" }
 
 Pillow is an open-source project maintained by volunteer contributors.
 
 **Pillow** (imported as `PIL`) is a popular library for opening, editing, and saving image files — photos, screenshots, thumbnails, anything in a common format like JPEG or PNG. It's a third-party package, not part of the standard library, but it's the de facto standard for image work in Python. Like [Tkinter](tkinter.md), Pillow ultimately produces visual output — a saved or displayed image — which can't be shown inside this site's browser sandbox, so the examples below aren't runnable here. Copy them into a local `.py` file alongside an image and run them with `python` to see the results.
 
+</div>
+
 <div class="pfg-section" markdown="block">
 
 ## Setup { data-card-link="skip" }