Machine Learning Visualized: a Jupyter Book that assembles notebooks from seven separate repositories

What this repository actually contains

The README is explicit that this repo is the code to configure and build the Jupyter Book, and that none of the Jupyter Notebooks are in this repository. The content is fetched from seven separate GitHub repositories: neural-network, autoencoder, logistic-regression, perceptron, pca, k-means-clustering, and gradient-descent. That single sentence changes how the project should be evaluated. You are not adopting an ML implementation. You are adopting a build pipeline whose inputs are external and mutable. The MIT licence covers the configuration, the SH download script, the Dockerfiles, and the LaTeX tooling in this repo. It does not automatically cover the notebooks pulled in from the sibling repositories, so anyone republishing the built site should check the licence of each algorithm repo rather than assuming the MIT here propagates. The primary language listed for the repository is TeX, which matches the EPUB path in the README that converts notebooks to LaTeX before Pandoc turns them into an EPUB.

The download script is the real dependency boundary

Step 1 of the usage instructions is chmod +x ./download_notebooks.sh followed by ./download_notebooks.sh. Everything downstream assumes that script succeeded. This is the project's weakest seam. A Jupyter Book build that fails because a notebook is missing produces an error that points at the book configuration, not at the network fetch, so the first thing to check when a build breaks is whether the download step actually populated the chapter directories. The README does not document pinning the fetched notebooks to a commit, so a rebuild months later can pull different notebook contents than the one you reviewed. For a teaching site that is tolerable. For anything where you need the built artifact to be reproducible, it is not, and the fix has to happen in the download script rather than in the book config. There is no release history retrieved for this repository, so there is no tagged snapshot of the configuration to pair with a known-good set of notebooks.

How the build is wired: _toc.yml, _config.yml, and CI

The book structure is declared in _toc.yml and the book configuration in _config.yml, which is the standard Jupyter Book split between ordering and settings. The README points at the Jupyter Book documentation for both files rather than reproducing their contents, so the actual chapter ordering and any execution settings have to be read from the files themselves. Publishing is handled by the GitHub Action at .github/workflows/ci.yml, which the README says rebuilds the website after every commit or pull request. That means the deployed site at ml-visualized.com tracks the main branch automatically, and a change to the download script or the table of contents goes live without a manual publish step. The trade-off is that a broken external notebook can take down the site build rather than failing in a staging environment. There is no mention of a preview or staging deployment in the material provided.

Three ways to build, and what each one costs you

The README gives three local build paths. The CLI route is pip install -U jupyter-book followed by jupyter-book build ., which installs the latest jupyter-book and therefore can shift under you between builds. The Docker Compose route is docker compose run --rm jupyter-book, with cleanup via docker compose down --remove-orphans --volumes --rmi local. The plain Docker route builds from Dockerfile.book and runs it with the working directory bind-mounted into /usr/src/app, followed by docker stop, docker rm, and docker rmi. The Dockerfile is named Dockerfile.book rather than the default Dockerfile, so a bare docker build . will not pick it up. Output lands in _build/html/index.html in all three cases. The pip route is the fastest to try and the least reproducible; the Docker routes cost an image build but pin the toolchain. The EPUB path is separate and heavier: it installs MacTeX via brew install --cask mactex, merges notebooks per chapter with nbmerge, converts with jupyter nbconvert --to latex, then builds a Pandoc image from Dockerfile.pandoc and runs pandoc with --mathml --embed-resources --standalone. Note that the brew step is macOS-specific, so the EPUB instructions do not transfer to Linux as written.

Marimo notebooks and the limits of a static book

The README distinguishes two content types: Jupyter Notebooks that implement and derive the algorithms, and Interactive Notebooks built with Marimo that let you see how the weights influence the loss functions. That split matters because a static Jupyter Book page can show a rendered plot but cannot let a reader drag a weight and watch the loss move. The Marimo pieces are where the interactivity lives, and the README does not explain how they are embedded in the built book or whether they require a running kernel on the host. If you are deploying this as a static site, verify that the Marimo pages degrade to something readable when no kernel is available. The README also states that the output of each notebook is a visualization of the algorithm converging at its optimal weights, which tells you the intended reading experience is watching training progress rather than calling a function. Anyone looking for scikit-learn-style estimators will not find them here; the description says the algorithms are implemented in NumPy from first principles.

Where a different tool is the better choice

If your goal is to train a model rather than to understand one, scikit-learn is the honest alternative and the difference is not cosmetic. scikit-learn ships importable estimators with fit and predict methods, tested against a stable API, and you can pin a version in requirements.txt. This project ships a book: the algorithms are spread across seven repositories, the notebooks are downloaded at build time, and the output is HTML and optionally an EPUB. There is no package to import from this repository and no API surface to depend on. The reverse also holds. If you want derivations with the LaTeX visible next to the code, scikit-learn's documentation will not give you that, and a general notebook collection without a book build will not give you a navigable site. The choice is between a dependency and a reading artifact, and this project is unambiguously the second.

Upgrade and maintenance exposure

Two maintenance surfaces are visible. The first is the jupyter-book dependency in the pip path, which the README installs with -U and therefore floats to the latest release; the Docker paths avoid this by baking the toolchain into Dockerfile.book. The second is the set of seven external repositories, which are pulled fresh on each build with no documented pinning. Add the GitHub Action, which rebuilds on every commit or pull request, and the practical consequence is that the published site can change because an upstream algorithm repo changed, not because this repo did. There are no retrieved releases, so there is no version number to cite when reporting a problem. On licensing, the MIT terms here cover this repository's own files; the notebooks fetched by download_notebooks.sh come from other repositories with their own licence files, and the README does not state what those are. Check each one before redistributing a built book, and treat that as a factual check rather than a legal conclusion.

Editorial conclusion

Adopt it if you want a static, self-hosted site of first-principles derivations and you accept that the algorithms live in seven other repositories that this one only downloads at build time. Do not adopt it as a library, as a pip dependency, or as a source of production NumPy code: the README describes a book build, and none of the notebooks are in this repository. Before committing, run ./download_notebooks.sh and check that every URL it fetches still resolves, then build once locally with jupyter-book build . and confirm _build/html/index.html renders the LaTeX and the Marimo notebooks.

Official sources

1. gavinkhung/machine-learning-visualized on GitHub
2. Issues
3. License: MIT
4. Project website
5. README