Skip to content

About

Free, interactive tutorials on the mathematics of machine learning and ML: lessons with live figures, quizzes, spaced-repetition review and Colab notebooks. Source of learn.mohebi.ai.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

learn.mohebi.ai

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.

Layout

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

Build and preview

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:8000

Checks:

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/

Notebooks in the browser (JupyterLite)

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 pass
  • tools/build_lite.py builds <out>/lab/ (about 22 MB, 600 files) with jupyterlite-core and jupyterlite-pyodide-kernel (dev dependencies, pinned in pyproject.toml), in a few seconds. It copies every notebooks/<lang>/<track>/*.ipynb to lab/files/<lang>/<track>/ and replaces lab/ 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.seterr and decimal.getcontext().prec would be lost after each cell; the setup cell saves and restores them (IPython pre_run_cell/post_run_cell hooks).
  • Notebooks that import torch at 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 --all includes them anyway.
  • uv run build.py without --lite keeps an existing <out>/lab/ as it is (fast; nothing is rebuilt). So after notebook changes, and before a deploy, run uv 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 (and comm) are served from /lab/, so starting a notebook does not need pypi.org.
  • static/_headers has a separate Content-Security-Policy for /lab/* (Cloudflare: ! Content-Security-Policy removes the site-wide one, then the lab one is set). It adds 'unsafe-eval' (JupyterLab compiles its settings schemas with new Function), 'wasm-unsafe-eval', the Pyodide CDN, workers, and pypi.org for %pip install. The rest of the site keeps the strict policy. --check serves 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.

Active learning and offline reading

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.

Deploy

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.

License

Text and figures: CC BY 4.0 (LICENSE-CONTENT.md). Code and notebooks: MIT (LICENSE). KaTeX: MIT (static/vendor/katex/LICENSE). Vazirmatn font: OFL.

About

Free, interactive tutorials on the mathematics of machine learning and ML: lessons with live figures, quizzes, spaced-repetition review and Colab notebooks. Source of learn.mohebi.ai.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages