Merge feature/docs-site-overhaul: docs-site overhaul (uvx-first, hero, dark mode, How It Works + FAQ, social cards, v0.4.0)

Author: abhiksark

.github/workflows/pages.yml

@@ -26,6 +26,8 @@ jobs:
           cache-dependency-path: requirements-docs.txt
       - uses: actions/configure-pages@v5
       - run: python -m pip install -r requirements-docs.txt
+      - name: Install social-card system deps
+        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev pango1.0-tools
       - run: mkdocs build --strict
       - uses: actions/upload-pages-artifact@v3
         with:

.gitignore

@@ -138,3 +138,6 @@ dmypy.json
 /pythonlings/.git/
 /pythonlings/.pythonlings.toml
 /pythonlings/exercises/
+
+# Docs build venv
+.venv-docs/

docs-site/assets/favicon.svg

@@ -0,0 +1,33 @@
+# FAQ
+
+## How is this different from Rustlings?
+
+Pythonlings brings the same fix-broken-exercises idea to Python. Instead of Rust's compiler, it uses a terminal TUI built with [Textual](https://textual.textualize.io/) and runs hidden `assert`-based checks in a subprocess each time you save.
+
+## Do I need `uv`?
+
+No. The easiest zero-install path is `uvx pythonlings`, but you can also install with `pipx install pythonlings`, `uv tool install pythonlings`, or plain `pip install pythonlings`.
+
+## Which Python versions are supported?
+
+Python 3.9 and above (`requires-python = ">=3.9"`).
+
+## Where is my progress stored?
+
+Progress lives in the learner workspace you create with `pythonlings init`, at `<workspace>/.pythonlings/state.json`. It is written atomically with a `.bak` recovery copy and is never stored inside the installed package.
+
+## How do I update or reset?
+
+Run `pythonlings update` to pull the latest exercises into an existing workspace. To restore a single exercise to its original broken state, run `pythonlings reset <exercise> --yes`.
+
+## Does it work offline?
+
+Yes. All exercises and the bundled local Python reference (press `F5` in the TUI) work without a network connection. Only the "open official docs" shortcut (`O`) requires internet access.
+
+## Is Pythonlings on PyPI?
+
+Yes — install it as [`pythonlings`](https://pypi.org/project/pythonlings/) (current release: `v0.4.0`).
+
+## How do I see the reference answer?
+
+Run `pythonlings solution <exercise>` (alias: `sol`). This executes the reference solution for the named exercise.

docs-site/assets/logo.svg

@@ -0,0 +1,75 @@
+# How It Works
+
+![Pythonlings demo](https://raw.githubusercontent.com/abhiksark/pythonlings/main/docs/assets/demos/pythonlings-demo.gif)
+
+Pythonlings follows a tight edit-check-advance loop. Here is what happens at each step.
+
+---
+
+## The Learner Loop
+
+1. **Open the next pending exercise** — the TUI shows the first incomplete exercise in the curriculum.
+2. **Edit the broken code** — fix the intentional mistake directly in the built-in editor (or any external editor you prefer).
+3. **Checks rerun automatically** — roughly 0.6 s after you stop typing, Pythonlings re-evaluates the exercise in a fresh subprocess. There is no filesystem watcher; the debounce fires inside the TUI editor.
+4. **Remove the `# I AM NOT DONE` marker** — the marker is your explicit "I'm finished" signal. Passing checks alone does not advance the exercise (see below).
+5. **Advance** — once checks are green *and* the marker is gone, the exercise is marked complete and the TUI moves to the next one.
+
+---
+
+## The `# I AM NOT DONE` Marker
+
+Every exercise file begins with the comment:
+
+```python
+# I AM NOT DONE
+```
+
+You must delete this line to finish the exercise. This is intentional: it prevents an accidental fix (or a pre-written solution) from silently skipping an exercise before you have thought it through. The marker is your deliberate "I understand this and I'm moving on" confirmation.
+
+---
+
+## Worked Example
+
+**Broken exercise** (`exercises/variables/variables1.py`):
+
+```python
+# I AM NOT DONE
+
+# Assign the integer 42 to the variable `answer`.
+answer = "forty-two"
+```
+
+The hidden check (`checks/variables/variables1.py`) does something like:
+
+```python
+assert answer == 42, f"Expected 42, got {answer!r}"
+```
+
+Running with the code above, the check fails. Fix the exercise:
+
+**Fixed exercise:**
+
+```python
+# Assign the integer 42 to the variable `answer`.
+answer = 42
+```
+
+Note that `# I AM NOT DONE` has been removed. Now the check passes *and* the marker is gone, so Pythonlings marks `variables1` complete and opens the next exercise.
+
+---
+
+## How Checks Run
+
+Pythonlings generates a tiny runner script that `exec()`s your exercise source, then the hidden check source, in a shared namespace inside a fresh subprocess (5 s timeout). Because the check runs in the same namespace as the exercise, it can inspect any variable you set — that is why checks are bare `assert` statements rather than a pytest file.
+
+---
+
+## Where Progress Is Stored
+
+Progress lives in your learner workspace, not in the Pythonlings package:
+
+```
+<workspace>/.pythonlings/state.json
+```
+
+The file is written atomically (write to a temp file, then rename), and a `.bak` copy is kept so Pythonlings can recover if `state.json` is ever corrupted. The workspace itself is created by `pythonlings init`.

docs-site/faq.md

@@ -1,36 +1,42 @@
-# Pythonlings
-
-Python learnings, Rustlings-style, in a live terminal TUI.
+---
+hide:
+  - toc
+---
+
+<div class="pl-hero" markdown>
+  <div class="pl-eyebrow">Rustlings for Python</div>
+  <div class="pl-title">Learn Python by fixing tiny broken programs.</div>
+  <div class="pl-subtitle">292 exercises across 31 topics. Hidden checks rerun the
+    instant you save — fix the code, watch it go green, advance.</div>
+  <div class="pl-install">$ uvx pythonlings init</div>
+  <div class="pl-ctas">
+    <a class="pl-btn" href="quick-start/">Get started →</a>
+    <a class="pl-btn pl-btn--ghost" href="https://github.com/abhiksark/pythonlings">View on GitHub</a>
+  </div>
+  <div class="pl-stats"><span><b>292</b> exercises</span><span><b>31</b> topics</span><span><b>zero</b> setup</span></div>
+</div>
 
 ![Pythonlings terminal demo](https://raw.githubusercontent.com/abhiksark/pythonlings/main/docs/assets/demos/pythonlings-demo.gif)
 
-Pythonlings helps learners practice Python by fixing small broken programs and
-watching checks rerun as they work. The project includes 292 exercises across
-31 topics, hidden pytest-style checks, a Textual editor, progressive hints, and
-bundled Python documentation snippets for offline-friendly practice.
+## What you get
+
+- Rustlings-inspired Python practice, entirely in your terminal.
+- Hidden checks that rerun as you type and advance you automatically.
+- Topic picker, progress tracking, reset, progressive hints, and one-shot CLI commands.
+- A local docs window with links back to the official Python documentation.
+- A self-contained learner workspace created by `pythonlings init`.
 
-## Start Here
+## Start here
 
 ```bash
-pipx install "git+https://github.com/abhiksark/pythonlings.git@v0.1.0"
-pythonlings init --path ~/pythonlings-workspace
+uvx pythonlings init --path ~/pythonlings-workspace
 cd ~/pythonlings-workspace
-pythonlings
+uvx pythonlings
 ```
 
-The package name reserved for PyPI publishing is `pythonlings`. Until the
-PyPI release is live, install the stable v0.1.0 release from the GitHub tag.
-
-## What You Get
-
-- Rustlings-inspired Python coding practice in the terminal.
-- Live exercise verification while editing.
-- Topic picker, progress tracking, reset, hints, and one-shot CLI commands.
-- Local docs window with links back to the official Python documentation.
-- A self-contained learner workspace created by `pythonlings init`.
+Prefer a permanent install? See [Quick Start](quick-start.md) for `pipx`, `uv tool`, and `pip`.
 
-## Project Status
+## Project status
 
-Pythonlings is currently `v0.1.0` alpha. The public API, CLI, and curriculum are
-usable, but the project is still hardening packaging, docs, first-run flow, and
-release automation.
+Pythonlings is `v0.4.0`, published on PyPI as `pythonlings`. The learner loop, CLI, and
+curriculum are stable; see the [Roadmap](roadmap.md) for what's next.

docs-site/how-it-works.md

@@ -5,7 +5,7 @@
 ![Coding screen](https://raw.githubusercontent.com/abhiksark/pythonlings/main/docs/assets/screenshots/coding-screen.png)
 
 The coding screen keeps the exercise, editor, output, progress, and exercise
-list in one terminal view. Checks rerun as files change.
+list in one terminal view. Checks rerun automatically after each edit (debounced).
 
 ## Topic Picker
 

docs-site/index.md

@@ -1,22 +1,36 @@
 # Quick Start
 
-## Install
+> Current release: **v0.4.0** · [PyPI](https://pypi.org/project/pythonlings/)
 
-Install the current release from GitHub:
+## Zero-Install (uvx)
+
+No installation required — run Pythonlings directly with [uv](https://docs.astral.sh/uv/):
 
 ```bash
-pipx install "git+https://github.com/abhiksark/pythonlings.git@v0.1.0"
+uvx pythonlings init --path ~/pythonlings-workspace
+cd ~/pythonlings-workspace
+uvx pythonlings
 ```
 
-After PyPI publishing is enabled, the package install path will be:
+## Install Options
 
-```bash
-pipx install pythonlings
-```
+=== "uv (recommended)"
+    ```bash
+    uvx pythonlings            # zero-install, always latest
+    uv tool install pythonlings
+    ```
+
+=== "pipx"
+    ```bash
+    pipx install pythonlings
+    ```
 
-The command installed by the package is `pythonlings`.
+=== "pip"
+    ```bash
+    pip install pythonlings
+    ```
 
-## Create A Workspace
+## Create a Workspace
 
 ```bash
 pythonlings init --path ~/pythonlings-workspace
@@ -25,27 +39,27 @@ pythonlings
 ```
 
 `pythonlings init` copies exercises, hidden checks, reference solutions, and reset
-snapshots into a learner workspace. Run `pythonlings` from that workspace to open
-the first pending exercise.
+snapshots into a self-contained learner workspace. Running `pythonlings` (or
+`pythonlings watch`) from that workspace opens the first pending exercise in the
+TUI.
 
 ## Useful Commands
 
 ```bash
-pythonlings list
-pythonlings topics
-pythonlings hint variables1
-pythonlings run variables1
-pythonlings dry-run variables1
-pythonlings reset variables1 --yes
-pythonlings update
+pythonlings list                 # show all topics and progress
+pythonlings topics               # open the topic picker in the TUI
+pythonlings start variables      # launch TUI on a specific topic
+pythonlings hint variables1      # print the hint for an exercise
+pythonlings solution variables1  # run the reference solution for an exercise
+pythonlings run variables1       # run a single exercise and show output
+pythonlings dry-run variables1   # non-interactive run (CI-friendly)
+pythonlings reset variables1 --yes  # restore exercise to its original state
+pythonlings update               # pull new exercises into an existing workspace
 ```
 
-Use `pythonlings list` to inspect progress, `pythonlings hint <exercise>` for help, and
-`pythonlings reset <exercise> --yes` to restore an exercise to its original broken
-state.
-
 ## Exercise Loop
 
-Each exercise contains a `# I AM NOT DONE` marker. Fix the code, remove the
-marker, and let Pythonlings run the hidden check. Passing checks mark the exercise
-complete and move the progress state forward.
+Each exercise contains a `# I AM NOT DONE` marker. Open the file in the TUI
+editor (or any editor), fix the broken code, then remove the marker. Pythonlings
+runs the hidden check automatically; when the check passes and the marker is gone,
+the exercise is marked complete and progress advances to the next one.

docs-site/interface.md

@@ -1,19 +1,18 @@
 # Roadmap
 
-Pythonlings is currently `v0.1.0` alpha. The core learner loop works, but the
-project still needs product hardening before calling it stable.
+Pythonlings is `v0.4.0`, published on PyPI as `pythonlings`. Install with
+`uvx pythonlings` or `pip install pythonlings`.
 
-## Current Release
+## Shipped
 
 - 292 exercises across 31 topics.
 - Live Textual editor and automatic checks.
 - Topic picker, progress state, reset, hints, and CLI commands.
 - Bundled Python docs snippets with official docs links.
-- GitHub install path for `v0.1.0`.
+- Published on PyPI as `pythonlings`; canonical install is `uvx pythonlings`.
 
 ## Next Work
 
-- Finish PyPI publishing for the `pythonlings` project name.
 - Improve first-run onboarding and empty-state copy.
 - Harden keyboard flow around `Enter`, `Esc`, `F4`, and `F5`.
 - Add more TUI tests for the coding screen, docs window, and topic picker.