Eloquent JavaScript: what the repository actually contains

The repository is a book toolchain, not a JavaScript package

The npm package is named Eloquent-JavaScript and its description field reads "Sources for the book Eloquent JavaScript". That is the whole scope. The top level holds twenty-two chapter files numbered 00_intro.md through 21_skillsharing.md, plus code/, epub/, html/, img/, pdf/ and src/. There is no exported module, no CLI binary and no runtime component that a reader would install into an application.

The audience is correspondingly narrow: translators, contributors filing issues or pull requests, and people who want to regenerate one of the output formats themselves. The README says feedback is welcome in the form of issues and pull requests, which is the contribution path the author states. If you arrived looking for the book's contents, the README points at eloquentjavascript.net, and the HTML output lives in the html/ directory of the repository.

How the Markdown chapters become HTML, EPUB and PDF

The Makefile drives everything. A variable collects the chapter list from the numbered Markdown files, and each html/%.html target runs two Node scripts in sequence: src/render_html.mjs reads a chapter file and writes HTML to stdout, then src/build_code.mjs processes the code associated with that chapter. A separate target generates html/code/chapter_info.js from the chapter files and the code/solutions directory via src/chapter_info.mjs.

The interactive code editor is bundled rather than hand-written. A rollup target takes CodeMirror packages, acorn, acorn-walk and the modules under src/client/ and produces html/ejs.js. The dependency list in package.json reflects that: markdown-it with the sub and sup plugins for parsing, mold-template for templating, jszip, mime, and the CodeMirror 6 family. Two zip artifacts are built as well, one for the skillsharing project in chapter 21 and one for a chapter 20 solution.

The test target is the part worth noting. It depends on the HTML build, then loops over every chapter running node src/run_tests.mjs on each, and finishes with node src/check_links.mjs. So the book's code examples are executed as part of the build, and the links in the prose are checked. That is a real constraint on contributors: a chapter edit that breaks a listing will fail the build.

Building the HTML output from a fresh clone

The README gives the install and build steps directly. Run npm install to fetch the dependencies, then make html with GNU make. The output lands in html/, one file per chapter plus the bundled editor and the generated chapter_info.js.

npm install
make html

After this, html/ should contain a rendered page for each chapter, named after the source file, along with html/ejs.js and html/code/chapter_info.js. To run the chapter tests and the link checker on the result, the package.json test script calls make test, which rebuilds the HTML first and then executes src/run_tests.mjs against every chapter file before src/check_links.mjs runs.

npm test

The README is explicit that the PDF path is a different matter. It says not to bother trying unless you really need it, since the list has probably bitrotted and getting it all set up is a pain. The listed packages are texlive, texlive-xetex, fonts-inconsolata, fonts-symbola, texlive-lang-chinese and inkscape, followed by make book.pdf. The Makefile's all target goes further and also names book_mobile.pdf, book.epub and book.mobi.

Translating the book, and the size problem the README states

The README treats translation as a first-class use of the repository and describes the workflow. Fork the repository, open an issue describing your plan, translate the .md files in your fork, and publish the result or ask the author to host it. It notes that the license permits non-commercial derivations, which includes open translations, and that continuing someone else's abandoned translation is acceptable because the license carries over.

The warning attached to that workflow is concrete: the text is about 130,000 words and the paper book is 400 pages. The README calls that a lot of text which will take a lot of time. It also suggests omitting the index terms, marked with double parentheses and {{index ...}} syntax, since those mainly matter for print output.

One restriction is stated plainly rather than left to inference: the author is not interested in machine translations and asks to be contacted about a translation only when it was done by actual people. The stated reason for doing the work in public, with an issue linking to it, is to avoid several people starting the same language and possibly never finishing.

Where this repository is the wrong tool

The most common mistake is treating it as an installable learning environment. Nothing here runs a course, tracks progress or serves exercises. The interactive editor is a build artifact assembled from CodeMirror and the src/client modules; it is not published as a reusable package under this name.

The second mismatch is the PDF build. The README itself discourages it, and the Makefile's all target depends on book.pdf, book_mobile.pdf, book.epub and book.mobi, so a bare make attempts the whole chain. If you only need HTML, targeting make html avoids the LaTeX and Inkscape dependencies entirely.

The third is licensing. The package.json license field reads CC BY-NC 3.0. The README describes the license as allowing non-commercial derivations and says translations have to retain it. That is a boundary on reuse, not a permissive software license, and anyone planning to sell a derivative or embed the text in a commercial product should read the terms rather than assume the repository's public availability settles the question. This article does not give legal advice; the license text is the authority.

The fourth is maintenance expectations. The last push to the default branch was on 2026-07-28. That is recent, but the repository carries no releases, and the README's own PDF warning shows that at least one part of the toolchain is expected to drift out of date between edits.

Eloquent JavaScript versus JavaScript: The Definitive Guide and javascript.info

The nearest alternatives are other ways of learning the language, and the difference is mostly in form. JavaScript: The Definitive Guide is a reference work: broad, organized for lookup, and structured so you can find a specific API or behaviour rather than follow a narrative. Eloquent JavaScript is a teaching text with a single authorial voice, and its repository exists precisely because that text is written as connected chapters that build a project across the book, which is why the code directory and the per-chapter test runner matter here.

javascript.info takes a third approach: a web-native tutorial site. Its unit of publication is the page, and updates ship as pages change. Eloquent JavaScript's unit of publication is the chapter file, and updates ship by rebuilding the whole book through the Makefile. That difference decides which repository you want to fork. If your goal is translating or auditing a fixed body of text with a build pipeline attached, this one fits. If your goal is a continuously updated site of independent articles, this structure works against you, because every change runs through the chapter numbering and the full HTML build.

Editorial conclusion

Adopt this repository if you maintain a translation, want to run the book's automated chapter tests against the code listings, or need to regenerate the HTML and EPUB yourself. Do not adopt it if you want a JavaScript library, a tutorial framework or a course platform; there is nothing here to import. Before forking, check the CC BY-NC 3.0 terms in package.json against your intended use, and read the Makefile targets for the format you actually need, because the PDF path carries an explicit warning that its toolchain has bitrotted.

Frequently asked questions

Official sources

1. Issues
2. marijnh/Eloquent-JavaScript on GitHub
3. Project website
4. README