One XML source, three editions of SICP, and a test suite for the book

The pipeline is the product

The repository contains processing scripts and sources for Structure and Interpretation of Computer Programs, adapted from the original Scheme edition into JavaScript and Python, and it also publishes the original Scheme edition on its own. The structure follows the pipeline, with the XML sources under `xml/` and `xml_py/`, and then one output directory per format: `html_js/`, `html_split_js/`, `html_split_py/`, `latex_pdf_js/`, `latex_pdf_py/`, `latex_epub/`, `md_js/`, `md_py/`, `md_scm/`, and the JSON content under `json_js/`, `json_py/` and `json_scm/`. The `programs_js/`, `programs_py/` and `programs_scm/` directories hold the book's example code, one file per snippet, and the `javascript/` directory holds the processing code itself, with `scripts/` holding the shell scripts that orchestrate the steps.

One script produces every artefact

The package manifest makes the pipeline legible, because every output has a named command. The `all` script runs the whole chain, `yarn pdf && yarn split && yarn programs && yarn json`, and each of those is itself a wrapper. `yarn pdf` calls a shell script, `yarn split` runs the process with the `web split` arguments, `yarn programs` and `yarn json` call `yarn process` with a different target, and `yarn md` produces the Markdown export. There is a `yarn process` entry point that runs a TypeScript file directly with tsx, a `yarn svgpdf` script that converts SVG to PDF through a shell script, and a `yarn clean` that delegates to the same script directory. The `yarn prepare` hook runs before publishing, and the package is pinned to yarn 1.22.22 by hash, which is the reproducibility pattern that a book build needs.

Search and navigation are fetched at runtime, on purpose

The interactive editions have a design decision that is easy to miss and easy to break. The frontend fetches the table of contents and the previous and next navigation JSON at runtime, the same way it fetches section content and search data, and the README states plainly that it must not snapshot these into its own repository, because the published chapter range can shrink or grow independently of a frontend release. The mechanism for the search buttons is the same: the frontend's Text Search and Index Search buttons fetch a search data JSON file from the public static host rather than from the Source Academy backend, and filter it locally. The reason is a deployment one, since a static file host has no query interface to call. The search data is generated by `yarn json` as part of the pages deployment workflow, which runs on every push to master.

The book examples are a test suite

The example programs in each edition can be tested automatically against their expected outputs, and the CI workflow runs all three editions on every push and pull request. The test command runs through js-slang by default, and you can scope it to a folder:

yarn test
# scoped to a folder:
yarn test -- programs_js/chapter1

The alternative is to run natively on Node using the `sicp` npm package, the JavaScript analogue of the Scheme package, which re-exports js-slang's predeclared primitives such as pair, head, tail and the math functions as plain functions, generated from the js-slang repository. The difference is gating, since js-slang exposes only what the current chapter needs while the `sicp` package exposes everything unconditionally. Only SICPy chapters 1 to 3 against CPython are a required CI check today, and everything else runs informationally with continue-on-error, either because the interpreter is unproven infrastructure or because the content is not finished.

The Python edition has an extra layer

SICPy needs a generation step before its programs exist. The programs are produced from the XML sources with an environment variable selecting the edition:

SICP_EDITION=py npx t

The Python side of the pipeline uses py-slang as the interpreter package, and the manifest lists it as a dev dependency along with js-slang for the JavaScript side, plus xmldom and xpath for the XML processing, fs-extra for file operations, hono and http-server for serving, and lz-string for the compression the JSON payloads use. The dependency on a Python interpreter is a consequence of the design: SICPy runs the book in a Scheme-like Python dialect, so the programs are Python source that a custom runtime evaluates rather than plain Python that CPython runs.

The chatbot knowledge base is generated by hand, not by the build

One directory does not follow the pipeline rules, and the README is explicit about it. The `chatbot_notes_py/` directory is a knowledge base for retrieval-augmented-generation question answering over SICPy, and unlike the editions above it is not autogenerated by the XML build pipeline. It is AI-generated on demand, not by any pipeline in the repository, and checked into git directly, regenerated only for major revisions of the book. Each chapter has two files. The first is an Elixir module, `Cadet.Chatbot.SicpyNotesWithIndex.Chapter<N>`, with one summary module attribute per section or subsection, each an original bullet-point summary of that section followed by a key terms line drawn from the book's own back-of-book index. The second is a JSON lookup mapping terms to section numbers, built from the same index entries, for keyword-based retrieval alongside embedding-based search.

Why Scheme is the anchor rather than a third peer

The comparison edition is where the design shows. There is a Scheme versus JavaScript comparison and a Scheme versus Python comparison, and there is no Scheme versus Scheme comparison, because the README explains that Scheme is the comparison anchor the other two editions are diffed against, so a Scheme versus Scheme comparison would be nonsensical. The original Scheme edition has the PDF, the structured per-section JSON content including the generated search data, the source code archive and the Markdown export, but its JSON is not yet wired up to a live interactive frontend, unlike the JavaScript and Python editions. That asymmetry is a useful signal about where the remaining work sits. The platform requirement is also split: generating the JSON edition and extracting the programs works on any platform with Node.js, while generating the PDF edition and running the full build require Unix or macOS, and Windows users are pointed at WSL. The licence is CC-BY-SA 4.0 for the book content, with the tooling package under Apache 2.0.

Editorial conclusion

Adopt this repository if you want to read SICP in the browser with working examples, or if you maintain the book's tooling, since the XML source and the generation pipeline are the canonical artefacts here. Do not adopt it as a JavaScript textbook with runnable code, because the examples are tested through js-slang rather than in your own Node project by default. Verify first that your platform can run the parts you need, since the JSON generation and program extraction work anywhere with Node but the PDF edition and the full build need Unix or macOS, and check the SICP JS preface for what the JavaScript adaptation changed.

Frequently asked questions

Official sources

1. License: CC-BY-SA-4.0
2. Project website
3. README
4. Releases
5. source-academy/sicp on GitHub