Free, open tutorials on the mathematics of machine learning, one track at a time. Each lesson has interactive figures, worked examples with answers, verified videos and a Colab notebook with self-checking exercises. The first track is Linear Algebra (19 lessons).
Static site: Markdown in content/, a Python build script, vanilla-JS widgets, KaTeX rendered at
build time. Served by Cloudflare (Workers static assets), like mohebi.ai.
| Path | What |
|---|---|
content/site.yaml |
site settings and the list of tracks |
content/<track>/track.yaml |
parts and lesson order of a track |
content/<track>/NN-slug.md |
lessons (Markdown, $math$, ::: widget/video/callout blocks) |
static/widgets/*.js |
interactive figures, one ES module each |
static/js/lib/ |
shared libraries: ui, plane (2D), space3d (3D), chart, la (linear algebra) |
notebooks/<track>/src/*.py |
notebook sources (percent format) → notebooks/<track>/*.ipynb |
templates/ |
Jinja page templates |
tools/ |
KaTeX renderer, notebook builder and checker, video checker, link checker, screenshots |
AUTHORING.md |
how to write a lesson, a widget and a notebook |
public/ |
build output (not committed); deployed with npx wrangler deploy |
Needs uv, Node.js (for KaTeX at build time) and, for screenshots, Chrome.
uv sync
uv run tools/nbbuild.py # notebook sources -> .ipynb
uv run build.py # -> public/
python3 -m http.server 8000 -d public # http://localhost:8000Checks:
uv run build.py --strict # fail on KaTeX errors, unknown widgets, missing files
uv run tools/check_notebooks.py # run every notebook unsolved and solved
uv run tools/check_videos.py # every YouTube id exists, with its real title
uv run tools/check_links.py # every external link answers
uv run tools/shoot.py page /linear-algebra/08-svd/ --dark # screenshot to .shots/Every lesson page also has Run in browser: the notebook opens in JupyterLite with the Pyodide kernel (CPython compiled to WebAssembly). It needs no Google account and no install, so it also works where Colab is blocked (for example for many learners in Iran).
uv run build.py --lite # site + public/lab/ (the lite step alone: uv run tools/build_lite.py)
python3 -m http.server 8000 -d public # http://localhost:8000/lab/notebooks/index.html?path=en/linear-algebra/01-matrices-span-basis.ipynb
uv run tools/build_lite.py --check # open a sample of notebooks in headless Chrome and run every cell
uv run tools/build_lite.py --check --solved notebooks/en/calculus/06-backprop-losses-layers.ipynb
# same, with each exercise replaced by its solution; all checks must passtools/build_lite.pybuilds<out>/lab/(about 22 MB, 600 files) withjupyterlite-coreandjupyterlite-pyodide-kernel(dev dependencies, pinned inpyproject.toml), in a few seconds. It copies everynotebooks/<lang>/<track>/*.ipynbtolab/files/<lang>/<track>/and replaceslab/in one step. Link form:/lab/notebooks/index.html?path=<lang>/<track>/<name>.ipynb.- The browser copy differs from the source in two ways: the kernelspec, and one collapsed setup cell
before the first code cell. The Pyodide kernel runs each cell in a new asyncio task, so
np.set_printoptions,np.seterranddecimal.getcontext().precwould be lost after each cell; the setup cell saves and restores them (IPythonpre_run_cell/post_run_cellhooks). - Notebooks that import
torchat top level are left out (there is no PyTorch for Pyodide), so their lessons have no "Run in browser" button.uv run tools/build_lite.py --allincludes them anyway. uv run build.pywithout--litekeeps an existing<out>/lab/as it is (fast; nothing is rebuilt). So after notebook changes, and before a deploy, runuv run build.py --lite. The "Run in browser" button appears only for notebooks that exist in<out>/lab/files/.- Pyodide and the packages (numpy, scipy, matplotlib, scikit-learn, pandas, ...) are not in the repo.
They load from the jsdelivr CDN (
cdn.jsdelivr.net/pyodide/v314.0.6/full/) the first time they are imported: about 37–41 MB for a typical notebook, then the browser caches them. The kernel's own small wheels (andcomm) are served from/lab/, so starting a notebook does not need pypi.org. static/_headershas a separate Content-Security-Policy for/lab/*(Cloudflare:! Content-Security-Policyremoves the site-wide one, then the lab one is set). It adds'unsafe-eval'(JupyterLab compiles its settings schemas withnew Function),'wasm-unsafe-eval', the Pyodide CDN, workers, and pypi.org for%pip install. The rest of the site keeps the strict policy.--checkserves the folder with these headers.- Learners' edits are saved in their browser (IndexedDB). A learner who has edited a notebook keeps that copy even after we publish a new version of it.
- Other differences from Colab: Python 3.14 with the Pyodide builds of the packages; no subprocesses or
threads; the default NumPy integer is
int32; the JupyterLite interface is in English. See AUTHORING.md §6.1.
Everything a learner does is stored only in their browser (localStorage); nothing is sent anywhere.
| Feature | Where | Data |
|---|---|---|
| Concept map | /map/, /fa/map/ (templates/map.html, static/js/map.js) |
/graph-<lang>.json from build.py: one node per lesson of each live track, edges from the links in each lesson's Before this lesson line plus the previous lesson of the track. Links to a later lesson of the same track are ignored. Untranslated lessons appear on the Persian map with English titles. |
| Lessons done | lesson pages, track pages, map, review | learn:done:<track>/<slug> = "1" (shared by both languages) |
| Review deck | review page | learn:srs = {cardId: {due, ivl, ease, reps, lapses}} |
| Review history | review dashboard (streak, 14-day forecast, retention) | learn:srs-log = {"YYYY-MM-DD": [again, hard, good, easy]} |
| Backup | review page | JSON export/import (merges, never deletes); Anki CSV with the cards' TeX source (qs/as in cards-<lang>.json) as \( \) / \[ \] |
| Offline reading | static/sw.js, registered by site.js |
Cache Storage: learn-pages (HTML and JSON data), learn-static-<build> (CSS, JS, widgets, fonts, KaTeX) |
Service worker. build.py hashes static/ into a build id. It writes the id and the app-shell list
into public/sw.js, into <html data-build> of every page, and into the CSS/JS URLs (?v=<build>).
Pages and JSON data are network first; static files are cache first. When a page arrives with a
different build id (a new deploy), the old worker stops trusting its static cache and asks the browser
to install the new one, so CSS/JS are never stale after a deploy. /lab/ and /notebooks/ are never
cached. The Save this track for offline reading button on a track page sends the track's pages,
widgets (with their imports) and data to the worker.
Test locally with python3 -m http.server -d public (service workers work on localhost). To start
clean: DevTools → Application → Storage → Clear site data.
npx wrangler deploy uploads public/ and attaches learn.mohebi.ai (see wrangler.jsonc).
Colab links point to github.com/salmanmohebi/learn.mohebi.ai, so the notebooks open in Colab once
that repository is public.
Text and figures: CC BY 4.0 (LICENSE-CONTENT.md). Code and notebooks: MIT (LICENSE). KaTeX: MIT (static/vendor/katex/LICENSE). Vazirmatn font: OFL.