The Eloquent JavaScript Spanish edition keeps the Markdown as the source of truth

A translation that keeps the original toolchain

The repository is a Spanish translation of the fourth edition of Eloquent JavaScript by midudev, and the original repository it descends from is the upstream book project by Marijn Haverbeke.

What makes it more than a folder of translated text is that it inherits the original build system wholesale. The top level of the repository holds one Markdown file per chapter, numbered the way the book numbers them: 00_intro.md, 01_values.md, 02_program_structure.md, 03_functions.md, and on through 21_skillsharing.md. Alongside them are code/, epub/, html/, img/, original/, pdf/ and src/, plus the generated book.epub, book.mobi, book.pdf and book_mobile.pdf at the root.

The original/ directory is the clearest signal of how the translation was made. It holds the upstream English material, and the Spanish chapters were produced by translating from it rather than by starting a new book. That means the Spanish edition inherits the entire upstream apparatus, including the interactive code playground, the solution zips and the PDF typesetting.

The primary language of the repository is listed as HTML, which fits, because the HTML output is the artefact people actually read online. The homepage is eloquentjavascript.es.

The licence is CC BY-NC 3.0, with the code in the book also considered licensed under MIT, and the README keeps the upstream attribution intact, crediting the author and the artists behind the cover and chapter illustrations.

Markdown in, HTML PDF EPUB and MOBI out, one make target

The Makefile is where the whole pipeline shows itself, and it is short enough to read in full.

CHAPTERS := $(basename $(shell ls [0-9][0-9]_*.md) .md)

SVGS := $(wildcard img/*.svg)

all: html book.pdf book_mobile.pdf book.epub book.mobi

The first line is the important one. The chapter list is not hardcoded, it is derived from the files matching the two-digit prefix pattern, which is why the chapter filenames start with a zero. Add a chapter file and the build picks it up.

The default target builds all four published formats, and the html target is the one that matters for the web edition.

html/%.html: %.md src/render_html.mjs src/chapter.html
	node src/render_html.mjs $< > $@
	node src/build_code.mjs $<

Each chapter is rendered by a Node script that takes the Markdown file and writes the HTML, and a second script extracts the code samples from the same file. That second step is the reason the repository carries a code/ directory with solution zips for the exercises: the code that appears in the chapter is extracted from the prose and shipped as runnable files.

The client side is bundled with rollup, pulling in CodeMirror for the interactive editor along with acorn and acorn-walk for parsing the JavaScript samples so the editor can highlight them.

test: html
	@for F in $(CHAPTERS); do echo Testing $$F:; node src/run_tests.mjs $$F.md; done
	@node src/check_links.mjs
	@echo Done.

And that test target is the part most people would not expect. The book runs its own code samples. Each chapter's JavaScript is executed by a script, and a separate pass checks the links. For a book whose entire subject is code that the reader is supposed to be able to run, testing the code in the prose is the point rather than a nicety.

Four output formats, and the reason the PDF stage is separate

The four published artefacts are the PDF, a smaller PDF for phones, the EPUB and the MOBI, and they are not produced by the same route.

The HTML is the primary output and it comes from Node. The other three come from a LaTeX route, and the Makefile shows a separate tex target that depends on per-chapter .tex files and a shared hints.tex.

tex: $(foreach CHAP,$(CHAPTERS),pdf/$(CHAP).tex) pdf/hints.tex $(patsubst img/%.svg,img/generated/%.pdf,$(SVGS))

The last dependency is the part worth reading. Every SVG in img/ is converted to PDF, because LaTeX cannot embed SVG directly. So the illustrated figures in the book exist as vector source and are rasterised through a conversion step to get into the typeset pages.

That is why the PDF pipeline is a separate target rather than a flag on the HTML one. The web edition uses SVG in the browser, where it is native, and the print edition needs a PDF variant of the same artwork. The build compiles the same illustrations twice for two different consumers.

The EPUB and MOBI then come from the LaTeX output, and the epub/ directory at the top level holds the packaging for the e-reader formats.

So a contributor who edits a Markdown chapter is producing four artefacts from one source file, and the interesting engineering question is not the translation but keeping the SVG to PDF step and the LaTeX chapter splitting in step with the Markdown.

The contribution rule, and why the HTML is generated

The contribution instructions are short enough to state exactly, and the first line is a prohibition.

Do not edit the HTML files. These are generated automatically from the Markdown files.

Then the process is the usual three steps: make a fork of the repository, clone the repository to your local machine, and edit the Markdown files with your favourite text editor.

The prohibition is the whole design, and it is the right one. A book of twenty-two chapters in four output formats will drift immediately if anyone can edit the built artefacts, and the generated HTML carries the interactive code editor, the extracted code samples and the chapter metadata, none of which are things a translator should be touching by hand.

The build is also where the tooling earns its keep. The Makefile's html target depends on src/render_html.mjs and src/chapter.html, and the ejs.js bundle target depends on the CodeMirror packages, acorn, acorn-walk and the client sources under src/client/, all bundled through a rollup config at src/client/rollup.config.mjs.

The npm side is consistent with that. The dependencies are CodeMirror and the Lezer highlight packages, acorn for parsing the book's own JavaScript, rollup with the node-resolve and terser plugins, markdown-it with the sub and sup plugins for the footnote and superscript syntax the book uses, jszip for packaging the downloadable solution archives, and mold-template for the PDF templates. The dev dependencies are jsdom, promise and standard, and the test script simply delegates to make test.

One detail tells you the translation is a real fork rather than a copy: the repository field in package.json still points at the original book project, and the author field names Marijn Haverbeke, with the description reading Sources for the book Eloquent JavaScript.

Where this repository is the wrong resource

Three cases, and each is a limitation of what a book repository can be.

The first is if you want a general translation workflow. The tooling is bound to this book. The Makefile expects files named with two-digit prefixes, a src/render_html.mjs that knows how to render an Eloquent JavaScript chapter, a chapter.html template, and a rollup config for the interactive editor. None of that is general, and the JSON database of the book, which chapter each code sample belongs to, is generated from the chapter structure. You could learn from the approach, but you would be writing the pipeline yourself.

The second is if you need the code samples as a separate library. The repository carries code/ with the solutions and the skill sharing package, and the skill sharing zip is packaged as a downloadable archive from the web edition, but the code lives inside the book rather than as a versioned package you depend on. The README links the original book and the upstream repository, and for a working code project you want that one.

The third is if you want the print edition from this repository specifically. The PDF route depends on a LaTeX toolchain, the pandoc-based build in the pdf directory, and the SVG conversion step, none of which the README documents. The prebuilt PDFs are published at the links in the README, so a reader does not need to build them, but a maintainer who wants to regenerate them is left reading the Makefile.

There is a licence point to keep in view. The book is under a Creative Commons Attribution-NonCommercial licence, with the code also under MIT. That combination allows a noncommercial Spanish translation, which is exactly what this is, and it constrains what a publisher or a commercial course could do with the text without permission.

Editorial conclusion

Adopt this repository if you want to read or contribute to Eloquent JavaScript in Spanish, since it keeps the book in Markdown and regenerates every published format from it. Do not adopt it as a translation workflow for arbitrary books, because the tooling is bound to this book's structure, its code samples and its chapter naming. Verify first that the build dependencies are available in your environment, since the Makefile drives pandoc for the PDF and EPUB stages and needs the Node toolchain for the HTML stage.

Frequently asked questions

Official sources

1. Issues
2. midudev/eloquent-javascript-es on GitHub
3. Project website
4. README