docs: rewrite image paths to jsDelivr CDN, add VS Code setup screenshots

.gitignore

@@ -3,4 +3,5 @@ hku-logo-xs.png
 .workspace/
 .codebuddy/
 .vscode
-.idea
+.idea
+assets/.DS_Store

.workbuddy/memory/2026-08-10.md

@@ -0,0 +1,43 @@
+# 2026-08-10 — conda-first install guide + git recovery incident
+
+## Project
+`python-setup-moodle` — beginner Python install tutorial (English prose, Chinese UI chat).
+Convention (AGENTS.md): emoji callouts (📝💡⚠️❗) instead of GitHub alert syntax; no authoring
+instructions in reader-facing `.md`; commands split per OS, no copyable `$`.
+
+## install guide content decisions (this session)
+- Reorder: **conda first (Method A, most recommended)**, **uv second (Method B)**, standalone third.
+- Anaconda vs Miniconda: documented as two conda distributions (differ only in pre-installed
+  packages; full Anaconda ~3GB, Miniconda minimal). "conda" command identical for both.
+- Install now requires **concrete versions** (not "latest"). Anaconda example Anaconda3-2026.07-1.
+- Course env = **`mffintech`** (cloned from base): out-of-box Python 3.14.6 / NumPy 2.4.6 /
+  pandas 3.0.3 / PyArrow 23.0.1 / pytest 9.0.3 / JupyterLab 4.5.9. Extra: duckdb=1.5.4,
+  polars=1.43.2, yfinance=1.5.2.
+- **conda rule:** prefer `conda install` over `pip` inside conda envs (pip pkgs invisible to conda).
+- uv: must `cd` into project before `uv pip install`/`uv run` or it pollutes `~/.venv` in home.
+- Section order: test → Run your first program → **How to debug** (debug moved to very end).
+
+## ⚠️ GIT REPO IS FRAGILE — read before any git op
+- During a PR attempt the repo got corrupted. `main` ref now = `08aa301` (origin/base, the
+  published Aug-5 version). `HEAD` currently points to branch `docs/ide-setup-cdn-images`.
+- A dangling root commit `0235d60` exists but its tree is broken at the `pages` subtree
+  (object `ad15a881` missing) → cannot extract files from it.
+- Loose blob `477f05` = an *intermediate* installation.md (has conda-first + 📝 note, but
+  missing mffintech/pkg-table/conda-install/Miniconda-links/heading-restructure/uv-warning).
+- **Do NOT run `git commit`/`checkout -f`/`switch` casually here** — earlier a `checkout -f main`
+  reverted installation.md, virtual-environment.md AND AGENTS.md to base (lost all our edits).
+
+## Recovery status (end of session)
+- `pages/installation.md`: **REBUILT** (conda-first, mffintech env, pkg table, conda-install
+  pref, Miniconda links, heading restructure, uv cd warning, debug-at-end). NOT touched again.
+- `pages/virtual-environment.md`: **REBUILT this turn** (full Write). Re-ordered conda+Channels
+  BEFORE uv; added Anaconda vs Miniconda comparison table; fixed Channels to "prefer conda
+  install over pip"; added uv `requirements.txt` 2nd method + cd warning; ending 💡 now
+  recommends **conda (Miniconda)**.
+- `AGENTS.md`: **REBUILT this turn** (3 Edits). "why conda is preferred (uv as fast
+  alternative)"; conda listed before uv; "specific, concrete versions" (no "latest"); with
+  conda split into **Anaconda + Miniconda** two distributions, each with verified install-doc
+  URLs (mac-cli-install / windows-cli-install / linux-install).
+- Verified Anaconda install-doc URLs via WebFetch: mac-cli-install ✓, windows-cli-install ✓,
+  linux-install ✓. (mac-os-install / mac-install / windows-install all 404.)
+- Temp/backup files created during recovery were deleted; `.bak.tar.gz` removed.

AGENTS.md

@@ -70,14 +70,13 @@ Options and arguments (and corresponding environment variables):
 - why executables on windows has `exe` extension and why unix does not have
 - pwsh commands: unix-like aliases and its original commands and why windows is not prefered. e.g. `Get-Command` = `which`
 ### (short, non-compulsory)concept of virtual enviroment
-- why need virtual env rather than standalone python, why uv is prefered. why /usr/bin/python3 cannot be used directly
-- uv
+- why need virtual env rather than standalone python, why conda is preferred (uv as a fast alternative). why /usr/bin/python3 cannot be used directly
 - conda:https://www.anaconda.com/docs/getting-started/concepts/anaconda-or-miniconda
-- anaconda 
-- miniconda, difference of channels, conda-forge and others
+- anaconda (full distribution: conda + 250+ pre-installed packages, ~3 GB) and miniconda (minimal installer: conda only, ~100 MB), difference of channels, conda-forge and others
+- uv:https://docs.astral.sh/uv/ (fast alternative)
 - difference of `conda` and `uv`, `conda activate` vs `source .venv/bin/activate`, global vs local enviroment
 ### (very detail) How to installation python executable
-- how to choose version (amd64, arm64, x86_64, exe) and how to set up first python enviroment
+- how to choose **specific, concrete versions** — a fixed Python version (e.g. 3.12), the exact CPU arch (amd64, arm64, x86_64, aarch64), and the exact installer version number for Anaconda/Miniconda. Never write "latest" or leave the version blank. Then how to set up first python enviroment
 - standalone installation, double click exe to install
     - win: 
         - https://www.python.org/downloads/windows/
@@ -91,14 +90,18 @@ Options and arguments (and corresponding environment variables):
         - with standalone installer:https://www.python.org/downloads/source/
         - typecially it will be installed under the path of 
 
-- with conda:
-    - url: 
-        - macos:https://www.anaconda.com/docs/getting-started/miniconda/install/mac-cli-install#using-miniconda-in-a-commercial-setting
-        - windows:https://www.anaconda.com/docs/getting-started/miniconda/install/windows-cli-install#powershell
-        - linux:https://www.anaconda.com/docs/getting-started/miniconda/install/linux-install#installation-steps
-    - how to install
-        - introduce cli reference`conda create --name py310 python=3.12`
-        - `conda activate <enviroment name>` condaand how to re-activate after close terminal
+- with conda (two distributions — pick one):
+    - **Anaconda** (full distribution: conda + 250+ pre-installed packages, ~3 GB) — official install docs:
+        - macos: https://www.anaconda.com/docs/getting-started/anaconda/install/mac-cli-install
+        - windows: https://www.anaconda.com/docs/getting-started/anaconda/install/windows-cli-install
+        - linux: https://www.anaconda.com/docs/getting-started/anaconda/install/linux-install
+    - **Miniconda** (minimal installer: conda only, no pre-installed packages — recommended) — official install docs:
+        - macos: https://www.anaconda.com/docs/getting-started/miniconda/install/mac-cli-install
+        - windows: https://www.anaconda.com/docs/getting-started/miniconda/install/windows-cli-install
+        - linux: https://www.anaconda.com/docs/getting-started/miniconda/install/linux-install
+    - how to install (same for both distributions)
+        - introduce cli reference `conda create --name py310 python=3.12`
+        - `conda activate <enviroment name>` and how to re-activate after close terminal
         - how to set specific pre-installed python executable for new env to save space
 - with uv:
     - url: https://docs.astral.sh/uv/getting-started/installation/#pypi

build_release.py

@@ -22,11 +22,10 @@
 
 Requires: Python 3.8+, the `markdown` package.
 
-TODO: image references in the release still point to the local relative path
-(`../assets/img/...`) as produced by the Markdown. Before publishing, rewrite
-these to GitHub permalinks (e.g.
-`https://github.com/fyq163/python-setup-moodle/raw/main/assets/img/...`) so the
-release needs no bundled `assets/` folder. This step is done manually.
+Image handling in the release build: any image whose URL is already an absolute
+`https://` link is kept as-is, while local repo-relative paths (`../assets/img/...`)
+are rewritten to a public CDN URL. So the release output is fully self-contained
+and needs no bundled `assets/` folder.
 """
 import os
 import re
@@ -76,8 +75,20 @@ def slugify(s):
 def render_body(md_text):
     """Render markdown to HTML and add heading ids / collect a TOC."""
     html = _md.markdown(md_text, extensions=MD_EXTENSIONS)
-    # TODO: image src still uses the local relative path (`../assets/img/...`).
-    # Rewrite to a GitHub permalink before publishing (see file header).
+    # Rewrite ONLY local repo-relative image paths (../assets/img/...) to a
+    # public URL. Images that already use an absolute https:// URL are left
+    # untouched ("detect https -> skip; detect repo path -> render").
+    GITHUB_CDN = "https://cdn.jsdelivr.net/gh/fyq163/python-setup-moodle@main"
+
+    def _rewrite_img(mo):
+        src = mo.group(1)
+        if src.startswith("https://"):
+            return mo.group(0)          # already public -> keep as-is
+        if src.startswith("../assets/img/"):
+            return 'src="%s/assets/img/%s"' % (GITHUB_CDN, src[len("../assets/img/"):])
+        return mo.group(0)              # other relative path -> leave alone
+
+    html = re.sub(r'src="([^"]+)"', _rewrite_img, html)
     # Turn any leftover GitHub-style alert markers into emoji callouts.
     html = re.sub(
         r'<blockquote>\s*<p>\s*\[!(NOTE|TIP|WARNING|IMPORTANT|CAUTION)\]\s*',
@@ -261,7 +272,6 @@ def main():
         with open(os.path.join(OUT, name + ".html"), "w", encoding="utf-8") as f:
             f.write(out)
         print("built release/%s.html" % name)
-    # No local assets/ folder: release references images via GitHub permalink.
     print("release build complete -> %s" % OUT)
 
 

pages/ide-setup.md

@@ -18,27 +18,35 @@ identical:
 4. Select the interpreter: press `Ctrl/Cmd + Shift + P`, type **"Python: Select
    Interpreter"**, and choose the environment you made in Chapter 3 (the `.venv` or conda
    env). The bottom-right status bar then shows that Python.
+   ![vscode plugin marketplace](https://pub-639e92bd227c4441a00a10db2a268512.r2.dev/image/GitHub-pages/python-install/vscode-extension-python.png)
 5. Use the built-in terminal (`Ctrl/Cmd + `` `) to run `uv run main.py` or
    `python main.py`.
-
-![TODO: Screenshot of VS Code — the "Python: Select Interpreter" picker, highlighting the virtual environment created in Chapter 3.](../assets/img/placeholder.svg)
+![Screenshot of VS Code — the "Python: Select Interpreter" picker, highlighting the virtual environment created in Chapter 3.](https://pub-639e92bd227c4441a00a10db2a268512.r2.dev/image/GitHub-pages/python-install/vscode-interpreter-selection.png)
 
 > 💡
 > Once the interpreter is selected, the play button (▶) and the terminal both use *your*
 > project's Python — not the system one. That is the whole point.
 
-## PyCharm Community Edition
+## PyCharm
+
+> ❗
+> Since 2025, JetBrains has **merged the Community and Professional editions** of PyCharm
+> into a single product. The **basic features are free to use**; the **advanced features
+> require a paid subscription**. As a student, you can get that subscription for free via
+> the [JetBrains Student Pack](https://www.jetbrains.com/academy/student-pack/) — sign in
+> with your school email and the advanced features unlock at no cost.
 
-PyCharm is a Python-focused IDE with a free **Community** edition (the **Professional**
-edition adds web/DB features and is paid, though free for students).
+PyCharm is a Python-focused IDE. The **basic features** (editing, running, debugging Python)
+are free; the **advanced features** (web frameworks, database tools, etc.) need a
+subscription, which students get free with the Student Pack above.
 
-1. Download [PyCharm Community](https://www.jetbrains.com/pycharm/download/).
+1. Download [PyCharm](https://www.jetbrains.com/pycharm/download/).
 2. **New Project** → choose a location. Under "Python Interpreter", select **Previously
    configured interpreter** and point it at your `conda` env or the `python` inside
    `.venv/bin` (macOS/Linux) / `.venv\Scripts\python.exe` (Windows). Or let PyCharm create
    a new `venv` for you.
 3. Right-click a `.py` file and choose **Run**.
-
+- ![PyCharm change interpreter](https://pub-639e92bd227c4441a00a10db2a268512.r2.dev/image/GitHub-pages/python-install/pycharm-interpreter-selection.png)
 References: [PyCharm + conda](https://www.anaconda.com/docs/getting-started/working-with-conda/ides/pycharm),
 [Python path](https://www.anaconda.com/docs/getting-started/working-with-conda/ides/python-path)
 
@@ -57,4 +65,3 @@ Python your shell currently has active.
 
 GitHub Copilot is an AI pair-programmer that suggests code as you type. **Students get it
 free** (and many other developer tools) through the [GitHub Copilot - Information Technology Services - HKU](https://its.hku.hk/software/github-copilot/)
-pack with a school email.