npm/documentation: the MDX source behind docs.npmjs.com

Two deliverables in one repository: content and workflows

The npm documentation repository is the content for docs.npmjs.com, and it also contains the GitHub Actions workflows that generate the site itself. Both statements matter, because the second one is the part most people do not expect. This is not a static dump of markdown that someone else builds; the machinery that turns the MDX into the published site lives here, in .github/.

The project documentation frames it as documentation for the npm registry, the website and the command-line interface, and the primary language is recorded as MDX. The homepage of the published site is docs.npmjs.com, and there is a publish workflow badge at the top of that file pointing at the publish.yml workflow.

The topic list carries a single entry, npm-cli, and there are no GitHub releases. The repository is not archived and the last push was on 2026-10-16.

The tree gives the layout. There is content/ for the documentation content, src/ for the site source, static/ for static assets, scripts/ for build scripts, cli/ as a workspace, a gatsby-config.mjs, gatsby-node.mjs and gatsby-ssr.js, a webpack.config.js, and a .reuse/ directory which is the REUSE specification metadata for the licensing setup. There is also CONTENT-MODEL.md, which is the file to read before writing a page, and cli-cache.json, which is a data file for the CLI pages.

The quick start is seven steps and Gatsby does the watching

The readme gives the local workflow as seven numbered steps, and the order matters because the first one pulls down the toolchain and the second one starts the thing.

The first step is `npm install`, which downloads gatsby, the theme and the dependencies. The second is `npm run develop`, which starts the test server at http://localhost:8000. The third is to update the content, and the instructions are specific that the content is Mdx, which is like markdown, in the content directory.

The fourth step is to review at the same localhost address, with a note that Gatsby watches the filesystem and will reload content changes immediately. That is the practical point of the whole loop: you do not restart anything to see a text change, which is what makes editing a documentation page a quick cycle rather than a slow one.

The fifth step is to commit and open a pull request at the npm/documentation repository on GitHub. The sixth is that a CI workflow run will publish the pull request to a GitHub Preview Page. The seventh is that once the content is reviewed, merging the pull request will deploy the site, and the publish workflow is linked for that.

So the reviewer experience is built in: a pull request gets its own preview URL before anyone merges it, and the same workflow that publishes previews publishes the site. The contributing guide in CONTRIBUTING.md is where the details beyond these seven steps live.

A Gatsby site with a Primer theme, not a hand-rolled renderer

The dependency list explains what kind of site this is. Gatsby is at version 5.16 or above, with gatsby-plugin-mdx for the MDX pipeline, gatsby-plugin-manifest, gatsby-plugin-meta-redirect and gatsby-plugin-postcss. The rendering layer is @primer/react, the design system GitHub uses, along with @primer/octicons-react for icons and framer-motion for animation, with styled-components compiled through babel-plugin-styled-components. The search is fuse.js and the select behaviour is downshift.

So the visual language of docs.npmjs.com is Primer, which is why the site looks like it does rather than because of custom CSS work. That is a deliberate trade for a documentation site maintained by a small team: the design system is maintained elsewhere and the cost here is a dependency.

The script section of package.json is worth reading, because it explains the build shape:

    "develop": "npm run gatsby -- develop",
    "develop:ssr": "GATSBY_DEV_SSR=true npm run develop",
    "build": "npm run gatsby -- build --verbose --log-pages",
    "clean": "npm run gatsby -- clean",
    "serve": "npm run gatsby -- serve",

The gatsby script sets PARCEL_WORKERS=0 for every invocation, and the package.json itself points to a Parcel issue explaining why. The develop:ssr variant turns on GATSBY_DEV_SSR, so there is a server-side rendering path for local development, and the build passes --verbose --log-pages, which is what you want when a page is missing from the output. The lint script is eslint over js, mjs and mdx files, the test script is jest, and the posttest hook runs lint, so a passing test run that fails lint still fails the command.

The CLI is a workspace, and the docs are shipped with it

The package.json declares a workspaces array containing cli/, and there are matching scripts that fan out across workspaces. test-all runs the test command with --workspaces --include-workspace-root --if-present, and lint-all does the same for lint, with the --if-present flag meaning a workspace without that script is skipped rather than failing the run.

That is the shape of a monorepo that keeps the command-line interface documentation next to the code the documentation describes. The cli/ directory in the tree, the cli-cache.json file and the npm-cli topic all point the same way.

The linting setup has two layers that are easy to miss. The lint script is eslint over js, mjs and mdx, and a postlint hook runs template-oss-check, while template-oss-apply is the counterpart that applies the same checks. That is a template enforcement mechanism: rather than relying on reviewers to notice a deviation from npm's own project template, a check runs after lint and fails.

The testing stack is jest, with jest.config.js, jest-setup.js and jest-preprocess.js at the root, plus a preprocessor for the MDX. There is also a .eslintrc.js alongside an .eslint.config.js, which is the flat config and the legacy config coexisting during a migration, and a .prettierrc.js with a .prettierignore for formatting. The format and format:check scripts run prettier over the whole repository.

The .nvmrc file pins the Node version, which matters for a site build with this many dependencies, and the .npmrc carries the registry configuration for the workspace setup.

CC-BY 4.0 for the prose, MIT for the code

The licence arrangement is the clearest thing in the repository, and it is a split rather than a single grant. The npm product documentation in the content and the static folders are licensed under a CC-BY 4.0 licence in the LICENSE file. All other code in the repository is licensed under an MIT licence in the LICENSE-CODE file. There is also a LICENSES/ directory, which is the REUSE convention for keeping licence texts alongside the files they cover, and the .reuse/ directory holds the metadata that ties it together.

The practical reason for the split is that the two halves are used differently. The content is prose that people read, and a Creative Commons attribution licence is the conventional choice for documentation. The code is the site generator, and MIT is the conventional choice for that. If you contribute a page, your work lands under CC-BY 4.0; if you contribute a build script, it lands under MIT.

One instruction sits alongside the licences: when using the GitHub logos, be sure to follow the GitHub logo guidelines. That is the one place in the repository where the content depends on a third party's trademark rather than a licence, and it is the one rule a contributor is most likely to trip over by copying an image from the site into a new page.

The project also has a CODE_OF_CONDUCT.md and a SECURITY.md, and the SECURITY.md is a sign that a site with a public preview pipeline treats reports as something to be routed rather than filed on the tracker.

Where this repository is the wrong place to look

The first limit is that this is not the npm registry, the npm website or the npm CLI implementation. It is the documentation for all three. The description says so, and the tree backs it up: there is a cli/ workspace for the CLI documentation, but the CLI's own source is not here. A question about how the CLI behaves is a question for the CLI code and its own issue tracker.

The second limit is the pull request workflow. Every content change goes through a review and a CI run, and the site is deployed from the merge. That is the right process for the official documentation, and it is a slower path than editing a wiki. If you want to fix a typo in a public package's README, this is the wrong repository.

The third is the toolchain weight. A local run needs Gatsby, a theme and a dependency tree, and the gatsby script explicitly disables Parcel workers, which is a workaround for a known issue rather than a default. The first npm install of a fresh clone is the slow part of every contribution, and it is the reason a text-only change needs a build environment rather than a text editor.

The fourth is that the content model is not plain markdown. The project documentation says the content is Mdx, which is like markdown, and there is a separate CONTENT-MODEL.md that describes the model. Mdx means JSX inside the document, which is what lets a page embed a live component such as a CLI reference or an interactive example, and it also means the content has to be valid JSX. A contributor who writes markdown by habit will hit that, and the content model document is where the rules are.

The fifth is that the published site is a snapshot, not a live view of the registry. Whatever the documentation says about a package or a flag was true when the page was written, and the site has no mechanism described here for keeping it in step with the code it describes.

Editorial conclusion

npm documentation is the right repository for anyone who has found an error in the npm documentation and wants it fixed, because the content is MDX in a content/ directory and a pull request is reviewed and published through a CI workflow that gives you a preview page. It is the wrong place to look for the npm registry, the CLI implementation or the package publishing machinery, since the repository is a Gatsby site and the CLI is only present as a workspace. Before you open a pull request, check the three things the repository states for itself: that the product content and the static folders are CC-BY 4.0 while all other code is MIT, so you know which licence your contribution lands under; that the content is MDX rather than plain markdown and follows the model described in CONTENT-MODEL.md; and that the local workflow is npm install followed by npm run develop on http://localhost:8000, with the build and publish steps run by GitHub Actions rather than by you.

Frequently asked questions

Official sources

1. Issues
2. License: CC-BY-4.0
3. npm/documentation on GitHub
4. Project website
5. README