mdn/content: the Markdown repository behind MDN Web Docs

What mdn/content actually is, and who it is for

This repository holds the Markdown source for MDN Web Docs, the reference documentation for HTML, CSS, JavaScript, HTTP and Web APIs. The README describes it as "an open-source, collaborative project" and says the corpus covers over 45,000 documents. The homepage field in package.json points at developer.mozilla.org, and the package description is blunt about scope: "Content of https://developer.mozilla.org".

The audience is narrower than the page count suggests. There are three groups. First, technical writers and engineers who want to fix or extend a page that already lives on MDN. Second, translators: the README states that over 35 volunteers lead localization for Chinese, French, Japanese, Korean, Portuguese, Russian and Spanish. Third, people who need the corpus itself, for search indexes, offline readers or dataset work, and who are willing to run the build tooling.

It is not a documentation framework you adopt for your own product. There is no theming layer, no plugin API and no generic content model. The files are MDN's pages, and the rendering is MDN's rendering.

How the Markdown becomes a site: Rari, Fred and the files/ tree

The repository is split between prose and machinery. The files/ directory holds the Markdown pages. scripts/ and tests/ hold the tooling that checks them. front-matter-config.json, .markdownlint-cli2.jsonc and .prettierrc.json define the shape a page must have before it is accepted.

The build is delegated to two external projects, and package.json is explicit about it. The build script runs a helper named info:rari, which prints a notice pointing at github.com/mdn/rari, then invokes rari build with CONTENT_ROOT set to files and BUILD_OUT_ROOT set to build. A second script, content, calls rari content with CONTENT_ROOT=files. The info:fred script points at github.com/mdn/fred, a separate project, so the toolchain is not self-contained in this repository.

One consequence is worth stating plainly: reading this repository tells you the input format, not the output. The page templates, routing and client-side behaviour live in Rari and Fred, which are separate codebases. If you want to know why a page renders a particular way on developer.mozilla.org, this is the wrong repository to open.

Installing mdn/content and previewing a page locally

The README gives the setup in four commands. Node.js is required, and npm ships with it. Check both are present first, because package.json pins engines to node >=24 and the packageManager field to [email protected], with devEngines requiring npm >=11.8.0. An older Node will not satisfy the engine constraint.

node -v
npm -v

If those print a version of Node 24 or later and an npm of 11.8.0 or later, install the dependencies. The README uses the short form:

npm i
npm start

The README states that once started, a live preview is available at http://localhost:5042/. That is the port the local preview listens on; it is not a configurable value in the repository files.

For a first real use, pick a page under files/ and edit its prose, then reload the preview. Before opening a pull request, run the front matter linter, which the repository exposes as a script and which can also rewrite files in place:

npm run lint:fm
npm run fix:fm

The linter reads front-matter-config.json, so a page that fails usually has a missing or malformed key rather than a prose problem. There is a separate filecheck script for structural checks across the tree:

npm run filecheck

The front matter contract and the linters that enforce it

Every page under files/ carries front matter, and the repository treats it as a schema rather than a convention. front-matter-config.json is the source of truth, and scripts/front-matter_linter.js validates against it. The npm run fix:fm script runs the same linter with --fix, which is the practical way to repair a batch of pages after a schema change.

Markdown itself is constrained from two directions. .markdownlint-cli2.jsonc configures markdownlint-cli2, and the fix:md script chains it with Prettier: markdownlint-cli2 --fix "**/*.md" followed by prettier --write --cache "**/*.md". The README carries a comment explaining why reference-style links are used in its own text, citing the fqdn-moz-links lint rule and two pull requests. That detail matters for contributors: link style is linted, and a normal inline link to a Mozilla domain can fail the check.

There is also a pre-commit path. .lefthook.yml configures lefthook, and npm run fix:pre-commit runs the hooks manually. The practical effect is that a contributor can pass their own review and still fail CI, because the hooks and the CI linters are configured separately and only one of them runs on save.

Where mdn/content is the wrong tool

The most common mistake is treating this as a general-purpose docs site. It is not. The build output goes to a directory named build via Rari, and the site that readers see is assembled by MDN's own stack. There is no supported path in this repository for deploying the corpus under a different domain with your own navigation, search or versioning.

The second limitation is the licence. package.json declares "license": "SEE LICENSE IN LICENSE.md", and the repository metadata reports the licence as NOASSERTION, meaning no standard SPDX identifier was detected. Anyone planning to redistribute the corpus, mirror it commercially or ship it inside a product needs to read LICENSE.md directly. The README says nothing about redistribution terms, and neither does the package metadata beyond the pointer.

Third, there are no releases. The repository has no release history to pin against, so "which version of mdn/content should I depend on" has no clean answer. Consumers pin a commit, and a commit is a moving target for a corpus that changes daily.

Finally, the toolchain is not self-contained. Because the build calls Rari and the info scripts point at Rari and Fred, a change in either external project can alter your local build without any commit landing in this repository.

Alternatives, and how they differ in approach

The closest alternative in spirit is a docs-as-code framework such as Docusaurus or MkDocs. The difference is architectural, not cosmetic. Those tools own the whole pipeline: you install one package, configure a theme, and the site is yours to deploy anywhere. mdn/content owns only the content and the checks; the rendering lives in Rari and Fred, which are separate repositories, and the deploy target is developer.mozilla.org. If you want to control the output, you want the framework, not this repository.

A second alternative is to consume MDN as a service rather than as source. The homepage field points at developer.mozilla.org, which serves the rendered documentation, and the README describes the project as a resource for web developers worldwide. Reading the site requires no Node install, no npm i and no 45,000-file checkout. The trade-off is that you cannot edit, diff or build from it, and you have no local copy when you are offline.

A third path is a documentation dataset derived from MDN rather than the repository itself. Those exist for search and training use, but they are downstream artifacts: they inherit whatever the licence permits and whatever the extraction got wrong. Starting from mdn/content at least keeps you on the primary source.

Maintenance cost and what to check before you depend on it

The repository is not archived, and the last push was on 2026-09-21. That is the only maintenance signal available: there are no releases to track and no changelog in the repository. A corpus that changes daily means your fork diverges quickly, and a long-lived fork of 45,000 documents is expensive to rebase.

Upgrades are a different problem from most dependencies. There is no version number to bump. What changes is the front matter schema, the lint rules and the Rari build contract. The engines field pins Node to >=24, and packageManager pins [email protected], so the runtime floor moves with the repository. When front-matter-config.json gains a key, every page that lacks it fails npm run lint:fm, and npm run fix:fm is the bulk repair.

On licensing, the only accurate statement is procedural: package.json points at LICENSE.md and the metadata reports NOASSERTION. Read that file before you mirror the corpus, and treat the absence of an SPDX identifier as a question to answer, not a permission to assume. This is not legal advice, and the distinction between contributing a page upstream and redistributing the whole corpus is exactly the kind of thing a lawyer should look at.

Editorial conclusion

Adopt mdn/content if you are writing reference documentation for web platform features and want it published on MDN, or if you need to mirror the corpus and build it with Rari. Do not adopt it as a general documentation platform for an internal API, a product manual or a marketing site: the build pipeline is wired to MDN's own rendering, and the licence is not a standard SPDX identifier that a legal review can clear in one pass. Before committing, verify three things: that Node 24 or later is available in your environment, that the front matter in your pages passes npm run lint:fm, and what LICENSE.md actually permits for your redistribution plan.

Frequently asked questions

Official sources

1. Issues
2. mdn/content on GitHub
3. Project website
4. README