prometheus/docs: the Next.js site and doc pipeline behind prometheus.io

One repository holds both the words and the site that publishes them

The prometheus/docs repository contains both the content and the static-site generator code for the Prometheus documentation site and the associated landing pages, and the published result is prometheus.io.

The implementation is a Next.js website with custom code to integrate documentation from other repositories and to fetch information about available Prometheus component downloads from GitHub. The project is written in TypeScript, and the package.json names it prometheus-next, which is a hint about how the site is put together.

There are two audiences with different interests. For an engineer reading the documentation, this is invisible infrastructure: the site is the Prometheus website, and the repository is how it happens. For a contributor, the repository is the place where the shape of the documentation is decided, along with how it is built and how it is searched.

The content side is more than prose. The docs directory holds the main documentation contents, and there is a separate blog directory, a public directory for static assets, a scripts directory holding the pre-build fetchers, and an openmetrics-spec-tests directory that sits next to the specification it tests. The stack is visible in the dependencies: react-markdown with remark and rehype plugins, shiki for syntax highlighting, gray-matter for frontmatter, Mantine for the component layer, and octokit for the GitHub API calls the pre-build scripts make.

The site assembles docs from three repositories at build time

The most distinctive mechanic is that the published documentation is not all in this repository. The README states that the documentation hosted on the website is pulled together from multiple repositories.

The main documentation contents live in the docs directory here. Documentation about the Prometheus server is maintained in the Prometheus server repository and cloned into the website at build time. Documentation about the Alertmanager server is maintained in the Alertmanager repository and is cloned in the same way.

The consequence for a contributor is significant. A change to server documentation is a pull request against the server repository, and the website picks it up when it rebuilds. Editing the same text in this repository would be overwritten by the clone step, so there is a clear ownership boundary that newcomers often trip over.

The README also states a content guideline, and it is a useful one for a project that accumulates contributions: keep the documentation generally applicable and avoid use-case-specific changes. A general Prometheus user should not have to read about one company's deployment. Formatting rules and the available frontmatter fields live in a separate markdown-guide.md file, and there is a .mdox.validator.yaml that drives link validation for the files the formatter covers.

The choice to clone at build time, rather than vendor the text, is what keeps three repositories in sync without anyone copying files by hand.

Building requires a GitHub token before npm install

The prerequisites are Node.js and NPM, and then there is one step that catches newcomers out. The pre-build scripts need a GitHub access token with read access to the repositories, in order to bypass anonymous user rate limits when downloading documentation from the other repositories and when fetching download information from the GitHub API. No write access is required, and the token is created in your GitHub account settings.

The token goes into a .env file in the root of the repository.

GITHUB_TOKEN=<your_github_token>

With that in place, dependencies install with the standard command.

npm install

The full build is a single script.

npm run build-all

The README describes exactly what that does: it cleans previous build artifacts, fetches the latest documentation from the Prometheus and Alertmanager repositories, fetches information about available downloads for the Download page, builds the website, and then indexes it for the built-in Pagefind based search functionality. The final output is a static website in the out directory.

Each stage is also available on its own, which is what you want while iterating. The clean step removes the generated directory, the out directory and the .next directory, and the fetch scripts are npm run fetch-repo-docs and npm run fetch-downloads-info. The package.json shows the composition of the full build.

    "clean": "rm -rf generated out .next",
    "build": "next build",
    "postbuild": "pagefind --site out",
    "build-all": "npm run clean && npm run fetch-repo-docs && npm run fetch-downloads-info && npm run build",

Note the postbuild hook. Pagefind indexes the static output after the site is built, and the README points out a practical wrinkle: with npm the postbuild script runs automatically, while with pnpm you either run npm run postbuild by hand or enable the enablePrePostScripts option in your pnpm-workspace.yaml file. Anyone arriving from a pnpm-based workflow will otherwise end up with a site that builds but does not search.

Serving the build and running in development mode

Two ways to look at the site locally, and they behave differently.

To serve the static build output, the README gives a one-liner.

npx serve out

That starts a web server on port 3000, and the site is at http://localhost:3000. In development mode you run the dev server instead.

npm run dev

That also serves on port 3000, and the README states that the website reloads automatically when you change source files.

The important difference is search. The README notes that site search is not available in development mode, because it requires a Pagefind index built on the static output and then loading the generated pagefind.js file, and that only happens when building for production with npm run build as part of npm run build-all. So a contributor checking a rewrite of a search-heavy page cannot verify the search behaviour without doing a full production build.

The package.json shows the dev script running Next.js with its Turbopack bundler, and a separate start script for next start. The npm run lint script runs next lint, and the repository also has an eslint.config.mjs file for the flat configuration style.

The LTS release table is generated from docs-config.ts, not written by hand

The configuration file for the site is docs-config.ts in the repository root, and it sets a small number of high-level things: the base URL of the website, which repositories to fetch documentation from, which repositories to fetch download information from, and information about LTS versions.

The LTS mechanism is the interesting part, because it is a build-time code path rather than a set of Markdown files. The ltsVersions list holds all known LTS versions, past and upcoming, each with a releaseDate and an inclusive endDate in YYYY-MM-DD format in UTC, and upcoming releases can use TBD as the version and YYYY-MM as the release date.

During fetch-repo-docs, the placeholder in the release-cycle page is replaced with a table generated from that configuration, and the result is written under generated/local-docs/.

The rules for what counts as active are careful. A version is treated as an active LTS only once a stable GitHub release exists and through its end date. Active LTS versions are kept in the documentation even outside the recent-version window, are included in the downloads listing, and are labelled as LTS. Expired versions can still appear under the usual recent and latest version rules, but without the LTS label.

That is a deliberate piece of policy engineering: version lifecycle state is derived from release reality rather than hand-maintained in prose, so a version cannot be advertised as supported after its end date.

Netlify publishes main and gives every pull request a preview

The site is deployed automatically using Netlify, and the README describes the moving parts. A GitHub webhook notifies Netlify of branch changes, and the Netlify project is the prometheus-docs site. Changes to the main branch are deployed to the main site at prometheus.io.

Pull requests get their own preview deploys, and the README gives the exact path to find one. In the CI section of the pull request you click Show all checks, then open the Details view on the deploy/netlify entry to see the preview site for that pull request. There is a caveat worth heeding: the deploy/netlify check can take a while to appear after you create or update a pull request, even when the other checks have already passed.

That preview model is the reason the build has to be reproducible outside Netlify. If the site only built correctly on the hosting side, a local build would be a different artefact from the deployed one. The scripts, the token, the configuration file and the ordered build steps are all in the repository so that a contributor can reproduce the same output before opening a pull request.

The repository also carries the usual governance files: CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md and MAINTAINERS.md. The licence is Apache License 2.0, with the LICENSE and NOTICE files at the root.

The Makefile formats one specification file with mdox

The Makefile in the repository root does something narrow and specific: it formats and validates the OpenMetrics specification document.

MD_FILES_TO_FORMAT=docs/specs/om/open_metrics_spec_2_0.md

The tool used is mdox, and it is installed on demand into the Go toolchain rather than being vendored.

$(MDOX):
	@go install github.com/bwplotka/mdox@e88e0a8655a0c91ef6a849edd29798e7e4809d75

There are two targets, and the check one is the interesting one. The fmt target runs the formatter with link validation, and the check target runs the same thing in check mode with a link validation config file, failing the build with a message telling you to run make fmt. The pinned commit in the go install line is what makes that check reproducible.

The scope is deliberately narrow, and there is a TODO comment in the Makefile saying more files should be added to the formatting list. For now, the automated formatting and link checking applies to the OpenMetrics specification, and everything else in docs relies on the general Markdown conventions described in markdown-guide.md.

For a documentation project, that narrowness is understandable, since a formatter that rewrites prose in front of every contributor creates a review burden, but it does mean broken links elsewhere in the tree are not caught by make check.

Editorial conclusion

prometheus/docs fits contributors who want to change how the Prometheus documentation is written, built or searched, and it fits anyone who needs to reproduce the published site locally to check a change before it goes live. It does not fit people looking for the Prometheus server code or the Alertmanager code, which live in their own repositories and are only pulled in at build time, and it does not fit a reader who simply wants the documentation, since prometheus.io already serves it. Before you start, create a .env file with a GITHUB_TOKEN that has read access, run npm run build-all rather than npm run build, and read docs-config.ts, since the LTS table and the repository list are configured there rather than in the Markdown.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. prometheus/docs on GitHub
5. README