# One XML source, three editions of SICP, and a test suite for the book > The source-academy/sicp repository holds the XML sources of Structure and Interpretation of Computer Programs and the scripts that turn them into the Scheme original, a JavaScript adaptation and a Python adaptation, each with a PDF, an interactive edition and a single file Markdown export. It also runs the book's example programs against their expected outputs in CI. **source-academy/sicp** — XML sources of SICP and SICP JS, and support for generating Interactive SICP JS, PDF, e-book and comparison editions - Repository: https://github.com/source-academy/sicp - Website: https://sourceacademy.org/sicpjs - Stars: 1,026 · Forks: 147 - Language: JavaScript - License: CC-BY-SA-4.0 - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/source-academy-sicp ## 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: ```bash 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: ```bash 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`, 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. ## 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. ## FAQ ### What does the source-academy/sicp repository contain? It contains processing scripts and the XML sources of SICP, adapted from the original Scheme edition into JavaScript and Python, and it also publishes the original Scheme edition on its own. The outputs include PDF editions, interactive editions, comparison editions, source code archives and single-file Markdown exports. ### How do I generate the JSON edition and the programs? The `yarn json` command generates the structured per-section JSON content and the search data, and `yarn programs` extracts the example programs from the book. Both work on any platform with Node.js, while the PDF edition and the full build require Unix or macOS. ### How are the book's example programs tested? Each edition's programs are tested automatically against their expected outputs via `scripts/test.js`, and CI runs all three editions on every push and pull request. Only SICPy chapters 1 to 3 against CPython are a required check today, with the rest running informationally. ### What is the SICPy chatbot knowledge base? It is a retrieval-augmented-generation knowledge base over SICPy, published alongside the other editions. It is not autogenerated by the XML build pipeline but generated on demand and checked into git, with per-chapter Elixir modules of section summaries and JSON term lookups for keyword-based retrieval. ### Why is there no Scheme comparison edition? 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 Scheme edition has a PDF, structured JSON content, a source archive and a Markdown export, but its JSON is not yet wired to a live interactive frontend. ## Sources - [License: CC-BY-SA-4.0](https://github.com/source-academy/sicp/blob/master/LICENSE) - [Project website](https://sourceacademy.org/sicpjs) - [README](https://github.com/source-academy/sicp/blob/master/README.md) - [Releases](https://github.com/source-academy/sicp/releases) - [source-academy/sicp on GitHub](https://github.com/source-academy/sicp) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/source-academy-sicp