Prometheus landing page and documentation website

This repository contains both the content and the static-site generator code for the Prometheus documentation site and associated landing pages.

This is a Next.js-based website with some custom code to integrate documentation from other repositories and fetch information about available Prometheus component downloads from GitHub.

Contributing Changes

See CONTRIBUTING.md for general instructions for new Prometheus contributors.

The documentation hosted on this website is pulled together from multiple repositories:

• The main documentation contents are located in the docs directory of this repository.
• Documentation concerning the Prometheus server is maintained in the Prometheus server repository and cloned into the website at build time.
• Documentation concerning the Alertmanager server is maintained in the Alertmanager server repository and cloned into the website at build time.

As a guideline, please keep the documentation generally applicable and avoid use-case-specific changes.

For guidelines around Markdown formatting and available frontmatter fields and features, please see the Markdown guide.

Building and running the website

Prerequisites

You'll need to have the following installed on your system:

• Node.js
• NPM

Environment variables

To bypass anonymous user rate limits while downloading documentation from the other repositories, as well as fetching information about available downloads from the GitHub API, the pre-build scripts require a GitHub access token with read access to the repositories (no write access is required). You can create a personal access token in your GitHub account settings (https://github.com/settings/tokens/new).

Create a .env file in the root of the repository and add the following environment variable:

GITHUB_TOKEN=<your_github_token>

Installing npm dependencies

To install all required npm package dependencies, run:

npm install

Building the website

To build the website, run:

npm run build-all

This cleans any 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.

You can also run each of these build steps separately:

• npm run clean - Cleans any build output and generated files from previous runs.
• npm run fetch-repo-docs - Fetches the latest documentation from the Prometheus and Alertmanager repositories.
• npm run fetch-downloads-info - Fetches information about available downloads (for the Download page).
• npm run build - Builds the website. When using npm, this automatically also runs the postbuild script, which generates Pagefind search indexes. If you are using pnpm, you will either need to run npm run postbuild manually, or set the enablePrePostScripts option in your pnpm-workspace.yaml file.

Serving the static build output

To serve the static build output, run:

npx serve out

This will start a web server on port 3000. You can access the website at http://localhost:3000.

Running the website in development mode

To run the website in development mode, run:

npm run dev

This will start a web server on port 3000. You can access the website at http://localhost:3000.

The website will automatically reload when you make changes to the source files.

NOTE: Site search is not available in development mode, as it requires building a Pagefind index on the static build output and then loading the generated /pagefind/pagefind.js file. This only happens when building the app for production via npm run build (part of npm run build-all).

Configuration

You can configure some high-level settings for the documentation website in the docs-config.ts file in the root of the repository. This file configures:

• The base URL of the website.
• Which repositories to fetch documentation from.
• Which repositories to fetch download information from.
• Information about LTS (long-term-support) versions.

Automatic Deployment

This site is automatically deployed using Netlify.

If you have the prerequisite access rights, you can view the Netlify settings here:

• GitHub webhook notifying Netlify of branch changes: https://github.com/prometheus/docs/settings/hooks
• Netlify project: https://app.netlify.com/sites/prometheus-docs

Changes to the main branch are deployed to the main site at https://prometheus.io.

Netlify also creates preview deploys for every pull request. To view these for a PR where all checks have passed:

1. In the CI section of the PR, click on "Show all checks".
2. On the "deploy/netlify" entry, click on "Details" to view the preview site for the PR.

You may have to wait a while for the "deploy/netlify" check to appear after creating or updating the PR, even if the other checks have already passed.

License

Apache License 2.0, see LICENSE.