# babel/website: Where the Babel Documentation Actually Lives

> The Babel website repository holds the documentation for every Babel package in one place, built with Docusaurus and published per branch to babeljs.io and its versioned subdomains. It suits anyone who wants to fix or extend the Babel docs rather than only read them.

**babel/website** — :globe_with_meridians: The Babel documentation website

- Repository: https://github.com/babel/website
- Website: https://babeljs.io/docs/en/index.html
- Stars: 777 · Forks: 1,390
- Language: TypeScript
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/babel-website

## One repository holds the docs for every Babel package

The repository is the source for the babeljs.io website, and the readme invites people to suggest changes to the docs. The important structural fact is where the documentation lives now: to keep documentation in sync across all of Babel's packages, the docs are directly located in this repository. The READMEs in babel/babel are auto generated by a script in that repository and point to this documentation. That is a reversal of the arrangement most projects use, where the docs live next to the code and the website pulls them in. The consequence is that a documentation change is a change in a website repository, reviewed by people who review the site, and a code change does not need to carry its docs along with it. It also means the website repository is a large TypeScript project rather than a folder of Markdown, because it holds the whole site infrastructure.

## One branch, one deployed site

The readme carries a short table mapping branches to websites, and it is the clearest statement of the deployment model. The main branch goes to babeljs.io, the 7.x branch goes to v7.babeljs.io, and the 6.x branch goes to v6.babeljs.io. Each major version of Babel therefore has its own branch in the documentation repository and its own deployment, so a doc fix for an old release can be made without touching current documentation and without a versioning scheme inside a single site. The repository root holds a CNAME file, which is the usual custom domain configuration for a static host, and a _redirects file, which is the Netlify-style redirect table, copied into the build output by a script. The older branches are separate deployments rather than a version dropdown, which keeps each site's build simple at the cost of duplicating the site scaffolding per branch.

## Setting up the site locally with Node and Yarn 1

The setup instructions are specific about versions, which is what you would expect from a project that still pins Yarn 1. Node has to be installed at version 20.5.0 or up, and you can check it with `node -v`. Yarn must be version 1.19.0 or newer. Then you clone and bootstrap.

```shell
git clone git@github.com:babel/website.git
yarn && yarn bootstrap
```

The bootstrap script is not just an install, because the package manifest shows it running the sponsors download script and then the build, so the first run fetches data and produces a site. After that, `yarn start` is the command to use, and the readme points you at the package.json scripts to see the rest. The repository also carries a .node-version file and a .yarnrc.yml, so the toolchain versions are recorded in the tree rather than left to the developer's machine.

## Docusaurus, the site scaffold, and where the content sits

The website is built with Docusaurus, and the readme tells contributors to get familiar with it before making significant changes. The dependency list confirms the choice and the version, with @docusaurus/core, the classic preset, the faster package and the remark npm2yarn plugin all at 3.9.2, alongside @mdx-js/react, React type definitions and eslint with the React plugin. The layout matches what you would expect from a Docusaurus project: a docs/ directory for the Markdown content, a website/ directory holding the site itself including its own package.json and its own dependency install, scripts/ for the Node scripts the build calls, and a top-level package.json for the workspace. The build script moves into website, installs there, and builds into a babel output directory, which is why there are two package manifests in one repository.

## The lint that acts as the test suite

There is no unit test suite, and the test script is a documentation lint instead.

```bash
remark docs README.md --quiet
```

The remark configuration in the package manifest is where the house style lives. The recommended preset is on, and a set of individual rules are turned off: list item indentation, blockquotes without a marker, inline padding, literal URLs and list item bullet indent are all allowed, while duplicate headings within a section and empty URLs are errors. That is a telling set of choices. Duplicate headings in a section are prohibited because the site generates anchors from them and duplicates break navigation. Literal URLs are allowed because Babel's docs are full of them, in code blocks and in prose. Running this lint is how you check a documentation change, which reframes what a test failure means in this project: the failure is a style rule, not a behaviour.

## The build scripts that pull in live data

Two scripts are worth noticing because they make the site depend on data outside the repository. The bootstrap step runs a sponsors download script, node ./scripts/download-sponsors.js, which fetches the sponsor list that the site renders. The version script runs a generate-repl-past-versions script and then stages the generated file with git add, which is the past-versions.json in the repl component. The repl is the in-browser Babel playground, and the list of past versions it offers has to be regenerated when a new Babel release ships, which is why that generation is wired into a version script rather than being a manual step. The build also produces the redirects, copying the _redirects file into the built output with fs.cpSync, so the redirect table travels with the build rather than being configured on the host.

## Where to ask, and what a contribution looks like

Support for contributing goes to the Babel Slack community, in the #website channel, with a direct link to the channel messages as an alternative. The repository also carries a .husky/ directory, and the manifest has husky as a dependency, so there is a git hook layer on top of the lint. The licence is MIT and the project publishes no GitHub releases, which is what you would expect for a repository whose output is a website deployed from a branch rather than a distributed package. The site itself is versioned by branch, and the main branch is the one people read by default at babeljs.io. For anyone evaluating the project, the practical test is small: clone it, run the bootstrap, start the dev server, and change a page to see the loop you would be working in.

## Conclusion

babel/website fits a developer who wants to correct a Babel documentation page, explain a new plugin option, or translate a doc page, since the docs and the site that renders them sit in the same repository. It is the wrong place to look for Babel itself, because the compiler lives in babel/babel, and the wrong place if you want a local Babel playground, since the repl served here is only part of the site. Before you open a pull request, read the contribution channels and run the remark lint the test script uses, since that lint is what the project treats as a test.

## FAQ

### Where does the Babel documentation live now?

The docs are directly located in the babel/website repository, so that documentation stays in sync across all of Babel's packages. The READMEs in babel/babel are auto generated and point to this documentation.

### How do I set up the Babel website locally?

You need Node 20.5.0 or newer and Yarn 1.19.0 or newer. Clone the repository, then run yarn and yarn bootstrap to install and build, and use yarn start afterwards. The repository also records the toolchain in .node-version and .yarnrc.yml.

### How are different Babel versions documented?

Each major version has its own branch and its own deployment, with main mapped to babeljs.io, 7.x to v7.babeljs.io and 6.x to v6.babeljs.io, so older documentation is a separate site rather than a version switch inside one site.

### What does the test script for the Babel website do?

There is no unit test suite. The test script runs remark over the docs directory and the README with a set of lint rules configured in the package manifest, which prohibits duplicate headings within a section and empty URLs while allowing literal URLs and several list and blockquote styles.

### Where can I ask for help contributing to the Babel docs?

The Babel Slack community, in the #website channel, with a direct link to the channel messages. The repository also uses husky for git hooks and MIT as the licence.

## Sources

- [babel/website on GitHub](https://github.com/babel/website)
- [Issues](https://github.com/babel/website/issues)
- [License: MIT](https://github.com/babel/website/blob/main/LICENSE)
- [Project website](https://babeljs.io/docs/en/index.html)
- [README](https://github.com/babel/website/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/babel-website