en.javascript.info: the file conventions behind a 25,000 star JavaScript tutorial

A content repository with a rendering server kept elsewhere

The repository description is a single line: it hosts the English content of the Modern JavaScript Tutorial, published at javascript.info. Everything else follows from that division of labour. There is no build step in this repository, no site generator, no CSS pipeline. The tree is nine numbered content directories, a `script/` directory, a handful of authoring documents and two `.sketch` files.

The site itself is served from somewhere else. The README points contributors at a separate `javascript-tutorial/server` repository to preview the tutorial locally, which means the publishing system can change without a single edit here. It also means the raw markdown in this repository really is just content, and the format is described in the README as an enhanced markdown that is easy to grasp and editable in any editor.

That is a deliberate choice for a project with this reach. Contributors are not asked to install a Node toolchain, learn a templating language, or match a house style enforced by linting. They write text in files. The cost is that the enhanced markdown conventions are only documented in `AUTHORING.md`, and anything not covered there is something a contributor has to infer by reading neighbouring chapters.

Folder names are the URL, which makes renames expensive

The structural convention is stated in three lines and it explains most of the repository's shape. Every chapter, article or task gets its own folder, and the folder is named `N-url`, where `N` is a number used for sorting and `URL` is the URL part carrying the title of the chapter. The top-level directories follow the same idea at a larger scale: `1-js/`, `2-ui/`, `3-frames-and-windows/`, `4-binary/`, `5-network/`, `6-data-storage/`, `7-animation/`, `8-web-components/`, `9-regular-expressions/`.

So the numbers give ordering and the slug gives identity. A chapter on, say, timers and intervals lives in a numbered folder whose name is the address a reader visits. That has a nice property for a tutorial people link to from bug reports and Stack Overflow answers: the URL in the folder name is the URL on the site, so a link in an issue is verifiable by looking at a directory listing.

It also has an obvious cost. Renaming a chapter to improve its title is a URL change, which breaks every inbound link, and the numbering makes insertion in the middle of a section worse rather than better because it renumbers siblings. A project at this scale will accumulate folders whose titles no longer match what a newcomer would guess, which is exactly the situation the `todo.md` file at the root seems to exist for.

Three file types, and one rule that trips up new contributors

The type of material is defined by which file sits inside the folder, which is an unusually clean way to do it. `index.md` is a chapter, `article.md` is an article, `task.md` is a task, and the type does not appear in the folder name at all. Each of those files starts with a `# Main header`, so the first line of every file is the same.

The task case has the one requirement that catches people out: a task must ship with its solution, in a `solution.md` file in the same folder. The tutorial's whole pedagogy depends on the reader attempting the exercise before seeing the answer, so a task folder without a solution is not a half-finished contribution, it is a broken one. The README's confidence that it is very easy to add something new holds as long as that rule is respected.

Because the type is inferred from a filename rather than declared in metadata, there is no way to tell a chapter from an article without opening the folder. In practice the two are separated by the numbered top-level directory, so chapters cluster in the foundational sections and articles appear as supporting material inside them. That is a convention you absorb by reading the tree, not something the repository states outright.

Translations are a first-class goal, kept out of this repository

The README asks for translation help before it asks for content help, and links to a translate page for the details. This repository holds the English content only, so every other language lives somewhere else, and the English files are the source that translations are derived from rather than one peer among many.

That is the right arrangement for a project that has been running for years, because it means a translation can lag the English original without blocking it, and the English text can be rewritten without invalidating fifty other trees at once. The cost is that contributors who want to fix a translation are contributing to a different repository and may not find it from here.

The topics metadata reflects the narrow scope of this particular repository: `english`, `javascript`, `tutorial`. If you are looking for the site itself, or for the preview server, or for the translation targets, none of them are here. The README also notes that the full contributor list is published on the site rather than in a file, which is consistent with keeping the repository to content and metadata only.

Scale, activity and the open issue backlog

At 25,476 stars and 3,997 forks this is one of the most starred repositories in the JavaScript ecosystem, which is not surprising for the reference many developers describe as the free book they actually read. The last push was on 2026-07-25, and there are no tagged releases at all, which is the correct shape for a repository whose output is a website rather than a package.

The number that stands out is 542 open issues. That is a large backlog against a repository with no code to break, so the issues are content corrections, unclear explanations, and feature requests for topics that are not yet written. It is worth reading that ratio as a signal about where the project spends its attention: writing and reviewing prose takes human time, and the throughput limit is review capacity rather than authoring capacity.

The repository root also carries a few files that reveal how the project is worked on. `todo.md` is the planning document, `AUTHORING.md` holds the format rules, `BACKERS.md` records support, `css.md` exists for styling notes that the separate server consumes, and `changes.sketch` plus `svgs.zip` show that the diagrams are drawn in Sketch rather than authored as text. `script/` holds whatever automation the site needs.

Editorial conclusion

The useful thing to take from this repository is that its structure is a specification, not a convenience. Chapter, article and task are three different file shapes, the folder name is the URL, and a task without a solution file is not a valid submission. Contributors work in any editor and preview through a separate server repository, which keeps the writing free of tooling. The other number worth noticing is 542 open issues against 25,476 stars, a ratio that says the backlog is the constraint here rather than interest.

Frequently asked questions

Official sources

1. Issues
2. javascript-tutorial/en.javascript.info on GitHub
3. Project website
4. README