Minor checks, corrections, clean-ups and dead-link fixes.

ntoll · ntoll · commit b963591c83f4 · 2026-01-15T18:48:49.000Z
diff --git a/docs/example-apps/overview.md b/docs/example-apps/overview.md
@@ -12,7 +12,8 @@ for understanding how PyScript works.
 ## Running the examples
 
 Each example is self-contained with its own `index.html` file. To run
-an application locally (we'll use the "Pirate Translator" as an example):
+an application locally with Python (we'll use the "Pirate Translator" as
+an example):
 
 ```sh
 # Navigate to the example directory.
@@ -24,6 +25,22 @@ python -m http.server 8000
 # Visit http://localhost:8000 in your browser.
 ```
 
+**Sometimes an example uses web-workers, and these need the server to
+respond with special headers.** The 
+[`mini-coi` command](https://github.com/WebReflection/mini-coi) (which
+uses [node.js](https://nodejs.org/en) under the hood) does the right
+thing for you:
+
+```sh
+# Navigate to the worker-related project.
+cd example_apps/prime-worker
+
+# Serve the app with the correct headers.
+npx mini-coi .
+
+# Visit http://localhost:8080/ in your browser.
+```
+
 All examples use the latest PyScript release referenced in this
 version of the docs. Check each example's `index.html` for the reference
 to the specific version of PyScript in use.
diff --git a/docs/example-apps/task-board-ffi/info.md b/docs/example-apps/task-board-ffi/info.md
@@ -22,7 +22,7 @@ JavaScript API calls.
 ## Features
 
 This is the exact same application as the
-[pyscript.web version](../task-board-web/index.html), but implemented using
+[pyscript.web version](../task-board-web/info.md), but implemented using
 JavaScript APIs directly. Key differences:
 
 ## Files
diff --git a/docs/example-apps/task-board-web/info.md b/docs/example-apps/task-board-web/info.md
@@ -40,5 +40,5 @@ All DOM manipulation uses `pyscript.web`'s Pythonic interface:
 
 ## Compare with FFI version
 
-See the [FFI version](../task-board-ffi/index.html) of this same application to
+See the [FFI version](../task-board-ffi/info.md) of this same application to
 compare the Pythonic approach with direct JavaScript API calls.
diff --git a/docs/faq.md b/docs/faq.md
@@ -340,8 +340,8 @@ This error message indicates a serious problem:
 #### When
 
 This error occurs when code on a worker and the main thread are in
-[deadlock](https://en.wikipedia.org/wiki/Deadlock). Neither fragment can
-proceed without waiting for the other.
+[deadlock](https://en.wikipedia.org/wiki/Deadlock_(computer_science)).
+Neither fragment can proceed without waiting for the other.
 
 #### Why
 
@@ -452,8 +452,8 @@ When reporting bugs or asking questions, always mention which PyScript
 version you're using. Different versions may behave differently, and
 version information helps diagnose problems.
 
-Check the [releases page](https://pyscript.net/releases/) to see
-available versions and their release notes.
+Check the [releases page](https://github.com/pyscript/pyscript/releases)
+to see available versions and their release notes.
 
 ### Workers via JavaScript
 
diff --git a/docs/index.md b/docs/index.md
@@ -1,5 +1,5 @@
 
-<div><img alt="PyScript Logo" src="assets/images/pyscript.svg"></div>
+<img alt="PyScript Logo" src="assets/images/pyscript.svg">
 
 <h1 style="text-align: center; font-weight: bold;">PyScript is an <u>open source</u> platform for Python in the browser.</h1>
 
@@ -10,13 +10,13 @@
 <script type="module" src="https://pyscript.net/releases/2025.11.2/core.js"></script>
 ```
 
-**Step 2:** Start PyScript with a `<script>` tag:
+**Step 2:** Start PyScript with a `<script>` tag in the `<body>` of your HTML document:
 
 ```html
 <script type="py" config="./conf.json" src="./main.py"></script>
 ```
 
-**Step 3:** Write Python (use the `pyscript` namespace):
+**Step 3:** Write Python and explore the `pyscript` namespace:
 
 ```python
 from pyscript import when, display
diff --git a/docs/user-guide/architecture.md b/docs/user-guide/architecture.md
@@ -154,12 +154,12 @@ minimise network transfer. It works especially well for user interface
 code, simple scripting, or applications on mobile devices. The trade-off
 is no package installation - you only get the standard library subset
 MicroPython provides, or code you directly copy into the PyScript
-environment via `files` based configuration.
+environment via [`files` based configuration](./configuration.md#files).
 
 ### Cross-interpreter compatibility
 
 Both interpreters implement almost the same Foreign Function Interface for
-Python-JavaScript interaction. PyScript's unified `pyscript.ffi`
+Python-JavaScript interaction. PyScript's unified [`pyscript.ffi`](../api/ffi.md)
 namespace works consistently across both interpreters, making it
 relatively straightforward to migrate between them.
 
@@ -170,7 +170,7 @@ in MicroPython. Test thoroughly if you switch interpreters.
 ## Understanding WebAssembly compilation
 
 Both interpreters use [Emscripten](https://emscripten.org/), a compiler
-toolchain built on LLVM, to compile C to WebAssembly. Emscripten
+toolchain built on [LLVM](https://llvm.org/), to compile C to WebAssembly. Emscripten
 provides more than just compilation - it supplies APIs for operating
 system-level features in the browser environment.
 
diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md
@@ -48,12 +48,14 @@ packages = ["arrr", "numberwang" ]
 ## File or inline
 
 The recommended way to write configuration is via a separate file and then
-reference it from the tag used to specify the Python code:
+reference it as a URL from the tag used to specify the Python code:
 
 ```HTML title="Reference a configuration file."
 <script type="py" src="main.py" config="pyscript.json"></script>
 ```
 
+The name of the file doesn't matter, so long as it's either JSON or TOML.
+
 If you use JSON, you can make it the value of the `config` attribute:
 
 ```HTML title="JSON as the value of the config attribute."
diff --git a/docs/user-guide/dom.md b/docs/user-guide/dom.md
@@ -22,13 +22,13 @@ explore each one, starting with the Pythonic `pyscript.web` module.
 
     **New to PyScript?** Start with `pyscript.web`. It's designed to
     feel natural if you know Python, and it handles many common tasks
-    more elegantly than direct JavaScript API calls.
+    more Pythonically than direct JavaScript API calls.
     
     The FFI becomes useful when you need to integrate specific
     JavaScript libraries or when you're already familiar with web
     development in JavaScript.
 
-## Quick start: pyscript.web
+## Quick start: `pyscript.web`
 
 The `pyscript.web` module provides an idiomatic Python interface to the
 DOM. It wraps the FFI in a way that feels natural to Python developers,
diff --git a/docs/user-guide/editor.md b/docs/user-guide/editor.md
@@ -261,5 +261,8 @@ interface for interactive Python sessions.
 differences from traditional PyGame development and techniques for making
 games work well in the browser.
 
+**[PyScript in JavaScript](from_javascript.md)** - drive PyScript from the
+world JavaScript. 
+
 **[Plugins](plugins.md)** - Understand the plugin system, lifecycle hooks,
 and how to write plugins that integrate with PyScript.
diff --git a/docs/user-guide/events.md b/docs/user-guide/events.md
@@ -198,7 +198,7 @@ def handle_inner(event):
 
 ## Custom Pythonic events
 
-The `Event` class lets you create custom events within your Python
+The `pyscript.Event` class lets you create custom events within your Python
 code. This is useful for decoupling parts of your application or
 creating your own event-driven architecture.
 
diff --git a/docs/user-guide/ffi.md b/docs/user-guide/ffi.md
@@ -6,9 +6,9 @@ access browser APIs, and manipulate the DOM directly. JavaScript code
 can call Python functions and access Python objects. This
 interoperability is what makes PyScript possible.
 
-PyScript provides a unified FFI through `pyscript.ffi` that works
-consistently across both Pyodide and MicroPython interpreters. This
-guide explains how to use the FFI to bridge between Python and
+PyScript provides a unified FFI through [`pyscript.ffi`](../api/ffi.md)
+that works consistently across both Pyodide and MicroPython interpreters.
+This guide explains how to use the FFI to bridge between Python and
 JavaScript when necessary.
 
 !!! info
@@ -22,7 +22,8 @@ JavaScript when necessary.
 
 The FFI is a low-level interface for situations where higher-level
 abstractions don't suffice. Most of the time, you should prefer
-`pyscript.web` for DOM manipulation, `pyscript.media` for device
+[`pyscript.web`](../api/web.md) for DOM manipulation,
+[`pyscript.media`](../api/media.md) for device
 access, and other purpose-built APIs. These modules use the FFI
 internally whilst providing cleaner, more Pythonic interfaces.
 
@@ -37,8 +38,8 @@ where `pyscript.web` doesn't apply.
 
 ## Converting Python to JavaScript
 
-The `to_js()` function converts Python objects into their JavaScript
-equivalents:
+The [`to_js()`](../api/ffi.md#pyscript.ffi.to_js) function converts Python
+objects into their JavaScript equivalents:
 
 ```python
 from pyscript.ffi import to_js
@@ -88,9 +89,10 @@ button = document.getElementById("my-button")
 button.addEventListener("click", create_proxy(handle_click))
 ```
 
-Without `create_proxy()`, the Python function would be garbage collected
-immediately, causing the event listener to fail. The proxy maintains a
-reference, keeping the function alive for JavaScript to call.
+Without [`create_proxy()`](../api/ffi.md#pyscript.ffi.create_proxy), the
+Python function would be garbage collected immediately, causing the event
+listener to fail. The proxy maintains a reference, keeping the function
+alive for JavaScript to call.
 
 !!! warning
 
@@ -101,7 +103,7 @@ reference, keeping the function alive for JavaScript to call.
 ## Checking for null values
 
 JavaScript has both `null` and `undefined`. Python has `None`. The
-`is_none()` function checks for both:
+[`is_none()`](../api/ffi.md#pyscript.ffi.is_none) function checks for both:
 
 ```python
 from pyscript.ffi import is_none
@@ -119,8 +121,8 @@ across interpreters.
 
 ## Merging JavaScript objects
 
-The `assign()` function merges JavaScript objects, similar to
-`Object.assign()` in JavaScript:
+The [`assign()`](../api/ffi.md#pyscript.ffi.assign) function merges
+JavaScript objects, similar to `Object.assign()` in JavaScript:
 
 ```python
 from pyscript.ffi import assign, to_js
@@ -140,7 +142,8 @@ whole.
 
 ## Accessing JavaScript globals
 
-The `js` module provides access to JavaScript's global namespace:
+The `js` module provides access to
+[JavaScript's global namespace](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis):
 
 ```python
 from pyscript import js
@@ -226,7 +229,7 @@ When working with workers, the FFI provides additional utilities for
 cross-thread communication. The `direct`, `gather`, and `query`
 functions help manage objects and data across thread boundaries. These
 are advanced features covered in detail in the
-[workers API docs](../api/workers.md) and are primarily relevant when building
+[FFI API docs](../api/ffi.md) and are primarily relevant when building
 complex multi-threaded applications.
 
 ## In summary
@@ -242,7 +245,7 @@ Convert Python objects to JavaScript when calling browser APIs. Most
 JavaScript functions expect JavaScript objects, not Python objects, so
 use `to_js()` when passing dictionaries or complex data structures.
 
-Handle null values correctly. JavaScript's `null` and `undefined` both
+Handle `null` values correctly. JavaScript's `null` and `undefined` both
 exist alongside Python's `None`, so use `is_none()` for reliable null
 checking.
 
diff --git a/docs/user-guide/filesystem.md b/docs/user-guide/filesystem.md
@@ -30,8 +30,8 @@ local filesystem appears at a directory in the browser's virtual filesystem*.
 
 !!! danger 
 
-    Access to the device's local filesystem is only available in recent Chromium
-    based browsers. The maximum capacity for files shared in this way is 4GB.
+    **Access to the device's local filesystem is only available in recent Chromium
+    based browsers**. The maximum capacity for files shared in this way is 4GB.
 
     Firefox and Safari do not support this capability yet, so it is not
     available to PyScript running in these browsers.
@@ -89,7 +89,7 @@ control).
     Chromium based browsers.
 
 Your device that runs your browser has a filesystem provided by a hard drive.
-Thanks to the `pyscript.fs` namespace, both MicroPython and Pyodide can gain
+Thanks to the [`pyscript.fs` namespace](../api/fs.md), both MicroPython and Pyodide can gain
 access to this filesystem, should the user of your code allow this to happen.
 
 This requires what's called a
diff --git a/docs/user-guide/media.md b/docs/user-guide/media.md
@@ -2,7 +2,8 @@
 
 Modern web applications often need to interact with cameras,
 microphones, and other media devices. PyScript provides a Pythonic
-interface to these devices through the `pyscript.media` module, letting
+interface to these devices through the 
+[`pyscript.media` module](../api/media.md), letting
 your Python code capture video, record audio, and enumerate available
 hardware directly from the browser.
 
diff --git a/docs/user-guide/offline.md b/docs/user-guide/offline.md
@@ -3,7 +3,7 @@
 PyScript applications typically load from a Content Delivery Network
 or webserver, fetching core files and Python interpreters over the internet.
 This works well when you have reliable network access, but sometimes you need
-applications to run offline - in air-gapped environments, on local
+applications to run offline ~ in air-gapped environments, on local
 networks, or where internet connectivity isn't available or is patchy.
 
 Running PyScript offline means bundling everything your application
@@ -216,23 +216,23 @@ the Pyodide package bundle. Download it from the
 
 !!! warning
 
-    The complete package bundle exceeds 200MB. It contains all packages
+    The complete package bundle exceeds 300MB. It contains all packages
     available in Pyodide. Pyodide loads packages on demand, so you only
     download what your code actually imports, but the entire bundle must
     be available locally.
 
 Download and extract the bundle for your Pyodide version (e.g.,
-`pyodide-0.26.2.tar.bz2`):
+`pyodide-0.29.1.tar.bz2`):
 
 ```sh
 # Download the bundle.
-wget https://github.com/pyodide/pyodide/releases/download/0.26.2/pyodide-0.26.2.tar.bz2
+wget https://github.com/pyodide/pyodide/releases/download/0.29.1/pyodide-0.29.1.tar.bz2
 
 # Extract it.
-tar -xjf pyodide-0.26.2.tar.bz2
+tar -xjf pyodide-0.29.1.tar.bz2
 
 # Copy package files to your public directory.
-cp -R pyodide-0.26.2/pyodide/* public/pyodide/
+cp -R pyodide-0.29.1/pyodide/* public/pyodide/
 ```
 
 Now use packages in your application:
@@ -283,8 +283,9 @@ or local files with no network errors.
 
 If your application uses workers, you need a server that sets
 Cross-Origin Isolation (COI) headers. These headers enable
-`SharedArrayBuffer` and other features required for worker support. Use
-`mini-coi` instead of Python's simple server:
+`SharedArrayBuffer` and other features required for worker support.
+[Use `mini-coi` instead](https://github.com/WebReflection/mini-coi)
+of Python's simple server:
 
 ```sh
 # Install mini-coi if needed.
diff --git a/docs/user-guide/plugins.md b/docs/user-guide/plugins.md
@@ -245,4 +245,7 @@ web pages with the built-in code editor.
 
 **[PyGame](pygame-ce.md)** - Use PyGame-CE with PyScript, covering the
 differences from traditional PyGame development and techniques for making
-games work well in the browser.
+games work well in the browser.
+
+**[PyScript in JavaScript](from_javascript.md)** - drive PyScript from the
+world JavaScript. 
diff --git a/docs/user-guide/pygame-ce.md b/docs/user-guide/pygame-ce.md
@@ -138,7 +138,7 @@ The configuration file lists game assets:
 ```
 
 Download `intro_ball.gif` from the
-[PyGame-CE repository](https://github.com/pygame-community/pygame-ce/blob/main/docs/reST/tutorials/assets/intro_ball.webp?raw=true).
+[example on this website](../example-apps/bouncing-ball/intro_ball.gif).
 
 ## Running locally and in browser
 
@@ -318,5 +318,8 @@ interface for interactive Python sessions.
 **[Editor](editor.md)** - Create interactive Python coding environments in
 web pages with the built-in code editor.
 
+**[PyScript in JavaScript](from_javascript.md)** - drive PyScript from the
+world JavaScript. 
+
 **[Plugins](plugins.md)** - Understand the plugin system, lifecycle hooks,
 and how to write plugins that integrate with PyScript.
diff --git a/docs/user-guide/terminal.md b/docs/user-guide/terminal.md
diff --git a/docs/user-guide/what.md b/docs/user-guide/what.md
