diff --git a/.gitignore b/.gitignore
index 5ef6a520..91005fde 100644
--- a/.gitignore
+++ b/.gitignore
@@ -39,3 +39,6 @@ yarn-error.log*
 # typescript
 *.tsbuildinfo
 next-env.d.ts
+
+# Generated docs files
+/generated
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 00000000..72446f43
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,3 @@
+{
+    "typescript.tsdk": "node_modules/typescript/lib"
+}
diff --git a/docs-config.ts b/docs-config.ts
new file mode 100644
index 00000000..dd5e758b
--- /dev/null
+++ b/docs-config.ts
@@ -0,0 +1,34 @@
+import { DocsConfig } from "./src/docs-config-types";
+
+export default {
+  // Docs to load from repo-local files.
+  localMarkdownSources: [
+    {
+      docsDir: "docs",
+      slugPrefix: "",
+    },
+  ],
+
+  // Sources for docs to load from external repos (Prometheus, Alertmanager).
+  githubMarkdownSources: [
+    {
+      owner: "prometheus",
+      repo: "prometheus",
+      repoDocsDir: "docs",
+      slugPrefix: "prometheus",
+      minNumVersions: 10,
+    },
+    {
+      owner: "prometheus",
+      repo: "alertmanager",
+      repoDocsDir: "docs",
+      slugPrefix: "alerting",
+      minNumVersions: 8,
+    },
+  ],
+
+  // Long-term support versions configuration.
+  ltsVersions: {
+    prometheus: ["2.53"],
+  },
+} satisfies DocsConfig;
diff --git a/docs/alerting/index.md b/docs/alerting/index.md
new file mode 100644
index 00000000..46e1b28f
--- /dev/null
+++ b/docs/alerting/index.md
@@ -0,0 +1,5 @@
+---
+title: Alertmanager
+sort_rank: 7
+nav_icon: bell
+---
diff --git a/docs/concepts/data_model.md b/docs/concepts/data_model.md
new file mode 100644
index 00000000..6fa583b0
--- /dev/null
+++ b/docs/concepts/data_model.md
@@ -0,0 +1,71 @@
+---
+title: Data model
+sort_rank: 1
+---
+
+# Data model
+
+Prometheus fundamentally stores all data as [_time
+series_](http://en.wikipedia.org/wiki/Time_series): streams of timestamped
+values belonging to the same metric and the same set of labeled dimensions.
+Besides stored time series, Prometheus may generate temporary derived time series
+as the result of queries.
+
+## Metric names and labels
+
+Every time series is uniquely identified by its metric name and optional key-value pairs called labels.
+
+***Metric names:***
+
+* Metric names SHOULD specify the general feature of a system that is measured (e.g. `http_requests_total` - the total number of HTTP requests received). 
+* Metric names MAY use any UTF-8 characters.
+* Metric names SHOULD match the regex `[a-zA-Z_:][a-zA-Z0-9_:]*` for the best experience and compatibility (see the warning below). Metric names outside of that set will require quoting e.g. when used in PromQL (see the [UTF-8 guide](../guides/utf8.md#querying)).
+
+NOTE: Colons (':') are reserved for user-defined recording rules. They SHOULD NOT be used by exporters or direct instrumentation.
+
+***Metric labels:***
+
+Labels let you capture different instances of the same metric name. For example: all HTTP requests that used the method `POST` to the `/api/tracks` handler. We refer to this as Prometheus's "dimensional data model". The query language allows filtering and aggregation based on these dimensions. The change of any label's value, including adding or removing labels, will create a new time series.
+
+* Label names MAY use any UTF-8 characters. 
+* Label names beginning with `__` (two underscores) MUST be reserved for internal Prometheus use.
+* Label names SHOULD match the regex `[a-zA-Z_][a-zA-Z0-9_]*` for the best experience and compatibility (see the warning below). Label names outside of that regex will require quoting e.g. when used in PromQL (see the [UTF-8 guide](../guides/utf8.md#querying)).
+* Label values MAY contain any UTF-8 characters.
+* Labels with an empty label value are considered equivalent to labels that do not exist.
+
+WARNING: The [UTF-8](../guides/utf8.md) support for metric and label names was added relatively recently in Prometheus v3.0.0. It might take time for the wider ecosystem (downstream PromQL compatible projects and vendors, tooling, third-party instrumentation, collectors, etc.) to adopt new quoting mechanisms, relaxed validation etc. For the best compatibility it's recommended to stick to the recommended ("SHOULD") character set.
+
+INFO: See also the [best practices for naming metrics and labels](/docs/practices/naming/).
+
+## Samples
+
+Samples form the actual time series data. Each sample consists of:
+
+* a float64 or [native histogram](https://prometheus.io/docs/specs/native_histograms/) value
+* a millisecond-precision timestamp
+
+## Notation
+
+Given a metric name and a set of labels, time series are frequently identified
+using this notation:
+
+    <metric name>{<label name>="<label value>", ...}
+
+For example, a time series with the metric name `api_http_requests_total` and
+the labels `method="POST"` and `handler="/messages"` could be written like
+this:
+
+    api_http_requests_total{method="POST", handler="/messages"}
+
+This is the same notation that [OpenTSDB](http://opentsdb.net/) uses.
+
+Names with UTF-8 characters outside the recommended set must be quoted, using
+this notation:
+
+    {"<metric name>", <label name>="<label value>", ...}
+
+Since metric name are internally represented as a label pair
+with a special label name (`__name__="<metric name>"`) one could also use the following notation:
+
+    {__name__="<metric name>", <label name>="<label value>", ...}
+
diff --git a/docs/concepts/index.md b/docs/concepts/index.md
new file mode 100644
index 00000000..8284a65e
--- /dev/null
+++ b/docs/concepts/index.md
@@ -0,0 +1,5 @@
+---
+title: Concepts
+sort_rank: 2
+nav_icon: flask
+---
diff --git a/docs/concepts/jobs_instances.md b/docs/concepts/jobs_instances.md
new file mode 100644
index 00000000..f9b11f57
--- /dev/null
+++ b/docs/concepts/jobs_instances.md
@@ -0,0 +1,52 @@
+---
+title: Jobs and instances
+sort_rank: 3
+---
+
+# Jobs and instances
+
+In Prometheus terms, an endpoint you can scrape is called an _instance_,
+usually corresponding to a single process. A collection of instances with the same purpose, a process replicated for scalability or reliability for example, is called a _job_.
+
+For example, an API server job with four replicated instances:
+
+   * job: `api-server`
+      * instance 1: `1.2.3.4:5670`
+      * instance 2: `1.2.3.4:5671`
+      * instance 3: `5.6.7.8:5670`
+      * instance 4: `5.6.7.8:5671`
+
+## Automatically generated labels and time series
+
+When Prometheus scrapes a target, it attaches some labels automatically to the
+scraped time series which serve to identify the scraped target:
+
+* `job`: The configured job name that the target belongs to.
+* `instance`: The `<host>:<port>` part of the target's URL that was scraped.
+
+If either of these labels are already present in the scraped data, the behavior
+depends on the `honor_labels` configuration option. See the
+[scrape configuration documentation](/docs/prometheus/latest/configuration/configuration/#scrape_config)
+for more information.
+
+For each instance scrape, Prometheus stores a [sample](/docs/introduction/glossary#sample) in
+the following time series:
+
+* `up{job="<job-name>", instance="<instance-id>"}`: `1` if the instance is
+   healthy, i.e. reachable, or `0` if the scrape failed.
+* `scrape_duration_seconds{job="<job-name>", instance="<instance-id>"}`:
+   duration of the scrape.
+* `scrape_samples_post_metric_relabeling{job="<job-name>", instance="<instance-id>"}`:
+   the number of samples remaining after metric relabeling was applied.
+* `scrape_samples_scraped{job="<job-name>", instance="<instance-id>"}`:
+   the number of samples the target exposed.
+* `scrape_series_added{job="<job-name>", instance="<instance-id>"}`:
+   the approximate number of new series in this scrape. *New in v2.10*
+
+The `up` time series is useful for instance availability monitoring.
+
+With the [`extra-scrape-metrics` feature flag](/docs/prometheus/latest/feature_flags/#extra-scrape-metrics) several additional metrics are available:
+
+* `scrape_timeout_seconds{job="<job-name>", instance="<instance-id>"}`: The configured `scrape_timeout` for a target.
+* `scrape_sample_limit{job="<job-name>", instance="<instance-id>"}`: The configured `sample_limit` for a target. Returns zero if there is no limit configured.
+* `scrape_body_size_bytes{job="<job-name>", instance="<instance-id>"}`: The uncompressed size of the most recent scrape response, if successful. Scrapes failing because `body_size_limit` is exceeded report -1, other scrape failures report 0.
diff --git a/docs/concepts/metric_types.md b/docs/concepts/metric_types.md
new file mode 100644
index 00000000..c1b5d5a6
--- /dev/null
+++ b/docs/concepts/metric_types.md
@@ -0,0 +1,122 @@
+---
+title: Metric types
+sort_rank: 2
+---
+
+# Metric types
+
+The Prometheus client libraries offer four core metric types. These are
+currently only differentiated in the client libraries (to enable APIs tailored
+to the usage of the specific types) and in the wire protocol. The Prometheus
+server does not yet make use of the type information and flattens all data into
+untyped time series. This may change in the future.
+
+## Counter
+
+A _counter_ is a cumulative metric that represents a single [monotonically 
+increasing counter](https://en.wikipedia.org/wiki/Monotonic_function) whose
+value can only increase or be reset to zero on restart. For example, you can
+use a counter to represent the number of requests served, tasks completed, or
+errors.
+
+Do not use a counter to expose a value that can decrease. For example, do not
+use a counter for the number of currently running processes; instead use a gauge.
+
+Client library usage documentation for counters:
+
+   * [Go](http://godoc.org/github.com/prometheus/client_golang/prometheus#Counter)
+   * [Java](https://prometheus.github.io/client_java/getting-started/metric-types/#counter)
+   * [Python](https://prometheus.github.io/client_python/instrumenting/counter/)
+   * [Ruby](https://github.com/prometheus/client_ruby#counter)
+   * [.Net](https://github.com/prometheus-net/prometheus-net#counters)
+   * [Rust](https://docs.rs/prometheus-client/latest/prometheus_client/metrics/counter/index.html)
+
+## Gauge
+
+A _gauge_ is a metric that represents a single numerical value that can
+arbitrarily go up and down.
+
+Gauges are typically used for measured values like temperatures or current
+memory usage, but also "counts" that can go up and down, like the number of
+concurrent requests.
+
+Client library usage documentation for gauges:
+
+   * [Go](http://godoc.org/github.com/prometheus/client_golang/prometheus#Gauge)
+   * [Java](https://prometheus.github.io/client_java/getting-started/metric-types/#gauge)
+   * [Python](https://prometheus.github.io/client_python/instrumenting/gauge/)
+   * [Ruby](https://github.com/prometheus/client_ruby#gauge)
+   * [.Net](https://github.com/prometheus-net/prometheus-net#gauges)
+   * [Rust](https://docs.rs/prometheus-client/latest/prometheus_client/metrics/gauge/index.html)
+
+## Histogram
+
+A _histogram_ samples observations (usually things like request durations or
+response sizes) and counts them in configurable buckets. It also provides a sum
+of all observed values.
+
+A histogram with a base metric name of `<basename>` exposes multiple time series
+during a scrape:
+
+  * cumulative counters for the observation buckets, exposed as `<basename>_bucket{le="<upper inclusive bound>"}`
+  * the **total sum** of all observed values, exposed as `<basename>_sum`
+  * the **count** of events that have been observed, exposed as `<basename>_count` (identical to `<basename>_bucket{le="+Inf"}` above)
+
+Use the
+[`histogram_quantile()` function](/docs/prometheus/latest/querying/functions/#histogram_quantile)
+to calculate quantiles from histograms or even aggregations of histograms. A
+histogram is also suitable to calculate an
+[Apdex score](http://en.wikipedia.org/wiki/Apdex). When operating on buckets,
+remember that the histogram is
+[cumulative](https://en.wikipedia.org/wiki/Histogram#Cumulative_histogram). See
+[histograms and summaries](/docs/practices/histograms) for details of histogram
+usage and differences to [summaries](#summary).
+
+NOTE: Beginning with Prometheus v2.40, there is experimental support for native
+histograms. A native histogram requires only one time series, which includes a
+dynamic number of buckets in addition to the sum and count of
+observations. Native histograms allow much higher resolution at a fraction of
+the cost. Detailed documentation will follow once native histograms are closer
+to becoming a stable feature.
+
+NOTE: Beginning with Prometheus v3.0, the values of the `le` label of classic
+histograms are normalized during ingestion to follow the format of
+[OpenMetrics Canonical Numbers](https://github.com/prometheus/OpenMetrics/blob/main/specification/OpenMetrics.md#considerations-canonical-numbers).
+
+Client library usage documentation for histograms:
+
+   * [Go](http://godoc.org/github.com/prometheus/client_golang/prometheus#Histogram)
+   * [Java](https://prometheus.github.io/client_java/getting-started/metric-types/#histogram)
+   * [Python](https://prometheus.github.io/client_python/instrumenting/histogram/)
+   * [Ruby](https://github.com/prometheus/client_ruby#histogram)
+   * [.Net](https://github.com/prometheus-net/prometheus-net#histogram)
+   * [Rust](https://docs.rs/prometheus-client/latest/prometheus_client/metrics/histogram/index.html)
+
+## Summary
+
+Similar to a _histogram_, a _summary_ samples observations (usually things like
+request durations and response sizes). While it also provides a total count of
+observations and a sum of all observed values, it calculates configurable
+quantiles over a sliding time window.
+
+A summary with a base metric name of `<basename>` exposes multiple time series
+during a scrape:
+
+  * streaming **φ-quantiles** (0 ≤ φ ≤ 1) of observed events, exposed as `<basename>{quantile="<φ>"}`
+  * the **total sum** of all observed values, exposed as `<basename>_sum`
+  * the **count** of events that have been observed, exposed as `<basename>_count`
+
+See [histograms and summaries](/docs/practices/histograms) for
+detailed explanations of φ-quantiles, summary usage, and differences
+to [histograms](#histogram).
+
+NOTE: Beginning with Prometheus v3.0, the values of the `quantile` label are normalized during
+ingestion to follow the format of [OpenMetrics Canonical Numbers](https://github.com/prometheus/OpenMetrics/blob/main/specification/OpenMetrics.md#considerations-canonical-numbers).
+
+Client library usage documentation for summaries:
+
+   * [Go](http://godoc.org/github.com/prometheus/client_golang/prometheus#Summary)
+   * [Java](https://prometheus.github.io/client_java/getting-started/metric-types/#summary)
+   * [Python](https://prometheus.github.io/client_python/instrumenting/summary/)
+   * [Ruby](https://github.com/prometheus/client_ruby#summary)
+   * [.Net](https://github.com/prometheus-net/prometheus-net#summary)
diff --git a/docs/guides/basic-auth.md b/docs/guides/basic-auth.md
new file mode 100644
index 00000000..009de070
--- /dev/null
+++ b/docs/guides/basic-auth.md
@@ -0,0 +1,111 @@
+---
+title: Basic auth
+---
+
+# Securing Prometheus API and UI endpoints using basic auth
+
+Prometheus supports [basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) (aka "basic auth") for connections to the Prometheus [expression browser](/docs/visualization/browser) and [HTTP API](/docs/prometheus/latest/querying/api).
+
+NOTE: This tutorial covers basic auth connections *to* Prometheus instances. Basic auth is also supported for connections *from* Prometheus instances to [scrape targets](../../prometheus/latest/configuration/configuration/#scrape_config).
+
+## Hashing a password
+
+Let's say that you want to require a username and password from all users accessing the Prometheus instance. For this example, use `admin` as the username and choose any password you'd like.
+
+First, generate a [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) hash of the password.
+To generate a hashed password, we will use python3-bcrypt.
+
+Let's install it by running `apt install python3-bcrypt`, assuming you are
+running a debian-like distribution. Other alternatives exist to generate hashed
+passwords; for testing you can also use [bcrypt generators on the
+web](https://bcrypt-generator.com/).
+
+Here is a python script which uses python3-bcrypt to prompt for a password and
+hash it:
+
+```python
+import getpass
+import bcrypt
+
+password = getpass.getpass("password: ")
+hashed_password = bcrypt.hashpw(password.encode("utf-8"), bcrypt.gensalt())
+print(hashed_password.decode())
+```
+
+Save that script as `gen-pass.py` and run it:
+
+```shell
+$ python3 gen-pass.py
+```
+
+That should prompt you for a password:
+
+```
+password:
+$2b$12$hNf2lSsxfm0.i4a.1kVpSOVyBCfIB51VRjgBUyv6kdnyTlgWj81Ay
+```
+
+In this example, I used "test" as password.
+
+Save that password somewhere, we will use it in the next steps!
+
+
+## Creating web.yml
+
+Let's create a web.yml file
+([documentation](https://prometheus.io/docs/prometheus/latest/configuration/https/)),
+with the following content:
+
+```yaml
+basic_auth_users:
+    admin: $2b$12$hNf2lSsxfm0.i4a.1kVpSOVyBCfIB51VRjgBUyv6kdnyTlgWj81Ay
+```
+
+You can validate that file with `promtool check web-config web.yml`
+
+```shell
+$ promtool check web-config web.yml
+web.yml SUCCESS
+```
+
+You can add multiple users to the file.
+
+## Launching Prometheus
+
+You can launch prometheus with the web configuration file as follows:
+
+```shell
+$ prometheus --web.config.file=web.yml
+```
+
+## Testing
+
+You can use cURL to interact with your setup. Try this request:
+
+```bash
+curl --head http://localhost:9090/graph
+```
+
+This will return a `401 Unauthorized` response because you've failed to supply a valid username and password.
+
+To successfully access Prometheus endpoints using basic auth, for example the `/metrics` endpoint, supply the proper username using the `-u` flag and supply the password when prompted:
+
+```bash
+curl -u admin http://localhost:9090/metrics
+Enter host password for user 'admin':
+```
+
+That should return Prometheus metrics output, which should look something like this:
+
+```
+# HELP go_gc_duration_seconds A summary of the GC invocation durations.
+# TYPE go_gc_duration_seconds summary
+go_gc_duration_seconds{quantile="0"} 0.0001343
+go_gc_duration_seconds{quantile="0.25"} 0.0002032
+go_gc_duration_seconds{quantile="0.5"} 0.0004485
+...
+```
+
+## Summary
+
+In this guide, you stored a username and a hashed password in a `web.yml` file, launched prometheus with the parameter required to use the credentials in that file to authenticate users accessing Prometheus' HTTP endpoints.
diff --git a/docs/guides/cadvisor.md b/docs/guides/cadvisor.md
new file mode 100644
index 00000000..67932dad
--- /dev/null
+++ b/docs/guides/cadvisor.md
@@ -0,0 +1,125 @@
+---
+title: Monitoring Docker container metrics using cAdvisor
+---
+
+# Monitoring Docker container metrics using cAdvisor
+
+[cAdvisor](https://github.com/google/cadvisor) (short for **c**ontainer **Advisor**) analyzes and exposes resource usage and performance data from running containers. cAdvisor exposes Prometheus metrics out of the box. In this guide, we will:
+
+* create a local multi-container [Docker Compose](https://docs.docker.com/compose/) installation that includes containers running Prometheus, cAdvisor, and a [Redis](https://redis.io/) server, respectively
+* examine some container metrics produced by the Redis container, collected by cAdvisor, and scraped by Prometheus
+
+## Prometheus configuration
+
+First, you'll need to [configure Prometheus](/docs/prometheus/latest/configuration/configuration) to scrape metrics from cAdvisor. Create a `prometheus.yml` file and populate it with this configuration:
+
+```yaml
+scrape_configs:
+- job_name: cadvisor
+  scrape_interval: 5s
+  static_configs:
+  - targets:
+    - cadvisor:8080
+```
+
+## Docker Compose configuration
+
+Now we'll need to create a Docker Compose [configuration](https://docs.docker.com/compose/compose-file/) that specifies which containers are part of our installation as well as which ports are exposed by each container, which volumes are used, and so on.
+
+In the same folder where you created the [`prometheus.yml`](#prometheus-configuration) file, create a `docker-compose.yml` file and populate it with this Docker Compose configuration:
+
+```yaml
+version: '3.2'
+services:
+  prometheus:
+    image: prom/prometheus:latest
+    container_name: prometheus
+    ports:
+    - 9090:9090
+    command:
+    - --config.file=/etc/prometheus/prometheus.yml
+    volumes:
+    - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
+    depends_on:
+    - cadvisor
+  cadvisor:
+    image: gcr.io/cadvisor/cadvisor:latest
+    container_name: cadvisor
+    ports:
+    - 8080:8080
+    volumes:
+    - /:/rootfs:ro
+    - /var/run:/var/run:rw
+    - /sys:/sys:ro
+    - /var/lib/docker/:/var/lib/docker:ro
+    depends_on:
+    - redis
+  redis:
+    image: redis:latest
+    container_name: redis
+    ports:
+    - 6379:6379
+```
+
+This configuration instructs Docker Compose to run three services, each of which corresponds to a [Docker](https://docker.com) container:
+
+1. The `prometheus` service uses the local `prometheus.yml` configuration file (imported into the container by the `volumes` parameter).
+1. The `cadvisor` service exposes port 8080 (the default port for cAdvisor metrics) and relies on a variety of local volumes (`/`, `/var/run`, etc.).
+1. The `redis` service is a standard Redis server. cAdvisor will gather container metrics from this container automatically, i.e. without any further configuration.
+
+To run the installation:
+
+```bash
+docker-compose up
+```
+
+If Docker Compose successfully starts up all three containers, you should see output like this:
+
+```
+prometheus  | level=info ts=2018-07-12T22:02:40.5195272Z caller=main.go:500 msg="Server is ready to receive web requests."
+```
+
+You can verify that all three containers are running using the [`ps`](https://docs.docker.com/compose/reference/ps/) command:
+
+```bash
+docker-compose ps
+```
+
+Your output will look something like this:
+
+```
+   Name                 Command               State           Ports
+----------------------------------------------------------------------------
+cadvisor     /usr/bin/cadvisor -logtostderr   Up      8080/tcp
+prometheus   /bin/prometheus --config.f ...   Up      0.0.0.0:9090->9090/tcp
+redis        docker-entrypoint.sh redis ...   Up      0.0.0.0:6379->6379/tcp
+```
+
+## Exploring the cAdvisor web UI
+
+You can access the cAdvisor [web UI](https://github.com/google/cadvisor/blob/master/docs/web.md) at `http://localhost:8080`. You can explore stats and graphs for specific Docker containers in our installation at `http://localhost:8080/docker/<container>`. Metrics for the Redis container, for example, can be accessed at `http://localhost:8080/docker/redis`, Prometheus at `http://localhost:8080/docker/prometheus`, and so on.
+
+## Exploring metrics in the expression browser
+
+cAdvisor's web UI is a useful interface for exploring the kinds of things that cAdvisor monitors, but it doesn't provide an interface for exploring container *metrics*. For that we'll need the Prometheus [expression browser](/docs/visualization/browser), which is available at `http://localhost:9090/graph`. You can enter Prometheus expressions into the expression bar, which looks like this:
+
+![Prometheus expression bar](/assets/prometheus-expression-bar.png)
+
+Let's start by exploring the `container_start_time_seconds` metric, which records the start time of containers (in seconds). You can select for specific containers by name using the `name="<container_name>"` expression. The container name corresponds to the `container_name` parameter in the Docker Compose configuration. The [`container_start_time_seconds{name="redis"}`](http://localhost:9090/graph?g0.range_input=1h&g0.expr=container_start_time_seconds%7Bname%3D%22redis%22%7D&g0.tab=1) expression, for example, shows the start time for the `redis` container.
+
+NOTE: A full listing of cAdvisor-gathered container metrics exposed to Prometheus can be found in the [cAdvisor documentation](https://github.com/google/cadvisor/blob/master/docs/storage/prometheus.md).
+
+## Other expressions
+
+The table below lists some other example expressions
+
+Expression | Description | For
+:----------|:------------|:---
+[`rate(container_cpu_usage_seconds_total{name="redis"}[1m])`](http://localhost:9090/graph?g0.range_input=1h&g0.expr=rate(container_cpu_usage_seconds_total%7Bname%3D%22redis%22%7D%5B1m%5D)&g0.tab=1) | The [cgroup](https://en.wikipedia.org/wiki/Cgroups)'s CPU usage in the last minute | The `redis` container
+[`container_memory_usage_bytes{name="redis"}`](http://localhost:9090/graph?g0.range_input=1h&g0.expr=container_memory_usage_bytes%7Bname%3D%22redis%22%7D&g0.tab=1) | The cgroup's total memory usage (in bytes) | The `redis` container
+[`rate(container_network_transmit_bytes_total[1m])`](http://localhost:9090/graph?g0.range_input=1h&g0.expr=rate(container_network_transmit_bytes_total%5B1m%5D)&g0.tab=1) | Bytes transmitted over the network by the container per second in the last minute | All containers
+[`rate(container_network_receive_bytes_total[1m])`](http://localhost:9090/graph?g0.range_input=1h&g0.expr=rate(container_network_receive_bytes_total%5B1m%5D)&g0.tab=1) | Bytes received over the network by the container per second in the last minute | All containers
+
+## Summary
+
+In this guide, we ran three separate containers in a single installation using Docker Compose: a Prometheus container scraped metrics from a cAdvisor container which, in turns, gathered metrics produced by a Redis container. We then explored a handful of cAdvisor container metrics using the Prometheus expression browser.
diff --git a/docs/guides/dockerswarm.md b/docs/guides/dockerswarm.md
new file mode 100644
index 00000000..a8001f44
--- /dev/null
+++ b/docs/guides/dockerswarm.md
@@ -0,0 +1,230 @@
+---
+title: Docker Swarm
+sort_rank: 1
+---
+
+# Docker Swarm
+
+Prometheus can discover targets in a [Docker Swarm][swarm] cluster, as of
+v2.20.0. This guide demonstrates how to use that service discovery mechanism.
+
+## Docker Swarm service discovery architecture
+
+The [Docker Swarm service discovery][swarmsd] contains 3 different roles: nodes, services,
+and tasks.
+
+The first role, **nodes**, represents the hosts that are part of the Swarm. It
+can be used to automatically monitor the Docker daemons or the Node Exporters
+who run on the Swarm hosts.
+
+The second role, **tasks**, represents any individual container deployed in the
+swarm. Each task gets its associated service labels. One service can be backed by
+one or multiple tasks.
+
+The third one, **services**, will discover the services deployed in the
+swarm. It will discover the ports exposed by the services. Usually you will want
+to use the tasks role instead of this one.
+
+Prometheus will only discover tasks and service that expose ports.
+
+NOTE: The rest of this post assumes that you have a Swarm running.
+
+## Setting up Prometheus
+
+For this guide, you need to [setup Prometheus][setup]. We will assume that
+Prometheus runs on a Docker Swarm manager node and has access to the Docker
+socket at `/var/run/docker.sock`.
+
+## Monitoring Docker daemons
+
+Let's dive into the service discovery itself.
+
+Docker itself, as a daemon, exposes [metrics][dockermetrics] that can be
+ingested by a Prometheus server.
+
+You can enable them by editing `/etc/docker/daemon.json` and setting the
+following properties:
+
+```json
+{
+  "metrics-addr" : "0.0.0.0:9323",
+  "experimental" : true
+}
+```
+
+Instead of `0.0.0.0`, you can set the IP of the Docker Swarm node.
+
+A restart of the daemon is required to take the new configuration into account.
+
+The [Docker documentation][dockermetrics] contains more info about this.
+
+Then, you can configure Prometheus to scrape the Docker daemon, by providing the
+following `prometheus.yml` file:
+
+
+```yaml
+scrape_configs:
+  # Make Prometheus scrape itself for metrics.
+  - job_name: 'prometheus'
+    static_configs:
+    - targets: ['localhost:9090']
+
+  # Create a job for Docker daemons.
+  - job_name: 'docker'
+    dockerswarm_sd_configs:
+      - host: unix:///var/run/docker.sock
+        role: nodes
+    relabel_configs:
+      # Fetch metrics on port 9323.
+      - source_labels: [__meta_dockerswarm_node_address]
+        target_label: __address__
+        replacement: $1:9323
+      # Set hostname as instance label
+      - source_labels: [__meta_dockerswarm_node_hostname]
+        target_label: instance
+```
+
+For the nodes role, you can also use the `port` parameter of
+`dockerswarm_sd_configs`. However, using `relabel_configs` is recommended as it
+enables Prometheus to reuse the same API calls across identical Docker Swarm
+configurations.
+
+## Monitoring Containers
+
+Let's now deploy a service in our Swarm. We will deploy [cadvisor][cad], which
+exposes container resources metrics:
+
+```shell
+docker service create --name cadvisor -l prometheus-job=cadvisor \
+    --mode=global --publish target=8080,mode=host \
+    --mount type=bind,src=/var/run/docker.sock,dst=/var/run/docker.sock,ro \
+    --mount type=bind,src=/,dst=/rootfs,ro \
+    --mount type=bind,src=/var/run,dst=/var/run \
+    --mount type=bind,src=/sys,dst=/sys,ro \
+    --mount type=bind,src=/var/lib/docker,dst=/var/lib/docker,ro \
+    google/cadvisor -docker_only
+```
+
+This is a minimal `prometheus.yml` file to monitor it:
+
+```yaml
+scrape_configs:
+  # Make Prometheus scrape itself for metrics.
+  - job_name: 'prometheus'
+    static_configs:
+    - targets: ['localhost:9090']
+
+  # Create a job for Docker Swarm containers.
+  - job_name: 'dockerswarm'
+    dockerswarm_sd_configs:
+      - host: unix:///var/run/docker.sock
+        role: tasks
+    relabel_configs:
+      # Only keep containers that should be running.
+      - source_labels: [__meta_dockerswarm_task_desired_state]
+        regex: running
+        action: keep
+      # Only keep containers that have a `prometheus-job` label.
+      - source_labels: [__meta_dockerswarm_service_label_prometheus_job]
+        regex: .+
+        action: keep
+      # Use the prometheus-job Swarm label as Prometheus job label.
+      - source_labels: [__meta_dockerswarm_service_label_prometheus_job]
+        target_label: job
+```
+
+Let's analyze each part of the [relabel configuration][rela].
+
+
+```yaml
+- source_labels: [__meta_dockerswarm_task_desired_state]
+  regex: running
+  action: keep
+```
+
+Docker Swarm exposes the desired [state of the tasks][state] over the API. In
+out example, we only **keep** the targets that should be running. It prevents
+monitoring tasks that should be shut down.
+
+```yaml
+- source_labels: [__meta_dockerswarm_service_label_prometheus_job]
+  regex: .+
+  action: keep
+```
+
+When we deployed our cadvisor, we have added a label `prometheus-job=cadvisor`.
+As Prometheus fetches the tasks labels, we can instruct it to **only** keep the
+targets which have a `prometheus-job` label.
+
+
+```yaml
+- source_labels: [__meta_dockerswarm_service_label_prometheus_job]
+  target_label: job
+```
+
+That last part takes the label `prometheus-job` of the task and turns it into
+a target label, overwriting the default `dockerswarm` job label that comes from
+the scrape config.
+
+## Discovered labels
+
+The [Prometheus Documentation][swarmsd] contains the full list of labels, but
+here are other relabel configs that you might find useful.
+
+### Scraping metrics via a certain network only
+
+```yaml
+- source_labels: [__meta_dockerswarm_network_name]
+  regex: ingress
+  action: keep
+```
+
+### Scraping global tasks only
+
+Global tasks run on every daemon.
+
+```yaml
+- source_labels: [__meta_dockerswarm_service_mode]
+  regex: global
+  action: keep
+- source_labels: [__meta_dockerswarm_task_port_publish_mode]
+  regex: host
+  action: keep
+```
+
+### Adding a docker_node label to the targets
+
+```yaml
+- source_labels: [__meta_dockerswarm_node_hostname]
+  target_label: docker_node
+```
+
+## Connecting to the Docker Swarm
+
+The above `dockerswarm_sd_configs` entries have a field host:
+
+```yaml
+host: unix:///var/run/docker.sock
+```
+
+That is using the Docker socket. Prometheus offers [additional configuration
+options][swarmsd] to connect to Swarm using HTTP and HTTPS, if you prefer that
+over the unix socket.
+
+## Conclusion
+
+There are many discovery labels you can play with to better determine which
+targets to monitor and how, for the tasks, there is more than 25 labels
+available. Don't hesitate to look at the "Service Discovery" page of your
+Prometheus server (under the "Status" menu) to see all the discovered labels.
+
+The service discovery makes no assumptions about your Swarm stack, in such a way
+that given proper configuration, this should be pluggable to any existing stack.
+
+[state]:https://docs.docker.com/engine/swarm/how-swarm-mode-works/swarm-task-states/
+[rela]:https://prometheus.io/docs/prometheus/latest/configuration/configuration/#relabel_config
+[swarm]:https://docs.docker.com/engine/swarm/
+[swarmsd]:https://prometheus.io/docs/prometheus/latest/configuration/configuration/#dockerswarm_sd_config
+[dockermetrics]:https://docs.docker.com/config/daemon/prometheus/
+[cad]:https://github.com/google/cadvisor
+[setup]:https://prometheus.io/docs/prometheus/latest/getting_started/
diff --git a/docs/guides/file-sd.md b/docs/guides/file-sd.md
new file mode 100644
index 00000000..defd4f53
--- /dev/null
+++ b/docs/guides/file-sd.md
@@ -0,0 +1,126 @@
+---
+title: Use file-based service discovery to discover scrape targets
+---
+
+# Use file-based service discovery to discover scrape targets
+
+Prometheus offers a variety of [service discovery options](https://github.com/prometheus/prometheus/tree/main/discovery) for discovering scrape targets, including [Kubernetes](/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config), [Consul](/docs/prometheus/latest/configuration/configuration/#consul_sd_config), and many others. If you need to use a service discovery system that is not currently supported, your use case may be best served by Prometheus' [file-based service discovery](/docs/prometheus/latest/configuration/configuration/#file_sd_config) mechanism, which enables you to list scrape targets in a JSON file (along with metadata about those targets).
+
+In this guide, we will:
+
+* Install and run a Prometheus [Node Exporter](../node-exporter) locally
+* Create a `targets.json` file specifying the host and port information for the Node Exporter
+* Install and run a Prometheus instance that is configured to discover the Node Exporter using the `targets.json` file
+
+## Installing and running the Node Exporter
+
+See [this section](../node-exporter#installing-and-running-the-node-exporter) of the [Monitoring Linux host metrics with the Node Exporter](../node-exporter) guide. The Node Exporter runs on port 9100. To ensure that the Node Exporter is exposing metrics:
+
+```bash
+curl http://localhost:9100/metrics
+```
+
+The metrics output should look something like this:
+
+```
+# HELP go_gc_duration_seconds A summary of the GC invocation durations.
+# TYPE go_gc_duration_seconds summary
+go_gc_duration_seconds{quantile="0"} 0
+go_gc_duration_seconds{quantile="0.25"} 0
+go_gc_duration_seconds{quantile="0.5"} 0
+...
+```
+
+## Installing, configuring, and running Prometheus
+
+Like the Node Exporter, Prometheus is a single static binary that you can install via tarball. [Download the latest release](/download#prometheus) for your platform and untar it:
+
+```bash
+wget https://github.com/prometheus/prometheus/releases/download/v*/prometheus-*.*-amd64.tar.gz
+tar xvf prometheus-*.*-amd64.tar.gz
+cd prometheus-*.*
+```
+
+The untarred directory contains a `prometheus.yml` configuration file. Replace the current contents of that file with this:
+
+```yaml
+scrape_configs:
+- job_name: 'node'
+  file_sd_configs:
+  - files:
+    - 'targets.json'
+```
+
+This configuration specifies that there is a job called `node` (for the Node Exporter) that retrieves host and port information for Node Exporter instances from a `targets.json` file.
+
+Now create that `targets.json` file and add this content to it:
+
+```json
+[
+  {
+    "labels": {
+      "job": "node"
+    },
+    "targets": [
+      "localhost:9100"
+    ]
+  }
+]
+```
+
+NOTE: In this guide we'll work with JSON service discovery configurations manually for the sake of brevity. In general, however, we recommend that you use some kind of JSON-generating process or tool instead.
+
+This configuration specifies that there is a `node` job with one target: `localhost:9100`.
+
+Now you can start up Prometheus:
+
+```bash
+./prometheus
+```
+
+If Prometheus has started up successfully, you should see a line like this in the logs:
+
+```
+level=info ts=2018-08-13T20:39:24.905651509Z caller=main.go:500 msg="Server is ready to receive web requests."
+```
+
+## Exploring the discovered services' metrics
+
+With Prometheus up and running, you can explore metrics exposed by the `node` service using the Prometheus [expression browser](/docs/visualization/browser). If you explore the [`up{job="node"}`](http://localhost:9090/graph?g0.range_input=1h&g0.expr=up%7Bjob%3D%22node%22%7D&g0.tab=1) metric, for example, you can see that the Node Exporter is being appropriately discovered.
+
+## Changing the targets list dynamically
+
+When using Prometheus' file-based service discovery mechanism, the Prometheus instance will listen for changes to the file and automatically update the scrape target list, without requiring an instance restart. To demonstrate this, start up a second Node Exporter instance on port 9200. First navigate to the directory containing the Node Exporter binary and run this command in a new terminal window:
+
+```bash
+./node_exporter --web.listen-address=":9200"
+```
+
+Now modify the config in `targets.json` by adding an entry for the new Node Exporter:
+
+```json
+[
+  {
+    "targets": [
+      "localhost:9100"
+    ],
+    "labels": {
+      "job": "node"
+    }
+  },
+  {
+    "targets": [
+      "localhost:9200"
+    ],
+    "labels": {
+      "job": "node"
+    }
+  }
+]
+```
+
+When you save the changes, Prometheus will automatically be notified of the new list of targets. The [`up{job="node"}`](http://localhost:9090/graph?g0.range_input=1h&g0.expr=up%7Bjob%3D%22node%22%7D&g0.tab=1) metric should display two instances with `instance` labels `localhost:9100` and `localhost:9200`.
+
+## Summary
+
+In this guide, you installed and ran a Prometheus Node Exporter and configured Prometheus to discover and scrape metrics from the Node Exporter using file-based service discovery.
diff --git a/docs/guides/go-application.md b/docs/guides/go-application.md
new file mode 100644
index 00000000..1f44c96d
--- /dev/null
+++ b/docs/guides/go-application.md
@@ -0,0 +1,131 @@
+---
+title: Instrumenting a Go application
+---
+
+# Instrumenting a Go application for Prometheus
+
+Prometheus has an official [Go client library](https://github.com/prometheus/client_golang) that you can use to instrument Go applications. In this guide, we'll create a simple Go application that exposes Prometheus metrics via HTTP.
+
+NOTE: For comprehensive API documentation, see the [GoDoc](https://godoc.org/github.com/prometheus/client_golang) for Prometheus' various Go libraries.
+
+## Installation
+
+You can install the `prometheus`, `promauto`, and `promhttp` libraries necessary for the guide using [`go get`](https://golang.org/doc/articles/go_command.html):
+
+```bash
+go get github.com/prometheus/client_golang/prometheus
+go get github.com/prometheus/client_golang/prometheus/promauto
+go get github.com/prometheus/client_golang/prometheus/promhttp
+```
+
+## How Go exposition works
+
+To expose Prometheus metrics in a Go application, you need to provide a `/metrics` HTTP endpoint. You can use the [`prometheus/promhttp`](https://godoc.org/github.com/prometheus/client_golang/prometheus/promhttp) library's HTTP [`Handler`](https://godoc.org/github.com/prometheus/client_golang/prometheus/promhttp#Handler) as the handler function.
+
+This minimal application, for example, would expose the default metrics for Go applications via `http://localhost:2112/metrics`:
+
+```go
+package main
+
+import (
+        "net/http"
+
+        "github.com/prometheus/client_golang/prometheus/promhttp"
+)
+
+func main() {
+        http.Handle("/metrics", promhttp.Handler())
+        http.ListenAndServe(":2112", nil)
+}
+```
+
+To start the application:
+
+```bash
+go run main.go
+```
+
+To access the metrics:
+
+```bash
+curl http://localhost:2112/metrics
+```
+
+## Adding your own metrics
+
+The application [above](#how-go-exposition-works) exposes only the default Go metrics. You can also register your own custom application-specific metrics. This example application exposes a `myapp_processed_ops_total` [counter](/docs/concepts/metric_types/#counter) that counts the number of operations that have been processed thus far. Every 2 seconds, the counter is incremented by one.
+
+```go
+package main
+
+import (
+        "net/http"
+        "time"
+
+        "github.com/prometheus/client_golang/prometheus"
+        "github.com/prometheus/client_golang/prometheus/promauto"
+        "github.com/prometheus/client_golang/prometheus/promhttp"
+)
+
+func recordMetrics() {
+        go func() {
+                for {
+                        opsProcessed.Inc()
+                        time.Sleep(2 * time.Second)
+                }
+        }()
+}
+
+var (
+        opsProcessed = promauto.NewCounter(prometheus.CounterOpts{
+                Name: "myapp_processed_ops_total",
+                Help: "The total number of processed events",
+        })
+)
+
+func main() {
+        recordMetrics()
+
+        http.Handle("/metrics", promhttp.Handler())
+        http.ListenAndServe(":2112", nil)
+}
+```
+
+To run the application:
+
+```bash
+go run main.go
+```
+
+To access the metrics:
+
+```bash
+curl http://localhost:2112/metrics
+```
+
+In the metrics output, you'll see the help text, type information, and current value of the `myapp_processed_ops_total` counter:
+
+```
+# HELP myapp_processed_ops_total The total number of processed events
+# TYPE myapp_processed_ops_total counter
+myapp_processed_ops_total 5
+```
+
+You can [configure](/docs/prometheus/latest/configuration/configuration/#scrape_config) a locally running Prometheus instance to scrape metrics from the application. Here's an example `prometheus.yml` configuration:
+
+```yaml
+scrape_configs:
+- job_name: myapp
+  scrape_interval: 10s
+  static_configs:
+  - targets:
+    - localhost:2112
+```
+
+## Other Go client features
+
+In this guide we covered just a small handful of features available in the Prometheus Go client libraries. You can also expose other metrics types, such as [gauges](https://godoc.org/github.com/prometheus/client_golang/prometheus#Gauge) and [histograms](https://godoc.org/github.com/prometheus/client_golang/prometheus#Histogram), [non-global registries](https://godoc.org/github.com/prometheus/client_golang/prometheus#Registry), functions for [pushing metrics](https://godoc.org/github.com/prometheus/client_golang/prometheus/push) to Prometheus [PushGateways](/docs/instrumenting/pushing/), bridging Prometheus and [Graphite](https://godoc.org/github.com/prometheus/client_golang/prometheus/graphite), and more.
+
+## Summary
+
+In this guide, you created two sample Go applications that expose metrics to Prometheus---one that exposes only the default Go metrics and one that also exposes a custom Prometheus counter---and configured a Prometheus instance to scrape metrics from those applications.
diff --git a/docs/guides/index.md b/docs/guides/index.md
new file mode 100644
index 00000000..7d4cad3f
--- /dev/null
+++ b/docs/guides/index.md
@@ -0,0 +1,5 @@
+---
+title: Guides
+sort_rank: 9
+nav_icon: map
+---
diff --git a/docs/guides/multi-target-exporter.md b/docs/guides/multi-target-exporter.md
new file mode 100644
index 00000000..563667f0
--- /dev/null
+++ b/docs/guides/multi-target-exporter.md
@@ -0,0 +1,499 @@
+---
+title: Understanding and using the multi-target exporter pattern
+---
+
+# Understanding and using the multi-target exporter pattern
+
+This guide will introduce you to the multi-target exporter pattern. To achieve this we will:
+
+* describe the multi-target exporter pattern and why it is used,
+* run the [blackbox](https://github.com/prometheus/blackbox_exporter) exporter as an example of the pattern,
+* configure a custom query module for the blackbox exporter,
+* let the blackbox exporter run basic metric queries against the Prometheus [website](https://prometheus.io),
+* examine a popular pattern of configuring Prometheus to scrape exporters using relabeling.
+
+## The multi-target exporter pattern?
+
+By multi-target [exporter](/docs/instrumenting/exporters/) pattern we refer to a specific design, in which:
+
+* the exporter will get the target’s metrics via a network protocol.
+* the exporter does not have to run on the machine the metrics are taken from.
+* the exporter gets the targets and a query config string as parameters of Prometheus’ GET request.
+* the exporter subsequently starts the scrape after getting Prometheus’ GET requests and once it is done with scraping.
+* the exporter can query multiple targets.
+
+This pattern is only used for certain exporters, such as the [blackbox](https://github.com/prometheus/blackbox_exporter) and the [SNMP exporter](https://github.com/prometheus/snmp_exporter).
+
+The reason is that we either can’t run an exporter on the targets, e.g. network gear speaking SNMP, or that we are explicitly interested in the distance, e.g. latency and reachability of a website from a specific point outside of our network, a common use case for the [blackbox](https://github.com/prometheus/blackbox_exporter) exporter.
+
+## Running multi-target exporters
+
+Multi-target exporters are flexible regarding their environment and can be run in many ways. As regular programs, in containers, as background services, on baremetal, on virtual machines. Because they are queried and do query over network they do need appropriate open ports. Otherwise they are frugal.
+
+Now let’s try it out for yourself!
+
+Use [Docker](https://www.docker.com/) to start a blackbox exporter container by running this in a terminal. Depending on your system configuration you might need to prepend the command with a `sudo`:
+
+```bash
+docker run -p 9115:9115 prom/blackbox-exporter
+```
+
+You should see a few log lines and if everything went well the last one should report `msg="Listening on address"` as seen here:
+
+```
+level=info ts=2018-10-17T15:41:35.4997596Z caller=main.go:324 msg="Listening on address" address=:9115
+```
+
+## Basic querying of multi-target exporters
+
+There are two ways of querying:
+
+1. Querying the exporter itself. It has its own metrics, usually available at `/metrics`.
+1. Querying the exporter to scrape another target. Usually available at a "descriptive" endpoint, e.g. `/probe`. This is likely what you are primarily interested in, when using multi-target exporters.
+
+You can manually try the first query type with curl in another terminal or use this [link](http://localhost:9115/metrics):
+
+<a name="query-exporter"></a>
+
+```bash
+curl 'localhost:9115/metrics'
+```
+
+The response should be something like this:
+
+```
+# HELP blackbox_exporter_build_info A metric with a constant '1' value labeled by version, revision, branch, and goversion from which blackbox_exporter was built.
+# TYPE blackbox_exporter_build_info gauge
+blackbox_exporter_build_info{branch="HEAD",goversion="go1.10",revision="4a22506cf0cf139d9b2f9cde099f0012d9fcabde",version="0.12.0"} 1
+# HELP go_gc_duration_seconds A summary of the GC invocation durations.
+# TYPE go_gc_duration_seconds summary
+go_gc_duration_seconds{quantile="0"} 0
+go_gc_duration_seconds{quantile="0.25"} 0
+go_gc_duration_seconds{quantile="0.5"} 0
+go_gc_duration_seconds{quantile="0.75"} 0
+go_gc_duration_seconds{quantile="1"} 0
+go_gc_duration_seconds_sum 0
+go_gc_duration_seconds_count 0
+# HELP go_goroutines Number of goroutines that currently exist.
+# TYPE go_goroutines gauge
+go_goroutines 9
+
+[…]
+
+# HELP process_cpu_seconds_total Total user and system CPU time spent in seconds.
+# TYPE process_cpu_seconds_total counter
+process_cpu_seconds_total 0.05
+# HELP process_max_fds Maximum number of open file descriptors.
+# TYPE process_max_fds gauge
+process_max_fds 1.048576e+06
+# HELP process_open_fds Number of open file descriptors.
+# TYPE process_open_fds gauge
+process_open_fds 7
+# HELP process_resident_memory_bytes Resident memory size in bytes.
+# TYPE process_resident_memory_bytes gauge
+process_resident_memory_bytes 7.8848e+06
+# HELP process_start_time_seconds Start time of the process since unix epoch in seconds.
+# TYPE process_start_time_seconds gauge
+process_start_time_seconds 1.54115492874e+09
+# HELP process_virtual_memory_bytes Virtual memory size in bytes.
+# TYPE process_virtual_memory_bytes gauge
+process_virtual_memory_bytes 1.5609856e+07
+```
+
+Those are metrics in the Prometheus [format](/docs/instrumenting/exposition_formats/#text-format-example). They come from the exporter’s [instrumentation](/docs/practices/instrumentation/) and tell us about the state of the exporter itself while it is running. This is called whitebox monitoring and very useful in daily ops practice. If you are curious, try out our guide on how to [instrument your own applications](https://prometheus.io/docs/guides/go-application/).
+
+For the second type of querying we need to provide a target and module as parameters in the HTTP GET Request. The target is a URI or IP and the module must defined in the exporter’s configuration. The blackbox exporter container comes with a meaningful default configuration.  
+We will use the target `prometheus.io` and the predefined module `http_2xx`. It tells the exporter to make a GET request like a browser would if you go to `prometheus.io` and to expect a [200 OK](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#2xx_Success) response.
+
+You can now tell your blackbox exporter to query `prometheus.io` in the terminal with curl:
+
+```bash
+curl 'localhost:9115/probe?target=prometheus.io&module=http_2xx'
+```
+
+This will return a lot of metrics:
+
+```
+# HELP probe_dns_lookup_time_seconds Returns the time taken for probe dns lookup in seconds
+# TYPE probe_dns_lookup_time_seconds gauge
+probe_dns_lookup_time_seconds 0.061087943
+# HELP probe_duration_seconds Returns how long the probe took to complete in seconds
+# TYPE probe_duration_seconds gauge
+probe_duration_seconds 0.065580871
+# HELP probe_failed_due_to_regex Indicates if probe failed due to regex
+# TYPE probe_failed_due_to_regex gauge
+probe_failed_due_to_regex 0
+# HELP probe_http_content_length Length of http content response
+# TYPE probe_http_content_length gauge
+probe_http_content_length 0
+# HELP probe_http_duration_seconds Duration of http request by phase, summed over all redirects
+# TYPE probe_http_duration_seconds gauge
+probe_http_duration_seconds{phase="connect"} 0
+probe_http_duration_seconds{phase="processing"} 0
+probe_http_duration_seconds{phase="resolve"} 0.061087943
+probe_http_duration_seconds{phase="tls"} 0
+probe_http_duration_seconds{phase="transfer"} 0
+# HELP probe_http_redirects The number of redirects
+# TYPE probe_http_redirects gauge
+probe_http_redirects 0
+# HELP probe_http_ssl Indicates if SSL was used for the final redirect
+# TYPE probe_http_ssl gauge
+probe_http_ssl 0
+# HELP probe_http_status_code Response HTTP status code
+# TYPE probe_http_status_code gauge
+probe_http_status_code 0
+# HELP probe_http_version Returns the version of HTTP of the probe response
+# TYPE probe_http_version gauge
+probe_http_version 0
+# HELP probe_ip_protocol Specifies whether probe ip protocol is IP4 or IP6
+# TYPE probe_ip_protocol gauge
+probe_ip_protocol 6
+# HELP probe_success Displays whether or not the probe was a success
+# TYPE probe_success gauge
+probe_success 0
+```
+
+Notice that almost all metrics have a value of `0`. The last one reads `probe_success 0`. This means the prober could not successfully reach `prometheus.io`. The reason is hidden in the metric `probe_ip_protocol` with the value `6`. By default the prober uses [IPv6](https://en.wikipedia.org/wiki/IPv6) until told otherwise. But the Docker daemon blocks IPv6 until told otherwise. Hence our blackbox exporter running in a Docker container can’t connect via IPv6.
+
+We could now either tell Docker to allow IPv6 or the blackbox exporter to use IPv4. In the real world both can make sense and as so often the answer to the question "what is to be done?" is "it depends". Because this is an exporter guide we will change the exporter and take the opportunity to configure a custom module.
+
+## Configuring modules
+
+The modules are predefined in a file inside the docker container called `config.yml` which is a copy of [blackbox.yml](https://github.com/prometheus/blackbox_exporter/blob/master/blackbox.yml) in the github repo.
+
+We will copy this file, [adapt](https://github.com/prometheus/blackbox_exporter/blob/master/CONFIGURATION.md) it to our own needs and tell the exporter to use our config file instead of the one included in the container.  
+
+First download the file using curl or your browser:
+
+```bash
+curl -o blackbox.yml https://raw.githubusercontent.com/prometheus/blackbox_exporter/master/blackbox.yml
+```
+
+Open it in an editor. The first few lines look like this:
+
+```yaml
+modules:
+  http_2xx:
+    prober: http
+  http_post_2xx:
+    prober: http
+    http:
+      method: POST
+```
+
+[YAML](https://en.wikipedia.org/wiki/YAML) uses whitespace indentation to express hierarchy, so you can recognise that two `modules` named `http_2xx` and `http_post_2xx` are defined, and that they both have a prober `http` and for one the method value is specifically set to `POST`.  
+You will now change the module `http_2xx` by setting the `preferred_ip_protocol` of the prober `http` explicitly to the string `ip4`.
+
+```yaml
+modules:
+  http_2xx:
+    prober: http
+    http:
+      preferred_ip_protocol: "ip4"
+  http_post_2xx:
+    prober: http
+    http:
+      method: POST
+```
+
+If you want to know more about the available probers and options check out the [documentation](https://github.com/prometheus/blackbox_exporter/blob/master/CONFIGURATION.md).
+
+Now we need to tell the blackbox exporter to use our freshly changed file. You can do that with the flag `--config.file="blackbox.yml"`. But because we are using Docker, we first must make this file [available](https://docs.docker.com/storage/bind-mounts/) inside the container using the `--mount` command.  
+
+NOTE: If you are using macOS you first need to allow the Docker daemon to access the directory in which your `blackbox.yml` is. You can do that by clicking on the little Docker whale in menu bar and then on `Preferences`->`File Sharing`->`+`. Afterwards press `Apply & Restart`.
+
+First you stop the old container by changing into its terminal and press `ctrl+c`.
+Make sure you are in the directory containing your `blackbox.yml`.
+Then you run this command. It is long, but we will explain it:
+
+<a name="run-exporter"></a>
+
+```bash
+docker \
+  run -p 9115:9115 \
+  --mount type=bind,source="$(pwd)"/blackbox.yml,target=/blackbox.yml,readonly \
+  prom/blackbox-exporter \
+  --config.file="/blackbox.yml"
+```
+
+With this command, you told `docker` to:
+
+1. `run` a container with the port `9115` outside the container mapped to the port `9115` inside of the container.
+1. `mount` from your current directory (`$(pwd)` stands for print working directory) the file `blackbox.yml` into `/blackbox.yml` in `readonly` mode.
+1. use the image `prom/blackbox-exporter` from [Docker hub](https://hub.docker.com/r/prom/blackbox-exporter/).
+1. run the blackbox-exporter with the flag `--config.file` telling it to use `/blackbox.yml` as config file.
+
+If everything is correct, you should see something like this:
+
+```
+level=info ts=2018-10-19T12:40:51.650462756Z caller=main.go:213 msg="Starting blackbox_exporter" version="(version=0.12.0, branch=HEAD, revision=4a22506cf0cf139d9b2f9cde099f0012d9fcabde)"
+level=info ts=2018-10-19T12:40:51.653357722Z caller=main.go:220 msg="Loaded config file"
+level=info ts=2018-10-19T12:40:51.65349635Z caller=main.go:324 msg="Listening on address" address=:9115
+```
+
+Now you can try our new IPv4-using module `http_2xx` in a terminal:
+
+```bash
+curl 'localhost:9115/probe?target=prometheus.io&module=http_2xx'
+```
+
+Which should return Prometheus metrics like this:
+
+```
+# HELP probe_dns_lookup_time_seconds Returns the time taken for probe dns lookup in seconds
+# TYPE probe_dns_lookup_time_seconds gauge
+probe_dns_lookup_time_seconds 0.02679421
+# HELP probe_duration_seconds Returns how long the probe took to complete in seconds
+# TYPE probe_duration_seconds gauge
+probe_duration_seconds 0.461619124
+# HELP probe_failed_due_to_regex Indicates if probe failed due to regex
+# TYPE probe_failed_due_to_regex gauge
+probe_failed_due_to_regex 0
+# HELP probe_http_content_length Length of http content response
+# TYPE probe_http_content_length gauge
+probe_http_content_length -1
+# HELP probe_http_duration_seconds Duration of http request by phase, summed over all redirects
+# TYPE probe_http_duration_seconds gauge
+probe_http_duration_seconds{phase="connect"} 0.062076202999999996
+probe_http_duration_seconds{phase="processing"} 0.23481845699999998
+probe_http_duration_seconds{phase="resolve"} 0.029594103
+probe_http_duration_seconds{phase="tls"} 0.163420078
+probe_http_duration_seconds{phase="transfer"} 0.002243199
+# HELP probe_http_redirects The number of redirects
+# TYPE probe_http_redirects gauge
+probe_http_redirects 1
+# HELP probe_http_ssl Indicates if SSL was used for the final redirect
+# TYPE probe_http_ssl gauge
+probe_http_ssl 1
+# HELP probe_http_status_code Response HTTP status code
+# TYPE probe_http_status_code gauge
+probe_http_status_code 200
+# HELP probe_http_uncompressed_body_length Length of uncompressed response body
+# TYPE probe_http_uncompressed_body_length gauge
+probe_http_uncompressed_body_length 14516
+# HELP probe_http_version Returns the version of HTTP of the probe response
+# TYPE probe_http_version gauge
+probe_http_version 1.1
+# HELP probe_ip_protocol Specifies whether probe ip protocol is IP4 or IP6
+# TYPE probe_ip_protocol gauge
+probe_ip_protocol 4
+# HELP probe_ssl_earliest_cert_expiry Returns earliest SSL cert expiry in unixtime
+# TYPE probe_ssl_earliest_cert_expiry gauge
+probe_ssl_earliest_cert_expiry 1.581897599e+09
+# HELP probe_success Displays whether or not the probe was a success
+# TYPE probe_success gauge
+probe_success 1
+# HELP probe_tls_version_info Contains the TLS version used
+# TYPE probe_tls_version_info gauge
+probe_tls_version_info{version="TLS 1.3"} 1
+```
+
+You can see that the probe was successful and get many useful metrics, like latency by phase, status code, ssl status or certificate expiry in [Unix time](https://en.wikipedia.org/wiki/Unix_time).  
+The blackbox exporter also offers a tiny web interface at [localhost:9115](http://localhost:9115) for you to check out the last few probes, the loaded config and debug information. It even offers a direct link to probe `prometheus.io`. Handy if you are wondering why something does not work.
+
+## Querying multi-target exporters with Prometheus
+
+So far, so good. Congratulate yourself. The blackbox exporter works and you can manually tell it to query a remote target. You are almost there. Now you need to tell Prometheus to do the queries for us.  
+
+Below you find a minimal prometheus config. It is telling Prometheus to scrape the exporter itself as we did [before](#query-exporter) using `curl 'localhost:9115/metrics'`:
+
+NOTE: If you use Docker for Mac or Docker for Windows, you can’t use `localhost:9115` in the last line, but must use `host.docker.internal:9115`. This has to do with the virtual machines used to implement Docker on those operating systems. You should not use this in production.
+
+`prometheus.yml` for Linux:
+
+```yaml
+global:
+  scrape_interval: 5s
+
+scrape_configs:
+- job_name: blackbox # To get metrics about the exporter itself
+  metrics_path: /metrics
+  static_configs:
+    - targets:
+      - localhost:9115
+```
+
+`prometheus.yml` for macOS and Windows:
+
+```yaml
+global:
+  scrape_interval: 5s
+
+scrape_configs:
+- job_name: blackbox # To get metrics about the exporter itself
+  metrics_path: /metrics
+  static_configs:
+    - targets:
+      - host.docker.internal:9115
+```
+
+Now run a Prometheus container and tell it to mount our config file from above. Because of the way networking on the host is addressable from the container you need to use a slightly different command on Linux than on MacOS and Windows.:
+
+<a name=run-prometheus></a>
+
+Run Prometheus on Linux (don’t use `--network="host"` in production):
+
+```bash
+docker \
+  run --network="host"\
+  --mount type=bind,source="$(pwd)"/prometheus.yml,target=/prometheus.yml,readonly \
+  prom/prometheus \
+  --config.file="/prometheus.yml"
+```
+
+Run Prometheus on MacOS and Windows:
+
+```bash
+docker \
+  run -p 9090:9090 \
+  --mount type=bind,source="$(pwd)"/prometheus.yml,target=/prometheus.yml,readonly \
+  prom/prometheus \
+  --config.file="/prometheus.yml"
+```
+
+This command works similarly to [running the blackbox exporter using a config file](#run-exporter).
+
+If everything worked, you should be able to go to [localhost:9090/targets](http://localhost:9090/targets) and see under `blackbox` an endpoint with the state `UP` in green. If you get a red `DOWN` make sure that the blackbox exporter you started [above](#run-exporter) is still running. If you see nothing or a yellow `UNKNOWN` you are really fast and need to give it a few more seconds before reloading your browser’s tab.
+
+To tell Prometheus to query `"localhost:9115/probe?target=prometheus.io&module=http_2xx"` you add another scrape job `blackbox-http` where you set the `metrics_path` to `/probe` and the parameters under `params:` in the Prometheus config file `prometheus.yml`:
+
+<a name="prometheus-config"></a>
+
+```yaml
+global:
+  scrape_interval: 5s
+
+scrape_configs:
+- job_name: blackbox # To get metrics about the exporter itself
+  metrics_path: /metrics
+  static_configs:
+    - targets:
+      - localhost:9115   # For Windows and macOS replace with - host.docker.internal:9115
+
+- job_name: blackbox-http # To get metrics about the exporter’s targets
+  metrics_path: /probe
+  params:
+    module: [http_2xx]
+    target: [prometheus.io]
+  static_configs:
+    - targets:
+      - localhost:9115   # For Windows and macOS replace with - host.docker.internal:9115
+```
+
+After saving the config file switch to the terminal with your Prometheus docker container and stop it by pressing `ctrl+C` and start it again to reload the configuration by using the existing [command](#run-prometheus).
+
+The terminal should return the message `"Server is ready to receive web requests."` and after a few seconds you should start to see colourful graphs in [your Prometheus](http://localhost:9090/graph?g0.range_input=5m&g0.stacked=0&g0.expr=probe_http_duration_seconds&g0.tab=0).
+
+This works, but it has a few disadvantages:
+
+1. The actual targets are up in the param config, which is very unusual and hard to understand later.
+1. The `instance` label has the value of the blackbox exporter’s address which is technically true, but not what we are interested in.
+1. We can’t see which URL we probed. This is unpractical and will also mix up different metrics into one if we probe several URLs.
+
+To fix this, we will use [relabeling](/docs/prometheus/latest/configuration/configuration/#relabel_config).
+Relabeling is useful here because behind the scenes many things in Prometheus are configured with internal labels.
+The details are complicated and out of scope for this guide. Hence we will limit ourselves to the necessary. But if you want to know more check out this [talk](https://www.youtube.com/watch?v=b5-SvvZ7AwI). For now it suffices if you understand this:
+
+* All labels starting with `__` are dropped after the scrape. Most internal labels start with `__`.
+* You can set internal labels that are called `__param_<name>`. Those set URL parameter with the key `<name>` for the scrape request.
+* There is an internal label `__address__` which is set by the `targets` under `static_configs` and whose value is the hostname for the scrape request. By default it is later used to set the value for the label `instance`, which is attached to each metric and tells you where the metrics came from.
+
+Here is the config you will use to do that. Don’t worry if this is a bit much at once, we will go through it step by step:
+
+```yaml
+global:
+  scrape_interval: 5s
+
+scrape_configs:
+- job_name: blackbox # To get metrics about the exporter itself
+  metrics_path: /metrics
+  static_configs:
+    - targets:
+      - localhost:9115   # For Windows and macOS replace with - host.docker.internal:9115
+
+- job_name: blackbox-http # To get metrics about the exporter’s targets
+  metrics_path: /probe
+  params:
+    module: [http_2xx]
+  static_configs:
+    - targets:
+      - http://prometheus.io    # Target to probe with http
+      - https://prometheus.io   # Target to probe with https
+      - http://example.com:8080 # Target to probe with http on port 8080
+  relabel_configs:
+    - source_labels: [__address__]
+      target_label: __param_target
+    - source_labels: [__param_target]
+      target_label: instance
+    - target_label: __address__
+      replacement: localhost:9115  # The blackbox exporter’s real hostname:port. For Windows and macOS replace with - host.docker.internal:9115
+```
+
+So what is new compared to the [last config](#prometheus-config)?
+
+`params` does not include `target` anymore. Instead we add the actual targets under `static configs:` `targets`. We also use several because we can do that now:
+
+```yaml
+  params:
+    module: [http_2xx]
+  static_configs:
+    - targets:
+      - http://prometheus.io    # Target to probe with http
+      - https://prometheus.io   # Target to probe with https
+      - http://example.com:8080 # Target to probe with http on port 8080
+```
+
+`relabel_configs` contains the new relabeling rules:
+
+```yaml
+  relabel_configs:
+    - source_labels: [__address__]
+      target_label: __param_target
+    - source_labels: [__param_target]
+      target_label: instance
+    - target_label: __address__
+      replacement: localhost:9115  # The blackbox exporter’s real hostname:port. For Windows and macOS replace with - host.docker.internal:9115
+```
+
+Before applying the relabeling rules, the URI of a request Prometheus would make would look like this:
+`"http://prometheus.io/probe?module=http_2xx"`. After relabeling it will look like this `"http://localhost:9115/probe?target=http://prometheus.io&module=http_2xx"`.
+
+Now let us explore how each rule does that:
+
+First we take the values from the label `__address__` (which contain the values from `targets`) and write them to a new label `__param_target` which will add a parameter `target` to the Prometheus scrape requests:
+
+```yaml
+  relabel_configs:
+    - source_labels: [__address__]
+      target_label: __param_target
+```
+
+After this our imagined Prometheus request URI has now a target parameter: `"http://prometheus.io/probe?target=http://prometheus.io&module=http_2xx"`.
+
+Then we take the values from the label `__param_target` and create a label instance with the values.
+
+```yaml
+  relabel_configs:
+    - source_labels: [__param_target]
+      target_label: instance
+```
+
+Our request will not change, but the metrics that come back from our request will now bear a label `instance="http://prometheus.io"`.
+
+After that we write the value `localhost:9115` (the URI of our exporter) to the label `__address__`. This will be used as the hostname and port for the Prometheus scrape requests. So that it queries the exporter and not the target URI directly.
+
+```yaml
+  relabel_configs:
+    - target_label: __address__
+      replacement: localhost:9115  # The blackbox exporter’s real hostname:port. For Windows and macOS replace with - host.docker.internal:9115
+```
+
+Our request is now `"localhost:9115/probe?target=http://prometheus.io&module=http_2xx"`. This way we can have the actual targets there, get them as `instance` label values while letting Prometheus make a request against the blackbox exporter.
+
+Often people combine these with a specific service discovery. Check out the [configuration documentation](/docs/prometheus/latest/configuration/configuration) for more information. Using them is no problem, as these write into the `__address__` label just like `targets` defined under `static_configs`.
+
+That is it. Restart the Prometheus docker container and look at your [metrics](http://localhost:9090/graph?g0.range_input=30m&g0.stacked=0&g0.expr=probe_http_duration_seconds&g0.tab=0). Pay attention that you selected the period of time when the metrics were actually collected.
+
+# Summary
+
+In this guide, you learned how the multi-target exporter pattern works, how to run a blackbox exporter with a customised module, and to configure Prometheus using relabeling to scrape metrics with prober labels.
diff --git a/docs/guides/node-exporter.md b/docs/guides/node-exporter.md
new file mode 100644
index 00000000..95785899
--- /dev/null
+++ b/docs/guides/node-exporter.md
@@ -0,0 +1,109 @@
+---
+title: Monitoring Linux host metrics with the Node Exporter
+---
+
+# Monitoring Linux host metrics with the Node Exporter
+
+The Prometheus [**Node Exporter**](https://github.com/prometheus/node_exporter) exposes a wide variety of hardware- and kernel-related metrics.
+
+In this guide, you will:
+
+* Start up a Node Exporter on `localhost`
+* Start up a Prometheus instance on `localhost` that's configured to scrape metrics from the running Node Exporter
+
+NOTE: While the Prometheus Node Exporter is for *nix systems, there is the [Windows exporter](https://github.com/prometheus-community/windows_exporter) for Windows that serves an analogous purpose.
+
+## Installing and running the Node Exporter
+
+The Prometheus Node Exporter is a single static binary that you can install [via tarball](#tarball-installation). Once you've downloaded it from the Prometheus [downloads page](/download#node_exporter) extract it, and run it:
+
+```bash
+# NOTE: Replace the URL with one from the above mentioned "downloads" page.
+# <VERSION>, <OS>, and <ARCH> are placeholders.
+wget https://github.com/prometheus/node_exporter/releases/download/v<VERSION>/node_exporter-<VERSION>.<OS>-<ARCH>.tar.gz
+tar xvfz node_exporter-*.*-amd64.tar.gz
+cd node_exporter-*.*-amd64
+./node_exporter
+```
+
+You should see output like this indicating that the Node Exporter is now running and exposing metrics on port 9100:
+
+```
+INFO[0000] Starting node_exporter (version=0.16.0, branch=HEAD, revision=d42bd70f4363dced6b77d8fc311ea57b63387e4f)  source="node_exporter.go:82"
+INFO[0000] Build context (go=go1.9.6, user=root@a67a9bc13a69, date=20180515-15:53:28)  source="node_exporter.go:83"
+INFO[0000] Enabled collectors:                           source="node_exporter.go:90"
+INFO[0000]  - boottime                                   source="node_exporter.go:97"
+...
+INFO[0000] Listening on :9100                            source="node_exporter.go:111"
+```
+
+## Node Exporter metrics
+
+Once the Node Exporter is installed and running, you can verify that metrics are being exported by cURLing the `/metrics` endpoint:
+
+```bash
+curl http://localhost:9100/metrics
+```
+
+You should see output like this:
+
+```
+# HELP go_gc_duration_seconds A summary of the GC invocation durations.
+# TYPE go_gc_duration_seconds summary
+go_gc_duration_seconds{quantile="0"} 3.8996e-05
+go_gc_duration_seconds{quantile="0.25"} 4.5926e-05
+go_gc_duration_seconds{quantile="0.5"} 5.846e-05
+# etc.
+```
+
+Success! The Node Exporter is now exposing metrics that Prometheus can scrape, including a wide variety of system metrics further down in the output (prefixed with `node_`). To view those metrics (along with help and type information):
+
+```bash
+curl http://localhost:9100/metrics | grep "node_"
+```
+
+## Configuring your Prometheus instances
+
+Your locally running Prometheus instance needs to be properly configured in order to access Node Exporter metrics. The following [`prometheus.yml`](../../prometheus/latest/configuration/configuration/) example configuration file will tell the Prometheus instance to scrape, and how frequently, from the Node Exporter via `localhost:9100`:
+
+<a id="config"></a>
+
+```yaml
+global:
+  scrape_interval: 15s
+
+scrape_configs:
+- job_name: node
+  static_configs:
+  - targets: ['localhost:9100']
+```
+
+To install Prometheus, [download the latest release](/download) for your platform and untar it:
+
+```bash
+wget https://github.com/prometheus/prometheus/releases/download/v*/prometheus-*.*-amd64.tar.gz
+tar xvf prometheus-*.*-amd64.tar.gz
+cd prometheus-*.*
+```
+
+Once Prometheus is installed you can start it up, using the `--config.file` flag to point to the Prometheus configuration that you created [above](#config):
+
+```bash
+./prometheus --config.file=./prometheus.yml
+```
+
+## Exploring Node Exporter metrics through the Prometheus expression browser
+
+Now that Prometheus is scraping metrics from a running Node Exporter instance, you can explore those metrics using the Prometheus UI (aka the [expression browser](/docs/visualization/browser)). Navigate to `localhost:9090/graph` in your browser and use the main expression bar at the top of the page to enter expressions. The expression bar looks like this:
+
+![Prometheus expressions browser](/assets/prometheus-expression-bar.png)
+
+Metrics specific to the Node Exporter are prefixed with `node_` and include metrics like `node_cpu_seconds_total` and `node_exporter_build_info`.
+
+Click on the links below to see some example metrics:
+
+Metric | Meaning
+:------|:-------
+[`rate(node_cpu_seconds_total{mode="system"}[1m])`](http://localhost:9090/graph?g0.range_input=1h&g0.expr=rate(node_cpu_seconds_total%7Bmode%3D%22system%22%7D%5B1m%5D)&g0.tab=1) | The average amount of CPU time spent in system mode, per second, over the last minute (in seconds)
+[`node_filesystem_avail_bytes`](http://localhost:9090/graph?g0.range_input=1h&g0.expr=node_filesystem_avail_bytes&g0.tab=1) | The filesystem space available to non-root users (in bytes)
+[`rate(node_network_receive_bytes_total[1m])`](http://localhost:9090/graph?g0.range_input=1h&g0.expr=rate(node_network_receive_bytes_total%5B1m%5D)&g0.tab=1) | The average network traffic received, per second, over the last minute (in bytes)
diff --git a/docs/guides/opentelemetry.md b/docs/guides/opentelemetry.md
new file mode 100644
index 00000000..3500658f
--- /dev/null
+++ b/docs/guides/opentelemetry.md
@@ -0,0 +1,170 @@
+---
+title: OpenTelemetry
+---
+
+# Using Prometheus as your OpenTelemetry backend
+
+Prometheus supports [OTLP](https://opentelemetry.io/docs/specs/otlp) (aka "OpenTelemetry Protocol") ingestion through [HTTP](https://opentelemetry.io/docs/specs/otlp/#otlphttp).
+
+## Enable the OTLP receiver
+
+By default, the OTLP receiver is disabled, similarly to the Remote Write receiver.
+This is because Prometheus can work without any authentication, so it would not be
+safe to accept incoming traffic unless explicitly configured.
+
+To enable the receiver you need to toggle the CLI flag `--web.enable-otlp-receiver`. 
+This will cause Prometheus to serve OTLP metrics receiving on HTTP `/api/v1/otlp/v1/metrics` path. 
+
+```shell
+$ prometheus --web.enable-otlp-receiver
+```
+
+## Send OpenTelemetry Metrics to the Prometheus Server
+
+Generally you need to tell the source of the OTLP metrics traffic about Prometheus endpoint and the fact that the
+[HTTP](https://opentelemetry.io/docs/specs/otlp/#otlphttp) mode of OTLP should be used (gRPC is usually a default).
+
+OpenTelemetry SDKs and instrumentation libraries can be usually configured via [standard environment variables](https://opentelemetry.io/docs/languages/sdk-configuration/). The following are the OpenTelemetry variables needed to send OpenTelemetry metrics to a Prometheus server on localhost:
+
+```shell
+export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://localhost:9090/api/v1/otlp/v1/metrics
+```
+
+Turn off traces and logs:
+
+```shell
+export OTEL_TRACES_EXPORTER=none
+export OTEL_LOGS_EXPORTER=none
+```
+
+The default push interval for OpenTelemetry metrics is 60 seconds. The following will set a 15 second push interval:
+
+```shell
+export OTEL_METRIC_EXPORT_INTERVAL=15000
+```
+
+If your instrumentation library does not provide `service.name` and `service.instance.id` out-of-the-box, it is highly recommended to set them.
+
+```shell
+export OTEL_SERVICE_NAME="my-example-service"
+export OTEL_RESOURCE_ATTRIBUTES="service.instance.id=$(uuidgen)"
+```
+
+The above assumes that `uuidgen` command is available on your system. Make sure that `service.instance.id` is unique for each instance, and that a new `service.instance.id` is generated whenever a resource attribute chances. The [recommended](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/resource) way is to generate a new UUID on each startup of an instance.
+
+## Configuring Prometheus
+
+This section explains various recommended configuration aspects of Prometheus server to enable and tune your OpenTelemetry flow.
+
+See the example Prometheus configuration [file](https://github.com/prometheus/prometheus/blob/main/documentation/examples/prometheus-otlp.yml)
+we will use in the below section.
+
+### Enable out-of-order ingestion
+
+There are multiple reasons why you might want to enable out-of-order ingestion.
+
+For example, the OpenTelemetry collector encourages batching and you could have multiple replicas of the collector sending data to Prometheus. Because there is no mechanism ordering those samples they could get out-of-order.
+
+To enable out-of-order ingestion you need to extend the Prometheus configuration file with the following:
+
+```shell
+storage:
+  tsdb:
+    out_of_order_time_window: 30m
+```
+
+30 minutes of out-of-order have been enough for most cases but don't hesitate to adjust this value to your needs.
+
+### Promoting resource attributes
+
+Based on experience and conversations with our community, we've found that out of all the commonly seen resource attributes,
+there are certain worth attaching to all your OTLP metrics.
+
+By default, Prometheus won't be promoting any attributes. If you'd like to promote any
+of them, you can do so in this section of the Prometheus configuration file. The following
+snippet shares the best practice set of attributes to promote:
+
+```yaml
+otlp:
+  # Recommended attributes to be promoted to labels.
+  promote_resource_attributes:
+    - service.instance.id
+    - service.name
+    - service.namespace
+    - service.version
+    - cloud.availability_zone
+    - cloud.region
+    - container.name
+    - deployment.environment
+    - deployment.environment.name
+    - k8s.cluster.name
+    - k8s.container.name
+    - k8s.cronjob.name
+    - k8s.daemonset.name
+    - k8s.deployment.name
+    - k8s.job.name
+    - k8s.namespace.name
+    - k8s.pod.name
+    - k8s.replicaset.name
+    - k8s.statefulset.name
+```
+
+## Including resource attributes at query time
+
+All non-promoted, more verbose or unique labels are attached to a special `target_info`.
+
+You can use this metric to join some labels on query time.
+
+An example of such a query can look like the following:
+
+```promql
+rate(http_server_request_duration_seconds_count[2m])
+* on (job, instance) group_left (k8s_cluster_name)
+target_info
+```
+
+What happens in this query is that the time series resulting from `rate(http_server_request_duration_seconds_count[2m])` are augmented with the `k8s_cluster_name` label from the `target_info` series that share the same `job` and `instance` labels.
+In other words, the `job` and `instance` labels are shared between `http_server_request_duration_seconds_count` and `target_info`, akin to SQL foreign keys.
+The `k8s_cluster_name` label, On the other hand, corresponds to the OTel resource attribute `k8s.cluster.name` (Prometheus converts dots to underscores).
+
+So, what is the relation between the `target_info` metric and OTel resource attributes?
+When Prometheus processes an OTLP write request, and provided that contained resources include the attributes `service.instance.id` and/or `service.name`, Prometheus generates the info metric `target_info` for every (OTel) resource.
+It adds to each such `target_info` series the label `instance` with the value of the `service.instance.id` resource attribute, and the label `job` with the value of the `service.name` resource attribute.
+If the resource attribute `service.namespace` exists, it's prefixed to the `job` label value (i.e., `<service.namespace>/<service.name>`).
+
+By default `service.name`, `service.namespace` and `service.instance.id` themselves are not added to `target_info`, because they are converted into `job` and `instance`. However the following configuration parameter can be enabled to add them to `target_info` directly (going through normalization to replace dots with underscores, if `otlp.translation_strategy` is `UnderscoreEscapingWithSuffixes`) on top of the conversion into `job` and `instance`.
+
+```
+otlp:
+  keep_identifying_resource_attributes: true
+```
+
+The rest of the resource attributes are also added as labels to the `target_info` series, names converted to Prometheus format (e.g. dots converted to underscores) if `otlp.translation_strategy` is `UnderscoreEscapingWithSuffixes`.
+If a resource lacks both `service.instance.id` and `service.name` attributes, no corresponding `target_info` series is generated.
+
+For each of a resource's OTel metrics, Prometheus converts it to a corresponding Prometheus time series, and (if `target_info` is generated) adds the right `instance` and `job` labels.
+
+## UTF-8
+
+From the 3.x version, Prometheus supports UTF-8 for metric names and labels, so [Prometheus normalization translator package from OpenTelemetry](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/pkg/translator/prometheus) can be omitted.
+
+UTF-8 is enabled by default in Prometheus storage and UI, but you need to `translation_strategy` for OTLP metric receiver, which by default is set to old normalization `UnderscoreEscapingWithSuffixes`.
+
+Setting it to `NoUTF8EscapingWithSuffixes`, which we recommend, will disable changing special characters to `_` which allows native use of OpenTelemetry metric format, especially with [the semantic conventions](https://opentelemetry.io/docs/specs/semconv/general/metrics/). Note that special suffixes like units and `_total` for counters will be attached. There is [ongoing work to have no suffix generation](https://github.com/prometheus/proposals/pull/39), stay tuned for that. 
+
+```
+otlp:
+  # Ingest OTLP data keeping UTF-8 characters in metric/label names.
+  translation_strategy: NoUTF8EscapingWithSuffixes
+```
+
+## Delta Temporality
+
+The [OpenTelemetry specification says](https://opentelemetry.io/docs/specs/otel/metrics/data-model/#temporality) that both Delta temporality and Cumulative temporality are supported. While delta temporality is common in systems like statsd and graphite, cumulative temporality is the default in Prometheus.
+
+Today, Prometheus embeds the [delta to cumulative processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/deltatocumulativeprocessor) from [OpenTelemetry-Collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib), which is capable of ingesting deltas and transforming them into the equivalent cumulative representation before storing in Prometheus' TSDB.
+
+This feature is ***experimental***, so start Prometheus with the feature-flag `otlp-deltatocumulative` enabled to use it.
+
+The team is still working on a more efficient way of handling OTLP deltas.
diff --git a/docs/guides/query-log.md b/docs/guides/query-log.md
new file mode 100644
index 00000000..f27fc817
--- /dev/null
+++ b/docs/guides/query-log.md
@@ -0,0 +1,173 @@
+---
+title: Query Log
+sort_rank: 1
+---
+
+# Using the Prometheus query log
+
+Prometheus has the ability to log all the queries run by the engine to a log
+file, as of 2.16.0. This guide demonstrates how to use that log file, which
+fields it contains, and provides advanced tips about how to operate the log
+file.
+
+## Enable the query log
+
+The query log can be toggled at runtime. It can therefore be activated when you
+want to investigate slownesses or high load on your Prometheus instance.
+
+To enable or disable the query log, two steps are needed:
+
+1. Adapt the configuration to add or remove the query log configuration.
+1. Reload the Prometheus server configuration.
+
+### Logging all the queries to a file
+
+This example demonstrates how to log all the queries to
+a file called `/prometheus/query.log`. We will assume that `/prometheus` is the
+data directory and that Prometheus has write access to it.
+
+First, adapt the `prometheus.yml` configuration file:
+
+```yaml
+global:
+  scrape_interval:     15s
+  evaluation_interval: 15s
+  query_log_file: /prometheus/query.log
+scrape_configs:
+- job_name: 'prometheus'
+  static_configs:
+  - targets: ['localhost:9090']
+```
+
+Then, [reload](/docs/prometheus/latest/management_api/#reload) the Prometheus configuration:
+
+
+```shell
+$ curl -X POST http://127.0.0.1:9090/-/reload
+```
+
+Or, if Prometheus is not launched with `--web.enable-lifecycle`, and you're not
+running on Windows, you can trigger the reload by sending a SIGHUP to the
+Prometheus process.
+
+
+The file `/prometheus/query.log` should now exist and all the queries
+will be logged to that file.
+
+To disable the query log, repeat the operation but remove `query_log_file` from
+the configuration.
+
+## Verifying if the query log is enabled
+
+Prometheus conveniently exposes metrics that indicates if the query log is
+enabled and working:
+
+```
+# HELP prometheus_engine_query_log_enabled State of the query log.
+# TYPE prometheus_engine_query_log_enabled gauge
+prometheus_engine_query_log_enabled 0
+# HELP prometheus_engine_query_log_failures_total The number of query log failures.
+# TYPE prometheus_engine_query_log_failures_total counter
+prometheus_engine_query_log_failures_total 0
+```
+
+The first metric, `prometheus_engine_query_log_enabled` is set to 1 of the
+query log is enabled, and 0 otherwise.
+The second one, `prometheus_engine_query_log_failures_total`, indicates the
+number of queries that could not be logged.
+
+## Format of the query log
+
+The query log is a JSON-formatted log. Here is an overview of the fields
+present for a query:
+
+```
+{
+    "params": {
+        "end": "2020-02-08T14:59:50.368Z",
+        "query": "up == 0",
+        "start": "2020-02-08T13:59:50.368Z",
+        "step": 5
+    },
+    "stats": {
+        "timings": {
+            "evalTotalTime": 0.000447452,
+            "execQueueTime": 7.599e-06,
+            "execTotalTime": 0.000461232,
+            "innerEvalTime": 0.000427033,
+            "queryPreparationTime": 1.4177e-05,
+            "resultSortTime": 6.48e-07
+        }
+    },
+    "ts": "2020-02-08T14:59:50.387Z"
+}
+```
+
+- `params`: The query. The start and end timestamp, the step and the actual
+  query statement.
+- `stats`: Statistics. Currently, it contains internal engine timers.
+- `ts`: The timestamp when the query ended.
+
+Additionally, depending on what triggered the request, you will have additional
+fields in the JSON lines.
+
+### API Queries and consoles
+
+HTTP requests contain the client IP, the method, and the path:
+
+```
+{
+    "httpRequest": {
+        "clientIP": "127.0.0.1",
+        "method": "GET",
+        "path": "/api/v1/query_range"
+    }
+}
+```
+
+The path will contain the web prefix if it is set, and can also point to a
+console.
+
+The client IP is the network IP address and does not take into consideration the
+headers like `X-Forwarded-For`. If you wish to log the original caller behind a
+proxy, you need to do so in the proxy itself.
+
+### Recording rules and alerts
+
+Recording rules and alerts contain a ruleGroup element which contains the path
+of the file and the name of the group:
+
+```
+{
+    "ruleGroup": {
+        "file": "rules.yml",
+        "name": "partners"
+    }
+}
+```
+
+
+## Rotating the query log
+
+Prometheus will not rotate the query log itself. Instead, you can use external
+tools to do so.
+
+One of those tools is logrotate. It is enabled by default on most Linux
+distributions.
+
+Here is an example of file you can add as
+`/etc/logrotate.d/prometheus`:
+
+```
+/prometheus/query.log {
+    daily
+    rotate 7
+    compress
+    delaycompress
+    postrotate
+        killall -HUP prometheus
+    endscript
+}
+```
+
+That will rotate your file daily and keep one week of history.
diff --git a/docs/guides/tls-encryption.md b/docs/guides/tls-encryption.md
new file mode 100644
index 00000000..07218e38
--- /dev/null
+++ b/docs/guides/tls-encryption.md
@@ -0,0 +1,80 @@
+---
+title: TLS encryption
+sort_rank: 1
+---
+
+# Securing Prometheus API and UI endpoints using TLS encryption
+
+Prometheus supports [Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security) (TLS) encryption for connections to Prometheus instances (i.e. to the expression browser or [HTTP API](../../prometheus/latest/querying/api)). If you would like to enforce TLS for those connections, you would need to create a specific web configuration file.
+
+NOTE: This guide is about TLS connections *to* Prometheus instances. TLS is also supported for connections *from* Prometheus instances to [scrape targets](../../prometheus/latest/configuration/configuration/#tls_config).
+
+## Pre-requisites
+
+Let's say that you already have a Prometheus instance up and running, and you
+want to adapt it. We will not cover the initial Prometheus setup in this guide.
+
+Let's say that you want to run a Prometheus instance served with TLS, available at the `example.com` domain (which you own).
+
+Let's also say that you've generated the following using [OpenSSL](https://www.digitalocean.com/community/tutorials/openssl-essentials-working-with-ssl-certificates-private-keys-and-csrs) or an analogous tool:
+
+* an SSL certificate at `/home/prometheus/certs/example.com/example.com.crt`
+* an SSL key at `/home/prometheus/certs/example.com/example.com.key`
+
+You can generate a self-signed certificate and private key using this command:
+
+```bash
+mkdir -p /home/prometheus/certs/example.com && cd /home/prometheus/certs/certs/example.com
+openssl req \
+  -x509 \
+  -newkey rsa:4096 \
+  -nodes \
+  -keyout example.com.key \
+  -out example.com.crt
+```
+
+Fill out the appropriate information at the prompts, and make sure to enter `example.com` at the `Common Name` prompt.
+
+## Prometheus configuration
+
+Below is an example [`web-config.yml`](https://prometheus.io/docs/prometheus/latest/configuration/https/) configuration file. With this configuration, Prometheus will serve all its endpoints behind TLS.
+
+```yaml
+tls_server_config:
+  cert_file: /home/prometheus/certs/example.com/example.com.crt
+  key_file: /home/prometheus/certs/example.com/example.com.key
+```
+
+To make Prometheus use this config, you will need to call it with the flag
+`--web.config.file`.
+
+
+```bash
+prometheus \
+  --config.file=/path/to/prometheus.yml \
+  --web.config.file=/path/to/web-config.yml \
+  --web.external-url=https://example.com/
+```
+
+The `--web.external-url=` flag is optional here.
+
+## Testing
+
+If you'd like to test out TLS locally using the `example.com` domain, you can add an entry to your `/etc/hosts` file that re-routes `example.com` to `localhost`:
+
+```
+127.0.0.1     example.com
+```
+
+You can then use cURL to interact with your local Prometheus setup:
+
+```bash
+curl --cacert /home/prometheus/certs/example.com/example.com.crt \
+  https://example.com/api/v1/label/job/values
+```
+
+You can connect to the Prometheus server without specifying certs using the `--insecure` or `-k` flag:
+
+```bash
+curl -k https://example.com/api/v1/label/job/values
+```
diff --git a/docs/guides/utf8.md b/docs/guides/utf8.md
new file mode 100644
index 00000000..15ccd366
--- /dev/null
+++ b/docs/guides/utf8.md
@@ -0,0 +1,122 @@
+---
+title: UTF-8 in Prometheus
+---
+
+# Introduction
+
+Versions of Prometheus before 3.0 required that metric and label names adhere to
+a strict set of character requirements. With Prometheus 3.0, all UTF-8 strings
+are valid names, but there are some manual changes needed for other parts of the ecosystem to introduce names with any UTF-8 characters.
+
+There may also be circumstances where users want to enforce the legacy character
+set, perhaps for compatibility with an older system or one that does not yet
+support UTF-8.
+
+This document guides you through the UTF-8 transition details.
+
+# Go Instrumentation 
+
+Currently, metrics created by the official Prometheus [client_golang library](https://github.com/prometheus/client_golang) will reject UTF-8 names
+by default. It is necessary to change the default validation scheme to allow
+UTF-8. The requirement to set this value will be removed in a future version of
+the common library.
+
+```golang
+import "github.com/prometheus/common/model"
+
+func init() {
+	model.NameValidationScheme = model.UTF8Validation
+}
+```
+
+If users want to enforce the legacy character set, they can set the validation
+scheme to `LegacyValidation`.
+
+Setting the validation scheme must be done before the instantiation of metrics
+and can be set on the fly if desired.
+
+## Instrumenting in other languages
+
+Other client libraries may have similar requirements to set the validation
+scheme. Check the documentation for the library you are using.
+
+# Configuring Name Validation during Scraping
+
+By default, Prometheus 3.0 accepts all UTF-8 strings as valid metric and label
+names. It is possible to override this behavior for scraped targets and reject
+names that do not conform to the legacy character set.
+
+This option can be set in the Prometheus YAML file on a global basis:
+
+```yaml
+global:
+  metric_name_validation_scheme: legacy
+```
+
+or on a per-scrape config basis:
+
+```yaml
+scrape_configs:
+  - job_name: prometheus
+    metric_name_validation_scheme: legacy
+```
+
+Scrape config settings override the global setting.
+
+## Scrape Content Negotiation for UTF-8 escaping
+
+At scrape time, the scraping system **must** pass `escaping=allow-utf-8` in the
+Accept header in order to be served UTF-8 names. If a system being scraped does
+not see this header, it will automatically convert UTF-8 names to
+legacy-compatible using underscore replacement.
+
+Scraping systems can also request a specific escaping method if desired by
+setting the `escaping` header to a different value.
+
+* `underscores`: The default: convert legacy-invalid characters to underscores.
+* `dots`: similar to UnderscoreEscaping, except that dots are converted to
+  `_dot_` and pre-existing underscores are converted to `__`. This allows for
+  round-tripping of simple metric names that also contain dots.
+* `values`: This mode prepends the name with `U__` and replaces all invalid
+  characters with the unicode value, surrounded by underscores. Single
+  underscores are replaced with double underscores. This mode allows for full
+  round-tripping of UTF-8 names with a legacy system.
+
+## Remote Write 2.0
+
+Remote Write 2.0 automatically accepts all UTF-8 names in Prometheus 3.0. There
+is no way to enforce the legacy character set validation with Remote Write 2.0.
+
+# OTLP Metrics
+
+OTLP receiver in Prometheus 3.0 still normalizes all names to Prometheus format by default. You can change this in `otlp` section of the Prometheus configuration as follows:
+
+
+    otlp:
+      # Ingest OTLP data keeping UTF-8 characters in metric/label names.
+      translation_strategy: NoUTF8EscapingWithSuffixes
+
+
+See [OpenTelemetry guide](/docs/guides/opentelemetry) for more details.
+
+
+# Querying
+
+
+Querying for metrics with UTF-8 names will require a slightly different syntax
+in PromQL.
+
+The classic query syntax will still work for legacy-compatible names:
+
+`my_metric{}`
+
+But UTF-8 names must be quoted **and** moved into the braces:
+
+`{"my.metric"}`
+
+Label names must also be quoted if they contain legacy-incompatible characters:
+
+`{"metric.name", "my.label.name"="bar"}`
+
+The metric name can appear anywhere inside the braces, but style prefers that it
+be the first term.
diff --git a/docs/instrumenting/clientlibs.md b/docs/instrumenting/clientlibs.md
new file mode 100644
index 00000000..c2e0e6cc
--- /dev/null
+++ b/docs/instrumenting/clientlibs.md
@@ -0,0 +1,55 @@
+---
+title: Client libraries
+sort_rank: 1
+---
+
+# Client libraries
+
+Before you can monitor your services, you need to add instrumentation to their
+code via one of the Prometheus client libraries. These implement the Prometheus
+[metric types](/docs/concepts/metric_types/).
+
+Choose a Prometheus client library that matches the language in which your
+application is written. This lets you define and expose internal metrics via an
+HTTP endpoint on your application’s instance:
+
+* [Go](https://github.com/prometheus/client_golang)
+* [Java or Scala](https://github.com/prometheus/client_java)
+* [Python](https://github.com/prometheus/client_python)
+* [Ruby](https://github.com/prometheus/client_ruby)
+* [Rust](https://github.com/prometheus/client_rust)
+
+Unofficial third-party client libraries:
+
+* [Bash](https://github.com/aecolley/client_bash)
+* [C](https://github.com/digitalocean/prometheus-client-c)
+* [C++](https://github.com/jupp0r/prometheus-cpp)
+* [Common Lisp](https://github.com/deadtrickster/prometheus.cl)
+* [Dart](https://github.com/tentaclelabs/prometheus_client)
+* [Delphi](https://github.com/marcobreveglieri/prometheus-client-delphi)
+* [Elixir](https://github.com/deadtrickster/prometheus.ex)
+* [Erlang](https://github.com/deadtrickster/prometheus.erl)
+* [Haskell](https://github.com/fimad/prometheus-haskell)
+* [Julia](https://github.com/fredrikekre/Prometheus.jl)
+* [Lua](https://github.com/knyar/nginx-lua-prometheus) for Nginx
+* [Lua](https://github.com/tarantool/metrics) for Tarantool
+* [.NET / C#](https://github.com/prometheus-net/prometheus-net)
+* [Node.js](https://github.com/siimon/prom-client)
+* [OCaml](https://github.com/mirage/prometheus)
+* [Perl](https://metacpan.org/pod/Net::Prometheus)
+* [PHP](https://github.com/promphp/prometheus_client_php)
+* [R](https://github.com/cfmack/pRometheus)
+
+When Prometheus scrapes your instance's HTTP endpoint, the client library
+sends the current state of all tracked metrics to the server.
+
+If no client library is available for your language, or you want to avoid
+dependencies, you may also implement one of the supported [exposition
+formats](/docs/instrumenting/exposition_formats/) yourself to expose metrics.
+
+When implementing a new Prometheus client library, please follow the
+[guidelines on writing client libraries](/docs/instrumenting/writing_clientlibs).
+Note that this document is still a work in progress. Please also consider
+consulting the [development mailing list](https://groups.google.com/forum/#!forum/prometheus-developers).
+We are happy to give advice on how to make your library as useful and
+consistent as possible.
diff --git a/docs/instrumenting/exporters.md b/docs/instrumenting/exporters.md
new file mode 100644
index 00000000..4204aace
--- /dev/null
+++ b/docs/instrumenting/exporters.md
@@ -0,0 +1,354 @@
+---
+title: Exporters and integrations
+sort_rank: 4
+---
+
+# Exporters and integrations
+
+There are a number of libraries and servers which help in exporting existing
+metrics from third-party systems as Prometheus metrics. This is useful for
+cases where it is not feasible to instrument a given system with Prometheus
+metrics directly (for example, HAProxy or Linux system stats).
+
+## Third-party exporters
+
+Some of these exporters are maintained as part of the official [Prometheus GitHub organization](https://github.com/prometheus),
+those are marked as *official*, others are externally contributed and maintained.
+
+We encourage the creation of more exporters but cannot vet all of them for
+[best practices](/docs/instrumenting/writing_exporters/).
+Commonly, those exporters are hosted outside of the Prometheus GitHub
+organization.
+
+The [exporter default
+port](https://github.com/prometheus/prometheus/wiki/Default-port-allocations)
+wiki page has become another catalog of exporters, and may include exporters
+not listed here due to overlapping functionality or still being in development.
+
+The [JMX exporter](https://github.com/prometheus/jmx_exporter) can export from a
+wide variety of JVM-based applications, for example [Kafka](http://kafka.apache.org/) and
+[Cassandra](http://cassandra.apache.org/).
+
+### Databases
+
+   * [Aerospike exporter](https://github.com/aerospike/aerospike-prometheus-exporter)
+   * [AWS RDS exporter](https://github.com/qonto/prometheus-rds-exporter)
+   * [ClickHouse exporter](https://github.com/f1yegor/clickhouse_exporter)
+   * [Consul exporter](https://github.com/prometheus/consul_exporter) (**official**)
+   * [Couchbase exporter](https://github.com/couchbase/couchbase-exporter)
+   * [CouchDB exporter](https://github.com/gesellix/couchdb-exporter)
+   * [Druid Exporter](https://github.com/opstree/druid-exporter)
+   * [Elasticsearch exporter](https://github.com/prometheus-community/elasticsearch_exporter)
+   * [EventStore exporter](https://github.com/marcinbudny/eventstore_exporter)
+   * [IoTDB exporter](https://github.com/fagnercarvalho/prometheus-iotdb-exporter)
+   * [KDB+ exporter](https://github.com/KxSystems/prometheus-kdb-exporter)
+   * [Memcached exporter](https://github.com/prometheus/memcached_exporter) (**official**)
+   * [MongoDB exporter](https://github.com/percona/mongodb_exporter)
+   * [MongoDB query exporter](https://github.com/raffis/mongodb-query-exporter)
+   * [MongoDB Node.js Driver exporter](https://github.com/christiangalsterer/mongodb-driver-prometheus-exporter)
+   * [MSSQL server exporter](https://github.com/awaragi/prometheus-mssql-exporter)
+   * [MySQL router exporter](https://github.com/rluisr/mysqlrouter_exporter)
+   * [MySQL server exporter](https://github.com/prometheus/mysqld_exporter) (**official**)
+   * [OpenTSDB Exporter](https://github.com/cloudflare/opentsdb_exporter)
+   * [Oracle DB Exporter](https://github.com/iamseth/oracledb_exporter)
+   * [PgBouncer exporter](https://github.com/prometheus-community/pgbouncer_exporter)
+   * [PostgreSQL exporter](https://github.com/prometheus-community/postgres_exporter)
+   * [Presto exporter](https://github.com/yahoojapan/presto_exporter)
+   * [ProxySQL exporter](https://github.com/percona/proxysql_exporter)
+   * [RavenDB exporter](https://github.com/marcinbudny/ravendb_exporter)
+   * [Redis exporter](https://github.com/oliver006/redis_exporter)
+   * [RethinkDB exporter](https://github.com/oliver006/rethinkdb_exporter)
+   * [SQL exporter](https://github.com/burningalchemist/sql_exporter)
+   * [Tarantool metric library](https://github.com/tarantool/metrics)
+   * [Twemproxy](https://github.com/stuartnelson3/twemproxy_exporter)
+
+### Hardware related
+   * [apcupsd exporter](https://github.com/mdlayher/apcupsd_exporter)
+   * [BIG-IP exporter](https://github.com/ExpressenAB/bigip_exporter)
+   * [Bosch Sensortec BMP/BME exporter](https://github.com/David-Igou/bsbmp-exporter)
+   * [Collins exporter](https://github.com/soundcloud/collins_exporter)
+   * [Dell Hardware OMSA exporter](https://github.com/galexrt/dellhw_exporter)
+   * [Disk usage exporter](https://github.com/dundee/disk_usage_exporter)
+   * [Fortigate exporter](https://github.com/bluecmd/fortigate_exporter)
+   * [IBM Z HMC exporter](https://github.com/zhmcclient/zhmc-prometheus-exporter)
+   * [IoT Edison exporter](https://github.com/roman-vynar/edison_exporter)
+   * [InfiniBand exporter](https://github.com/treydock/infiniband_exporter)
+   * [IPMI exporter](https://github.com/soundcloud/ipmi_exporter)
+   * [knxd exporter](https://github.com/RichiH/knxd_exporter)
+   * [Modbus exporter](https://github.com/RichiH/modbus_exporter)
+   * [Netgear Cable Modem Exporter](https://github.com/ickymettle/netgear_cm_exporter)
+   * [Netgear Router exporter](https://github.com/DRuggeri/netgear_exporter)
+   * [Network UPS Tools (NUT) exporter](https://github.com/DRuggeri/nut_exporter)
+   * [Node/system metrics exporter](https://github.com/prometheus/node_exporter) (**official**)
+   * [NVIDIA GPU exporter](https://github.com/mindprince/nvidia_gpu_prometheus_exporter)
+   * [ProSAFE exporter](https://github.com/dalance/prosafe_exporter)
+   * [SmartRAID exporter](https://gitlab.com/calestyo/prometheus-smartraid-exporter)
+   * [Waveplus Radon Sensor Exporter](https://github.com/jeremybz/waveplus_exporter)
+   * [Weathergoose Climate Monitor Exporter](https://github.com/branttaylor/watchdog-prometheus-exporter)
+   * [Windows exporter](https://github.com/prometheus-community/windows_exporter)
+   * [Intel® Optane™ Persistent Memory Controller Exporter](https://github.com/intel/ipmctl-exporter)
+
+### Issue trackers and continuous integration
+
+   * [Bamboo exporter](https://github.com/AndreyVMarkelov/bamboo-prometheus-exporter)
+   * [Bitbucket exporter](https://github.com/AndreyVMarkelov/prom-bitbucket-exporter)
+   * [Confluence exporter](https://github.com/AndreyVMarkelov/prom-confluence-exporter)
+   * [Jenkins exporter](https://github.com/lovoo/jenkins_exporter)
+   * [JIRA exporter](https://github.com/AndreyVMarkelov/jira-prometheus-exporter)
+
+### Messaging systems
+   * [Beanstalkd exporter](https://github.com/messagebird/beanstalkd_exporter)
+   * [EMQ exporter](https://github.com/nuvo/emq_exporter)
+   * [Gearman exporter](https://github.com/bakins/gearman-exporter)
+   * [IBM MQ exporter](https://github.com/ibm-messaging/mq-metric-samples/tree/master/cmd/mq_prometheus)
+   * [Kafka exporter](https://github.com/danielqsj/kafka_exporter)
+   * [NATS exporter](https://github.com/nats-io/prometheus-nats-exporter)
+   * [NSQ exporter](https://github.com/lovoo/nsq_exporter)
+   * [Mirth Connect exporter](https://github.com/vynca/mirth_exporter)
+   * [MQTT blackbox exporter](https://github.com/inovex/mqtt_blackbox_exporter)
+   * [MQTT2Prometheus](https://github.com/hikhvar/mqtt2prometheus)
+   * [RabbitMQ exporter](https://github.com/kbudde/rabbitmq_exporter)
+   * [RabbitMQ Management Plugin exporter](https://github.com/deadtrickster/prometheus_rabbitmq_exporter)
+   * [RocketMQ exporter](https://github.com/apache/rocketmq-exporter)
+   * [Solace exporter](https://github.com/solacecommunity/solace-prometheus-exporter)
+
+### Storage
+   * [Ceph exporter](https://github.com/digitalocean/ceph_exporter)
+   * [Ceph RADOSGW exporter](https://github.com/blemmenes/radosgw_usage_exporter)
+   * [Gluster exporter](https://github.com/ofesseler/gluster_exporter)
+   * [GPFS exporter](https://github.com/treydock/gpfs_exporter)
+   * [Hadoop HDFS FSImage exporter](https://github.com/marcelmay/hadoop-hdfs-fsimage-exporter)
+   * [HPE CSI info metrics provider](https://scod.hpedev.io/csi_driver/metrics.html)
+   * [HPE storage array exporter](https://hpe-storage.github.io/array-exporter/)
+   * [Lustre exporter](https://github.com/HewlettPackard/lustre_exporter)
+   * [NetApp E-Series exporter](https://github.com/treydock/eseries_exporter)
+   * [Pure Storage exporter](https://github.com/PureStorage-OpenConnect/pure-exporter)
+   * [ScaleIO exporter](https://github.com/syepes/sio2prom)
+   * [Tivoli Storage Manager/IBM Spectrum Protect exporter](https://github.com/treydock/tsm_exporter)
+
+### HTTP
+   * [Apache exporter](https://github.com/Lusitaniae/apache_exporter)
+   * [HAProxy exporter](https://github.com/prometheus/haproxy_exporter) (**official**)
+   * [Nginx metric library](https://github.com/knyar/nginx-lua-prometheus)
+   * [Nginx VTS exporter](https://github.com/sysulq/nginx-vts-exporter)
+   * [Passenger exporter](https://github.com/stuartnelson3/passenger_exporter)
+   * [Squid exporter](https://github.com/boynux/squid-exporter)
+   * [Tinyproxy exporter](https://github.com/gmm42/tinyproxy_exporter)
+   * [Varnish exporter](https://github.com/jonnenauha/prometheus_varnish_exporter)
+   * [WebDriver exporter](https://github.com/mattbostock/webdriver_exporter)
+
+### APIs
+   * [AWS ECS exporter](https://github.com/slok/ecs-exporter)
+   * [AWS Health exporter](https://github.com/Jimdo/aws-health-exporter)
+   * [AWS SQS exporter](https://github.com/jmal98/sqs_exporter)
+   * [AWS SQS Prometheus exporter](https://github.com/jmriebold/sqs-prometheus-exporter)
+   * [Azure Health exporter](https://github.com/FXinnovation/azure-health-exporter)
+   * [BigBlueButton](https://github.com/greenstatic/bigbluebutton-exporter)
+   * [Cloudflare exporter](https://gitlab.com/gitlab-org/cloudflare_exporter)
+   * [Cryptowat exporter](https://github.com/nbarrientos/cryptowat_exporter)
+   * [DigitalOcean exporter](https://github.com/metalmatze/digitalocean_exporter)
+   * [Docker Cloud exporter](https://github.com/infinityworks/docker-cloud-exporter)
+   * [Docker Hub exporter](https://github.com/infinityworks/docker-hub-exporter)
+   * [Fastly exporter](https://github.com/peterbourgon/fastly-exporter)
+   * [GitHub exporter](https://github.com/githubexporter/github-exporter)
+   * [Gmail exporter](https://github.com/jamesread/prometheus-gmail-exporter/)
+   * [GraphQL exporter](https://github.com/ricardbejarano/graphql_exporter)
+   * [InstaClustr exporter](https://github.com/fcgravalos/instaclustr_exporter)
+   * [Mozilla Observatory exporter](https://github.com/Jimdo/observatory-exporter)
+   * [OpenWeatherMap exporter](https://github.com/RichiH/openweathermap_exporter)
+   * [Pagespeed exporter](https://github.com/foomo/pagespeed_exporter)
+   * [Rancher exporter](https://github.com/infinityworks/prometheus-rancher-exporter)
+   * [Speedtest exporter](https://github.com/nlamirault/speedtest_exporter)
+   * [Tankerkönig API Exporter](https://github.com/lukasmalkmus/tankerkoenig_exporter)
+
+### Logging
+   * [Fluentd exporter](https://github.com/V3ckt0r/fluentd_exporter)
+   * [Google's mtail log data extractor](https://github.com/google/mtail)
+   * [Grok exporter](https://github.com/fstab/grok_exporter)
+
+### FinOps
+   * [AWS Cost Exporter](https://github.com/electrolux-oss/aws-cost-exporter)
+   * [Azure Cost Exporter](https://github.com/electrolux-oss/azure-cost-exporter)
+   * [Kubernetes Cost Exporter](https://github.com/electrolux-oss/kubernetes-cost-exporter)
+
+### Other monitoring systems
+   * [Akamai Cloudmonitor exporter](https://github.com/ExpressenAB/cloudmonitor_exporter)
+   * [Alibaba Cloudmonitor exporter](https://github.com/aylei/aliyun-exporter)
+   * [AWS CloudWatch exporter](https://github.com/prometheus/cloudwatch_exporter) (**official**)
+   * [Azure Monitor exporter](https://github.com/RobustPerception/azure_metrics_exporter)
+   * [Cloud Foundry Firehose exporter](https://github.com/cloudfoundry-community/firehose_exporter)
+   * [Collectd exporter](https://github.com/prometheus/collectd_exporter) (**official**)
+   * [Google Stackdriver exporter](https://github.com/frodenas/stackdriver_exporter)
+   * [Graphite exporter](https://github.com/prometheus/graphite_exporter) (**official**)
+   * [Heka dashboard exporter](https://github.com/docker-infra/heka_exporter)
+   * [Heka exporter](https://github.com/imgix/heka_exporter)
+   * [Huawei Cloudeye exporter](https://github.com/huaweicloud/cloudeye-exporter)
+   * [InfluxDB exporter](https://github.com/prometheus/influxdb_exporter) (**official**)
+   * [ITM exporter](https://github.com/rafal-szypulka/itm_exporter)
+   * [Java GC exporter](https://github.com/loyispa/jgc_exporter)
+   * [JavaMelody exporter](https://github.com/fschlag/javamelody-prometheus-exporter)
+   * [JMX exporter](https://github.com/prometheus/jmx_exporter) (**official**)
+   * [Munin exporter](https://github.com/pvdh/munin_exporter)
+   * [Nagios / Naemon exporter](https://github.com/Griesbacher/Iapetos)
+   * [Neptune Apex exporter](https://github.com/dl-romero/neptune_exporter)
+   * [New Relic exporter](https://github.com/mrf/newrelic_exporter)
+   * [NRPE exporter](https://github.com/robustperception/nrpe_exporter)
+   * [Osquery exporter](https://github.com/zwopir/osquery_exporter)
+   * [OTC CloudEye exporter](https://github.com/tiagoReichert/otc-cloudeye-prometheus-exporter)
+   * [Pingdom exporter](https://github.com/giantswarm/prometheus-pingdom-exporter)
+   * [Promitor (Azure Monitor)](https://promitor.io)
+   * [scollector exporter](https://github.com/tgulacsi/prometheus_scollector)
+   * [Sensu exporter](https://github.com/reachlin/sensu_exporter)
+   * [site24x7_exporter](https://github.com/svenstaro/site24x7_exporter)
+   * [SNMP exporter](https://github.com/prometheus/snmp_exporter) (**official**)
+   * [StatsD exporter](https://github.com/prometheus/statsd_exporter) (**official**)
+   * [TencentCloud monitor exporter](https://github.com/tencentyun/tencentcloud-exporter)
+   * [ThousandEyes exporter](https://github.com/sapcc/1000eyes_exporter)
+   * [StatusPage exporter](https://github.com/sergeyshevch/statuspage-exporter)
+
+### Miscellaneous
+
+   * [ACT Fibernet Exporter](https://git.captnemo.in/nemo/prometheus-act-exporter)
+   * [BIND exporter](https://github.com/prometheus-community/bind_exporter)
+   * [BIND query exporter](https://github.com/DRuggeri/bind_query_exporter)
+   * [Bitcoind exporter](https://github.com/LePetitBloc/bitcoind-exporter)
+   * [Blackbox exporter](https://github.com/prometheus/blackbox_exporter) (**official**)
+   * [Bungeecord exporter](https://github.com/weihao/bungeecord-prometheus-exporter)
+   * [BOSH exporter](https://github.com/cloudfoundry-community/bosh_exporter)
+   * [cAdvisor](https://github.com/google/cadvisor)
+   * [Cachet exporter](https://github.com/ContaAzul/cachet_exporter)
+   * [ccache exporter](https://github.com/virtualtam/ccache_exporter)
+   * [c-lightning exporter](https://github.com/lightningd/plugins/tree/master/prometheus)
+   * [DHCPD leases exporter](https://github.com/DRuggeri/dhcpd_leases_exporter)
+   * [Dovecot exporter](https://github.com/kumina/dovecot_exporter)
+   * [Dnsmasq exporter](https://github.com/google/dnsmasq_exporter)
+   * [eBPF exporter](https://github.com/cloudflare/ebpf_exporter)
+   * [eBPF network traffic exporter](https://github.com/kasd/texporter)
+   * [Ethereum Client exporter](https://github.com/31z4/ethereum-prometheus-exporter)
+   * [FFmpeg exporter](https://github.com/domcyrus/ffmpeg_exporter)
+   * [File statistics exporter](https://github.com/michael-doubez/filestat_exporter)
+   * [JFrog Artifactory Exporter](https://github.com/peimanja/artifactory_exporter)
+   * [Hostapd Exporter](https://github.com/Fundacio-i2CAT/hostapd_prometheus_exporter)
+   * [IBM Security Verify Access / Security Access Manager Exporter](https://gitlab.com/zeblawson/isva-prometheus-exporter)
+   * [IPsec exporter](https://github.com/torilabs/ipsec-prometheus-exporter)
+   * [ipset exporter](https://github.com/hatamiarash7/ipset-exporter)
+   * [IRCd exporter](https://github.com/dgl/ircd_exporter)
+   * [Linux HA ClusterLabs exporter](https://github.com/ClusterLabs/ha_cluster_exporter)
+   * [JMeter plugin](https://github.com/johrstrom/jmeter-prometheus-plugin)
+   * [JSON exporter](https://github.com/prometheus-community/json_exporter)
+   * [Kannel exporter](https://github.com/apostvav/kannel_exporter)
+   * [Kemp LoadBalancer exporter](https://github.com/giantswarm/prometheus-kemp-exporter)
+   * [Kibana Exporter](https://github.com/pjhampton/kibana-prometheus-exporter)
+   * [kube-state-metrics](https://github.com/kubernetes/kube-state-metrics)
+   * [Locust Exporter](https://github.com/ContainerSolutions/locust_exporter)
+   * [Meteor JS web framework exporter](https://atmospherejs.com/sevki/prometheus-exporter)
+   * [Minecraft exporter module](https://github.com/Baughn/PrometheusIntegration)
+   * [Minecraft exporter](https://github.com/dirien/minecraft-prometheus-exporter)
+   * [Nomad exporter](https://gitlab.com/yakshaving.art/nomad-exporter)
+   * [nftables exporter](https://github.com/Intrinsec/nftables_exporter)
+   * [OpenStack exporter](https://github.com/openstack-exporter/openstack-exporter)
+   * [OpenStack blackbox exporter](https://github.com/infraly/openstack_client_exporter)
+   * [oVirt exporter](https://github.com/czerwonk/ovirt_exporter)
+   * [Pact Broker exporter](https://github.com/ContainerSolutions/pactbroker_exporter)
+   * [PHP-FPM exporter](https://github.com/bakins/php-fpm-exporter)
+   * [PowerDNS exporter](https://github.com/ledgr/powerdns_exporter)
+   * [Podman exporter](https://github.com/containers/prometheus-podman-exporter)
+   * [Prefect2 exporter](https://github.com/pathfinder177/prefect2-prometheus-exporter)
+   * [Process exporter](https://github.com/ncabatoff/process-exporter)
+   * [rTorrent exporter](https://github.com/mdlayher/rtorrent_exporter)
+   * [Rundeck exporter](https://github.com/phsmith/rundeck_exporter)
+   * [SABnzbd exporter](https://github.com/msroest/sabnzbd_exporter)
+   * [SAML exporter](https://github.com/DoodleScheduling/saml-exporter)
+   * [Script exporter](https://github.com/adhocteam/script_exporter)
+   * [Shield exporter](https://github.com/cloudfoundry-community/shield_exporter)
+   * [Smokeping prober](https://github.com/SuperQ/smokeping_prober)
+   * [SMTP/Maildir MDA blackbox prober](https://github.com/cherti/mailexporter)
+   * [SoftEther exporter](https://github.com/dalance/softether_exporter)
+   * [SSH exporter](https://github.com/treydock/ssh_exporter)
+   * [Teamspeak3 exporter](https://github.com/hikhvar/ts3exporter)
+   * [Transmission exporter](https://github.com/metalmatze/transmission-exporter)
+   * [Unbound exporter](https://github.com/kumina/unbound_exporter)
+   * [WireGuard exporter](https://github.com/MindFlavor/prometheus_wireguard_exporter)
+   * [Xen exporter](https://github.com/lovoo/xenstats_exporter)
+
+
+When implementing a new Prometheus exporter, please follow the
+[guidelines on writing exporters](/docs/instrumenting/writing_exporters)
+Please also consider consulting the [development mailing
+list](https://groups.google.com/forum/#!forum/prometheus-developers).  We are
+happy to give advice on how to make your exporter as useful and consistent as
+possible.
+
+## Software exposing Prometheus metrics
+
+Some third-party software exposes metrics in the Prometheus format, so no
+separate exporters are needed:
+
+   * [Ansible Automation Platform Automation Controller (AWX)](https://docs.ansible.com/automation-controller/latest/html/administration/metrics.html)
+   * [App Connect Enterprise](https://github.com/ot4i/ace-docker)
+   * [Ballerina](https://ballerina.io/)
+   * [BFE](https://github.com/baidu/bfe)
+   * [Caddy](https://caddyserver.com/docs/metrics) (**direct**)
+   * [Ceph](https://docs.ceph.com/en/latest/mgr/prometheus/)
+   * [CockroachDB](https://www.cockroachlabs.com/docs/stable/monitoring-and-alerting.html#prometheus-endpoint)
+   * [Collectd](https://collectd.org/wiki/index.php/Plugin:Write_Prometheus)
+   * [Concourse](https://concourse-ci.org/)
+   * [CRG Roller Derby Scoreboard](https://github.com/rollerderby/scoreboard) (**direct**)
+   * [Diffusion](https://docs.pushtechnology.com/docs/latest/manual/html/administratorguide/systemmanagement/r_statistics.html)
+   * [Docker Daemon](https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-metrics)
+   * [Doorman](https://github.com/youtube/doorman) (**direct**)
+   * [Dovecot](https://doc.dovecot.org/configuration_manual/stats/openmetrics/)
+   * [Envoy](https://www.envoyproxy.io/docs/envoy/latest/operations/admin.html#get--stats?format=prometheus)
+   * [Etcd](https://github.com/coreos/etcd) (**direct**)
+   * [Flink](https://github.com/apache/flink)
+   * [FreeBSD Kernel](https://www.freebsd.org/cgi/man.cgi?query=prometheus_sysctl_exporter&apropos=0&sektion=8&manpath=FreeBSD+12-current&arch=default&format=html)
+   * [GitLab](https://docs.gitlab.com/ee/administration/monitoring/prometheus/gitlab_metrics.html)
+   * [Grafana](https://grafana.com/docs/grafana/latest/administration/view-server/internal-metrics/)
+   * [JavaMelody](https://github.com/javamelody/javamelody/wiki/UserGuideAdvanced#exposing-metrics-to-prometheus)
+   * [Kong](https://github.com/Kong/kong-plugin-prometheus)
+   * [Kubernetes](https://github.com/kubernetes/kubernetes) (**direct**)
+   * [LavinMQ](https://lavinmq.com/)
+   * [Linkerd](https://github.com/BuoyantIO/linkerd)
+   * [mgmt](https://github.com/purpleidea/mgmt/blob/master/docs/prometheus.md)
+   * [MidoNet](https://github.com/midonet/midonet)
+   * [midonet-kubernetes](https://github.com/midonet/midonet-kubernetes) (**direct**)
+   * [MinIO](https://docs.minio.io/docs/how-to-monitor-minio-using-prometheus.html)
+   * [PATROL with Monitoring Studio X](https://www.sentrysoftware.com/library/swsyx/prometheus/exposing-patrol-parameters-in-prometheus.html)
+   * [Netdata](https://github.com/firehol/netdata)
+   * [OpenZiti](https://openziti.github.io)
+   * [Pomerium](https://pomerium.com/reference/#metrics-address)
+   * [Pretix](https://pretix.eu/)
+   * [Quobyte](https://www.quobyte.com/) (**direct**)
+   * [RabbitMQ](https://rabbitmq.com/prometheus.html)
+   * [RobustIRC](http://robustirc.net/)
+   * [ScyllaDB](http://github.com/scylladb/scylla)
+   * [Skipper](https://github.com/zalando/skipper)
+   * [SkyDNS](https://github.com/skynetservices/skydns) (**direct**)
+   * [Telegraf](https://github.com/influxdata/telegraf/tree/master/plugins/outputs/prometheus_client)
+   * [Traefik](https://github.com/containous/traefik)
+   * [Vector](https://vector.dev)
+   * [VerneMQ](https://github.com/vernemq/vernemq)
+   * [Flux](https://github.com/fluxcd/flux2)
+   * [Xandikos](https://www.xandikos.org/) (**direct**)
+   * [Zipkin](https://github.com/openzipkin/zipkin/tree/master/zipkin-server#metrics)
+
+The software marked *direct* is also directly instrumented with a Prometheus client library.
+
+## Other third-party utilities
+
+This section lists libraries and other utilities that help you instrument code
+in a certain language. They are not Prometheus client libraries themselves but
+make use of one of the normal Prometheus client libraries under the hood. As
+for all independently maintained software, we cannot vet all of them for best
+practices.
+
+   * Clojure: [iapetos](https://github.com/clj-commons/iapetos)
+   * Go: [go-metrics instrumentation library](https://github.com/armon/go-metrics)
+   * Go: [gokit](https://github.com/peterbourgon/gokit)
+   * Go: [prombolt](https://github.com/mdlayher/prombolt)
+   * Java/JVM: [EclipseLink metrics collector](https://github.com/VitaNuova/eclipselinkexporter)
+   * Java/JVM: [Hystrix metrics publisher](https://github.com/ahus1/prometheus-hystrix)
+   * Java/JVM: [Jersey metrics collector](https://github.com/VitaNuova/jerseyexporter)
+   * Java/JVM: [Micrometer Prometheus Registry](https://micrometer.io/docs/registry/prometheus)
+   * Python-Django: [django-prometheus](https://github.com/korfuri/django-prometheus)
+   * Node.js: [swagger-stats](https://github.com/slanatech/swagger-stats)
diff --git a/docs/instrumenting/exposition_formats.md b/docs/instrumenting/exposition_formats.md
new file mode 100644
index 00000000..7fe1fc39
--- /dev/null
+++ b/docs/instrumenting/exposition_formats.md
@@ -0,0 +1,182 @@
+---
+title: Exposition formats
+sort_rank: 6
+---
+
+# Exposition formats
+
+Metrics can be exposed to Prometheus using a simple [text-based](#text-based-format)
+exposition format. There are various [client libraries](/docs/instrumenting/clientlibs/)
+that implement this format for you. If your preferred language doesn't have a client
+library you can [create your own](/docs/instrumenting/writing_clientlibs/).
+
+## Text-based format
+
+As of Prometheus version 2.0, all processes that expose metrics to Prometheus need to use
+a text-based format. In this section you can find some [basic information](#basic-info)
+about this format as well as a more [detailed breakdown](#text-format-details) of the
+format.
+
+### Basic info
+
+| Aspect | Description |
+|--------|-------------|
+| **Inception** | April 2014  |
+| **Supported in** |  Prometheus version `>=0.4.0` |
+| **Transmission** | HTTP |
+| **Encoding** | UTF-8, `\n` line endings |
+| **HTTP `Content-Type`** | `text/plain; version=0.0.4` (A missing `version` value will lead to a fall-back to the most recent text format version.) |
+| **Optional HTTP `Content-Encoding`** | `gzip` |
+| **Advantages** | <ul><li>Human-readable</li><li>Easy to assemble, especially for minimalistic cases (no nesting required)</li><li>Readable line by line (with the exception of type hints and docstrings)</li></ul> |
+| **Limitations** | <ul><li>Verbose</li><li>Types and docstrings not integral part of the syntax, meaning little-to-nonexistent metric contract validation</li><li>Parsing cost</li></ul>|
+| **Supported metric primitives** | <ul><li>Counter</li><li>Gauge</li><li>Histogram</li><li>Summary</li><li>Untyped</li></ul> |
+
+### Text format details
+
+Prometheus' text-based format is line oriented. Lines are separated by a line
+feed character (`\n`). The last line must end with a line feed character.
+Empty lines are ignored.
+
+#### Line format
+
+Within a line, tokens can be separated by any number of blanks and/or tabs (and
+must be separated by at least one if they would otherwise merge with the previous
+token). Leading and trailing whitespace is ignored.
+
+#### Comments, help text, and type information
+
+Lines with a `#` as the first non-whitespace character are comments. They are
+ignored unless the first token after `#` is either `HELP` or `TYPE`. Those
+lines are treated as follows: If the token is `HELP`, at least one more token
+is expected, which is the metric name. All remaining tokens are considered the
+docstring for that metric name. `HELP` lines may contain any sequence of UTF-8
+characters (after the metric name), but the backslash and the line feed
+characters have to be escaped as `\\` and `\n`, respectively. Only one `HELP`
+line may exist for any given metric name.
+
+If the token is `TYPE`, exactly two more tokens are expected. The first is the
+metric name, and the second is either `counter`, `gauge`, `histogram`,
+`summary`, or `untyped`, defining the type for the metric of that name. Only
+one `TYPE` line may exist for a given metric name. The `TYPE` line for a
+metric name must appear before the first sample is reported for that metric
+name. If there is no `TYPE` line for a metric name, the type is set to
+`untyped`.
+
+The remaining lines describe samples (one per line) using the following syntax
+([EBNF](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form)):
+
+```
+metric_name [
+  "{" label_name "=" `"` label_value `"` { "," label_name "=" `"` label_value `"` } [ "," ] "}"
+] value [ timestamp ]
+```
+
+In the sample syntax:
+
+*  `metric_name` and `label_name` carry the usual Prometheus expression language restrictions.
+* `label_value` can be any sequence of UTF-8 characters, but the backslash (`\`), double-quote (`"`), and line feed (`\n`) characters have to be escaped as `\\`, `\"`, and `\n`, respectively.
+* `value` is a float represented as required by Go's [`ParseFloat()`](https://golang.org/pkg/strconv/#ParseFloat) function. In addition to standard numerical values, `NaN`, `+Inf`, and `-Inf` are valid values representing not a number, positive infinity, and negative infinity, respectively.
+* The `timestamp` is an `int64` (milliseconds since epoch, i.e. 1970-01-01 00:00:00 UTC, excluding leap seconds), represented as required by Go's [`ParseInt()`](https://golang.org/pkg/strconv/#ParseInt) function.
+
+#### Grouping and sorting
+
+All lines for a given metric must be provided as one single group, with
+the optional `HELP` and `TYPE` lines first (in no particular order). Beyond
+that, reproducible sorting in repeated expositions is preferred but not
+required, i.e. do not sort if the computational cost is prohibitive.
+
+Each line must have a unique combination of a metric name and labels. Otherwise,
+the ingestion behavior is undefined.
+
+#### Histograms and summaries
+
+The `histogram` and `summary` types are difficult to represent in the text
+format. The following conventions apply:
+
+* The sample sum for a summary or histogram named `x` is given as a separate sample named `x_sum`.
+* The sample count for a summary or histogram named `x` is given as a separate sample named `x_count`.
+* Each quantile of a summary named `x` is given as a separate sample line with the same name `x` and a label `{quantile="y"}`.
+* Each bucket count of a histogram named `x` is given as a separate sample line with the name `x_bucket` and a label `{le="y"}` (where `y` is the upper bound of the bucket).
+* A histogram _must_ have a bucket with `{le="+Inf"}`. Its value _must_ be identical to the value of `x_count`.
+* The buckets of a histogram and the quantiles of a summary must appear in increasing numerical order of their label values (for the `le` or the `quantile` label, respectively).
+
+### Text format example
+
+Below is an example of a full-fledged Prometheus metric exposition, including
+comments, `HELP` and `TYPE` expressions, a histogram, a summary, character
+escaping examples, and more.
+
+```
+# HELP http_requests_total The total number of HTTP requests.
+# TYPE http_requests_total counter
+http_requests_total{method="post",code="200"} 1027 1395066363000
+http_requests_total{method="post",code="400"}    3 1395066363000
+
+# Escaping in label values:
+msdos_file_access_time_seconds{path="C:\\DIR\\FILE.TXT",error="Cannot find file:\n\"FILE.TXT\""} 1.458255915e9
+
+# Minimalistic line:
+metric_without_timestamp_and_labels 12.47
+
+# A weird metric from before the epoch:
+something_weird{problem="division by zero"} +Inf -3982045
+
+# A histogram, which has a pretty complex representation in the text format:
+# HELP http_request_duration_seconds A histogram of the request duration.
+# TYPE http_request_duration_seconds histogram
+http_request_duration_seconds_bucket{le="0.05"} 24054
+http_request_duration_seconds_bucket{le="0.1"} 33444
+http_request_duration_seconds_bucket{le="0.2"} 100392
+http_request_duration_seconds_bucket{le="0.5"} 129389
+http_request_duration_seconds_bucket{le="1"} 133988
+http_request_duration_seconds_bucket{le="+Inf"} 144320
+http_request_duration_seconds_sum 53423
+http_request_duration_seconds_count 144320
+
+# Finally a summary, which has a complex representation, too:
+# HELP rpc_duration_seconds A summary of the RPC duration in seconds.
+# TYPE rpc_duration_seconds summary
+rpc_duration_seconds{quantile="0.01"} 3102
+rpc_duration_seconds{quantile="0.05"} 3272
+rpc_duration_seconds{quantile="0.5"} 4773
+rpc_duration_seconds{quantile="0.9"} 9001
+rpc_duration_seconds{quantile="0.99"} 76656
+rpc_duration_seconds_sum 1.7560473e+07
+rpc_duration_seconds_count 2693
+```
+
+## OpenMetrics Text Format
+
+[OpenMetrics](https://github.com/OpenObservability/OpenMetrics) is the an effort to standardize metric wire formatting built off of Prometheus text format. It is possible to scrape targets
+and it is also available to use for federating metrics since at least v2.23.0.
+
+### Exemplars (Experimental)
+
+Utilizing the OpenMetrics format allows for the exposition and querying of [Exemplars](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#exemplars).
+Exemplars provide a point in time snapshot related to a metric set for an otherwise summarized MetricFamily. Additionally they may have a Trace ID attached to them which when used to together
+with a tracing system can provide more detailed information related to the specific service.
+
+To enable this experimental feature you must have at least version v2.26.0 and add `--enable-feature=exemplar-storage` to your arguments.
+
+## Protobuf format
+
+Earlier versions of Prometheus supported an exposition format based on [Protocol Buffers](https://developers.google.com/protocol-buffers/) (aka Protobuf) in addition to the current text-based format. With Prometheus 2.0, the Protobuf format was marked as deprecated and Prometheus stopped ingesting samples from said exposition format.
+
+However, new experimental features were added to Prometheus where the Protobuf format was considered the most viable option. Making Prometheus accept Protocol Buffers once again.
+
+Here is a list of experimental features that, once enabled, will configure Prometheus to favor the Protobuf exposition format:
+
+| feature flag | version that introduced it |
+|--------------|----------------------------|
+| native-histograms | 2.40.0 |
+| created-timestamp-zero-ingestion | 2.50.0 |
+
+## Historical versions
+
+For details on historical format versions, see the legacy
+[Client Data Exposition Format](https://docs.google.com/document/d/1ZjyKiKxZV83VI9ZKAXRGKaUKK2BIWCT7oiGBKDBpjEY/edit?usp=sharing)
+document.
+
+The current version of the original Protobuf format (with the recent extensions
+for native histograms) is maintained in the [prometheus/client_model
+repository](https://github.com/prometheus/client_model).
diff --git a/docs/instrumenting/index.md b/docs/instrumenting/index.md
new file mode 100644
index 00000000..db8a42e3
--- /dev/null
+++ b/docs/instrumenting/index.md
@@ -0,0 +1,5 @@
+---
+title: Instrumenting
+sort_rank: 5
+nav_icon: code
+---
diff --git a/docs/instrumenting/pushing.md b/docs/instrumenting/pushing.md
new file mode 100644
index 00000000..7cf915de
--- /dev/null
+++ b/docs/instrumenting/pushing.md
@@ -0,0 +1,27 @@
+---
+title: Pushing metrics
+sort_rank: 3
+---
+
+# Pushing metrics
+
+Occasionally you will need to monitor components which cannot be scraped. The
+[Prometheus Pushgateway](https://github.com/prometheus/pushgateway) allows you
+to push time series from [short-lived service-level batch
+jobs](/docs/practices/pushing/) to an intermediary job which Prometheus can
+scrape. Combined with Prometheus's simple text-based exposition format, this
+makes it easy to instrument even shell scripts without a client library.
+
+ * For more information on using the Pushgateway and use from a Unix shell, see the project's
+[README.md](https://github.com/prometheus/pushgateway/blob/master/README.md).
+
+ * For use from Java see the
+[Pushgateway documentation](https://prometheus.github.io/client_java/exporters/pushgateway/).
+
+ * For use from Go see the [Push](https://godoc.org/github.com/prometheus/client_golang/prometheus/push#Pusher.Push) and [Add](https://godoc.org/github.com/prometheus/client_golang/prometheus/push#Pusher.Add) methods.
+
+ * For use from Python see [Exporting to a Pushgateway](https://prometheus.github.io/client_python/exporting/pushgateway/).
+
+ * For use from Ruby see the [Pushgateway documentation](https://github.com/prometheus/client_ruby#pushgateway).
+
+* To find out about Pushgateway support of [client libraries maintained outside of the Prometheus project](/docs/instrumenting/clientlibs/), refer to their respective documentation.
diff --git a/docs/instrumenting/writing_clientlibs.md b/docs/instrumenting/writing_clientlibs.md
new file mode 100644
index 00000000..ecb10752
--- /dev/null
+++ b/docs/instrumenting/writing_clientlibs.md
@@ -0,0 +1,408 @@
+---
+title: Writing client libraries
+sort_rank: 2
+---
+
+# Writing client libraries
+
+This document covers what functionality and API Prometheus client libraries
+should offer, with the aim of consistency across libraries, making the easy use
+cases easy and avoiding offering functionality that may lead users down the
+wrong path.
+
+There are [10 languages already supported](/docs/instrumenting/clientlibs) at
+the time of writing, so we’ve gotten a good sense by now of how to write a
+client. These guidelines aim to help authors of new client libraries produce
+good libraries.
+
+## Conventions
+
+MUST/MUST NOT/SHOULD/SHOULD NOT/MAY have the meanings given in
+[https://www.ietf.org/rfc/rfc2119.txt](https://www.ietf.org/rfc/rfc2119.txt)
+
+In addition ENCOURAGED means that a feature is desirable for a library to have,
+but it’s okay if it’s not present. In other words, a nice to have.
+
+Things to keep in mind:
+
+* Take advantage of each language’s features.
+
+* The common use cases should be easy.
+
+* The correct way to do something should be the easy way.
+
+* More complex use cases should be possible.
+
+The common use cases are (in order):
+
+* Counters without labels spread liberally around libraries/applications.
+
+* Timing functions/blocks of code in Summaries/Histograms.
+
+* Gauges to track current states of things (and their limits).
+
+* Monitoring of batch jobs.
+
+## Overall structure
+
+Clients MUST be written to be callback based internally. Clients SHOULD
+generally follow the structure described here.
+
+The key class is the Collector. This has a method (typically called ‘collect’)
+that returns zero or more metrics and their samples. Collectors get registered
+with a CollectorRegistry. Data is exposed by passing a CollectorRegistry to a
+class/method/function "bridge", which returns the metrics in a format
+Prometheus supports. Every time the CollectorRegistry is scraped it must
+callback to each of the Collectors’ collect method.
+
+The interface most users interact with are the Counter, Gauge, Summary, and
+Histogram Collectors. These represent a single metric, and should cover the
+vast majority of use cases where a user is instrumenting their own code.
+
+More advanced uses cases (such as proxying from another
+monitoring/instrumentation system) require writing a custom Collector. Someone
+may also want to write a "bridge" that takes a CollectorRegistry and produces
+data in a format a different monitoring/instrumentation system understands,
+allowing users to only have to think about one instrumentation system.
+
+CollectorRegistry SHOULD offer `register()`/`unregister()` functions, and a
+Collector SHOULD be allowed to be registered to multiple CollectorRegistrys.
+
+Client libraries MUST be thread safe.
+
+For non-OO languages such as C, client libraries should follow the spirit of
+this structure as much as is practical.
+
+### Naming
+
+Client libraries SHOULD follow function/method/class names mentioned in this
+document, keeping in mind the naming conventions of the language they’re
+working in. For example, `set_to_current_time()` is good for a method name in 
+Python, but `SetToCurrentTime()` is better in Go and `setToCurrentTime()` is
+the convention in Java. Where names differ for technical reasons (e.g. not
+allowing function overloading), documentation/help strings SHOULD point users
+towards the other names.
+
+Libraries MUST NOT offer functions/methods/classes with the same or similar
+names to ones given here, but with different semantics.
+
+## Metrics
+
+The Counter, Gauge, Summary and Histogram [metric
+types](/docs/concepts/metric_types/) are the primary interface by users.
+
+Counter and Gauge MUST be part of the client library. At least one of Summary
+and Histogram MUST be offered.
+
+These should be primarily used as file-static variables, that is, global
+variables defined in the same file as the code they’re instrumenting. The
+client library SHOULD enable this. The common use case is instrumenting a piece
+of code overall, not a piece of code in the context of one instance of an
+object. Users shouldn’t have to worry about plumbing their metrics throughout
+their code, the client library should do that for them (and if it doesn’t,
+users will write a wrapper around the library to make it "easier" - which
+rarely tends to go well).
+
+There MUST be a default CollectorRegistry, the standard metrics MUST by default
+implicitly register into it with no special work required by the user. There
+MUST be a way to have metrics not register to the default CollectorRegistry,
+for use in batch jobs and unittests. Custom collectors SHOULD also follow this.
+
+Exactly how the metrics should be created varies by language. For some (Java,
+Go) a builder approach is best, whereas for others (Python) function arguments
+are rich enough to do it in one call.
+
+For example in the Java Simpleclient we have:
+
+```java
+class YourClass {
+  static final Counter requests = Counter.build()
+      .name("requests_total")
+      .help("Requests.").register();
+}
+```
+
+This will register requests with the default CollectorRegistry. By calling
+`build()` rather than `register()` the metric won’t be registered (handy for
+unittests), you can also pass in a CollectorRegistry to `register()` (handy for
+batch jobs).
+
+### Counter
+
+[Counter](/docs/concepts/metric_types/#counter) is a monotonically increasing
+counter. It MUST NOT allow the value to decrease, however it MAY be reset to 0
+(such as by server restart).
+
+A counter MUST have the following methods:
+
+* `inc()`: Increment the counter by 1
+* `inc(double v)`: Increment the counter by the given amount. MUST check that v >= 0.
+
+A counter is ENCOURAGED to have:
+
+A way to count exceptions throw/raised in a given piece of code, and optionally
+only certain types of exceptions. This is count_exceptions in Python.
+
+Counters MUST start at 0.
+
+### Gauge
+
+[Gauge](/docs/concepts/metric_types/#gauge) represents a value that can go up
+and down.
+
+A gauge MUST have the following methods:
+
+* `inc()`: Increment the gauge by 1
+* `inc(double v)`: Increment the gauge by the given amount
+* `dec()`: Decrement the gauge by 1
+* `dec(double v)`: Decrement the gauge by the given amount
+* `set(double v)`: Set the gauge to the given value
+
+Gauges MUST start at 0, you MAY offer a way for a given gauge to start at a
+different number.
+
+A gauge SHOULD have the following methods:
+
+* `set_to_current_time()`: Set the gauge to the current unixtime in seconds.
+
+A gauge is ENCOURAGED to have:
+
+A way to track in-progress requests in some piece of code/function. This is
+`track_inprogress` in Python.
+
+A way to time a piece of code and set the gauge to its duration in seconds.
+This is useful for batch jobs. This is startTimer/setDuration in Java and the
+`time()` decorator/context manager in Python. This SHOULD match the pattern in
+Summary/Histogram (though `set()` rather than `observe()`).
+
+### Summary
+
+A [summary](/docs/concepts/metric_types/#summary) samples observations (usually
+things like request durations) over sliding windows of time and provides
+instantaneous insight into their distributions, frequencies, and sums.
+
+A summary MUST NOT allow the user to set "quantile" as a label name, as this is
+used internally to designate summary quantiles. A summary is ENCOURAGED to
+offer quantiles as exports, though these can’t be aggregated and tend to be
+slow. A summary MUST allow not having quantiles, as just `_count`/`_sum` is
+quite useful and this MUST be the default.
+
+A summary MUST have the following methods:
+
+* `observe(double v)`: Observe the given amount
+
+A summary SHOULD have the following methods:
+
+Some way to time code for users in seconds. In Python this is the `time()`
+decorator/context manager. In Java this is startTimer/observeDuration. Units
+other than seconds MUST NOT be offered (if a user wants something else, they
+can do it by hand). This should follow the same pattern as Gauge/Histogram.
+
+Summary `_count`/`_sum` MUST start at 0.
+
+### Histogram
+
+[Histograms](/docs/concepts/metric_types/#histogram) allow aggregatable
+distributions of events, such as request latencies. This is at its core a
+counter per bucket.
+
+A histogram MUST NOT allow `le` as a user-set label, as `le` is used internally
+to designate buckets.
+
+A histogram MUST offer a way to manually choose the buckets. Ways to set
+buckets in a `linear(start, width, count)` and `exponential(start, factor,
+count)` fashion SHOULD be offered. Count MUST include the `+Inf` bucket.
+
+A histogram SHOULD have the same default buckets as other client libraries.
+Buckets MUST NOT be changeable once the metric is created.
+
+A histogram MUST have the following methods:
+
+* `observe(double v)`: Observe the given amount
+
+A histogram SHOULD have the following methods:
+
+Some way to time code for users in seconds. In Python this is the `time()`
+decorator/context manager. In Java this is `startTimer`/`observeDuration`.
+Units other than seconds MUST NOT be offered (if a user wants something else,
+they can do it by hand). This should follow the same pattern as Gauge/Summary.
+
+Histogram  `_count`/`_sum` and the buckets MUST start at 0.
+
+**Further metrics considerations**
+
+Providing additional functionality in metrics beyond what’s documented above as
+makes sense for a given language is ENCOURAGED.
+
+If there’s a common use case you can make simpler then go for it, as long as it
+won’t encourage undesirable behaviours (such as suboptimal metric/label
+layouts, or doing computation in the client).
+
+### Labels
+
+Labels are one of the [most powerful
+aspects](/docs/practices/instrumentation/#use-labels) of Prometheus, but
+[easily abused](/docs/practices/instrumentation/#do-not-overuse-labels).
+Accordingly client libraries must be very careful in how labels are offered to
+users.
+
+Client libraries MUST NOT allow users to have different
+label names for the same metric for Gauge/Counter/Summary/Histogram or any
+other Collector offered by the library.
+
+Metrics from custom collectors should almost always have consistent label
+names. As there are still rare but valid use cases where this is not the case,
+client libraries should not verify this.
+
+While labels are powerful, the majority of metrics will not have labels.
+Accordingly the API should allow for labels but not dominate it.
+
+A client library MUST allow for optionally specifying a list of label names at
+Gauge/Counter/Summary/Histogram creation time. A client library SHOULD support
+any number of label names. A client library MUST validate that label names meet
+the [documented
+requirements](/docs/concepts/data_model/#metric-names-and-labels).
+
+The general way to provide access to labeled dimension of a metric is via a
+`labels()` method that takes either a list of the label values or a map from
+label name to label value and returns a "Child". The usual
+`.inc()`/`.dec()`/`.observe()` etc. methods can then be called on the Child.
+
+The Child returned by `labels()` SHOULD be cacheable by the user, to avoid
+having to look it up again - this matters in latency-critical code.
+
+Metrics with labels SHOULD support a `remove()` method with the same signature
+as `labels()` that will remove a Child from the metric no longer exporting it,
+and a `clear()` method that removes all Children from the metric. These
+invalidate caching of Children.
+
+There SHOULD be a way to initialize a given Child with the default value,
+usually just calling `labels()`. Metrics without labels MUST always be
+initialized to avoid [problems with missing
+metrics](/docs/practices/instrumentation/#avoid-missing-metrics).
+
+### Metric names
+
+Metric names must follow the
+[specification](/docs/concepts/data_model/#metric-names-and-labels). As with
+label names, this MUST be met for uses of Gauge/Counter/Summary/Histogram and
+in any other Collector offered with the library.
+
+Many client libraries offer setting the name in three parts:
+`namespace_subsystem_name` of which only the `name` is mandatory.
+
+Dynamic/generated metric names or subparts of metric names MUST be discouraged,
+except when a custom Collector is proxying from other
+instrumentation/monitoring systems. Generated/dynamic metric names are a sign
+that you should be using labels instead.
+
+### Metric description and help
+
+Gauge/Counter/Summary/Histogram MUST require metric descriptions/help to be
+provided.
+
+Any custom Collectors provided with the client libraries MUST have
+descriptions/help on their metrics.
+
+It is suggested to make it a mandatory argument, but not to check that it’s of
+a certain length as if someone really doesn’t want to write docs we’re not
+going to convince them otherwise. Collectors offered with the library (and
+indeed everywhere we can within the ecosystem) SHOULD have good metric
+descriptions, to lead by example.
+
+## Exposition
+
+Clients MUST implement the text-based exposition format outlined in the
+[exposition formats](/docs/instrumenting/exposition_formats) documentation.
+
+Reproducible order of the exposed metrics is ENCOURAGED (especially for human
+readable formats) if it can be implemented without a significant resource cost.
+
+## Standard and runtime collectors
+
+Client libraries SHOULD offer what they can of the Standard exports, documented
+below.
+
+These SHOULD be implemented as custom Collectors, and registered by default on
+the default CollectorRegistry. There SHOULD be a way to disable these, as there
+are some very niche use cases where they get in the way.
+
+### Process metrics
+
+These metrics have the prefix `process_`. If obtaining a necessary value is
+problematic or even impossible with the used language or runtime, client
+libraries SHOULD prefer leaving out the corresponding metric over exporting
+bogus, inaccurate, or special values (like `NaN`). All memory values in bytes,
+all times in unixtime/seconds.
+
+| Metric name                        | Help string                                            | Unit             |
+| ---------------------------------- | ------------------------------------------------------ | ---------------  |
+| `process_cpu_seconds_total`        | Total user and system CPU time spent in seconds.       | seconds          |
+| `process_open_fds`                 | Number of open file descriptors.                       | file descriptors |
+| `process_max_fds`                  | Maximum number of open file descriptors.               | file descriptors |
+| `process_virtual_memory_bytes`     | Virtual memory size in bytes.                          | bytes            |
+| `process_virtual_memory_max_bytes` | Maximum amount of virtual memory available in bytes.   | bytes            |
+| `process_resident_memory_bytes`    | Resident memory size in bytes.                         | bytes            |
+| `process_heap_bytes`               | Process heap size in bytes.                            | bytes            |
+| `process_start_time_seconds`       | Start time of the process since unix epoch in seconds. | seconds          |
+| `process_threads`                  | Number of OS threads in the process.             | threads          |
+
+### Runtime metrics
+
+In addition, client libraries are ENCOURAGED to also offer whatever makes sense
+in terms of metrics for their language’s runtime (e.g. garbage collection
+stats), with an appropriate prefix such as `go_`, `hotspot_` etc.
+
+## Unit tests
+
+Client libraries SHOULD have unit tests covering the core instrumentation
+library and exposition.
+
+Client libraries are ENCOURAGED to offer ways that make it easy for users to
+unit-test their use of the instrumentation code. For example, the
+`CollectorRegistry.get_sample_value` in Python.
+
+## Packaging and dependencies
+
+Ideally, a client library can be included in any application to add some
+instrumentation without breaking the application.
+
+Accordingly, caution is advised when adding dependencies to the client library.
+For example, if you add a library that uses a Prometheus client that requires
+version x.y of a library but the application uses x.z elsewhere, will that have
+an adverse impact on the application?
+
+It is suggested that where this may arise, that the core instrumentation is
+separated from the bridges/exposition of metrics in a given format. For
+example, the Java simpleclient `simpleclient` module has no dependencies, and
+the `simpleclient_servlet` has the HTTP bits.
+
+## Performance considerations
+
+As client libraries must be thread-safe, some form of concurrency control is
+required and consideration must be given to performance on multi-core machines
+and applications.
+
+In our experience the least performant is mutexes.
+
+Processor atomic instructions tend to be in the middle, and generally
+acceptable.
+
+Approaches that avoid different CPUs mutating the same bit of RAM work best,
+such as the DoubleAdder in Java’s simpleclient. There is a memory cost though.
+
+As noted above, the result of `labels()` should be cacheable. The concurrent
+maps that tend to back metric with labels tend to be relatively slow.
+Special-casing metrics without labels to avoid `labels()`-like lookups can help
+a lot.
+
+Metrics SHOULD avoid blocking when they are being incremented/decremented/set
+etc. as it’s undesirable for the whole application to be held up while a scrape
+is ongoing.
+
+Having benchmarks of the main instrumentation operations, including labels, is
+ENCOURAGED.
+
+Resource consumption, particularly RAM, should be kept in mind when performing
+exposition. Consider reducing the memory footprint by streaming results, and
+potentially having a limit on the number of concurrent scrapes.
diff --git a/docs/instrumenting/writing_exporters.md b/docs/instrumenting/writing_exporters.md
new file mode 100644
index 00000000..ec632744
--- /dev/null
+++ b/docs/instrumenting/writing_exporters.md
@@ -0,0 +1,534 @@
+---
+title: Writing exporters
+sort_rank: 5
+---
+
+# Writing exporters
+
+If you are instrumenting your own code, the [general rules of how to
+instrument code with a Prometheus client
+library](/docs/practices/instrumentation/) should be followed. When
+taking metrics from another monitoring or instrumentation system, things
+tend not to be so black and white.
+
+This document contains things you should consider when writing an
+exporter or custom collector. The theory covered will also be of
+interest to those doing direct instrumentation.
+
+If you are writing an exporter and are unclear on anything here, please
+contact us on IRC (#prometheus on libera) or the [mailing
+list](/community).
+
+## Maintainability and purity
+
+The main decision you need to make when writing an exporter is how much
+work you’re willing to put in to get perfect metrics out of it.
+
+If the system in question has only a handful of metrics that rarely
+change, then getting everything perfect is an easy choice, a good
+example of this is the [HAProxy
+exporter](https://github.com/prometheus/haproxy_exporter).
+
+On the other hand, if you try to get things perfect when the system has
+hundreds of metrics that change frequently with new versions, then
+you’ve signed yourself up for a lot of ongoing work. The [MySQL
+exporter](https://github.com/prometheus/mysqld_exporter) is on this end
+of the spectrum.
+
+The [node exporter](https://github.com/prometheus/node_exporter) is a
+mix of these, with complexity varying by module. For example, the
+`mdadm` collector hand-parses a file and exposes metrics created
+specifically for that collector, so we may as well get the metrics
+right. For the `meminfo` collector the results vary across kernel
+versions so we end up doing just enough of a transform to create valid
+metrics.
+
+## Configuration
+
+When working with applications, you should aim for an exporter that
+requires no custom configuration by the user beyond telling it where the
+application is.  You may also need to offer the ability to filter out
+certain metrics if they may be too granular and expensive on large
+setups, for example the [HAProxy
+exporter](https://github.com/prometheus/haproxy_exporter) allows
+filtering of per-server stats. Similarly, there may be expensive metrics
+that are disabled by default.
+
+When working with other monitoring systems, frameworks and protocols you
+will often need to provide additional configuration or customization to
+generate metrics suitable for Prometheus. In the best case scenario, a
+monitoring system has a similar enough data model to Prometheus that you
+can automatically determine how to transform metrics. This is the case
+for [Cloudwatch](https://github.com/prometheus/cloudwatch_exporter),
+[SNMP](https://github.com/prometheus/snmp_exporter) and
+[collectd](https://github.com/prometheus/collectd_exporter). At most, we
+need the ability to let the user select which metrics they want to pull
+out.
+
+In other cases, metrics from the system are completely non-standard,
+depending on the usage of the system and the underlying application.  In
+that case the user has to tell us how to transform the metrics. The [JMX
+exporter](https://github.com/prometheus/jmx_exporter) is the worst
+offender here, with the
+[Graphite](https://github.com/prometheus/graphite_exporter) and
+[StatsD](https://github.com/prometheus/statsd_exporter) exporters also
+requiring configuration to extract labels.
+
+Ensuring the exporter works out of the box without configuration, and
+providing a selection of example configurations for transformation if
+required, is advised.
+
+YAML is the standard Prometheus configuration format, all configuration
+should use YAML by default.
+
+## Metrics
+
+### Naming
+
+Follow the [best practices on metric naming](/docs/practices/naming).
+
+Generally metric names should allow someone who is familiar with
+Prometheus but not a particular system to make a good guess as to what a
+metric means.  A metric named `http_requests_total` is not extremely
+useful - are these being measured as they come in, in some filter or
+when they get to the user’s code?  And `requests_total` is even worse,
+what type of requests?
+
+With direct instrumentation, a given metric should exist within exactly
+one file. Accordingly, within exporters and collectors, a metric should
+apply to exactly one subsystem and be named accordingly.
+
+Metric names should never be procedurally generated, except when writing
+a custom collector or exporter.
+
+Metric names for applications should generally be prefixed by the
+exporter name, e.g. `haproxy_up`.
+
+Metrics must use base units (e.g. seconds, bytes) and leave converting
+them to something more readable to graphing tools. No matter what units
+you end up using, the units in the metric name must match the units in
+use. Similarly, expose ratios, not percentages. Even better, specify a
+counter for each of the two components of the ratio.
+
+Metric names should not include the labels that they’re exported with,
+e.g. `by_type`, as that won’t make sense if the label is aggregated
+away.
+
+The one exception is when you’re exporting the same data with different
+labels via multiple metrics, in which case that’s usually the sanest way
+to distinguish them. For direct instrumentation, this should only come
+up when exporting a single metric with all the labels would have too
+high a cardinality.
+
+Prometheus metrics and label names are written in `snake_case`.
+Converting `camelCase` to `snake_case` is desirable, though doing so
+automatically doesn’t always produce nice results for things like
+`myTCPExample` or `isNaN` so sometimes it’s best to leave them as-is.
+
+Exposed metrics should not contain colons, these are reserved for user
+defined recording rules to use when aggregating.
+
+Only `[a-zA-Z0-9:_]` are valid in metric names.
+
+The `_sum`, `_count`, `_bucket` and `_total` suffixes are used by
+Summaries, Histograms and Counters. Unless you’re producing one of
+those, avoid these suffixes.
+
+`_total` is a convention for counters, you should use it if you’re using
+the COUNTER type.
+
+The `process_` and `scrape_` prefixes are reserved. It’s okay to add
+your own prefix on to these if they follow matching semantics.
+For example, Prometheus has `scrape_duration_seconds` for how long a
+scrape took, it's good practice to also have an exporter-centric metric,
+e.g. `jmx_scrape_duration_seconds`, saying how long the specific
+exporter took to do its thing. For process stats where you have access
+to the PID, both Go and Python offer collectors that’ll handle this for
+you. A good example of this is the [HAProxy
+exporter](https://github.com/prometheus/haproxy_exporter).
+
+When you have a successful request count and a failed request count, the
+best way to expose this is as one metric for total requests and another
+metric for failed requests. This makes it easy to calculate the failure
+ratio. Do not use one metric with a failed or success label. Similarly,
+with hit or miss for caches, it’s better to have one metric for total and
+another for hits.
+
+Consider the likelihood that someone using monitoring will do a code or
+web search for the metric name. If the names are very well-established
+and unlikely to be used outside of the realm of people used to those
+names, for example SNMP and network engineers, then leaving them as-is
+may be a good idea. This logic doesn’t apply for all exporters, for
+example the MySQL exporter metrics may be used by a variety of people,
+not just DBAs. A `HELP` string with the original name can provide most
+of the same benefits as using the original names.
+
+### Labels
+
+Read the [general
+advice](/docs/practices/instrumentation/#things-to-watch-out-for) on
+labels.
+
+Avoid `type` as a label name, it’s too generic and often meaningless.
+You should also try where possible to avoid names that are likely to
+clash with target labels, such as `region`, `zone`, `cluster`,
+`availability_zone`, `az`, `datacenter`, `dc`, `owner`, `customer`,
+`stage`, `service`, `environment` and `env`. If, however, that’s what
+the application calls some resource, it’s best not to cause confusion by
+renaming it.
+
+Avoid the temptation to put things into one metric just because they
+share a prefix. Unless you’re sure something makes sense as one metric,
+multiple metrics is safer.
+
+The label `le` has special meaning for Histograms, and `quantile` for
+Summaries. Avoid these labels generally.
+
+Read/write and send/receive are best as separate metrics, rather than as
+a label. This is usually because you care about only one of them at a
+time, and it is easier to use them that way.
+
+The rule of thumb is that one metric should make sense when summed or
+averaged.  There is one other case that comes up with exporters, and
+that’s where the data is fundamentally tabular and doing otherwise would
+require users to do regexes on metric names to be usable. Consider the
+voltage sensors on your motherboard, while doing math across them is
+meaningless, it makes sense to have them in one metric rather than
+having one metric per sensor. All values within a metric should
+(almost) always have the same unit, for example consider if fan speeds
+were mixed in with the voltages, and you had no way to automatically
+separate them.
+
+Don’t do this:
+
+<pre>
+my_metric{label="a"} 1
+my_metric{label="b"} 6
+<b>my_metric{label="total"} 7</b>
+</pre>
+
+or this:
+
+<pre>
+my_metric{label="a"} 1
+my_metric{label="b"} 6
+<b>my_metric{} 7</b>
+</pre>
+
+The former breaks for people who do a `sum()` over your metric, and the
+latter breaks sum and is quite difficult to work with. Some client
+libraries, for example Go, will actively try to stop you doing the
+latter in a custom collector, and all client libraries should stop you
+from doing the latter with direct instrumentation. Never do either of
+these, rely on Prometheus aggregation instead.
+
+If your monitoring exposes a total like this, drop the total. If you
+have to keep it around for some reason, for example the total includes
+things not counted individually, use different metric names.
+
+Instrumentation labels should be minimal, every extra label is one more
+that users need to consider when writing their PromQL. Accordingly,
+avoid having instrumentation labels which could be removed without
+affecting the uniqueness of the time series. Additional information
+around a metric can be added via an info metric, for an example see
+below how to handle version numbers.
+
+However, there are cases where it is expected that virtually all users of
+a metric will want the additional information. If so, adding a
+non-unique label, rather than an info metric, is the right solution. For
+example the
+[mysqld_exporter](https://github.com/prometheus/mysqld_exporter)'s
+`mysqld_perf_schema_events_statements_total`'s `digest` label is a hash
+of the full query pattern and is sufficient for uniqueness. However, it
+is of little use without the human readable `digest_text` label, which
+for long queries will contain only the start of the query pattern and is
+thus not unique. Thus we end up with both the `digest_text` label for
+humans and the `digest` label for uniqueness.
+
+### Target labels, not static scraped labels
+
+If you ever find yourself wanting to apply the same label to all of your
+metrics, stop.
+
+There’s generally two cases where this comes up.
+
+The first is for some label it would be useful to have on the metrics
+such as the version number of the software. Instead, use the approach
+described at
+[https://www.robustperception.io/how-to-have-labels-for-machine-roles/](http://www.robustperception.io/how-to-have-labels-for-machine-roles/).
+
+The second case is when a label is really a target label. These are
+things like region, cluster names, and so on, that come from your
+infrastructure setup rather than the application itself. It’s not for an
+application to say where it fits in your label taxonomy, that’s for the
+person running the Prometheus server to configure and different people
+monitoring the same application may give it different names.
+
+Accordingly, these labels belong up in the scrape configs of Prometheus
+via whatever service discovery you’re using. It’s okay to apply the
+concept of machine roles here as well, as it’s likely useful information
+for at least some people scraping it.
+
+### Types
+
+You should try to match up the types of your metrics to Prometheus
+types. This usually means counters and gauges. The `_count` and `_sum`
+of summaries are also relatively common, and on occasion you’ll see
+quantiles. Histograms are rare, if you come across one remember that the
+exposition format exposes cumulative values.
+
+Often it won’t be obvious what the type of metric is, especially if
+you’re automatically processing a set of metrics. In general `UNTYPED`
+is a safe default.
+
+Counters can’t go down, so if you have a counter type coming from
+another instrumentation system that can be decremented, for example
+Dropwizard metrics then it's not a counter, it's a gauge. `UNTYPED` is
+probably the best type to use there, as `GAUGE` would be misleading if
+it were being used as a counter.
+
+### Help strings
+
+When you’re transforming metrics it’s useful for users to be able to
+track back to what the original was, and what rules were in play that
+caused that transformation. Putting in the name of the
+collector or exporter, the ID of any rule that was applied and the
+name and details of the original metric into the help string will greatly
+aid users.
+
+Prometheus doesn’t like one metric having different help strings. If
+you’re making one metric from many others, choose one of them to put in
+the help string.
+
+For examples of this, the SNMP exporter uses the OID and the JMX
+exporter puts in a sample mBean name. The [HAProxy
+exporter](https://github.com/prometheus/haproxy_exporter) has
+hand-written strings. The [node
+exporter](https://github.com/prometheus/node_exporter) also has a wide
+variety of examples.
+
+### Drop less useful statistics
+
+Some instrumentation systems expose 1m, 5m, 15m rates, average rates since
+application start (these are called `mean` in Dropwizard metrics for
+example) in addition to minimums, maximums and standard deviations.
+
+These should all be dropped, as they’re not very useful and add clutter.
+Prometheus can calculate rates itself, and usually more accurately as
+the averages exposed are usually exponentially decaying. You don’t know
+what time the min or max were calculated over, and the standard deviation
+is statistically useless and you can always expose sum of squares,
+`_sum` and `_count` if you ever need to calculate it.
+
+Quantiles have related issues, you may choose to drop them or put them
+in a Summary.
+
+### Dotted strings
+
+Many monitoring systems don’t have labels, instead doing things like
+`my.class.path.mymetric.labelvalue1.labelvalue2.labelvalue3`.
+
+The [Graphite](https://github.com/prometheus/graphite_exporter) and
+[StatsD](https://github.com/prometheus/statsd_exporter) exporters share
+a way of transforming these with a small configuration language. Other
+exporters should implement the same. The transformation is currently
+implemented only in Go, and would benefit from being factored out into a
+separate library.
+
+## Collectors
+
+When implementing the collector for your exporter, you should never use
+the usual direct instrumentation approach and then update the metrics on
+each scrape.
+
+Rather create new metrics each time. In Go this is done with
+[MustNewConstMetric](https://godoc.org/github.com/prometheus/client_golang/prometheus#MustNewConstMetric)
+in your `Collect()` method. For Python see
+[https://github.com/prometheus/client_python#custom-collectors](https://prometheus.github.io/client_python/collector/custom/)
+and for Java generate a `List<MetricFamilySamples>` in your collect
+method, see
+[StandardExports.java](https://github.com/prometheus/client_java/blob/master/simpleclient_hotspot/src/main/java/io/prometheus/client/hotspot/StandardExports.java)
+for an example.
+
+The reason for this is two-fold. Firstly, two scrapes could happen at
+the same time, and direct instrumentation uses what are effectively
+file-level global variables, so you’ll get race conditions. Secondly, if
+a label value disappears, it’ll still be exported.
+
+Instrumenting your exporter itself via direct instrumentation is fine,
+e.g. total bytes transferred or calls performed by the exporter across
+all scrapes.  For exporters such as the [blackbox
+exporter](https://github.com/prometheus/blackbox_exporter) and [SNMP
+exporter](https://github.com/prometheus/snmp_exporter), which aren’t
+tied to a single target, these should only be exposed on a vanilla
+`/metrics` call, not on a scrape of a particular target.
+
+### Metrics about the scrape itself
+
+Sometimes you’d like to export metrics that are about the scrape, like
+how long it took or how many records you processed.
+
+These should be exposed as gauges as they’re about an event, the scrape,
+and the metric name prefixed by the exporter name, for example
+`jmx_scrape_duration_seconds`. Usually the `_exporter` is excluded and
+if the exporter also makes sense to use as just a collector, then
+definitely exclude it.
+
+Other scrape "meta" metrics should be avoided. For example, a counter for
+the number of scrapes, or a histogram of the scrape duration. Having the
+exporter track these metrics duplicate the [automatically generated
+metrics](docs/concepts/jobs_instances/#automatically-generated-labels-and-time-series)
+of Prometheus itself. This adds to the storage cost of every exporter instance.
+
+### Machine and process metrics
+
+Many systems, for example Elasticsearch, expose machine metrics such as
+CPU, memory and filesystem information. As the [node
+exporter](https://github.com/prometheus/node_exporter) provides these in
+the Prometheus ecosystem, such metrics should be dropped.
+
+In the Java world, many instrumentation frameworks expose process-level
+and JVM-level stats such as CPU and GC. The Java client and JMX exporter
+already include these in the preferred form via
+[DefaultExports.java](https://github.com/prometheus/client_java/blob/master/simpleclient_hotspot/src/main/java/io/prometheus/client/hotspot/DefaultExports.java),
+so these should also be dropped.
+
+Similarly with other languages and frameworks.
+
+## Deployment
+
+Each exporter should monitor exactly one instance application,
+preferably sitting right beside it on the same machine. That means for
+every HAProxy you run, you run a `haproxy_exporter` process. For every
+machine with a Mesos worker, you run the [Mesos
+exporter](https://github.com/mesosphere/mesos_exporter) on it, and
+another one for the master, if a machine has both.
+
+The theory behind this is that for direct instrumentation this is what
+you’d be doing, and we’re trying to get as close to that as we can in
+other layouts.  This means that all service discovery is done in
+Prometheus, not in exporters.  This also has the benefit that Prometheus
+has the target information it needs to allow users probe your service
+with the [blackbox
+exporter](https://github.com/prometheus/blackbox_exporter).
+
+There are two exceptions:
+
+The first is where running beside the application you are monitoring is
+completely nonsensical. The SNMP, blackbox and IPMI exporters are the
+main examples of this. The IPMI and SNMP exporters as the devices are
+often black boxes that it’s impossible to run code on (though if you
+could run a node exporter on them instead that’d be better), and the
+blackbox exporter where you’re monitoring something like a DNS name,
+where there’s also nothing to run on. In this case, Prometheus should
+still do service discovery, and pass on the target to be scraped. See
+the blackbox and SNMP exporters for examples.
+
+Note that it is only currently possible to write this type of exporter
+with the Go, Python and Java client libraries.
+
+The second exception is where you’re pulling some stats out of a random
+instance of a system and don’t care which one you’re talking to.
+Consider a set of MySQL replicas you wanted to run some business queries
+against the data to then export. Having an exporter that uses your usual
+load balancing approach to talk to one replica is the sanest approach.
+
+This doesn’t apply when you’re monitoring a system with master-election,
+in that case you should monitor each instance individually and deal with
+the "masterness" in Prometheus. This is as there isn’t always exactly
+one master, and changing what a target is underneath Prometheus’s feet
+will cause oddities.
+
+### Scheduling
+
+Metrics should only be pulled from the application when Prometheus
+scrapes them, exporters should not perform scrapes based on their own
+timers. That is, all scrapes should be synchronous.
+
+Accordingly, you should not set timestamps on the metrics you expose, let
+Prometheus take care of that. If you think you need timestamps, then you
+probably need the
+[Pushgateway](https://prometheus.io/docs/instrumenting/pushing/)
+instead.
+
+If a metric is particularly expensive to retrieve, i.e. takes more than
+a minute, it is acceptable to cache it. This should be noted in the
+`HELP` string.
+
+The default scrape timeout for Prometheus is 10 seconds. If your
+exporter can be expected to exceed this, you should explicitly call this
+out in your user documentation.
+
+### Pushes
+
+Some applications and monitoring systems only push metrics, for example
+StatsD, Graphite and collectd.
+
+There are two considerations here.
+
+Firstly, when do you expire metrics? Collectd and things talking to
+Graphite both export regularly, and when they stop we want to stop
+exposing the metrics.  Collectd includes an expiry time so we use that,
+Graphite doesn’t so it is a flag on the exporter.
+
+StatsD is a bit different, as it is dealing with events rather than
+metrics. The best model is to run one exporter beside each application
+and restart them when the application restarts so that the state is
+cleared.
+
+Secondly, these sort of systems tend to allow your users to send either
+deltas or raw counters. You should rely on the raw counters as far as
+possible, as that’s the general Prometheus model.
+
+For service-level metrics, e.g. service-level batch jobs, you should
+have your exporter push into the Pushgateway and exit after the event
+rather than handling the state yourself. For instance-level batch
+metrics, there is no clear pattern yet. The options are either to abuse
+the node exporter’s textfile collector, rely on in-memory state
+(probably best if you don’t need to persist over a reboot) or implement
+similar functionality to the textfile collector.
+
+### Failed scrapes
+
+There are currently two patterns for failed scrapes where the
+application you’re talking to doesn’t respond or has other problems.
+
+The first is to return a 5xx error.
+
+The second is to have a `myexporter_up`, e.g. `haproxy_up`, variable
+that has a value of 0 or 1 depending on whether the scrape worked.
+
+The latter is better where there’s still some useful metrics you can get
+even with a failed scrape, such as the HAProxy exporter providing
+process stats. The former is a tad easier for users to deal with, as
+[`up` works in the usual way](/docs/concepts/jobs_instances/#automatically-generated-labels-and-time-series), although you can’t distinguish between the
+exporter being down and the application being down.
+
+### Landing page
+
+It’s nicer for users if visiting `http://yourexporter/` has a simple
+HTML page with the name of the exporter, and a link to the `/metrics`
+page.
+
+### Port numbers
+
+A user may have many exporters and Prometheus components on the same
+machine, so to make that easier each has a unique port number.
+
+[https://github.com/prometheus/prometheus/wiki/Default-port-allocations](https://github.com/prometheus/prometheus/wiki/Default-port-allocations)
+is where we track them, this is publicly editable.
+
+Feel free to grab the next free port number when developing your
+exporter, preferably before publicly announcing it. If you’re not ready
+to release yet, putting your username and WIP is fine.
+
+This is a registry to make our users’ lives a little easier, not a
+commitment to develop particular exporters. For exporters for internal
+applications we recommend using ports outside of the range of default
+port allocations.
+
+## Announcing
+
+Once you’re ready to announce your exporter to the world, email the
+mailing list and send a PR to add it to [the list of available
+exporters](https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exporters.md).
diff --git a/docs/introduction/comparison.md b/docs/introduction/comparison.md
new file mode 100644
index 00000000..bb4bbeac
--- /dev/null
+++ b/docs/introduction/comparison.md
@@ -0,0 +1,283 @@
+---
+title: Comparison to alternatives
+sort_rank: 4
+---
+
+# Comparison to alternatives
+
+## Prometheus vs. Graphite
+
+### Scope
+
+[Graphite](http://graphite.readthedocs.org/en/latest/) focuses on being a
+passive time series database with a query language and graphing features. Any
+other concerns are addressed by external components.
+
+Prometheus is a full monitoring and trending system that includes built-in and
+active scraping, storing, querying, graphing, and alerting based on time series
+data. It has knowledge about what the world should look like (which endpoints
+should exist, what time series patterns mean trouble, etc.), and actively tries
+to find faults.
+
+### Data model
+
+Graphite stores numeric samples for named time series, much like Prometheus
+does. However, Prometheus's metadata model is richer: while Graphite metric
+names consist of dot-separated components which implicitly encode dimensions,
+Prometheus encodes dimensions explicitly as key-value pairs, called labels, attached
+to a metric name. This allows easy filtering, grouping, and matching by these
+labels via the query language.
+
+Further, especially when Graphite is used in combination with
+[StatsD](https://github.com/etsy/statsd/), it is common to store only
+aggregated data over all monitored instances, rather than preserving the
+instance as a dimension and being able to drill down into individual
+problematic instances.
+
+For example, storing the number of HTTP requests to API servers with the
+response code `500` and the method `POST` to the `/tracks` endpoint would
+commonly be encoded like this in Graphite/StatsD:
+
+```
+stats.api-server.tracks.post.500 -> 93
+```
+
+In Prometheus the same data could be encoded like this (assuming three api-server instances):
+
+```
+api_server_http_requests_total{method="POST",handler="/tracks",status="500",instance="<sample1>"} -> 34
+api_server_http_requests_total{method="POST",handler="/tracks",status="500",instance="<sample2>"} -> 28
+api_server_http_requests_total{method="POST",handler="/tracks",status="500",instance="<sample3>"} -> 31
+```
+
+### Storage
+
+Graphite stores time series data on local disk in the
+[Whisper](http://graphite.readthedocs.org/en/latest/whisper.html) format, an
+RRD-style database that expects samples to arrive at regular intervals. Every
+time series is stored in a separate file, and new samples overwrite old ones
+after a certain amount of time.
+
+Prometheus also creates one local file per time series, but allows storing
+samples at arbitrary intervals as scrapes or rule evaluations occur. Since new
+samples are simply appended, old data may be kept arbitrarily long. Prometheus
+also works well for many short-lived, frequently changing sets of time series.
+
+### Summary
+
+Prometheus offers a richer data model and query language, in addition to being
+easier to run and integrate into your environment. If you want a clustered
+solution that can hold historical data long term, Graphite may be a better
+choice.
+
+
+## Prometheus vs. InfluxDB
+
+[InfluxDB](https://influxdata.com/) is an open-source time series database,
+with a commercial option for scaling and clustering. The InfluxDB project was
+released almost a year after Prometheus development began, so we were unable to
+consider it as an alternative at the time. Still, there are significant
+differences between Prometheus and InfluxDB, and both systems are geared
+towards slightly different use cases.
+
+### Scope
+
+For a fair comparison, we must also consider
+[Kapacitor](https://github.com/influxdata/kapacitor) together with InfluxDB, as
+in combination they address the same problem space as Prometheus and the
+Alertmanager.
+
+The same scope differences as in the case of
+[Graphite](#prometheus-vs-graphite) apply here for InfluxDB itself. In addition
+InfluxDB offers continuous queries, which are equivalent to Prometheus
+recording rules.
+
+Kapacitor’s scope is a combination of Prometheus recording rules, alerting
+rules, and the Alertmanager's notification functionality. Prometheus offers [a
+more powerful query language for graphing and
+alerting](https://www.robustperception.io/translating-between-monitoring-languages/).
+The Prometheus Alertmanager additionally offers grouping, deduplication and
+silencing functionality.
+
+### Data model / storage
+
+Like Prometheus, the InfluxDB data model has key-value pairs as labels, which
+are called tags. In addition, InfluxDB has a second level of labels called
+fields, which are more limited in use. InfluxDB supports timestamps with up to
+nanosecond resolution, and float64, int64, bool, and string data types.
+Prometheus, by contrast, supports the float64 data type with limited support for
+strings, and millisecond resolution timestamps.
+
+InfluxDB uses a variant of a [log-structured merge tree for storage with a write ahead log](https://docs.influxdata.com/influxdb/v1.7/concepts/storage_engine/),
+sharded by time. This is much more suitable to event logging than Prometheus's
+append-only file per time series approach.
+
+[Logs and Metrics and Graphs, Oh My!](https://grafana.com/blog/2016/01/05/logs-and-metrics-and-graphs-oh-my/)
+describes the differences between event logging and metrics recording.
+
+### Architecture
+
+Prometheus servers run independently of each other and only rely on their local
+storage for their core functionality: scraping, rule processing, and alerting.
+The open source version of InfluxDB is similar.
+
+The commercial InfluxDB offering is, by design, a distributed storage cluster
+with storage and queries being handled by many nodes at once.
+
+This means that the commercial InfluxDB will be easier to scale horizontally,
+but it also means that you have to manage the complexity of a distributed
+storage system from the beginning. Prometheus will be simpler to run, but at
+some point you will need to shard servers explicitly along scalability
+boundaries like products, services, datacenters, or similar aspects.
+Independent servers (which can be run redundantly in parallel) may also give
+you better reliability and failure isolation.
+
+Kapacitor's open-source release has no built-in distributed/redundant options for 
+rules,  alerting, or notifications.  The open-source release of Kapacitor can 
+be scaled via manual sharding by the user, similar to Prometheus itself.
+Influx offers [Enterprise Kapacitor](https://docs.influxdata.com/enterprise_kapacitor), which supports an 
+HA/redundant alerting system.
+
+Prometheus and the Alertmanager by contrast offer a fully open-source redundant 
+option via running redundant replicas of Prometheus and using the Alertmanager's 
+[High Availability](https://github.com/prometheus/alertmanager#high-availability)
+mode. 
+
+### Summary
+
+There are many similarities between the systems. Both have labels (called tags
+in InfluxDB) to efficiently support multi-dimensional metrics. Both use
+basically the same data compression algorithms. Both have extensive
+integrations, including with each other. Both have hooks allowing you to extend
+them further, such as analyzing data in statistical tools or performing
+automated actions.
+
+Where InfluxDB is better:
+
+  * If you're doing event logging.
+  * Commercial option offers clustering for InfluxDB, which is also better for long term data storage.
+  * Eventually consistent view of data between replicas.
+
+Where Prometheus is better:
+
+  * If you're primarily doing metrics.
+  * More powerful query language, alerting, and notification functionality.
+  * Higher availability and uptime for graphing and alerting.
+
+InfluxDB is maintained by a single commercial company following the open-core
+model, offering premium features like closed-source clustering, hosting and
+support. Prometheus is a [fully open source and independent project](/community/), maintained
+by a number of companies and individuals, some of whom also offer commercial services and support.
+
+## Prometheus vs. OpenTSDB
+
+[OpenTSDB](http://opentsdb.net/) is a distributed time series database based on
+[Hadoop](http://hadoop.apache.org/) and [HBase](http://hbase.apache.org/).
+
+### Scope
+
+The same scope differences as in the case of
+[Graphite](/docs/introduction/comparison/#prometheus-vs-graphite) apply here.
+
+### Data model
+
+OpenTSDB's data model is almost identical to Prometheus's: time series are
+identified by a set of arbitrary key-value pairs (OpenTSDB tags are
+Prometheus labels). All data for a metric is 
+[stored together](http://opentsdb.net/docs/build/html/user_guide/writing/index.html#time-series-cardinality),
+limiting the cardinality of metrics. There are minor differences though: Prometheus
+allows arbitrary characters in label values, while OpenTSDB is more restrictive. 
+OpenTSDB also lacks a full query language, only allowing simple aggregation and math via its API.
+
+### Storage
+
+[OpenTSDB](http://opentsdb.net/)'s storage is implemented on top of
+[Hadoop](http://hadoop.apache.org/) and [HBase](http://hbase.apache.org/). This
+means that it is easy to scale OpenTSDB horizontally, but you have to accept
+the overall complexity of running a Hadoop/HBase cluster from the beginning.
+
+Prometheus will be simpler to run initially, but will require explicit sharding
+once the capacity of a single node is exceeded.
+
+### Summary
+
+Prometheus offers a much richer query language, can handle higher cardinality
+metrics, and forms part of a complete monitoring system. If you're already
+running Hadoop and value long term storage over these benefits, OpenTSDB is a
+good choice.
+
+## Prometheus vs. Nagios
+
+[Nagios](https://www.nagios.org/) is a monitoring system that originated in the
+1990s as NetSaint.
+
+### Scope
+
+Nagios is primarily about alerting based on the exit codes of scripts. These are 
+called “checks”. There is silencing of individual alerts, however no grouping, 
+routing or deduplication.
+
+There are a variety of plugins. For example, piping the few kilobytes of
+perfData plugins are allowed to return [to a time series database such as Graphite](https://github.com/shawn-sterling/graphios) or using NRPE to [run checks on remote machines](https://exchange.nagios.org/directory/Addons/Monitoring-Agents/NRPE--2D-Nagios-Remote-Plugin-Executor/details).
+
+### Data model
+
+Nagios is host-based. Each host can have one or more services and each service
+can perform one check.
+
+There is no notion of labels or a query language.
+
+### Storage
+
+Nagios has no storage per-se, beyond the current check state.
+There are plugins which can store data such as [for visualisation](https://docs.pnp4nagios.org/).
+
+### Architecture
+
+Nagios servers are standalone. All configuration of checks is via file.
+
+### Summary
+
+Nagios is suitable for basic monitoring of small and/or static systems where
+blackbox probing is sufficient.
+
+If you want to do whitebox monitoring, or have a dynamic or cloud based
+environment, then Prometheus is a good choice.
+
+## Prometheus vs. Sensu
+
+[Sensu](https://sensu.io) is an open source monitoring and observability pipeline with a commercial distribution which offers additional features for scalability. It can reuse existing Nagios plugins.
+
+### Scope
+
+Sensu is an observability pipeline that focuses on processing and alerting of observability data as a stream of [Events](https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-events/events/). It provides an extensible framework for event [filtering](https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-filter/), aggregation, [transformation](https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-transform/), and [processing](https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-process/) – including sending alerts to other systems and storing events in third-party systems. Sensu's event processing capabilities are similar in scope to Prometheus alerting rules and Alertmanager. 
+
+### Data model
+
+Sensu [Events](https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-events/events/) represent service health and/or [metrics](https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-events/events/#metric-attributes) in a structured data format identified by an [entity](https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-entities/entities/) name (e.g. server, cloud compute instance, container, or service), an event name, and optional [key-value metadata](https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-events/events/#metadata-attributes) called "labels" or "annotations". The Sensu Event payload may include one or more metric [`points`](https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-events/events/#points-attributes), represented as a JSON object containing a `name`, `tags` (key/value pairs), `timestamp`, and `value` (always a float).
+
+### Storage
+
+Sensu stores current and recent event status information and real-time inventory data in an embedded database (etcd) or an external RDBMS (PostgreSQL). 
+
+### Architecture
+
+All components of a Sensu deployment can be clustered for high availability and improved event-processing throughput. 
+
+### Summary
+
+Sensu and Prometheus have a few capabilities in common, but they take very different approaches to monitoring. Both offer extensible discovery mechanisms for dynamic cloud-based environments and ephemeral compute platforms, though the underlying mechanisms are quite different. Both provide support for collecting multi-dimensional metrics via labels and annotations. Both have extensive integrations, and Sensu natively supports collecting metrics from all Prometheus exporters. Both are capable of forwarding observability data to third-party data platforms (e.g. event stores or TSDBs). Where Sensu and Prometheus differ the most is in their use cases.
+
+Where Sensu is better: 
+
+- If you're collecting and processing hybrid observability data (including metrics _and/or_ events)
+- If you're consolidating multiple monitoring tools and need support for metrics _and_ Nagios-style plugins or check scripts
+- More powerful event-processing platform
+
+Where Prometheus is better: 
+
+- If you're primarily collecting and evaluating metrics
+- If you're monitoring homogeneous Kubernetes infrastructure (if 100% of the workloads you're monitoring are in K8s, Prometheus offers better K8s integration)
+- More powerful query language, and built-in support for historical data analysis 
+
+Sensu is maintained by a single commercial company following the open-core business model, offering premium features like closed-source event correlation and aggregation, federation, and support. Prometheus is a fully open source and independent project, maintained by a number of companies and individuals, some of whom also offer commercial services and support.
diff --git a/docs/introduction/design-doc.md b/docs/introduction/design-doc.md
new file mode 100644
index 00000000..410f186f
--- /dev/null
+++ b/docs/introduction/design-doc.md
@@ -0,0 +1,25 @@
+---
+title: Design Documents
+sort_rank: 7
+---
+
+# Design Documents
+
+See the [github.com/prometheus/proposals](https://github.com/prometheus/proposals)
+repository to see all the past and current proposals for the Prometheus Ecosystem.
+
+If you are interested in creating a new proposal, read our [proposal process](https://github.com/prometheus/proposals#proposal-process).
+
+# Problem statements and exploratory documents
+
+Sometimes we're looking even further into potential futures. The documents in
+this section are largely exploratory. They should be taken as informing our
+collective thoughts, not as anything concrete or specific.
+
+| Document                                                                                                                             | Initial date |
+|--------------------------------------------------------------------------------------------------------------------------------------|--------------|
+| [Prometheus is not feature complete](https://docs.google.com/document/d/1lEP7pGYM2-5GT9fAIDqrOecG86VRU8-1qAV8b6xZ29Q)                | 2020-05      |
+| [Thoughts about timestamps and durations in PromQL](https://docs.google.com/document/d/1jMeDsLvDfO92Qnry_JLAXalvMRzMSB1sBr9V7LolpYM) | 2020-10      |
+| [Prometheus, OpenMetrics & OTLP](https://docs.google.com/document/d/1hn-u6WKLHxIsqYT1_u6eh94lyQeXrFaAouMshJcQFXs)                    | 2021-03      |
+| [Prometheus Sparse Histograms and PromQL](https://docs.google.com/document/d/1ch6ru8GKg03N02jRjYriurt-CZqUVY09evPg6yKTA1s/edit)      | 2021-10      |
+| [Quoting Prometheus names](https://docs.google.com/document/d/1yFj5QSd1AgCYecZ9EJ8f2t4OgF2KBZgJYVde-uzVEtI/edit)                     | 2023-01      |
diff --git a/docs/introduction/faq.md b/docs/introduction/faq.md
new file mode 100644
index 00000000..25c1cb9e
--- /dev/null
+++ b/docs/introduction/faq.md
@@ -0,0 +1,202 @@
+---
+title: FAQ
+sort_rank: 5
+toc: full-width
+---
+
+# Frequently Asked Questions
+
+## General
+
+### What is Prometheus?
+
+Prometheus is an open-source systems monitoring and alerting toolkit
+with an active ecosystem.
+It is the only system directly supported by [Kubernetes](https://kubernetes.io/) and the de facto standard across the [cloud native ecosystem](https://landscape.cncf.io/).
+See the [overview](/docs/introduction/overview/).
+
+### How does Prometheus compare against other monitoring systems?
+
+See the [comparison](/docs/introduction/comparison/) page.
+
+### What dependencies does Prometheus have?
+
+The main Prometheus server runs standalone as a single monolithic binary and has no external dependencies.
+
+#### Is this cloud native?
+
+Yes.
+
+Cloud native is a flexible operating model, breaking up old service boundaries to allow for more flexible and scalable deployments.
+
+Prometheus's [service discovery](https://prometheus.io/docs/prometheus/latest/configuration/configuration/) integrates with most tools and clouds. Its dimensional data model and scale into the tens of millions of active series allows it to monitor large cloud-native deployments.
+There are always trade-offs to make when running services, and Prometheus values reliably getting alerts out to humans above all else.
+
+### Can Prometheus be made highly available?
+
+Yes, run identical Prometheus servers on two or more separate machines.
+Identical alerts will be deduplicated by the [Alertmanager](https://github.com/prometheus/alertmanager).
+
+Alertmanager supports [high availability](https://github.com/prometheus/alertmanager#high-availability) by interconnecting multiple Alertmanager instances to build an Alertmanager cluster. Instances of a cluster communicate using a gossip protocol managed via [HashiCorp's Memberlist](https://github.com/hashicorp/memberlist) library. 
+
+### I was told Prometheus “doesn't scale”.
+
+This is often more of a marketing claim than anything else.
+
+A single instance of Prometheus can be more performant than some systems positioning themselves as long term storage solution for Prometheus.
+You can run Prometheus reliably with tens of millions of active series.
+
+If you need more than that, there are several options. [Scaling and Federating Prometheus](https://www.robustperception.io/scaling-and-federating-prometheus/) on the Robust Perception blog is a good starting point, as are the long storage systems listed on our [integrations page](https://prometheus.io/docs/operating/integrations/#remote-endpoints-and-storage).
+
+### What language is Prometheus written in?
+
+Most Prometheus components are written in Go. Some are also written in Java,
+Python, and Ruby.
+
+### How stable are Prometheus features, storage formats, and APIs?
+
+All repositories in the Prometheus GitHub organization that have reached
+version 1.0.0 broadly follow
+[semantic versioning](http://semver.org/). Breaking changes are indicated by
+increments of the major version. Exceptions are possible for experimental
+components, which are clearly marked as such in announcements.
+
+Even repositories that have not yet reached version 1.0.0 are, in general, quite
+stable. We aim for a proper release process and an eventual 1.0.0 release for
+each repository. In any case, breaking changes will be pointed out in release
+notes (marked by `[CHANGE]`) or communicated clearly for components that do not
+have formal releases yet.
+
+### Why do you pull rather than push?
+
+Pulling over HTTP offers a number of advantages:
+
+* You can start extra monitoring instances as needed, e.g. on your laptop when developing changes.
+* You can more easily and reliably tell if a target is down.
+* You can manually go to a target and inspect its health with a web browser.
+
+Overall, we believe that pulling is slightly better than pushing, but it should
+not be considered a major point when considering a monitoring system.
+
+For cases where you must push, we offer the [Pushgateway](/docs/instrumenting/pushing/).
+
+### How to feed logs into Prometheus?
+
+Short answer: Don't! Use something like [Grafana Loki](https://grafana.com/oss/loki/) or [OpenSearch](https://opensearch.org/) instead.
+
+Longer answer: Prometheus is a system to collect and process metrics, not an
+event logging system. The Grafana blog post
+[Logs and Metrics and Graphs, Oh My!](https://grafana.com/blog/2016/01/05/logs-and-metrics-and-graphs-oh-my/)
+provides more details about the differences between logs and metrics.
+
+If you want to extract Prometheus metrics from application logs, Grafana Loki is designed for just that. See Loki's [metric queries](https://grafana.com/docs/loki/latest/logql/metric_queries/) documentation.
+
+### Who wrote Prometheus?
+
+Prometheus was initially started privately by
+[Matt T. Proud](http://www.matttproud.com) and
+[Julius Volz](http://juliusv.com). The majority of its
+initial development was sponsored by [SoundCloud](https://soundcloud.com).
+
+It's now maintained and extended by a wide range of [companies](https://prometheus.devstats.cncf.io/d/5/companies-table?orgId=1) and [individuals](https://prometheus.io/governance).
+
+### What license is Prometheus released under?
+
+Prometheus is released under the
+[Apache 2.0](https://github.com/prometheus/prometheus/blob/main/LICENSE) license.
+
+### What is the plural of Prometheus?
+
+After [extensive research](https://youtu.be/B_CDeYrqxjQ), it has been determined
+that the correct plural of 'Prometheus' is 'Prometheis'.
+
+If you can not remember this, "Prometheus instances" is a good workaround.
+
+### Can I reload Prometheus's configuration?
+
+Yes, sending `SIGHUP` to the Prometheus process or an HTTP POST request to the
+`/-/reload` endpoint will reload and apply the configuration file. The
+various components attempt to handle failing changes gracefully.
+
+### Can I send alerts?
+
+Yes, with the [Alertmanager](https://github.com/prometheus/alertmanager).
+
+We support sending alerts through [email, various native integrations](https://prometheus.io/docs/alerting/latest/configuration/), and a [webhook system anyone can add integrations to](https://prometheus.io/docs/operating/integrations/#alertmanager-webhook-receiver).
+
+### Can I create dashboards?
+
+Yes, we recommend [Grafana](/docs/visualization/grafana/) for production
+usage. There are also [Console templates](/docs/visualization/consoles/).
+
+### Can I change the timezone? Why is everything in UTC?
+
+To avoid any kind of timezone confusion, especially when the so-called
+daylight saving time is involved, we decided to exclusively use Unix
+time internally and UTC for display purposes in all components of
+Prometheus. A carefully done timezone selection could be introduced
+into the UI. Contributions are welcome. See
+[issue #500](https://github.com/prometheus/prometheus/issues/500)
+for the current state of this effort.
+
+## Instrumentation
+
+### Which languages have instrumentation libraries?
+
+There are a number of client libraries for instrumenting your services with
+Prometheus metrics. See the [client libraries](/docs/instrumenting/clientlibs/)
+documentation for details.
+
+If you are interested in contributing a client library for a new language, see
+the [exposition formats](/docs/instrumenting/exposition_formats/).
+
+### Can I monitor machines?
+
+Yes, the [Node Exporter](https://github.com/prometheus/node_exporter) exposes
+an extensive set of machine-level metrics on Linux and other Unix systems such
+as CPU usage, memory, disk utilization, filesystem fullness, and network
+bandwidth.
+
+### Can I monitor network devices?
+
+Yes, the [SNMP Exporter](https://github.com/prometheus/snmp_exporter) allows
+monitoring of devices that support SNMP.
+For industrial networks, there's also a [Modbus exporter](https://github.com/RichiH/modbus_exporter).
+
+### Can I monitor batch jobs?
+
+Yes, using the [Pushgateway](/docs/instrumenting/pushing/). See also the
+[best practices](/docs/practices/instrumentation/#batch-jobs) for monitoring batch
+jobs.
+
+### What applications can Prometheus monitor out of the box?
+
+See [the list of exporters and integrations](/docs/instrumenting/exporters/).
+
+### Can I monitor JVM applications via JMX?
+
+Yes, for applications that you cannot instrument directly with the Java client, you can use the [JMX Exporter](https://github.com/prometheus/jmx_exporter)
+either standalone or as a Java Agent.
+
+### What is the performance impact of instrumentation?
+
+Performance across client libraries and languages may vary. For Java,
+[benchmarks](https://github.com/prometheus/client_java/blob/main/benchmarks/README.md)
+indicate that incrementing a counter/gauge with the Java client will take
+12-17ns, depending on contention. This is negligible for all but the most
+latency-critical code.
+
+## Implementation
+
+### Why are all sample values 64-bit floats?
+
+We restrained ourselves to 64-bit floats to simplify the design. The
+[IEEE 754 double-precision binary floating-point
+format](http://en.wikipedia.org/wiki/Double-precision_floating-point_format)
+supports integer precision for values up to 2<sup>53</sup>. Supporting
+native 64 bit integers would (only) help if you need integer precision
+above 2<sup>53</sup> but below 2<sup>63</sup>. In principle, support
+for different sample value types (including some kind of big integer,
+supporting even more than 64 bit) could be implemented, but it is not
+a priority right now. A counter, even if incremented one million times per
+second, will only run into precision issues after over 285 years.
diff --git a/docs/introduction/first_steps.md b/docs/introduction/first_steps.md
new file mode 100644
index 00000000..51d5ead6
--- /dev/null
+++ b/docs/introduction/first_steps.md
@@ -0,0 +1,130 @@
+---
+title: First steps
+sort_rank: 3
+---
+
+# First steps with Prometheus
+
+Welcome to Prometheus! Prometheus is a monitoring platform that collects metrics from monitored targets by scraping metrics HTTP endpoints on these targets. This guide will show you how to install, configure and monitor our first resource with Prometheus. You'll download, install and run Prometheus. You'll also download and install an exporter, tools that expose time series data on hosts and services. Our first exporter will be Prometheus itself, which provides a wide variety of host-level metrics about memory usage, garbage collection, and more.
+
+## Downloading Prometheus
+
+[Download the latest release](/download) of Prometheus for your platform, then
+extract it:
+
+```language-bash
+tar xvfz prometheus-*.tar.gz
+cd prometheus-*
+```
+
+The Prometheus server is a single binary called `prometheus` (or `prometheus.exe` on Microsoft Windows). We can run the binary and see help on its options by passing the `--help` flag.
+
+```language-bash
+./prometheus --help
+usage: prometheus [<flags>]
+
+The Prometheus monitoring server
+
+. . .
+```
+
+Before starting Prometheus, let's configure it.
+
+## Configuring Prometheus
+
+Prometheus configuration is [YAML](https://yaml.org/). The Prometheus download comes with a sample configuration in a file called `prometheus.yml` that is a good place to get started.
+
+We've stripped out most of the comments in the example file to make it more succinct (comments are the lines prefixed with a `#`).
+
+```language-yaml
+global:
+  scrape_interval:     15s
+  evaluation_interval: 15s
+
+rule_files:
+  # - "first.rules"
+  # - "second.rules"
+
+scrape_configs:
+  - job_name: prometheus
+    static_configs:
+      - targets: ['localhost:9090']
+```
+
+There are three blocks of configuration in the example configuration file: `global`, `rule_files`, and `scrape_configs`.
+
+The `global` block controls the Prometheus server's global configuration. We have two options present. The first, `scrape_interval`, controls how often Prometheus will scrape targets. You can override this for individual targets. In this case the global setting is to scrape every 15 seconds. The `evaluation_interval` option controls how often Prometheus will evaluate rules. Prometheus uses rules to create new time series and to generate alerts.
+
+The `rule_files` block specifies the location of any rules we want the Prometheus server to load. For now we've got no rules.
+
+The last block, `scrape_configs`, controls what resources Prometheus monitors. Since Prometheus also exposes data about itself as an HTTP endpoint it can scrape and monitor its own health. In the default configuration there is a single job, called `prometheus`, which scrapes the time series data exposed by the Prometheus server. The job contains a single, statically configured, target, the `localhost` on port `9090`. Prometheus expects metrics to be available on targets on a path of `/metrics`. So this default job is scraping via the URL: http://localhost:9090/metrics.
+
+The time series data returned will detail the state and performance of the Prometheus server.
+
+For a complete specification of configuration options, see the
+[configuration documentation](/docs/operating/configuration).
+
+## Starting Prometheus
+
+To start Prometheus with our newly created configuration file, change to the directory containing the Prometheus binary and run:
+
+```language-bash
+./prometheus --config.file=prometheus.yml
+```
+
+Prometheus should start up. You should also be able to browse to a status page about itself at http://localhost:9090. Give it about 30 seconds to collect data about itself from its own HTTP metrics endpoint.
+
+You can also verify that Prometheus is serving metrics about itself by
+navigating to its own metrics endpoint: http://localhost:9090/metrics.
+
+## Using the expression browser
+
+Let us try looking at some data that Prometheus has collected about itself. To
+use Prometheus's built-in expression browser, navigate to
+http://localhost:9090/graph and choose the "Table" view within the "Graph"
+tab.
+
+As you can gather from http://localhost:9090/metrics, one metric that
+Prometheus exports about itself is called
+`promhttp_metric_handler_requests_total` (the total number of `/metrics` requests the Prometheus server has served). Go ahead and enter this into the expression console:
+
+```
+promhttp_metric_handler_requests_total
+```
+
+This should return a number of different time series (along with the latest value recorded for each), all with the metric name `promhttp_metric_handler_requests_total`, but with different labels. These labels designate different requests statuses.
+
+If we were only interested in requests that resulted in HTTP code `200`, we could use this query to retrieve that information:
+
+```
+promhttp_metric_handler_requests_total{code="200"}
+```
+
+To count the number of returned time series, you could write:
+
+```
+count(promhttp_metric_handler_requests_total)
+```
+
+For more about the expression language, see the
+[expression language documentation](/docs/querying/basics/).
+
+## Using the graphing interface
+
+To graph expressions, navigate to http://localhost:9090/graph and use the "Graph" tab.
+
+For example, enter the following expression to graph the per-second HTTP request rate returning status code 200 happening in the self-scraped Prometheus:
+
+```
+rate(promhttp_metric_handler_requests_total{code="200"}[1m])
+```
+
+You can experiment with the graph range parameters and other settings.
+
+## Monitoring other targets
+
+Collecting metrics from Prometheus alone isn't a great representation of Prometheus' capabilities. To get a better sense of what Prometheus can do, we recommend exploring documentation about other exporters. The [Monitoring Linux or macOS host metrics using a node exporter](/docs/guides/node-exporter) guide is a good place to start.
+
+## Summary
+
+In this guide, you installed Prometheus, configured a Prometheus instance to monitor resources, and learned some basics of working with time series data in Prometheus' expression browser. To continue learning about Prometheus, check out the [Overview](/docs/introduction/overview) for some ideas about what to explore next.
diff --git a/docs/introduction/glossary.md b/docs/introduction/glossary.md
new file mode 100644
index 00000000..8e9b6f17
--- /dev/null
+++ b/docs/introduction/glossary.md
@@ -0,0 +1,134 @@
+---
+title: Glossary
+sort_rank: 9
+---
+
+# Glossary
+
+
+### Alert
+
+An alert is the outcome of an alerting rule in Prometheus that is
+actively firing. Alerts are sent from Prometheus to the Alertmanager.
+
+### Alertmanager
+
+The [Alertmanager](../../alerting/overview/) takes in alerts, aggregates them into
+groups, de-duplicates, applies silences, throttles, and then sends out
+notifications to email, Pagerduty, Slack etc.
+
+### Bridge
+
+A bridge is a component that takes samples from a client library and
+exposes them to a non-Prometheus monitoring system. For example, the Python, Go, and Java clients can export metrics to Graphite.
+
+### Client library
+
+A client library is a library in some language (e.g. Go, Java, Python, Ruby)
+that makes it easy to directly instrument your code, write custom collectors to
+pull metrics from other systems and expose the metrics to Prometheus.
+
+### Collector
+
+A collector is a part of an exporter that represents a set of metrics. It may be
+a single metric if it is part of direct instrumentation, or many metrics if it is pulling metrics from another system.
+
+### Direct instrumentation
+
+Direct instrumentation is instrumentation added inline as part of the source code of a program, using a [client library](#client-library).
+
+### Endpoint
+
+A source of metrics that can be scraped, usually corresponding to a single process.
+
+### Exporter
+
+An exporter is a binary running alongside the application you
+want to obtain metrics from. The exporter exposes Prometheus metrics, commonly by converting metrics that are exposed in a non-Prometheus format into a format that Prometheus supports.
+
+### Instance
+
+An instance is a label that uniquely identifies a target in a job.
+
+### Job
+
+A collection of targets with the same purpose, for example monitoring a group of like processes replicated for scalability or reliability, is called a job.
+
+### Notification
+
+A notification represents a group of one or more alerts, and is sent by the Alertmanager to email, Pagerduty, Slack etc.
+
+### Promdash
+
+Promdash was a native dashboard builder for Prometheus. It has been deprecated and replaced by [Grafana](../../visualization/grafana/).
+
+### Prometheus
+
+Prometheus usually refers to the core binary of the Prometheus system. It may
+also refer to the Prometheus monitoring system as a whole.
+
+### PromQL
+
+[PromQL](/docs/prometheus/latest/querying/basics/) is the Prometheus Query Language. It allows for
+a wide range of operations including aggregation, slicing and dicing, prediction and joins.
+
+### Pushgateway
+
+The [Pushgateway](../../instrumenting/pushing/) persists the most recent push
+of metrics from batch jobs. This allows Prometheus to scrape their metrics
+after they have terminated.
+
+### Recording Rules
+
+Recording rules precompute frequently needed or computationally expensive expressions 
+and save their results as a new set of time series.
+
+### Remote Read
+
+Remote read is a Prometheus feature that allows transparent reading of time series from
+other systems (such as long term storage) as part of queries.
+
+### Remote Read Adapter
+
+Not all systems directly support remote read. A remote read adapter sits between
+Prometheus and another system, converting time series requests and responses between them.
+
+### Remote Read Endpoint
+
+A remote read endpoint is what Prometheus talks to when doing a remote read.
+
+### Remote Write
+
+Remote write is a Prometheus feature that allows sending ingested samples on the
+fly to other systems, such as long term storage.
+
+### Remote Write Adapter
+
+Not all systems directly support remote write. A remote write adapter sits
+between Prometheus and another system, converting the samples in the remote
+write into a format the other system can understand.
+
+### Remote Write Endpoint
+
+A remote write endpoint is what Prometheus talks to when doing a remote write.
+
+### Sample
+
+A sample is a single value at a point in time in a time series.
+
+In Prometheus, each sample consists of a float64 value and a millisecond-precision timestamp.
+
+### Silence
+
+A silence in the Alertmanager prevents alerts, with labels matching the silence, from
+being included in notifications.
+
+### Target
+
+A target is the definition of an object to scrape. For example, what labels to apply, any authentication required to connect, or other information that defines how the scrape will occur.
+
+### Time Series
+
+The Prometheus time series are streams of timestamped values belonging to the same metric and the same set of labeled dimensions.
+Prometheus stores all data as time series.
+
diff --git a/docs/introduction/index.md b/docs/introduction/index.md
new file mode 100644
index 00000000..c2f17b81
--- /dev/null
+++ b/docs/introduction/index.md
@@ -0,0 +1,5 @@
+---
+title: Introduction
+sort_rank: 1
+nav_icon: hand-finger-right
+---
diff --git a/docs/introduction/media.md b/docs/introduction/media.md
new file mode 100644
index 00000000..9bdd7bf4
--- /dev/null
+++ b/docs/introduction/media.md
@@ -0,0 +1,59 @@
+---
+title: Media
+sort_rank: 8
+---
+
+# Media
+
+There is a [subreddit](https://www.reddit.com/r/prometheusmonitoring)
+collecting all Prometheus-related resources on the internet.
+
+The following selection of resources are particularly useful to get started
+with Prometheus.
+[Awesome Prometheus](https://github.com/roaldnefs/awesome-prometheus)
+contains a more comprehensive community-maintained list of resources.
+
+## Blogs
+
+* This site has its own [blog](/blog/).
+* [SoundCloud's blog post announcing Prometheus](https://developers.soundcloud.com/blog/prometheus-monitoring-at-soundcloud)
+  – a more elaborate overview than the one given on this site.
+* Prometheus-related posts on the
+  [Robust Perception blog](https://www.robustperception.io/tag/prometheus/).
+
+## Tutorials
+
+* [Instructions and example code for a Prometheus workshop](https://github.com/juliusv/prometheus_workshop).
+* [How To Install Prometheus using Docker on Ubuntu 14.04](https://www.digitalocean.com/community/tutorials/how-to-install-prometheus-using-docker-on-ubuntu-14-04).
+
+## Podcasts and interviews
+
+* [Prometheus on FLOSS Weekly 357](https://twit.tv/shows/floss-weekly/episodes/357) - Julius Volz on the [FLOSS Weekly TWiT.tv](https://twit.tv/shows/floss-weekly/) show.
+* [Prometheus and Service Monitoring](https://changelog.com/podcast/168) - Julius Volz on the [Changelog](https://changelog.com/) podcast.
+
+## Recorded talks
+
+* [Prometheus: A Next-Generation Monitoring System](https://www.usenix.org/conference/srecon15europe/program/presentation/rabenstein) – Julius Volz and Björn Rabenstein at SREcon15 Europe, Dublin.
+* [Prometheus: A Next-Generation Monitoring System](https://www.youtube.com/watch?v=cwRmXqXKGtk) - Brian Brazil at FOSDEM 2016 ([slides](http://www.slideshare.net/brianbrazil/prometheus-a-next-generation-monitoring-system-fosdem-2016)).
+* [What is your application doing right now?](http://youtu.be/Z0LlilNpX1U) – Matthias Gruter, Transmode, at DevOps Stockholm Meetup.
+* [Prometheus workshop](https://vimeo.com/131581353) – Jamie Wilkinson at Monitorama PDX 2015 ([slides](https://docs.google.com/presentation/d/1X1rKozAUuF2MVc1YXElFWq9wkcWv3Axdldl8LOH9Vik/edit)).
+* [Monitoring Hadoop with Prometheus](https://www.youtube.com/watch?v=qs2sqOLNGtw) – Brian Brazil at the Hadoop User Group Ireland ([slides](http://www.slideshare.net/brianbrazil/monitoring-hadoop-with-prometheus-hadoop-user-group-ireland-december-2015)).
+* In German: [Monitoring mit Prometheus](https://media.ccc.de/v/eh16-43-monitoring_mit_prometheus#video&t=2804) – Michael Stapelberg at [Easterhegg 2016](https://eh16.easterhegg.eu/).
+* In German: [Prometheus in der Praxis](https://media.ccc.de/v/MRMCD16-7754-prometheus_in_der_praxis) – Jonas Große Sundrup at [MRMCD 2016](https://2016.mrmcd.net/)
+
+## Presentation slides
+
+### General
+
+* [Prometheus Overview](http://www.slideshare.net/brianbrazil/prometheus-overview) – by Brian Brazil.
+* [Systems Monitoring with Prometheus](http://www.slideshare.net/brianbrazil/devops-ireland-systems-monitoring-with-prometheus) – Brian Brazil at Devops Ireland Meetup, Dublin.
+* [OMG! Prometheus](https://www.dropbox.com/s/0l7kxhjqjbabtb0/prometheus%20site-ops%20preso.pdf?dl=0) – Benjamin Staffin, Fitbit Site Operations, explains the case for Prometheus to his team.
+
+### Docker
+
+* [Prometheus and Docker](http://www.slideshare.net/brianbrazil/prometheus-and-docker-docker-galway-november-2015) – Brian Brazil at Docker Galway.
+
+### Python
+
+* [Better Monitoring for Python](http://www.slideshare.net/brianbrazil/better-monitoring-for-python-inclusive-monitoring-with-prometheus-pycon-ireland-lightning-talk) – Brian Brazil at Pycon Ireland.
+* [Monitoring your Python with Prometheus](http://www.slideshare.net/brianbrazil/python-ireland-monitoring-your-python-with-prometheus) – Brian Brazil at Python Ireland Meetup, Dublin.
diff --git a/docs/introduction/overview.md b/docs/introduction/overview.md
new file mode 100644
index 00000000..8699a1f5
--- /dev/null
+++ b/docs/introduction/overview.md
@@ -0,0 +1,92 @@
+---
+title: Overview
+sort_rank: 1
+---
+
+# Overview
+
+## What is Prometheus?
+
+[Prometheus](https://github.com/prometheus) is an open-source systems
+monitoring and alerting toolkit originally built at
+[SoundCloud](http://soundcloud.com). Since its inception in 2012, many
+companies and organizations have adopted Prometheus, and the project has a very
+active developer and user [community](/community). It is now a standalone open source project
+and maintained independently of any company. To emphasize this, and to clarify
+the project's governance structure, Prometheus joined the
+[Cloud Native Computing Foundation](https://cncf.io/) in 2016
+as the second hosted project, after [Kubernetes](http://kubernetes.io/).
+
+Prometheus collects and stores its metrics as time series data, i.e. metrics information is stored with the timestamp at which it was recorded, alongside optional key-value pairs called labels.
+
+For more elaborate overviews of Prometheus, see the resources linked from the
+[media](/docs/introduction/media/) section.
+
+### Features
+
+Prometheus's main features are:
+
+* a multi-dimensional [data model](/docs/concepts/data_model/) with time series data identified by metric name and key/value pairs
+* PromQL, a [flexible query language](/docs/prometheus/latest/querying/basics/)
+  to leverage this dimensionality
+* no reliance on distributed storage; single server nodes are autonomous
+* time series collection happens via a pull model over HTTP
+* [pushing time series](/docs/instrumenting/pushing/) is supported via an intermediary gateway
+* targets are discovered via service discovery or static configuration
+* multiple modes of graphing and dashboarding support
+
+### What are metrics?
+
+Metrics are numerical measurements in layperson terms. The term time series refers to the recording of changes over time. What users want to measure differs from application to application. For a web server, it could be request times; for a database, it could be the number of active connections or active queries, and so on.
+
+Metrics play an important role in understanding why your application is working in a certain way. Let's assume you are running a web application and discover that it is slow. To learn what is happening with your application, you will need some information. For example, when the number of requests is high, the application may become slow. If you have the request count metric, you can determine the cause and increase the number of servers to handle the load.
+
+### Components
+
+The Prometheus ecosystem consists of multiple components, many of which are
+optional:
+
+* the main [Prometheus server](https://github.com/prometheus/prometheus) which scrapes and stores time series data
+* [client libraries](/docs/instrumenting/clientlibs/) for instrumenting application code
+* a [push gateway](https://github.com/prometheus/pushgateway) for supporting short-lived jobs
+* special-purpose [exporters](/docs/instrumenting/exporters/) for services like HAProxy, StatsD, Graphite, etc.
+* an [alertmanager](https://github.com/prometheus/alertmanager) to handle alerts
+* various support tools
+
+Most Prometheus components are written in [Go](https://golang.org/), making
+them easy to build and deploy as static binaries.
+
+### Architecture
+
+This diagram illustrates the architecture of Prometheus and some of
+its ecosystem components:
+
+![Prometheus architecture](/assets/architecture.png)
+
+Prometheus scrapes metrics from instrumented jobs, either directly or via an
+intermediary push gateway for short-lived jobs. It stores all scraped samples
+locally and runs rules over this data to either aggregate and record new time
+series from existing data or generate alerts. [Grafana](https://grafana.com/) or
+other API consumers can be used to visualize the collected data.
+
+## When does it fit?
+
+Prometheus works well for recording any purely numeric time series. It fits
+both machine-centric monitoring as well as monitoring of highly dynamic
+service-oriented architectures. In a world of microservices, its support for
+multi-dimensional data collection and querying is a particular strength.
+
+Prometheus is designed for reliability, to be the system you go to
+during an outage to allow you to quickly diagnose problems. Each Prometheus
+server is standalone, not depending on network storage or other remote services.
+You can rely on it when other parts of your infrastructure are broken, and
+you do not need to setup extensive infrastructure to use it.
+
+## When does it not fit?
+
+Prometheus values reliability. You can always view what statistics are
+available about your system, even under failure conditions. If you need 100%
+accuracy, such as for per-request billing, Prometheus is not a good choice as
+the collected data will likely not be detailed and complete enough. In such a
+case you would be best off using some other system to collect and analyze the
+data for billing, and Prometheus for the rest of your monitoring.
diff --git a/docs/introduction/release-cycle.md b/docs/introduction/release-cycle.md
new file mode 100644
index 00000000..9953a455
--- /dev/null
+++ b/docs/introduction/release-cycle.md
@@ -0,0 +1,58 @@
+---
+title: Long-Term Support
+sort_rank: 10
+---
+
+# Long Term Support
+
+Prometheus LTS are selected releases of Prometheus that receive bugfixes for an
+extended period of time.
+
+Every 6 weeks, a new Prometheus minor release cycle begins. After those 6
+weeks, minor releases generally no longer receive bugfixes. If a user is
+impacted by a bug in a minor release, they often need to upgrade to the
+latest Prometheus release.
+
+Upgrading Prometheus should be straightforward thanks to our [API stability
+guarantees][stab]. However,
+there is a risk that new features and enhancements could also bring regressions,
+requiring another upgrade.
+
+Prometheus LTS only receive bug, security, and documentation fixes, but over a
+time window of one year. The build toolchain will also be kept up-to-date. This
+allows companies that rely on Prometheus to limit the upgrade risks while still
+having a Prometheus server maintained by the community.
+
+## List of LTS releases
+
+<table class="table table-bordered downloads">
+    <thead>
+        <tr>
+            <th>Release</th>
+            <th>Date</th>
+            <th>End of support</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr class="danger">
+            <td>Prometheus 2.37</td><td>2022-07-14</td><td>2023-07-31</td>
+        </tr>
+        <tr class="danger">
+            <td>Prometheus 2.45</td><td>2023-06-23</td><td>2024-07-31</td>
+        </tr>
+        <tr class="success">
+            <td>Prometheus 2.53</td><td>2024-06-16</td><td>2025-07-31</td>
+        </tr>
+    </tbody>
+</table>
+
+## Limitations of LTS support
+
+Some features are excluded from LTS support:
+
+- Things listed as unstable in our [API stability guarantees][stab].
+- [Experimental features][fflag].
+- OpenBSD support.
+
+[stab]:https://prometheus.io/docs/prometheus/latest/stability/
+[fflag]:https://prometheus.io/docs/prometheus/latest/feature_flags/
diff --git a/docs/introduction/roadmap.md b/docs/introduction/roadmap.md
new file mode 100644
index 00000000..057c8450
--- /dev/null
+++ b/docs/introduction/roadmap.md
@@ -0,0 +1,42 @@
+---
+title: Roadmap
+sort_rank: 6
+---
+
+# Roadmap
+
+The following is only a selection of some of the major features we plan to
+implement in the near future. To get a more complete overview of planned
+features and current work, see the issue trackers for the various repositories,
+for example, the [Prometheus
+server](https://github.com/prometheus/prometheus/issues).
+
+### Server-side metric metadata support
+
+At this time, metric types and other metadata are only used in the
+client libraries and in the exposition format, but not persisted or
+utilized in the Prometheus server. We plan on making use of this
+metadata in the future. The first step is to aggregate this data in-memory
+in Prometheus and provide it via an experimental API endpoint.
+
+### Adopt OpenMetrics
+
+The OpenMetrics working group is developing a new standard for metric exposition.
+We plan to support this format in our client libraries and Prometheus itself.
+
+### Retroactive rule evaluations		
+
+Add support for retroactive rule evaluations making use of backfill.
+
+### TLS and authentication in HTTP serving endpoints
+
+TLS and authentication are currently being rolled out to the Prometheus,
+Alertmanager, and the official exporters. Adding this support will make it
+easier for people to deploy Prometheus components securely without requiring a
+reverse proxy to add those features externally.
+
+### Support the Ecosystem
+
+Prometheus has a range of client libraries and exporters. There are always more
+languages that could be supported, or systems that would be useful to export
+metrics from. We will support the ecosystem in creating and expanding these.
diff --git a/docs/operating/index.md b/docs/operating/index.md
new file mode 100644
index 00000000..d783f632
--- /dev/null
+++ b/docs/operating/index.md
@@ -0,0 +1,5 @@
+---
+title: Operating
+sort_rank: 5
+nav_icon: settings
+---
diff --git a/docs/operating/integrations.md b/docs/operating/integrations.md
new file mode 100644
index 00000000..61dd04ac
--- /dev/null
+++ b/docs/operating/integrations.md
@@ -0,0 +1,126 @@
+---
+title: Integrations
+sort_rank: 5
+---
+
+# Integrations
+
+In addition to [client libraries](/docs/instrumenting/clientlibs/) and
+[exporters and related libraries](/docs/instrumenting/exporters/), there are
+numerous other generic integration points in Prometheus. This page lists some
+of the integrations with these.
+
+
+Not all integrations are listed here, due to overlapping functionality or still
+being in development. The [exporter default
+port](https://github.com/prometheus/prometheus/wiki/Default-port-allocations)
+wiki page also happens to include a few non-exporter integrations that fit in
+these categories.
+
+## File Service Discovery
+
+For service discovery mechanisms not natively supported by Prometheus,
+[file-based service discovery](/docs/operating/configuration/#%3Cfile_sd_config%3E) provides an interface for integrating.
+
+ * [Kuma](https://github.com/kumahq/kuma/tree/master/app/kuma-prometheus-sd)
+ * [Lightsail](https://github.com/n888/prometheus-lightsail-sd)
+ * [Netbox](https://github.com/FlxPeters/netbox-prometheus-sd)
+ * [Packet](https://github.com/packethost/prometheus-packet-sd)
+ * [Scaleway](https://github.com/scaleway/prometheus-scw-sd)
+
+## Remote Endpoints and Storage
+
+The [remote write](/docs/operating/configuration/#remote_write) and [remote read](/docs/operating/configuration/#remote_read)
+features of Prometheus allow transparently sending and receiving samples. This
+is primarily intended for long term storage. It is recommended that you perform
+careful evaluation of any solution in this space to confirm it can handle your
+data volumes.
+
+  * [AppOptics](https://github.com/solarwinds/prometheus2appoptics): write
+  * [AWS Timestream](https://github.com/dpattmann/prometheus-timestream-adapter): read and write
+  * [Azure Data Explorer](https://github.com/cosh/PrometheusToAdx): read and write
+  * [Azure Event Hubs](https://github.com/bryanklewis/prometheus-eventhubs-adapter): write
+  * [Chronix](https://github.com/ChronixDB/chronix.ingester): write
+  * [Cortex](https://github.com/cortexproject/cortex): read and write
+  * [CrateDB](https://github.com/crate/crate_adapter): read and write
+  * [Elasticsearch](https://www.elastic.co/guide/en/beats/metricbeat/master/metricbeat-metricset-prometheus-remote_write.html): write
+  * [Gnocchi](https://gnocchi.osci.io/prometheus.html): write
+  * [Google BigQuery](https://github.com/KohlsTechnology/prometheus_bigquery_remote_storage_adapter): read and write
+  * [Google Cloud Spanner](https://github.com/google/truestreet): read and write
+  * [Grafana Mimir](https://github.com/grafana/mimir): read and write
+  * [Graphite](https://github.com/prometheus/prometheus/tree/main/documentation/examples/remote_storage/remote_storage_adapter): write
+  * [GreptimeDB](https://github.com/GreptimeTeam/greptimedb): read and write
+  * [InfluxDB](https://docs.influxdata.com/influxdb/v1.8/supported_protocols/prometheus): read and write
+  * [Instana](https://www.instana.com/docs/ecosystem/prometheus/#remote-write): write
+  * [IRONdb](https://github.com/circonus-labs/irondb-prometheus-adapter): read and write
+  * [Kafka](https://github.com/Telefonica/prometheus-kafka-adapter): write
+  * [M3DB](https://m3db.io/docs/integrations/prometheus/): read and write
+  * [Mezmo](https://docs.mezmo.com/telemetry-pipelines/prometheus-remote-write-pipeline-source): write
+  * [New Relic](https://docs.newrelic.com/docs/set-or-remove-your-prometheus-remote-write-integration): write
+  * [OpenTSDB](https://github.com/prometheus/prometheus/tree/main/documentation/examples/remote_storage/remote_storage_adapter): write
+  * [QuasarDB](https://doc.quasardb.net/master/user-guide/integration/prometheus.html): read and write
+  * [SignalFx](https://github.com/signalfx/metricproxy#prometheus): write
+  * [Splunk](https://github.com/kebe7jun/ropee): read and write
+  * [Sysdig Monitor](https://docs.sysdig.com/en/docs/installation/prometheus-remote-write/): write
+  * [TiKV](https://github.com/bragfoo/TiPrometheus): read and write
+  * [Thanos](https://github.com/thanos-io/thanos): read and write
+  * [VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics): write
+  * [Wavefront](https://github.com/wavefrontHQ/prometheus-storage-adapter): write
+
+[Prom-migrator](https://github.com/timescale/promscale/tree/master/migration-tool/cmd/prom-migrator) is a tool for migrating data between remote storage systems.
+
+## Alertmanager Webhook Receiver
+
+For notification mechanisms not natively supported by the Alertmanager, the
+[webhook receiver](/docs/alerting/configuration/#webhook_config) allows for integration.
+
+  * [alertmanager-webhook-logger](https://github.com/tomtom-international/alertmanager-webhook-logger): logs alerts
+  * [Alertsnitch](https://gitlab.com/yakshaving.art/alertsnitch): saves alerts to a MySQL database
+  * [All Quiet](https://allquiet.app/integrations/inbound/prometheus): on-call & incident management
+  * [Asana](https://gitlab.com/lupudu/alertmanager-asana-bridge)
+  * [AWS SNS](https://github.com/DataReply/alertmanager-sns-forwarder)
+  * [Better Uptime](https://docs.betteruptime.com/integrations/prometheus)
+  * [Canopsis](https://git.canopsis.net/canopsis-connectors/connector-prometheus2canopsis)
+  * [DingTalk](https://github.com/timonwong/prometheus-webhook-dingtalk)
+  * [Discord](https://github.com/benjojo/alertmanager-discord)
+  * [GitLab](https://docs.gitlab.com/ee/operations/metrics/alerts.html#external-prometheus-instances)
+  * [Gotify](https://github.com/DRuggeri/alertmanager_gotify_bridge)
+  * [GELF](https://github.com/b-com-software-basis/alertmanager2gelf)
+  * [Heii On-Call](https://heiioncall.com/guides/prometheus-integration)
+  * [Icinga2](https://github.com/vshn/signalilo)
+  * [iLert](https://docs.ilert.com/integrations/prometheus)
+  * [IRC Bot](https://github.com/multimfi/bot)
+  * [JIRAlert](https://github.com/free/jiralert)
+  * [Matrix](https://github.com/matrix-org/go-neb)
+  * [Phabricator / Maniphest](https://github.com/knyar/phalerts)
+  * [prom2teams](https://github.com/idealista/prom2teams): forwards notifications to Microsoft Teams
+  * [Ansible Tower](https://github.com/pja237/prom2tower): call Ansible Tower (AWX) API on alerts (launch jobs etc.)
+  * [Signal](https://github.com/dgl/alertmanager-webhook-signald)
+  * [SIGNL4](https://www.signl4.com/blog/portfolio_item/prometheus-alertmanager-mobile-alert-notification-duty-schedule-escalation)
+  * [Simplepush](https://codeberg.org/stealth/alertpush)
+  * [SMS](https://github.com/messagebird/sachet): supports [multiple providers](https://github.com/messagebird/sachet/blob/master/examples/config.yaml)
+  * [SNMP traps](https://github.com/maxwo/snmp_notifier)
+  * [Squadcast](https://support.squadcast.com/docs/prometheus)
+  * [STOMP](https://github.com/thewillyhuman/alertmanager-stomp-forwarder)
+  * [Telegram bot](https://github.com/inCaller/prometheus_bot)
+  * [xMatters](https://github.com/xmatters/xm-labs-prometheus)
+  * [XMPP Bot](https://github.com/jelmer/prometheus-xmpp-alerts)
+  * [Zenduty](https://docs.zenduty.com/docs/prometheus/)
+  * [Zoom](https://github.com/Code2Life/nodess-apps/tree/master/src/zoom-alert-2.0)
+
+## Management
+
+Prometheus does not include configuration management functionality, allowing
+you to integrate it with your existing systems or build on top of it.
+
+  * [Prometheus Operator](https://github.com/coreos/prometheus-operator): Manages Prometheus on top of Kubernetes
+  * [Promgen](https://github.com/line/promgen): Web UI and configuration generator for Prometheus and Alertmanager
+
+## Other
+
+  * [Alert analysis](https://github.com/m0nikasingh/am2ch): Stores alerts into a ClickHouse database and provides alert analysis dashboards
+  * [karma](https://github.com/prymitive/karma): alert dashboard
+  * [PushProx](https://github.com/RobustPerception/PushProx): Proxy to transverse NAT and similar network setups
+  * [Promdump](https://github.com/ihcsim/promdump): kubectl plugin to dump and restore data blocks
+  * [Promregator](https://github.com/promregator/promregator): discovery and scraping for Cloud Foundry applications
+  * [pint](https://github.com/cloudflare/pint): Prometheus rule linter
diff --git a/docs/operating/security.md b/docs/operating/security.md
new file mode 100644
index 00000000..4ee84226
--- /dev/null
+++ b/docs/operating/security.md
@@ -0,0 +1,279 @@
+---
+title: Security
+sort_rank: 4
+---
+
+NOTE: Before we dive into the technical details below, we would like to
+emphasize that Prometheus, as a monitoring system, collects and serves
+information about the systems it is monitoring. Therefore, the HTTP endpoints
+provided by Prometheus components should not be exposed to publicly accessible
+networks like the internet (unless you know what you are doing and have taken
+appropriate measures). This includes (but is not limited to) the `/metrics`
+endpoint of instrumented binaries, the various API endpoints of server
+components, and the `/pprof` endpoint of server components implemented in Go.
+Furthermore, it is easily possible to overload and ultimately DoS servers with
+requests to these endpoints.
+
+# Security Model
+
+Prometheus is a sophisticated system with many components and many integrations
+with other systems. It can be deployed in a variety of trusted and untrusted
+environments.
+
+This page describes the general security assumptions of Prometheus and the
+attack vectors that some configurations may enable.
+
+As with any complex system, it is near certain that bugs will be found, some of
+them security-relevant. If you find a _security bug_ please report it
+privately to the maintainers listed in the MAINTAINERS of the relevant
+repository and CC prometheus-team@googlegroups.com. We will fix the issue as soon
+as possible and coordinate a release date with you. You will be able to choose
+if you want public acknowledgement of your effort and if you want to be
+mentioned by name.
+
+### Automated security scanners
+
+Special note for security scanner users: Please be mindful with the reports produced.
+Most scanners are generic and produce lots of false positives. More and more
+reports are being sent to us, and it takes a significant amount of work to go
+through all of them and reply with the care you expect. This problem is particularly
+bad with Go and NPM dependency scanners.
+
+As a courtesy to us and our time, we would ask you not to submit raw reports.
+Instead, please submit them with an analysis outlining which specific results
+are applicable to us and why.
+
+Prometheus is maintained by volunteers, not by a company. Therefore, fixing
+security issues is done on a best-effort basis. We strive to release security
+fixes within 7 days for: Prometheus, Alertmanager, Node Exporter,
+Blackbox Exporter, and Pushgateway.
+
+## Prometheus
+
+It is presumed that untrusted users have access to the Prometheus HTTP endpoint
+and logs. They have access to all time series information contained in the
+database, plus a variety of operational/debugging information.
+
+It is also presumed that only trusted users have the ability to change the
+command line, configuration file, rule files and other aspects of the runtime
+environment of Prometheus and other components.
+
+Which targets Prometheus scrapes, how often and with what other settings is
+determined entirely via the configuration file. The administrator may
+decide to use information from service discovery systems, which combined with
+relabelling may grant some of this control to anyone who can modify data in
+that service discovery system.
+
+Scraped targets may be run by untrusted users. It should not by default be
+possible for a target to expose data that impersonates a different target.  The
+`honor_labels` option removes this protection, as can certain relabelling
+setups.
+
+As of Prometheus 2.0, the `--web.enable-admin-api` flag controls access to the
+administrative HTTP API which includes functionality such as deleting time
+series. This is disabled by default. If enabled, administrative and mutating
+functionality will be accessible under the `/api/*/admin/` paths. The
+`--web.enable-lifecycle` flag controls HTTP reloads and shutdowns of
+Prometheus. This is also disabled by default. If enabled they will be
+accessible under the `/-/reload` and `/-/quit` paths.
+
+In Prometheus 1.x, `/-/reload` and using `DELETE` on `/api/v1/series` are
+accessible to anyone with access to the HTTP API. The `/-/quit` endpoint is
+disabled by default, but can be enabled with the `-web.enable-remote-shutdown`
+flag.
+
+The remote read feature allows anyone with HTTP access to send queries to the
+remote read endpoint. If for example the PromQL queries were ending up directly
+run against a relational database, then anyone with the ability to send queries
+to Prometheus (such as via Grafana) can run arbitrary SQL against that
+database.
+
+## Alertmanager
+
+Any user with access to the Alertmanager HTTP endpoint has access to its data.
+They can create and resolve alerts. They can create, modify and delete
+silences.
+
+Where notifications are sent to is determined by the configuration file. With
+certain templating setups it is possible for notifications to end up at an
+alert-defined destination. For example if notifications use an alert label as
+the destination email address, anyone who can send alerts to the Alertmanager
+can send notifications to any email address. If the alert-defined destination
+is a templatable secret field, anyone with access to either Prometheus or
+Alertmanager will be able to view the secrets.
+
+Any secret fields which are templatable are intended for routing notifications
+in the above use case. They are not intended as a way for secrets to be
+separated out from the configuration files using the template file feature. Any
+secrets stored in template files could be exfiltrated by anyone able to
+configure receivers in the Alertmanager configuration file. For example in
+large setups, each team might have an alertmanager configuration file fragment
+which they fully control, that are then combined into the full final
+configuration file.
+
+## Pushgateway
+
+Any user with access to the Pushgateway HTTP endpoint can create, modify and
+delete the metrics contained within. As the Pushgateway is usually scraped with
+`honor_labels` enabled, this means anyone with access to the Pushgateway can
+create any time series in Prometheus.
+
+The `--web.enable-admin-api` flag controls access to the
+administrative HTTP API, which includes functionality such as wiping all the existing
+metric groups. This is disabled by default. If enabled, administrative
+functionality will be accessible under the `/api/*/admin/` paths.
+
+## Exporters
+
+Exporters generally only talk to one configured instance with a preset set of
+commands/requests, which cannot be expanded via their HTTP endpoint.
+
+There are also exporters such as the SNMP and Blackbox exporters that take
+their targets from URL parameters. Thus anyone with HTTP access to these
+exporters can make them send requests to arbitrary endpoints. As they also
+support client-side authentication, this could lead to a leak of secrets such
+as HTTP Basic Auth passwords or SNMP community strings. Challenge-response
+authentication mechanisms such as TLS are not affected by this.
+
+## Client Libraries
+
+Client libraries are intended to be included in users' applications.
+
+If using a client-library-provided HTTP handler, it should not be possible for
+malicious requests that reach that handler to cause issues beyond those
+resulting from additional load and failed scrapes.
+
+## Authentication, Authorization, and Encryption
+
+Prometheus, and most exporters, support TLS. Including authentication of clients
+via TLS client certificates. Details on configuring Prometheus are [`here`](https://prometheus.io/docs/guides/tls-encryption/).
+
+The Go projects share the same TLS library, based on the
+Go [crypto/tls](https://golang.org/pkg/crypto/tls) library.
+We default to TLS 1.2 as minimum version. Our policy regarding this is based on
+[Qualys SSL Labs](https://www.ssllabs.com/) recommendations, where we strive to
+achieve a grade 'A' with a default configuration and correctly provided
+certificates, while sticking as closely as possible to the upstream Go defaults.
+Achieving that grade provides a balance between perfect security and usability.
+
+TLS will be added to Java exporters in the future.
+
+If you have special TLS needs, like a different cipher suite or older TLS
+version, you can tune the minimum TLS version and the ciphers, as long as the
+cipher is not [marked as insecure](https://golang.org/pkg/crypto/tls/#InsecureCipherSuites)
+in the [crypto/tls](https://golang.org/pkg/crypto/tls) library. If that still
+does not suit you, the current TLS settings enable you to build a secure tunnel
+between the servers and reverse proxies with more special requirements.
+
+HTTP Basic Authentication is also supported. Basic Authentication can be
+used without TLS, but it will then expose usernames and passwords in cleartext
+over the network.
+
+On the server side, basic authentication passwords are stored as hashes with the
+[bcrypt](https://en.wikipedia.org/wiki/Bcrypt) algorithm. It is your
+responsibility to pick the number of rounds that matches your security
+standards. More rounds make brute-force more complicated at the cost of more CPU
+power and more time to authenticate the requests.
+
+Various Prometheus components support client-side authentication and
+encryption. If TLS client support is offered, there is often also an option
+called `insecure_skip_verify` which skips SSL verification.
+
+## API Security
+
+As administrative and mutating endpoints are intended to be accessed via simple
+tools such as cURL, there is no built in
+[CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery) protection as
+that would break such use cases. Accordingly when using a reverse proxy, you
+may wish to block such paths to prevent CSRF.
+
+For non-mutating endpoints, you may wish to set [CORS
+headers](https://fetch.spec.whatwg.org/#http-cors-protocol) such as
+`Access-Control-Allow-Origin` in your reverse proxy to prevent
+[XSS](https://en.wikipedia.org/wiki/Cross-site_scripting).
+
+If you are composing PromQL queries that include input from untrusted users
+(e.g. URL parameters to console templates, or something you built yourself) who
+are not meant to be able to run arbitrary PromQL queries make sure any
+untrusted input is appropriately escaped to prevent injection attacks. For
+example `up{job="<user_input>"}` would become `up{job=""} or
+some_metric{zzz=""}` if the `<user_input>` was `"} or some_metric{zzz="`.
+
+For those using Grafana note that [dashboard permissions are not data source
+permissions](https://grafana.com/docs/grafana/latest/permissions/#data-source-permissions),
+so do not limit a user's ability to run arbitrary queries in proxy mode.
+
+## Secrets
+
+Non-secret information or fields may be available via the HTTP API and/or logs.
+
+In Prometheus, metadata retrieved from service discovery is not considered
+secret. Throughout the Prometheus system, metrics are not considered secret.
+
+Fields containing secrets in configuration files (marked explicitly as such in
+the documentation) will not be exposed in logs or via the HTTP API. Secrets
+should not be placed in other configuration fields, as it is common for
+components to expose their configuration over their HTTP endpoint. It is the
+responsibility of the user to protect files on disk from unwanted reads and
+writes.
+
+Secrets from other sources used by dependencies (e.g. the `AWS_SECRET_KEY`
+environment variable as used by EC2 service discovery) may end up exposed due to
+code outside of our control or due to functionality that happens to expose
+wherever it is stored.
+
+## Denial of Service
+
+There are some mitigations in place for excess load or expensive queries.
+However, if too many or too expensive queries/metrics are provided components
+will fall over. It is more likely that a component will be accidentally taken
+out by a trusted user than by malicious action.
+
+It is the responsibility of the user to ensure they provide components with
+sufficient resources including CPU, RAM, disk space, IOPS, file descriptors,
+and bandwidth.
+
+It is recommended to monitor all components for failure, and to have them
+automatically restart on failure.
+
+## Libraries
+
+This document considers vanilla binaries built from the stock source code.
+Information presented here does not apply if you modify Prometheus source code,
+or use Prometheus internals (beyond the official client library APIs) in your
+own code.
+
+## Build Process
+
+The build pipeline for Prometheus runs on third-party providers to which many
+members of the Prometheus development team and the staff of those providers
+have access. If you are concerned about the exact provenance of your binaries,
+it is recommended to build them yourself rather than relying on the
+pre-built binaries provided by the project.
+
+## Prometheus-Community
+
+The repositories under the [Prometheus-Community](https://github.com/prometheus-community)
+organization are supported by third-party maintainers.
+
+If you find a _security bug_ in the [Prometheus-Community](https://github.com/prometheus-community) organization,
+please report it privately to the maintainers listed in the MAINTAINERS of the
+relevant repository and CC prometheus-team@googlegroups.com.
+
+Some repositories under that organization might have a different security model
+than the ones presented in this document. In such a case, please refer to the
+documentation of those repositories.
+
+## External audits
+
+* In 2018, [CNCF](https://cncf.io) sponsored an external security audit by
+[cure53](https://cure53.de) which ran from April 2018 to June 2018. For more
+details, please read the [final report of the audit](/assets/downloads/2018-06-11--cure53_security_audit.pdf).
+
+* In 2020, CNCF sponsored a
+[second audit by cure53](/assets/downloads/2020-07-21--cure53_security_audit_node_exporter.pdf)
+of Node Exporter.
+
+* In 2023, CNCF sponsored a
+[software supply chain security assessment of Prometheus](/assets/downloads/2023-04-19--chainguard_supply_chain_assessment.pdf)
+by Chainguard.
diff --git a/docs/practices/alerting.md b/docs/practices/alerting.md
new file mode 100644
index 00000000..8836c602
--- /dev/null
+++ b/docs/practices/alerting.md
@@ -0,0 +1,78 @@
+---
+title: Alerting
+sort_rank: 5
+---
+
+# Alerting
+
+We recommend that you read [My Philosophy on Alerting](https://docs.google.com/a/boxever.com/document/d/199PqyG3UsyXlwieHaqbGiWVa8eMWi8zzAn0YfcApr8Q/edit)
+based on Rob Ewaschuk's observations at Google.
+
+To summarize: keep alerting simple, alert on symptoms, have good consoles to
+allow pinpointing causes, and avoid having pages where there is nothing to do.
+
+## Naming
+
+There are no strict restrictions regarding the naming of alerting rules, as alert names may contain any number of Unicode characters, just like any other label value. However, [the community has rallied around](https://monitoring.mixins.dev/) using [Camel Case](https://en.wikipedia.org/wiki/Camel_case) for their alert names.
+
+## What to alert on
+
+Aim to have as few alerts as possible, by alerting on symptoms that are
+associated with end-user pain rather than trying to catch every possible way
+that pain could be caused. Alerts should link to relevant consoles
+and make it easy to figure out which component is at fault.
+
+Allow for slack in alerting to accommodate small blips.
+
+### Online serving systems
+
+Typically alert on high latency and error rates as high up in the stack as possible.
+
+Only page on latency at one point in a stack. If a lower-level component is
+slower than it should be, but the overall user latency is fine, then there is
+no need to page.
+
+For error rates, page on user-visible errors. If there are errors further down
+the stack that will cause such a failure, there is no need to page on them
+separately. However, if some failures are not user-visible, but are otherwise
+severe enough to require human involvement (for example, you are losing a lot of
+money), add pages to be sent on those.
+
+You may need alerts for different types of request if they have different
+characteristics, or problems in a low-traffic type of request would be drowned
+out by high-traffic requests.
+
+### Offline processing
+
+For offline processing systems, the key metric is how long data takes to get
+through the system, so page if that gets high enough to cause user impact.
+
+### Batch jobs
+
+For batch jobs it makes sense to page if the batch job has not succeeded
+recently enough, and this will cause user-visible problems.
+
+This should generally be at least enough time for 2 full runs of the batch job.
+For a job that runs every 4 hours and takes an hour, 10 hours would be a
+reasonable threshold. If you cannot withstand a single run failing, run the
+job more frequently, as a single failure should not require human intervention.
+
+### Capacity
+
+While not a problem causing immediate user impact, being close to capacity
+often requires human intervention to avoid an outage in the near future.
+
+### Metamonitoring
+
+It is important to have confidence that monitoring is working. Accordingly, have
+alerts to ensure that Prometheus servers, Alertmanagers, PushGateways, and
+other monitoring infrastructure are available and running correctly.
+
+As always, if it is possible to alert on symptoms rather than causes, this helps
+to reduce noise. For example, a blackbox test that alerts are getting from
+PushGateway to Prometheus to Alertmanager to email is better than individual
+alerts on each.
+
+Supplementing the whitebox monitoring of Prometheus with external blackbox
+monitoring can catch problems that are otherwise invisible, and also serves as
+a fallback in case internal systems completely fail.
diff --git a/docs/practices/consoles.md b/docs/practices/consoles.md
new file mode 100644
index 00000000..c0d6bc15
--- /dev/null
+++ b/docs/practices/consoles.md
@@ -0,0 +1,39 @@
+---
+title: Consoles and dashboards
+sort_rank: 3
+---
+
+# Consoles and dashboards
+
+It can be tempting to display as much data as possible on a dashboard, especially
+when a system like Prometheus offers the ability to have such rich
+instrumentation of your applications. This can lead to consoles that are
+impenetrable due to having too much information, that even an expert in the
+system would have difficulty drawing meaning from.
+
+Instead of trying to represent every piece of data you have, for operational
+consoles think of what are the most likely failure modes and how you would use the
+consoles to differentiate them. Take advantage of the structure of your
+services. For example, if you have a big tree of services in an online-serving
+system, latency in some lower service is a typical problem. Rather than showing
+every service's information on a single large dashboard, build separate dashboards
+for each service that include the latency and errors for each service they talk
+to. You can then start at the top and work your way down to the problematic
+service.
+
+We have found the following guidelines very effective:
+
+* Have no more than 5 graphs on a console.
+* Have no more than 5 plots (lines) on each graph. You can get away with more if it is a stacked/area graph.
+* When using the provided console template examples, avoid more than 20-30 entries in the right-hand-side table.
+
+If you find yourself exceeding these, it could make sense to demote the visibility of
+less important information, possibly splitting out some subsystems to a new console.
+For example, you could graph aggregated rather than broken-down data, move
+it to the right-hand-side table, or even remove data completely if it is rarely
+useful - you can always look at it in the [expression browser](/docs/visualization/browser/)!
+
+Finally, it is difficult for a set of consoles to serve more than one master.
+What you want to know when oncall (what is broken?) tends to be very different
+from what you want when developing features (how many people hit corner
+case X?). In such cases, two separate sets of consoles can be useful.
diff --git a/docs/practices/histograms.md b/docs/practices/histograms.md
new file mode 100644
index 00000000..1ee1cd9d
--- /dev/null
+++ b/docs/practices/histograms.md
@@ -0,0 +1,239 @@
+---
+title: Histograms and summaries
+sort_rank: 4
+---
+
+NOTE: This document predates native histograms (added as an experimental
+feature in Prometheus v2.40). Once native histograms are closer to becoming a
+stable feature, this document will be thoroughly updated.
+
+# Histograms and summaries
+
+Histograms and summaries are more complex metric types. Not only does
+a single histogram or summary create a multitude of time series, it is
+also more difficult to use these metric types correctly. This section
+helps you to pick and configure the appropriate metric type for your
+use case.
+
+## Library support
+
+First of all, check the library support for
+[histograms](/docs/concepts/metric_types/#histogram) and
+[summaries](/docs/concepts/metric_types/#summary).
+
+Some libraries support only one of the two types, or they support summaries
+only in a limited fashion (lacking [quantile calculation](#quantiles)).
+
+## Count and sum of observations
+
+Histograms and summaries both sample observations, typically request
+durations or response sizes. They track the number of observations
+*and* the sum of the observed values, allowing you to calculate the
+*average* of the observed values. Note that the number of observations
+(showing up in Prometheus as a time series with a `_count` suffix) is
+inherently a counter (as described above, it only goes up). The sum of
+observations (showing up as a time series with a `_sum` suffix)
+behaves like a counter, too, as long as there are no negative
+observations. Obviously, request durations or response sizes are
+never negative. In principle, however, you can use summaries and
+histograms to observe negative values (e.g. temperatures in
+centigrade). In that case, the sum of observations can go down, so you
+cannot apply `rate()` to it anymore. In those rare cases where you need to
+apply `rate()` and cannot avoid negative observations, you can use two
+separate summaries, one for positive and one for negative observations
+(the latter with inverted sign), and combine the results later with suitable
+PromQL expressions.
+
+To calculate the average request duration during the last 5 minutes
+from a histogram or summary called `http_request_duration_seconds`,
+use the following expression:
+
+      rate(http_request_duration_seconds_sum[5m])
+    /
+      rate(http_request_duration_seconds_count[5m])
+
+## Apdex score
+
+A straight-forward use of histograms (but not summaries) is to count
+observations falling into particular buckets of observation
+values.
+
+You might have an SLO to serve 95% of requests within 300ms. In that
+case, configure a histogram to have a bucket with an upper limit of
+0.3 seconds. You can then directly express the relative amount of
+requests served within 300ms and easily alert if the value drops below
+0.95. The following expression calculates it by job for the requests
+served in the last 5 minutes. The request durations were collected with
+a histogram called `http_request_duration_seconds`.
+
+      sum(rate(http_request_duration_seconds_bucket{le="0.3"}[5m])) by (job)
+    /
+      sum(rate(http_request_duration_seconds_count[5m])) by (job)
+
+
+You can approximate the well-known [Apdex
+score](http://en.wikipedia.org/wiki/Apdex) in a similar way. Configure
+a bucket with the target request duration as the upper bound and
+another bucket with the tolerated request duration (usually 4 times
+the target request duration) as the upper bound. Example: The target
+request duration is 300ms. The tolerable request duration is 1.2s. The
+following expression yields the Apdex score for each job over the last
+5 minutes:
+
+    (
+      sum(rate(http_request_duration_seconds_bucket{le="0.3"}[5m])) by (job)
+    +
+      sum(rate(http_request_duration_seconds_bucket{le="1.2"}[5m])) by (job)
+    ) / 2 / sum(rate(http_request_duration_seconds_count[5m])) by (job)
+
+Note that we divide the sum of both buckets. The reason is that the histogram
+buckets are
+[cumulative](https://en.wikipedia.org/wiki/Histogram#Cumulative_histogram). The
+`le="0.3"` bucket is also contained in the `le="1.2"` bucket; dividing it by 2
+corrects for that.
+
+The calculation does not exactly match the traditional Apdex score, as it
+includes errors in the satisfied and tolerable parts of the calculation.
+
+## Quantiles
+
+You can use both summaries and histograms to calculate so-called φ-quantiles,
+where 0 ≤ φ ≤ 1. The φ-quantile is the observation value that ranks at number
+φ*N among the N observations. Examples for φ-quantiles: The 0.5-quantile is
+known as the median. The 0.95-quantile is the 95th percentile.
+
+The essential difference between summaries and histograms is that summaries
+calculate streaming φ-quantiles on the client side and expose them directly,
+while histograms expose bucketed observation counts and the calculation of
+quantiles from the buckets of a histogram happens on the server side using the
+[`histogram_quantile()`
+function](/docs/prometheus/latest/querying/functions/#histogram_quantile).
+
+The two approaches have a number of different implications:
+
+|   | Histogram | Summary
+|---|-----------|---------
+| Required configuration | Pick buckets suitable for the expected range of observed values. | Pick desired φ-quantiles and sliding window. Other φ-quantiles and sliding windows cannot be calculated later.
+| Client performance | Observations are very cheap as they only need to increment counters. | Observations are expensive due to the streaming quantile calculation.
+| Server performance | The server has to calculate quantiles. You can use [recording rules](/docs/prometheus/latest/configuration/recording_rules/#recording-rules) should the ad-hoc calculation take too long (e.g. in a large dashboard). | Low server-side cost.
+| Number of time series (in addition to the `_sum` and `_count` series) | One time series per configured bucket. | One time series per configured quantile.
+| Quantile error (see below for details) | Error is limited in the dimension of observed values by the width of the relevant bucket. | Error is limited in the dimension of φ by a configurable value.
+| Specification of φ-quantile and sliding time-window | Ad-hoc with [Prometheus expressions](/docs/prometheus/latest/querying/functions/#histogram_quantile). | Preconfigured by the client.
+| Aggregation | Ad-hoc with [Prometheus expressions](/docs/prometheus/latest/querying/functions/#histogram_quantile). | In general [not aggregatable](http://latencytipoftheday.blogspot.de/2014/06/latencytipoftheday-you-cant-average.html).
+
+Note the importance of the last item in the table. Let us return to
+the SLO of serving 95% of requests within 300ms. This time, you do not
+want to display the percentage of requests served within 300ms, but
+instead the 95th percentile, i.e. the request duration within which
+you have served 95% of requests. To do that, you can either configure
+a summary with a 0.95-quantile and (for example) a 5-minute decay
+time, or you configure a histogram with a few buckets around the 300ms
+mark, e.g. `{le="0.1"}`, `{le="0.2"}`, `{le="0.3"}`, and
+`{le="0.45"}`. If your service runs replicated with a number of
+instances, you will collect request durations from every single one of
+them, and then you want to aggregate everything into an overall 95th
+percentile. However, aggregating the precomputed quantiles from a
+summary rarely makes sense. In this particular case, averaging the
+quantiles yields statistically nonsensical values.
+
+    avg(http_request_duration_seconds{quantile="0.95"}) // BAD!
+
+Using histograms, the aggregation is perfectly possible with the
+[`histogram_quantile()`
+function](/docs/prometheus/latest/querying/functions/#histogram_quantile).
+
+    histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[5m])) by (le)) // GOOD.
+
+Furthermore, should your SLO change and you now want to plot the 90th
+percentile, or you want to take into account the last 10 minutes
+instead of the last 5 minutes, you only have to adjust the expression
+above and you do not need to reconfigure the clients.
+
+## Errors of quantile estimation
+
+Quantiles, whether calculated client-side or server-side, are
+estimated. It is important to understand the errors of that
+estimation.
+
+Continuing the histogram example from above, imagine your usual
+request durations are almost all very close to 220ms, or in other
+words, if you could plot the "true" histogram, you would see a very
+sharp spike at 220ms. In the Prometheus histogram metric as configured
+above, almost all observations, and therefore also the 95th percentile,
+will fall into the bucket labeled `{le="0.3"}`, i.e. the bucket from
+200ms to 300ms. The histogram implementation guarantees that the true
+95th percentile is somewhere between 200ms and 300ms. To return a
+single value (rather than an interval), it applies linear
+interpolation, which yields 295ms in this case. The calculated
+quantile gives you the impression that you are close to breaching the
+SLO, but in reality, the 95th percentile is a tiny bit above 220ms,
+a quite comfortable distance to your SLO.
+
+Next step in our thought experiment: A change in backend routing
+adds a fixed amount of 100ms to all request durations. Now the request
+duration has its sharp spike at 320ms and almost all observations will
+fall into the bucket from 300ms to 450ms. The 95th percentile is
+calculated to be 442.5ms, although the correct value is close to
+320ms. While you are only a tiny bit outside of your SLO, the
+calculated 95th quantile looks much worse.
+
+A summary would have had no problem calculating the correct percentile
+value in both cases, at least if it uses an appropriate algorithm on
+the client side (like the [one used by the Go
+client](http://dimacs.rutgers.edu/~graham/pubs/slides/bquant-long.pdf)).
+Unfortunately, you cannot use a summary if you need to aggregate the
+observations from a number of instances.
+
+Luckily, due to your appropriate choice of bucket boundaries, even in
+this contrived example of very sharp spikes in the distribution of
+observed values, the histogram was able to identify correctly if you
+were within or outside of your SLO. Also, the closer the actual value
+of the quantile is to our SLO (or in other words, the value we are
+actually most interested in), the more accurate the calculated value
+becomes.
+
+Let us now modify the experiment once more. In the new setup, the
+distributions of request durations has a spike at 150ms, but it is not
+quite as sharp as before and only comprises 90% of the
+observations. 10% of the observations are evenly spread out in a long
+tail between 150ms and 450ms. With that distribution, the 95th
+percentile happens to be exactly at our SLO of 300ms. With the
+histogram, the calculated value is accurate, as the value of the 95th
+percentile happens to coincide with one of the bucket boundaries. Even
+slightly different values would still be accurate as the (contrived)
+even distribution within the relevant buckets is exactly what the
+linear interpolation within a bucket assumes.
+
+The error of the quantile reported by a summary gets more interesting
+now. The error of the quantile in a summary is configured in the
+dimension of φ. In our case we might have configured 0.95±0.01,
+i.e. the calculated value will be between the 94th and 96th
+percentile. The 94th quantile with the distribution described above is
+270ms, the 96th quantile is 330ms. The calculated value of the 95th
+percentile reported by the summary can be anywhere in the interval
+between 270ms and 330ms, which unfortunately is all the difference
+between clearly within the SLO vs. clearly outside the SLO.
+
+The bottom line is: If you use a summary, you control the error in the
+dimension of φ. If you use a histogram, you control the error in the
+dimension of the observed value (via choosing the appropriate bucket
+layout). With a broad distribution, small changes in φ result in
+large deviations in the observed value. With a sharp distribution, a
+small interval of observed values covers a large interval of φ.
+
+Two rules of thumb:
+
+  1. If you need to aggregate, choose histograms.
+
+  2. Otherwise, choose a histogram if you have an idea of the range
+     and distribution of values that will be observed. Choose a
+     summary if you need an accurate quantile, no matter what the
+     range and distribution of the values is.
+
+
+## What can I do if my client library does not support the metric type I need?
+
+Implement it! [Code contributions are welcome](/community/). In general, we
+expect histograms to be more urgently needed than summaries. Histograms are
+also easier to implement in a client library, so we recommend to implement
+histograms first, if in doubt.
diff --git a/docs/practices/index.md b/docs/practices/index.md
new file mode 100644
index 00000000..021e1dfb
--- /dev/null
+++ b/docs/practices/index.md
@@ -0,0 +1,5 @@
+---
+title: Best practices
+sort_rank: 8
+nav_icon: thumb-up
+---
diff --git a/docs/practices/instrumentation.md b/docs/practices/instrumentation.md
new file mode 100644
index 00000000..2f30a6b3
--- /dev/null
+++ b/docs/practices/instrumentation.md
@@ -0,0 +1,267 @@
+---
+title: Instrumentation
+sort_rank: 3
+---
+
+# Instrumentation
+
+This page provides an opinionated set of guidelines for instrumenting your code.
+
+## How to instrument
+
+The short answer is to instrument everything. Every library, subsystem and
+service should have at least a few metrics to give you a rough idea of how it is
+performing.
+
+Instrumentation should be an integral part of your code. Instantiate the metric
+classes in the same file you use them. This makes going from alert to console to code
+easy when you are chasing an error.
+
+### The three types of services
+
+For monitoring purposes, services can generally be broken down into three types:
+online-serving, offline-processing, and batch jobs. There is overlap between
+them, but every service tends to fit well into one of these categories.
+
+#### Online-serving systems
+
+An online-serving system is one where a human or another system is expecting an
+immediate response. For example, most database and HTTP requests fall into
+this category.
+
+The key metrics in such a system are the number of performed queries, errors,
+and latency. The number of in-progress requests can also be useful.
+
+For counting failed queries, see section [Failures](#failures) below.
+
+Online-serving systems should be monitored on both the client and server side.
+If the two sides see different behaviors, that is very useful information for debugging.
+If a service has many clients, it is not practical for the service to track them
+individually, so they have to rely on their own stats.
+
+Be consistent in whether you count queries when they start or when they end.
+When they end is suggested, as it will line up with the error and latency stats,
+and tends to be easier to code.
+
+#### Offline processing
+
+For offline processing, no one is actively waiting for a response, and batching
+of work is common. There may also be multiple stages of processing.
+
+For each stage, track the items coming in, how many are in progress, the last
+time you processed something, and how many items were sent out. If batching, you
+should also track batches going in and out.
+
+Knowing the last time that a system processed something is useful for detecting if it has stalled,
+but it is very localised information. A better approach is to send a heartbeat
+through the system: some dummy item that gets passed all the way through
+and includes the timestamp when it was inserted. Each stage can export the most
+recent heartbeat timestamp it has seen, letting you know how long items are
+taking to propagate through the system. For systems that do not have quiet
+periods where no processing occurs, an explicit heartbeat may not be needed.
+
+#### Batch jobs
+
+There is a fuzzy line between offline-processing and batch jobs, as offline
+processing may be done in batch jobs. Batch jobs are distinguished by the
+fact that they do not run continuously, which makes scraping them difficult.
+
+The key metric of a batch job is the last time it succeeded. It is also useful to track
+how long each major stage of the job took, the overall runtime and the last
+time the job completed (successful or failed). These are all gauges, and should
+be [pushed to a PushGateway](/docs/instrumenting/pushing/).
+There are generally also some overall job-specific statistics that would be
+useful to track, such as the total number of records processed.
+
+For batch jobs that take more than a few minutes to run, it is useful to also
+scrape them using pull-based monitoring. This lets you track the same metrics over time
+as for other types of jobs, such as resource usage and latency when talking to other
+systems. This can aid debugging if the job starts to get slow.
+
+For batch jobs that run very often (say, more often than every 15 minutes), you should
+consider converting them into daemons and handling them as offline-processing jobs.
+
+### Subsystems
+
+In addition to the three main types of services, systems have sub-parts that
+should also be monitored.
+
+#### Libraries
+
+Libraries should provide instrumentation with no additional configuration
+required by users.
+
+If it is a library used to access some resource outside of the process (for example,
+network, disk, or IPC), track the overall query count, errors (if errors are possible)
+and latency at a minimum.
+
+Depending on how heavy the library is, track internal errors and
+latency within the library itself, and any general statistics you think may be
+useful.
+
+A library may be used by multiple independent parts of an application against
+different resources, so take care to distinguish uses with labels where
+appropriate. For example, a database connection pool should distinguish the databases
+it is talking to, whereas there is no need to differentiate
+between users of a DNS client library.
+
+#### Logging
+
+As a general rule, for every line of logging code you should also have a
+counter that is incremented. If you find an interesting log message, you want to
+be able to see how often it has been happening and for how long.
+
+If there are multiple closely-related log messages in the same function (for example,
+different branches of an if or switch statement), it can sometimes make sense to
+increment a single counter for all of them.
+
+It is also generally useful to export the total number of info/error/warning
+lines that were logged by the application as a whole, and check for significant
+differences as part of your release process.
+
+#### Failures
+
+Failures should be handled similarly to logging. Every time there is a failure, a
+counter should be incremented. Unlike logging, the error may also bubble up to a
+more general error counter depending on how your code is structured.
+
+When reporting failures, you should generally have some other metric
+representing the total number of attempts. This makes the failure ratio easy to calculate.
+
+#### Threadpools
+
+For any sort of threadpool, the key metrics are the number of queued requests, the number of
+threads in use, the total number of threads, the number of tasks processed, and how long they took.
+It is also useful to track how long things were waiting in the queue.
+
+#### Caches
+
+The key metrics for a cache are total queries, hits, overall latency and then
+the query count, errors and latency of whatever online-serving system the cache is in front of.
+
+#### Collectors
+
+When implementing a non-trivial custom metrics collector, it is advised to export a
+gauge for how long the collection took in seconds and another for the number of
+errors encountered.
+
+This is one of the two cases when it is okay to export a duration as a gauge
+rather than a summary or a histogram, the other being batch job durations. This
+is because both represent information about that particular push/scrape, rather
+than tracking multiple durations over time.
+
+## Things to watch out for
+
+There are some general things to be aware of when doing monitoring, and also
+Prometheus-specific ones in particular.
+
+### Use labels
+
+Few monitoring systems have the notion of labels and an expression language to
+take advantage of them, so it takes a bit of getting used to.
+
+When you have multiple metrics that you want to add/average/sum, they should
+usually be one metric with labels rather than multiple metrics.
+
+For example, rather than `http_responses_500_total` and `http_responses_403_total`,
+create a single metric called `http_responses_total` with a `code` label
+for the HTTP response code. You can then process the entire metric as one in
+rules and graphs.
+
+As a rule of thumb, no part of a metric name should ever be procedurally
+generated (use labels instead). The one exception is when proxying metrics
+from another monitoring/instrumentation system.
+
+See also the [naming](/docs/practices/naming/) section.
+
+### Do not overuse labels
+
+Each labelset is an additional time series that has RAM, CPU, disk, and network
+costs. Usually the overhead is negligible, but in scenarios with lots of
+metrics and hundreds of labelsets across hundreds of servers, this can add up
+quickly.
+
+As a general guideline, try to keep the cardinality of your metrics below 10,
+and for metrics that exceed that, aim to limit them to a handful across your
+whole system. The vast majority of your metrics should have no labels.
+
+If you have a metric that has a cardinality over 100 or the potential to grow
+that large, investigate alternate solutions such as reducing the number of
+dimensions or moving the analysis away from monitoring and to a general-purpose
+processing system.
+
+To give you a better idea of the underlying numbers, let's look at node\_exporter.
+node\_exporter exposes metrics for every mounted filesystem. Every node will have
+in the tens of timeseries for, say, `node_filesystem_avail`. If you have
+10,000 nodes, you will end up with roughly 100,000 timeseries for
+`node_filesystem_avail`, which is fine for Prometheus to handle.
+
+If you were to now add quota per user, you would quickly reach a double digit
+number of millions with 10,000 users on 10,000 nodes. This is too much for the
+current implementation of Prometheus. Even with smaller numbers, there's an
+opportunity cost as you can't have other, potentially more useful metrics on
+this machine any more.
+
+If you are unsure, start with no labels and add more labels over time as
+concrete use cases arise.
+
+### Counter vs. gauge, summary vs. histogram
+
+It is important to know which of the four main metric types to use for
+a given metric.
+
+To pick between counter and gauge, there is a simple rule of thumb: if
+the value can go down, it is a gauge.
+
+Counters can only go up (and reset, such as when a process restarts). They are
+useful for accumulating the number of events, or the amount of something at
+each event. For example, the total number of HTTP requests, or the total number of
+bytes sent in HTTP requests. Raw counters are rarely useful. Use the
+`rate()` function to get the per-second rate at which they are increasing.
+
+Gauges can be set, go up, and go down. They are useful for snapshots of state,
+such as in-progress requests, free/total memory, or temperature. You should
+never take a `rate()` of a gauge.
+
+Summaries and histograms are more complex metric types discussed in
+[their own section](/docs/practices/histograms/).
+
+### Timestamps, not time since
+
+If you want to track the amount of time since something happened, export the
+Unix timestamp at which it happened - not the time since it happened.
+
+With the timestamp exported, you can use the expression `time() - my_timestamp_metric` to
+calculate the time since the event, removing the need for update logic and
+protecting you against the update logic getting stuck.
+
+### Inner loops
+
+In general, the additional resource cost of instrumentation is far outweighed by
+the benefits it brings to operations and development.
+
+For code which is performance-critical or called more than 100k times a second
+inside a given process, you may wish to take some care as to how many metrics
+you update.
+
+A Java counter takes
+[12-17ns](https://github.com/prometheus/client_java/blob/main/benchmarks/README.md)
+to increment depending on contention. Other languages will have similar
+performance. If that amount of time is significant for your inner loop, limit
+the number of metrics you increment in the inner loop and avoid labels (or
+cache the result of the label lookup, for example, the return value of `With()`
+in Go or `labels()` in Java) where possible.
+
+Beware also of metric updates involving time or durations, as getting the time
+may involve a syscall. As with all matters involving performance-critical code,
+benchmarks are the best way to determine the impact of any given change.
+
+### Avoid missing metrics
+
+Time series that are not present until something happens are difficult
+to deal with, as the usual simple operations are no longer sufficient to
+correctly handle them. To avoid this, export a default value such as `0` for
+any time series you know may exist in advance.
+
+Most Prometheus client libraries (including Go, Java, and Python) will
+automatically export a `0` for you for metrics with no labels.
diff --git a/docs/practices/naming.md b/docs/practices/naming.md
new file mode 100644
index 00000000..4888c1c9
--- /dev/null
+++ b/docs/practices/naming.md
@@ -0,0 +1,119 @@
+---
+title: Metric and label naming
+sort_rank: 1
+---
+
+# Metric and label naming
+
+The metric and label conventions presented in this document are not required
+for using Prometheus, but can serve as both a style-guide and a collection of
+best practices. Individual organizations may want to approach some of these
+practices, e.g. naming conventions, differently.
+
+## Metric names
+
+A metric name...
+
+* ...MUST comply with the [data model](/docs/concepts/data_model/#metric-names-and-labels) for valid characters.
+* ...SHOULD have a (single-word) application prefix relevant to the domain the
+  metric belongs to. The prefix is sometimes referred to as `namespace` by
+  client libraries. For metrics specific to an application, the prefix is
+  usually the application name itself. Sometimes, however, metrics are more
+  generic, like standardized metrics exported by client libraries. Examples:
+  * <code><b>prometheus</b>\_notifications\_total</code>
+    (specific to the Prometheus server)
+  * <code><b>process</b>\_cpu\_seconds\_total</code>
+    (exported by many client libraries)
+  * <code><b>http</b>\_request\_duration\_seconds</code>
+    (for all HTTP requests)
+* ...MUST have a single unit (i.e. do not mix seconds with milliseconds, or seconds with bytes).
+* ...SHOULD use base units (e.g. seconds, bytes, meters - not milliseconds, megabytes, kilometers). See [below](#base-units) for a list of base units.
+* ...SHOULD have a suffix describing the unit, in plural form. Note that an accumulating count has `total` as a suffix, in addition to the unit if applicable. Also note that this applies to units in the narrow sense (like the units in the table below), but not to countable things in general. For example, <code>connections</code> or <code>notifications</code> are not considered units for this rule and do not have to be at the end of the metric name. (See also examples in the next paragraph.)
+  * <code>http\_request\_duration\_<b>seconds</b></code>
+  * <code>node\_memory\_usage\_<b>bytes</b></code>
+  * <code>http\_requests\_<b>total</b></code>
+    (for a unit-less accumulating count)
+  * <code>process\_cpu\_<b>seconds\_total</b></code>
+    (for an accumulating count with unit)
+  * <code>foobar_build<b>\_info</b></code>
+    (for a pseudo-metric that provides [metadata](https://www.robustperception.io/exposing-the-software-version-to-prometheus) about the running binary)
+  * <code>data\_pipeline\_last\_record\_processed\_<b>timestamp_seconds</b></code>
+    (for a timestamp that tracks the time of the latest record processed in a data processing pipeline)
+* ...MAY order its name components in a way that leads to convenient grouping when a list of metric names is sorted lexicographically, as long as all the other rules are followed. The following examples have their the common name components first so that all the related metrics are sorted together:
+  * <code>prometheus\_tsdb\_head\_truncations\_closed\_total</code>
+  * <code>prometheus\_tsdb\_head\_truncations\_established\_total</code>
+  * <code>prometheus\_tsdb\_head\_truncations\_failed\_total</code>
+  * <code>prometheus\_tsdb\_head\_truncations\_total</code><br/>
+  The following examples are also valid, but are following a different trade-off. They are easier to read individually, but unrelated metrics like <code>prometheus\_tsdb\_head\_series</code> might get sorted in between.  
+  * <code>prometheus\_tsdb\_head\_closed\_truncations\_total</code>
+  * <code>prometheus\_tsdb\_head\_established\_truncations\_total</code>
+  * <code>prometheus\_tsdb\_head\_failed\_truncations\_total</code>
+  * <code>prometheus\_tsdb\_head\_truncations\_total</code>
+* ...SHOULD represent the same logical thing-being-measured across all label
+  dimensions.
+  * request duration
+  * bytes of data transfer
+  * instantaneous resource usage as a percentage
+
+As a rule of thumb, either the `sum()` or the `avg()` over all dimensions of a
+given metric should be meaningful (though not necessarily useful). If it is not
+meaningful, split the data up into multiple metrics. For example, having the
+capacity of various queues in one metric is good, while mixing the capacity of a
+queue with the current number of elements in the queue is not.
+
+### Why include unit and type suffixes in metric names?
+
+Some metric naming conventions (e.g. OpenTelemetry) do not recommend or even do not allow
+including information about a metric unit and type in the metric name. A common
+argument is that those pieces of information are already defined somewhere else (e.g. schema, 
+metadata, other labels, etc.).
+
+Prometheus strongly recommends including unit and type in a metric name, even if you store that
+information elsewhere, because of the following practical reasons:
+
+* **Metric consumption reliability and UX**: When interacting with a modern UI to 
+use such a metric in PromQL, it's possible to display rich information about the metric's type and unit
+(autocompletion, overlays, pop-ups). Unfortunately, interactive, adhoc querying in a powerful UI is not
+the only way that users interact with metrics. Metric consumption ecosystem is vast. Majority
+of the consumption comes in a form of the plain YAML configuration for variety of observability tools like
+alerting, recording, autoscaling, dashboards, analysis, processing, etc. It's **critical**, especially 
+during monitoring/SRE incident practices to look on PromQL expressions in plain YAML and understand
+the underlying metric type and unit you work with.
+* **Metric collisions**: With growing adoption and metric changes over time, there are cases where lack
+of unit and type information in the metric name will cause certain series to collide (e.g. `process_cpu` for seconds and milliseconds).
+
+## Labels
+
+Use labels to differentiate the characteristics of the thing that is being measured:
+
+ * `api_http_requests_total` - differentiate request types: `operation="create|update|delete"`
+ * `api_request_duration_seconds` - differentiate request stages: `stage="extract|transform|load"`
+
+Do not put the label names in the metric name, as this introduces redundancy
+and will cause confusion if the respective labels are aggregated away.
+
+CAUTION: Remember that every unique combination of key-value label
+pairs represents a new time series, which can dramatically increase the amount
+of data stored. Do not use labels to store dimensions with high cardinality
+(many different label values), such as user IDs, email addresses, or other
+unbounded sets of values.
+
+## Base Units
+
+Prometheus does not have any units hard coded. For better compatibility, base
+units should be used. The following lists some metrics families with their base unit.
+The list is not exhaustive.
+
+| Family | Base unit | Remark |
+| -------| --------- | ------ |
+| Time   | seconds   |        |
+| Temperature | celsius | _celsius_ is preferred over _kelvin_ for practical reasons. _kelvin_ is acceptable as a base unit in special cases like color temperature or where temperature has to be absolute. |
+| Length | meters | |
+| Bytes  | bytes | |
+| Bits   | bytes | To avoid confusion combining different metrics, always use _bytes_, even where _bits_ appear more common. |
+| Percent | ratio | Values are 0–1 (rather than 0–100). `ratio` is only used as a suffix for names like `disk_usage_ratio`. The usual metric name follows the pattern `A_per_B`. |
+| Voltage | volts | |
+| Electric current | amperes | |
+| Energy | joules | |
+| Power  | | Prefer exporting a counter of joules, then `rate(joules[5m])` gives you power in Watts. |
+| Mass   | grams | _grams_ is preferred over _kilograms_ to avoid issues with the _kilo_ prefix. |
diff --git a/docs/practices/pushing.md b/docs/practices/pushing.md
new file mode 100644
index 00000000..b1b49e24
--- /dev/null
+++ b/docs/practices/pushing.md
@@ -0,0 +1,58 @@
+---
+title: When to use the Pushgateway
+sort_rank: 7
+---
+
+# When to use the Pushgateway
+
+The Pushgateway is an intermediary service which allows you to push metrics
+from jobs which cannot be scraped. For details, see [Pushing metrics](/docs/instrumenting/pushing/).
+
+## Should I be using the Pushgateway?
+
+**We only recommend using the Pushgateway in certain limited cases.** There are
+several pitfalls when blindly using the Pushgateway instead of Prometheus's
+usual pull model for general metrics collection:
+
+* When monitoring multiple instances through a single Pushgateway, the
+  Pushgateway becomes both a single point of failure and a potential
+  bottleneck.
+* You lose Prometheus's automatic instance health monitoring via the `up`
+  metric (generated on every scrape).
+* The Pushgateway never forgets series pushed to it and will expose them to
+  Prometheus forever unless those series are manually deleted via the
+  Pushgateway's API.
+
+The latter point is especially relevant when multiple instances of a job
+differentiate their metrics in the Pushgateway via an `instance` label or
+similar. Metrics for an instance will then remain in the Pushgateway even if
+the originating instance is renamed or removed. This is because the lifecycle
+of the Pushgateway as a metrics cache is fundamentally separate from the
+lifecycle of the processes that push metrics to it. Contrast this to
+Prometheus's usual pull-style monitoring: when an instance disappears
+(intentional or not), its metrics will automatically disappear along with it.
+When using the Pushgateway, this is not the case, and you would now have to
+delete any stale metrics manually or automate this lifecycle synchronization
+yourself.
+
+**Usually, the only valid use case for the Pushgateway is for capturing the
+outcome of a service-level batch job**.  A "service-level" batch job is one
+which is not semantically related to a specific machine or job instance (for
+example, a batch job that deletes a number of users for an entire service).
+Such a job's metrics should not include a machine or instance label to decouple
+the lifecycle of specific machines or instances from the pushed metrics. This
+decreases the burden for managing stale metrics in the Pushgateway. See also
+the [best practices for monitoring batch jobs](/docs/practices/instrumentation/#batch-jobs).
+
+## Alternative strategies
+
+If an inbound firewall or NAT is preventing you from pulling metrics from
+targets, consider moving the Prometheus server behind the network barrier as
+well. We generally recommend running Prometheus servers on the same network as
+the monitored instances.  Otherwise, consider [PushProx](https://github.com/RobustPerception/PushProx),
+which allows Prometheus to traverse a firewall or NAT.
+
+For batch jobs that are related to a machine (such as automatic
+security update cronjobs or configuration management client runs), expose the
+resulting metrics using the [Node Exporter's](https://github.com/prometheus/node_exporter)
+[textfile collector](https://github.com/prometheus/node_exporter#textfile-collector) instead of the Pushgateway.
diff --git a/docs/practices/remote_write.md b/docs/practices/remote_write.md
new file mode 100644
index 00000000..e07baa56
--- /dev/null
+++ b/docs/practices/remote_write.md
@@ -0,0 +1,118 @@
+---
+title: Remote write tuning
+sort_rank: 8
+---
+
+# Remote write tuning
+
+Prometheus implements sane defaults for remote write, but many users have
+different requirements and would like to optimize their remote settings.
+
+This page describes the tuning parameters available via the [remote write
+configuration.](/docs/prometheus/latest/configuration/configuration/#remote_write)
+
+## Remote write characteristics
+
+Each remote write destination starts a queue which reads from the write-ahead
+log (WAL), writes the samples into an in memory queue owned by a shard, which
+then sends a request to the configured endpoint. The flow of data looks like:
+
+```
+      |-->  queue (shard_1)   --> remote endpoint
+WAL --|-->  queue (shard_...) --> remote endpoint
+      |-->  queue (shard_n)   --> remote endpoint
+```
+
+When one shard backs up and fills its queue, Prometheus will block reading from
+the WAL into any shards. Failures will be retried without loss of data unless
+the remote endpoint remains down for more than 2 hours. After 2 hours, the WAL
+will be compacted and data that has not been sent will be lost.
+
+During operation, Prometheus will continuously calculate the optimal number of
+shards to use based on the incoming sample rate, number of outstanding samples
+not sent, and time taken to send each sample.
+
+### Resource usage
+
+Using remote write increases the memory footprint of Prometheus. Most users
+report ~25% increased memory usage, but that number is dependent on the shape
+of the data. For each series in the WAL, the remote write code caches a mapping
+of series ID to label values, causing large amounts of series churn to
+significantly increase memory usage.
+
+In addition to the series cache, each shard and its queue increases memory
+usage. Shard memory is proportional to the `number of shards * (capacity +
+max_samples_per_send)`. When tuning, consider reducing `max_shards` alongside
+increases to `capacity` and `max_samples_per_send` to avoid inadvertently
+running out of memory. The default values for `capacity: 10000` and
+`max_samples_per_send: 2000` will constrain shard memory usage to less than 2
+MB per shard.
+
+Remote write will also increase CPU and network usage. However, for the same
+reasons as above, it is difficult to predict by how much. It is generally a
+good practice to check for CPU and network saturation if your Prometheus server
+falls behind sending samples via remote write
+(`prometheus_remote_storage_samples_pending`).
+
+## Parameters
+
+All the relevant parameters are found under the `queue_config` section of the
+remote write configuration.
+
+### `capacity`
+
+Capacity controls how many samples are queued in memory per shard before
+blocking reading from the WAL. Once the WAL is blocked, samples cannot be
+appended to any shards and all throughput will cease.
+
+Capacity should be high enough to avoid blocking other shards in most
+cases, but too much capacity can cause excess memory consumption and longer
+times to clear queues during resharding. It is recommended to set capacity
+to 3-10 times `max_samples_per_send`.
+
+### `max_shards`
+
+Max shards configures the maximum number of shards, or parallelism, Prometheus
+will use for each remote write queue. Prometheus will try not to use too many
+shards, but if the queue falls behind the remote write component will increase
+the number of shards up to max shards to increase throughput. Unless remote
+writing to a very slow endpoint, it is unlikely that `max_shards` should be
+increased beyond the default. However, it may be necessary to reduce max shards
+if there is potential to overwhelm the remote endpoint, or to reduce memory
+usage when data is backed up.
+
+### `min_shards`
+
+Min shards configures the minimum number of shards used by Prometheus, and is
+the number of shards used when remote write starts. If remote write falls
+behind, Prometheus will automatically scale up the number of shards so most
+users do not have to adjust this parameter. However, increasing min shards will
+allow Prometheus to avoid falling behind at the beginning while calculating the
+required number of shards.
+
+### `max_samples_per_send`
+
+Max samples per send can be adjusted depending on the backend in use. Many
+systems work very well by sending more samples per batch without a significant
+increase in latency. Other backends will have issues if trying to send a large
+number of samples in each request. The default value is small enough to work for
+most systems.
+
+### `batch_send_deadline`
+
+Batch send deadline sets the maximum amount of time between sends for a single
+shard. Even if the queued shards has not reached `max_samples_per_send`, a
+request will be sent. Batch send deadline can be increased for low volume
+systems that are not latency sensitive in order to increase request efficiency.
+
+### `min_backoff`
+
+Min backoff controls the minimum amount of time to wait before retrying a failed
+request. Increasing the backoff spreads out requests when a remote endpoint
+comes back online. The backoff interval is doubled for each failed requests up
+to `max_backoff`.
+
+### `max_backoff`
+
+Max backoff controls the maximum amount of time to wait before retrying a failed
+request.
diff --git a/docs/practices/rules.md b/docs/practices/rules.md
new file mode 100644
index 00000000..7e07e651
--- /dev/null
+++ b/docs/practices/rules.md
@@ -0,0 +1,129 @@
+---
+title: Recording rules
+sort_rank: 6
+---
+
+# Recording rules
+
+A consistent naming scheme for [recording rules](/docs/prometheus/latest/configuration/recording_rules/)
+makes it easier to interpret the meaning of a rule at a glance. It also avoids
+mistakes by making incorrect or meaningless calculations stand out.
+
+This page documents proper naming conventions and aggregation for recording rules.
+
+## Naming 
+
+* Recording rules should be of the general form `level:metric:operations`.
+* `level` represents the aggregation level and labels of the rule output.
+* `metric` is the metric name and should be unchanged other than stripping `_total` off counters when using `rate()` or `irate()`.
+* `operations` is a list of operations that were applied to the metric, newest operation first.
+
+Keeping the metric name unchanged makes it easy to know what a metric is and
+easy to find in the codebase.
+
+To keep the operations clean, `_sum` is omitted if there are other operations,
+as `sum()`. Associative operations can be merged (for example `min_min` is the
+same as `min`).
+
+If there is no obvious operation to use, use `sum`.  When taking a ratio by
+doing division, separate the metrics using `_per_` and call the operation
+`ratio`.
+
+## Aggregation
+
+* When aggregating up ratios, aggregate up the numerator and denominator
+separately and then divide.
+* Do not take the average of a ratio or average of an
+average, as that is not statistically valid.
+
+* When aggregating up the `_count` and `_sum` of a Summary and dividing to
+calculate average observation size, treating it as a ratio would be unwieldy.
+Instead keep the metric name without the `_count` or `_sum` suffix and replace
+the `rate` in the operation with `mean`. This represents the average
+observation size over that time period.
+
+* Always specify a `without` clause with the labels you are aggregating away.
+This is to preserve all the other labels such as `job`, which will avoid
+conflicts and give you more useful metrics and alerts.
+
+## Examples
+
+_Note the indentation style with outdented operators on their own line between
+two vectors. To make this style possible in Yaml, [block quotes with an
+indentation indicator](https://yaml.org/spec/1.2/spec.html#style/block/scalar)
+(e.g. `|2`) are used._
+
+Aggregating up requests per second that has a `path` label:
+
+```
+- record: instance_path:requests:rate5m
+  expr: rate(requests_total{job="myjob"}[5m])
+
+- record: path:requests:rate5m
+  expr: sum without (instance)(instance_path:requests:rate5m{job="myjob"})
+```
+
+Calculating a request failure ratio and aggregating up to the job-level failure ratio:
+
+```
+- record: instance_path:request_failures:rate5m
+  expr: rate(request_failures_total{job="myjob"}[5m])
+
+- record: instance_path:request_failures_per_requests:ratio_rate5m
+  expr: |2
+      instance_path:request_failures:rate5m{job="myjob"}
+    /
+      instance_path:requests:rate5m{job="myjob"}
+
+# Aggregate up numerator and denominator, then divide to get path-level ratio.
+- record: path:request_failures_per_requests:ratio_rate5m
+  expr: |2
+      sum without (instance)(instance_path:request_failures:rate5m{job="myjob"})
+    /
+      sum without (instance)(instance_path:requests:rate5m{job="myjob"})
+
+# No labels left from instrumentation or distinguishing instances,
+# so we use 'job' as the level.
+- record: job:request_failures_per_requests:ratio_rate5m
+  expr: |2
+      sum without (instance, path)(instance_path:request_failures:rate5m{job="myjob"})
+    /
+      sum without (instance, path)(instance_path:requests:rate5m{job="myjob"})
+```
+
+
+Calculating average latency over a time period from a Summary:
+
+```
+- record: instance_path:request_latency_seconds_count:rate5m
+  expr: rate(request_latency_seconds_count{job="myjob"}[5m])
+
+- record: instance_path:request_latency_seconds_sum:rate5m
+  expr: rate(request_latency_seconds_sum{job="myjob"}[5m])
+
+- record: instance_path:request_latency_seconds:mean5m
+  expr: |2
+      instance_path:request_latency_seconds_sum:rate5m{job="myjob"}
+    /
+      instance_path:request_latency_seconds_count:rate5m{job="myjob"}
+
+# Aggregate up numerator and denominator, then divide.
+- record: path:request_latency_seconds:mean5m
+  expr: |2
+      sum without (instance)(instance_path:request_latency_seconds_sum:rate5m{job="myjob"})
+    /
+      sum without (instance)(instance_path:request_latency_seconds_count:rate5m{job="myjob"})
+```
+
+Calculating the average query rate across instances and paths is done using the
+`avg()` function:
+
+```
+- record: job:request_latency_seconds_count:avg_rate5m
+  expr: avg without (instance, path)(instance:request_latency_seconds_count:rate5m{job="myjob"})
+```
+
+Notice that when aggregating that the labels in the `without` clause are removed
+from the level of the output metric name compared to the input metric names.
+When there is no aggregation, the levels always match. If this is not the case
+a mistake has likely been made in the rules.
diff --git a/docs/prometheus/index.md b/docs/prometheus/index.md
new file mode 100644
index 00000000..1817b89c
--- /dev/null
+++ b/docs/prometheus/index.md
@@ -0,0 +1,5 @@
+---
+title: Prometheus Server
+sort_rank: 3
+nav_icon: server
+---
diff --git a/docs/specs/index.md b/docs/specs/index.md
new file mode 100644
index 00000000..81ae2847
--- /dev/null
+++ b/docs/specs/index.md
@@ -0,0 +1,5 @@
+---
+title: Specifications
+sort_rank: 11
+nav_icon: file-description
+---
diff --git a/docs/specs/native_histograms.md b/docs/specs/native_histograms.md
new file mode 100644
index 00000000..e9630e94
--- /dev/null
+++ b/docs/specs/native_histograms.md
@@ -0,0 +1,2421 @@
+---
+title: Native Histograms [EXPERIMENTAL]
+sort_rank: 2
+---
+
+# Native Histograms
+
+Native histograms were introduced as an experimental feature in November 2022.
+They are a concept that touches almost every part of the Prometheus stack. The
+first version of the Prometheus server supporting native histograms was
+v2.40.0. The support had to be enabled via a feature flag
+`--enable-feature=native-histograms`. (TODO: This is still the case with the
+current release v2.55 and v3.00. Update this section with the stable release,
+once it has happened.)
+
+Due to the pervasive nature of the changes related to native histograms, the
+documentation of those changes and explanation of the underlying concepts are
+widely distributed over various channels (like the documentation of affected
+Prometheus components, doc comments in source code, sometimes the source code
+itself, design docs, conference talks, …). This document intends to gather all
+these pieces of information and present them concisely in a unified context.
+This document prefers to link existing detailed documentation rather than
+restating it, but it contains enough information to be comprehensible without
+referring to other sources. With all that said, it should be noted that this
+document is neither suitable as an introduction for beginners nor does it focus
+on the needs of developers. For the former, the plan is to provide an updated
+version of the [Best Practices article on histograms and
+summaries](../../practices/histograms/). (TODO: And a blog post or maybe even a
+series of them.) For the latter, there is Carrie
+Edward's [Developer’s Guide to Prometheus Native
+Histograms](https://docs.google.com/document/d/1VhtB_cGnuO2q_zqEMgtoaLDvJ_kFSXRXoE0Wo74JlSY/edit).
+
+While formal specifications are supposed to happen in their respective context
+(e.g. OpenMetrics changes will be specified in the general OpenMetrics
+specification), some parts of this document take the shape of a specification.
+In those parts, the key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL
+NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” are used as
+described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
+
+This document still contains a lot of TODOs. In most cases, they are not just
+referring to incompleteness of this doc but more importantly to incomplete
+implementation or open questions. For now, this is essentially a living
+document that will receive updates as implementations and specifications catch
+up.
+
+## Introduction
+
+The core idea of native histograms is to treat histograms as first class
+citizens in the Prometheus data model. Elevating histograms to a “native”
+sample type is the fundamental prerequisite for the key properties listed
+below, which explains the choice of the name _native histograms_.
+
+Prior to the introduction of native histograms, all Prometheus sample values
+have been 64-bit floating point values (short _float64_ or just _float_). These
+floats can directly represent _gauges_ or _counters_. The Prometheus metric
+types _summary_ and (the classic version of) _histogram_, as they exist in
+exposition formats, are broken down into float components upon ingestion: A
+_sum_ and a _count_ component for both types, a number of _quantile_ samples
+for a summary and a number of _bucket_ samples for a (classic) histogram.
+
+With native histograms, a new structured sample type is introduced. A single
+sample represents the previously known _sum_ and _count_ plus a dynamic set of
+buckets. This is not limited to ingestion, but PromQL expressions may also
+return the new sample type where previously it was only possible to return
+float samples.
+
+Native histograms have the following key properties:
+
+1. A sparse bucket representation, allowing (near) zero cost for empty buckets.
+2. Coverage of the full float64 range of values.
+3. No configuration of bucket boundaries during instrumentation.
+4. Dynamic resolution picked according to simple configuration parameters.
+5. Sophisticated exponential bucketing schemas, ensuring mergeability between
+   all histograms using those schemas.
+6. An efficient data representation for both exposition and storage.
+
+These key properties are fully realized with standard bucketing schemas. There
+are other schemas with different trade-offs that might only feature a subset of
+these properties. See the [Schema section](#schema) below for details
+
+Compared to the previously existing “classic” histograms, native histograms
+(with standard bucketing schemas) allow a higher bucket resolution across
+arbitrary ranges of observed values at a lower storage and query cost with very
+little to no configuration required. Even partitioning histograms by labels is
+now much more affordable.
+
+Because the sparse representation (property 1 in the list above) is so crucial
+for many of the other benefits of native histograms, _sparse histograms_ was
+a common name for _native histograms_ early during the design process. However,
+other key properties like the exponential bucketing schema or the dynamic
+nature of the buckets are also very important, but not caught at all in the
+term _sparse histograms_.
+
+### Design docs
+
+These are the design docs that guided the development of native histograms.
+Some details are obsolete now, but they describe rather well the underlying
+concepts and how they evolved.
+
+- [Sparse high-resolution histograms for
+  Prometheus](https://docs.google.com/document/d/1cLNv3aufPZb3fNfaJgdaRBZsInZKKIHo9E6HinJVbpM/edit),
+  the original design doc.
+- [Prometheus Sparse Histograms and
+  PromQL](https://docs.google.com/document/d/1ch6ru8GKg03N02jRjYriurt-CZqUVY09evPg6yKTA1s/edit),
+  more an exploratory document than a proper design doc about the handling of
+  native histograms in PromQL.
+
+### Conference talks
+
+A more approachable way of learning about native histograms is to watch
+conference talks, of which a selection is presented below. As an introduction,
+it might make sense to watch these talks and then return to this document to
+learn about all the details and technicalities.
+
+- [Secret History of Prometheus
+  Histograms](https://fosdem.org/2020/schedule/event/histograms/) about the
+  classic histograms and why Prometheus kept them for so long.
+- [Prometheus Histograms – Past, Present, and
+  Future](https://promcon.io/2019-munich/talks/prometheus-histograms-past-present-and-future/)
+  is the inaugural talk about the new approach that led to native histograms.
+- [Better Histograms for
+  Prometheus](https://www.youtube.com/watch?v=HG7uzON-IDM) explains why the
+  concepts work out in practice.
+- [Native Histograms in
+  Prometheus](https://promcon.io/2022-munich/talks/native-histograms-in-prometheus/)
+  presents and explains native histograms after the actual implementation.
+- [PromQL for Native
+  Histograms](https://promcon.io/2022-munich/talks/promql-for-native-histograms/)
+  explains the usage of native histograms in PromQL.
+- [Prometheus Native Histograms in
+  Production](https://www.youtube.com/watch?v=TgINvIK9SYc) provides an analysis
+  of performance and resource consumption.
+- [Using OpenTelemetry’s Exponential Histograms in
+  Prometheus](https://www.youtube.com/watch?v=W2_TpDcess8) covers the
+  interoperability with the OpenTelemetry.
+
+## Glossary
+
+- A __native histogram__ is an instance of the new complex sample type
+  representing a full histogram that this document is about. Where the context
+  is sufficiently clear, it is often just called a _histogram_ below.
+- A __classic histogram__ is an instance of the older sample type representing
+  a histogram with fixed buckets, formerly just called a _histogram_. It exists
+  as such in the exposition formats, but is broken into a number of float
+  samples upon ingestion into Prometheus.
+- __Sparse histogram__ is an older, now deprecated name for _native
+  histogram_. This name might still be found occasionally in older
+  documentation. __Sparse buckets__ remains a meaningful term for the buckets
+  of a native histogram.
+
+## Data model
+
+This section describes the data model of native histograms in general. It
+avoids implementation specifics as far as possible. This includes terminology.
+For example, a _list_ described in this section will become a _repeated
+message_ in a protobuf implementation and (most likely) a _slice_ in a Go
+implementation.
+
+### General structure
+
+Similar to a classic histogram, a native histogram has a field for the _count_
+of observations and a field for the _sum_ of observations. In addition, it
+contains the following components, which are described in detail in dedicated
+sections below:
+
+- A _schema_ to identify the method of determining the boundaries of any given
+  bucket with an index _i_.
+- A sparse representation of indexed buckets, mirrored for positive and
+  negative observations.
+- A _zero bucket_ to count observations close to zero.
+- A (possibly empty) list of _custom values_.
+- _Exemplars_.
+
+### Flavors
+
+Any native histogram has a specific flavor along each of two independent
+dimensions:
+
+1. Counter vs. gauge: Usually, a histogram is “counter like”, i.e. each of its
+   buckets acts as a counter of observations. However, there are also “gauge
+   like” histograms where each bucket is a gauge, representing arbitrary
+   distributions at a point in time. The concept of a gauge histogram was
+   previously introduced for classic histograms by
+   [OpenMetrics](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#gaugehistogram).
+2. Integer vs. floating point (short: float): The obvious use case of
+   histograms is to count observations, resulting in integer numbers of
+   observations ≥ 0 within each bucket, including the _zero bucket_, and for
+   the total _count_ of observations, represented as unsigned 64-bit integers
+   (short: uint64). However, there are specific use cases leading to a
+   “weighted” or “scaled” histogram, where all of these values are represented
+   as 64-bit floating point numbers (short: float64). Note that the _sum_ of
+   observations is a float64 in either case.
+
+Float histograms are occasionally used in direct instrumentation for “weighted”
+observations, for example to count the number of seconds an observed value was
+falling into different buckets of a histogram. The far more common use case for
+float histograms is within PromQL, though. PromQL generally only acts on float
+values, so the PromQL engine converts every histogram retrieved from the TSDB
+to a float histogram first, and any histogram stored back into TSDB via
+recording rules is a float histogram. If such a histogram is effectively an
+integer histogram (because the value of all non-_sum_ fields can be represented
+precisely as uint64), a TSDB implementation MAY convert them back to integer
+histograms to increase storage efficiency. (As of Prometheus v3.00, the TSDB
+implementation within Prometheus is not utilizing this option.) Note, however,
+that the most common PromQL function applied to a counter histogram is `rate`,
+which generally produces non-integer numbers, so that results of recording
+rules will commonly be float histograms with non-integer values anyway.
+
+Treating native histograms explicitly as integer histograms vs. float histogram
+is a notable deviation from the treatment of conventional simple numeric
+samples, which are always treated as floats throughout the whole stack for the
+sake of simplicity.
+
+The main reason for the more involved treatment of histograms is the easy
+efficiency gains in protobuf-based exposition formats. Protobuf uses varint
+encoding for integers, which reduces the data size for small integer values
+without requiring an additional compression layer. This benefit is amplified by
+the [delta encoding of integer buckets](#buckets), which generally results in
+smaller integer values. Floats, in contrast, always require 8 bytes in
+protobuf. In practice, many integers in an integer histogram will fit in 1
+byte, and most will fit in 2 bytes, so that the explicit presence of integer
+histogram in a protobuf-exposition format results directly in a data size
+reduction approaching 8x for histograms with many buckets. This is particularly
+relevant as the overwhelming majority of histograms exposed by instrumented
+targets are integer histograms.
+
+For similar reasons, the representation of integer histograms in RAM and on
+disk is generally more efficient than that of float histograms. This is less
+relevant than the benefits in the exposition format, though. For one,
+Prometheus uses Gorilla-style XOR encoding for floats, which reduces their
+size, albeit not as much as the double-delta encoding used for integers. More
+importantly, an implementation could always decide to internally use an integer
+representation for histogram fields that are effectively integer values (see
+above). (Historical note: Prometheus v1 used exactly this approach to improve
+the compression of float samples, and Prometheus v3 might very well adopt this
+approach again in the future.)
+
+In a counter histogram, the total _count_ of observation and the counts in the
+buckets individually behave like Prometheus counters, i.e. they only go down
+upon a counter reset. However, the _sum_ of observation may decrease as a
+consequence of the observation of negative values. PromQL implementations MUST
+detect counter resets based on the whole histogram (see the [counter reset
+considerations section](#counter-reset-considerations) below for details).
+(Note that this always has been a problem for the _sum_ component of classic
+histograms and summaries, too. The approach so far was to accept that counter
+reset detection silently breaks for _sum_ in those cases. Fortunately, negative
+observations are a very rare use case for Prometheus histograms and summaries.)
+
+### Schema
+
+The _schema_ is a signed integer value with a size of 8 bits (short: int8). It
+defines the way bucket boundaries are calculated. The currently valid values
+are -53 and the range between and including -4 and +8. More schemas may be
+added in the future. -53 is a schema for so-called _custom bucket boundaries_
+or short _custom buckets_, while the other schema numbers represent the
+different standard exponential schemas (short: _standard schemas_).
+
+The standard schemas are mergeable with each other and are RECOMMENDED for
+general use cases. Larger schema numbers correspond to higher resolutions.
+Schema _n_ has half the resolution of schema _n_+1, which implies that a
+histogram with schema _n_+1 can be converted into a histogram with schema _n_
+by merging neighboring buckets.
+
+For any standard schema _n_, the boundaries of a bucket with index _i_
+calculated as follows (using Python syntax):
+
+- The upper inclusive limit of a positive bucket:
+  `(2**2**-n)**i`
+- The lower exclusive limit of a positive bucket:
+  `(2**2**-n)**(i-1)`
+- The lower inclusive limit of a negative bucket:
+  `-((2**2**-n)**i)`
+- The upper exclusive limit of a negative bucket:
+  `-((2**2**-n)**(i-1))`
+
+_i_ is an integer number that may be negative.
+
+There are exceptions to the rules above concerning the largest and smallest
+finite values representable as a float64 (called `MaxFloat64` and `MinFloat64`
+in the following) and the positive and negative infinity values (`+Inf` and
+`-Inf`):
+
+- The positive bucket that contains `MaxFloat64` (according to the boundary
+  formulas above) has an upper inclusive limit of `MaxFloat64` (rather than the
+  limit calculated by the formulas above, which would overflow float64).
+- The next positive bucket (index _i_+1 relative to the bucket from the
+  previous item) has a lower exclusive limit of `MaxFloat64` and an upper
+  inclusive limit of `+Inf`. (It could be called a _positive overflow bucket_.)
+- The negative bucket that contains `MinFloat64` (according to the boundary
+  formulas above) has a lower inclusive limit of `MinFloat64` (rather than the
+  limit calculated by the formulas above, which would underflow float64).
+- The next negative bucket (index _i_+1 relative to the bucket from the
+  previous item) has an upper exclusive limit of `MinFloat64` and an lower
+  inclusive limit of `-Inf`. (It could be called a _negative overflow bucket_.)
+- Buckets beyond the `+Inf` and `-Inf` buckets described above MUST NOT be used.
+  
+There are more exceptions for values close to zero, see the [zero bucket
+section](#zero-bucket) below.
+
+The current limits of -4 for the lowest resolution and 8 for the highest
+resolution have been chosen based on practical usefulness. Should a practical
+need arise for even lower or higher resolution, an extension of the range will
+be considered. However, a schema greater than 52 does not make sense as the
+growth factor from one bucket to the next would then be smaller than the
+difference between representable float64 numbers. Likewise, a schema smaller
+than -9 does not make sense either, as the growth factor would then exceed the
+largest float representable as float64. Therefore, the schema numbers between
+(and including) -9 and +52 are reserved for future standard schemas (following
+the formulas for bucket boundaries above) and MUST NOT be used for any other
+schemas.
+
+For schema -53, the bucket boundaries are set explicitly via _custom values_,
+described in detail in the [custom values section](#custom-values) below. This
+results in a native histogram with custom bucket boundaries (or short _custom
+buckets_, often further abbreviated to NHCB). Such a histogram can be used to
+represent a classic histogram as a native histogram. It can also be used if
+the exponential bucketing featured by the standard schemas is a bad match for
+the distribution to be represented by the histogram. Histograms with different
+custom bucket boundaries are generally not mergeable with each other.
+Therefore, schema -53 SHOULD only be used as an informed decision in specific
+use cases.
+
+### Buckets
+
+For standard schemas, buckets are represented as two lists, one for positive
+buckets and one for negative buckets. For custom buckets (schema -53), only the
+positive bucket list is used, but repurposed for all buckets.
+
+Any unpopulated buckets MAY be excluded from the lists. (Which is the reason
+why the buckets are often called _sparse buckets_.)
+
+For float histograms, the elements of the lists are float64 and
+represent the bucket population directly.
+
+For integer histograms, the elements of the lists are signed 64-bit integers
+(short: int64), and each element represents the bucket population as a delta to
+the previous bucket in the list. The first bucket in each list contains an
+absolute population (which can also be seen as a delta relative to zero).
+
+To map buckets in the lists to the indices as defined in the previous section,
+there are two lists of so-called _spans_, one for the positive buckets and one
+for the negative buckets.
+
+Each span consists of a pair of numbers, a signed 32-bit integer (short: int32)
+called _offset_ and an unsigned 32-bit integer (short: uint32) called _length_.
+Only the first span in each list can have a negative offset. It defines the
+index of the first bucket in its corresponding bucket list. (Note that for
+NHCBs, the index is always positive, see the [custom values
+section](#custom-values) below for details.) The length defines the number of
+consecutive buckets the bucket list starts with. The offsets of the following
+spans define the number of excluded (and thus unpopulated buckets). The lengths
+define the number of consecutive buckets in the list following the excluded
+buckets.
+
+The sum of all length values in each span list MUST be equal to the length of
+the corresponding bucket list.
+
+Empty spans (with a length of zero) are valid and MAY be used, although they
+are generally not useful and they SHOULD be eliminated by adding their offset
+to the offset of the following span. Similarly, spans that are not the first
+span in a list MAY have an offset of zero, although those offsets SHOULD be
+eliminated by adding their length to the previous span. Both cases are allowed
+so that producers of native histograms MAY pick whatever representation has the
+best resource trade-offs at that moment. For example, if a histogram is
+processed through various stages, it might be most efficient to only eliminate
+redundant spans after the last processing stage.
+
+In a similar spirit, there are situation where excluding every unpopulated
+bucket from the bucket list is most efficient, but in other situations, it
+might be better to reduce the number of spans by representing small numbers of
+unpopulated buckets explicitly.
+
+Note that future high resolution schemas might require offsets that are too
+large to be represented with an int32. An extension of the data model will be
+required in that case. (The current standard schema with the highest resolution
+is schema 8, for which the bucket that contains `MaxFloat64` has index 262144,
+and thus the `+Inf` overflow bucket has index 262145, while the largest number
+representable with int32 is 2147483647. The highest standard schema that would
+still work with int32 offsets would be schema 20, corresponding to a growth
+factor from bucket to bucket of only ~1.000000661.)
+
+#### Examples
+
+An integer histogram has the following positive buckets (index→population):
+
+`-2→3, -1→5, 0→0, 1→0, 2→1, 3→0, 4→3, 5→2`
+
+They could be represented in this way:
+
+- Positive bucket list: `[3, 2, -4, 2, -1]`
+- Positive span list: `[[-2, 2], [2,1], [1,2]]`
+
+The second and third span could be merged into one if the single unpopulated
+bucket with index 3 is represented explicitly, leading to the following result:
+
+- Positive bucket list: `[3, 2, -4, -1, 3, -1]`
+- Positive span list: `[[-2, 2], [2,4]]`
+
+Or merge all the spans into one by representing all unpopulated buckets above
+explicitly:
+
+- Positive bucket list: `[3, 2, -5, 0, 1, -1, 3, -1]`
+- Positive span list: `[[-2, 8]]`
+
+### Zero bucket
+
+Observations of exactly zero do not fit into any bucket as defined by the
+standard schemas above. They are counted in a dedicated bucket called the _zero
+bucket_.
+
+The number of observations in the zero bucket is tracked by a single uint64
+(for integer histograms) or float64 (for float histograms).
+
+The zero bucket has an additional parameter called the _zero threshold_, which
+is a float64 ≥ 0. If the threshold is set to zero, only observations of exactly
+zero go into the zero bucket, which is the case described above. If the
+threshold has a positive value, all observations within the closed interval
+[-threshold, +threshold] go to the zero bucket rather than a regular bucket.
+This has two use cases:
+
+- Noisy observations close to zero tend to populate a high number of buckets.
+  Those observations might happen due to numerical inaccuracies or if the
+  source of the observations are actual physical measurements. A zero bucket
+  with a relatively small threshold redirects those observations into a single
+  bucket.
+- If the user is more interested in the long tail of a distribution, far away
+  from zero, a relatively large threshold of the zero bucket helps to avoid
+  many high resolution buckets for a range that is not of interest.
+
+The threshold of the zero bucket SHOULD coincide with a boundary of a regular
+bucket, which avoids the complication of the zero bucket overlapping with parts
+of a regular bucket. However, if such an overlap is happening, the observations
+that are counted in the regular bucket overlapping with the zero bucket MUST be
+outside of the [-threshold, +threshold] interval.
+
+To merge histograms with the same zero threshold, the two zero buckets are
+simply added. If the zero thresholds in the source histograms are different,
+however, the largest threshold in any of the source histograms is chosen. If
+that threshold happens to be within any populated bucket in the other source
+histograms, the threshold is increased until one of the following is true for
+each source histogram:
+
+- The new threshold coincides with the boundary of a populated bucket.
+- The new threshold is not within any populated bucket.
+
+Then the source zero buckets and any source buckets now inside the new
+threshold are added up to yield the population of the new zero bucket.
+
+The zero bucket is not used if the schema is -53 (custom buckets).
+
+### Custom values
+
+The list of custom values is unused for standard schemas. It is used by
+non-standard schemas in a custom way in case there is need to store additional
+data.
+
+The only currently defined schema for which custom values are used is -53
+(custom buckets). The remaining part of this section describes the usage of the
+custom values in more detail for this specific case.
+
+The custom values represent the upper inclusive boundaries of the custom
+buckets. They are sorted in ascending fashion. The custom buckets themselves
+are stored using the positive bucket list and the positive span list, although
+their boundaries, as determined via the custom values, can be negative. The
+index of each of those “positive” buckets defines the zero-based position of
+their upper boundary within the custom values list.
+
+The lower exclusive boundary is defined by the custom value preceding the upper
+boundary. For the first custom value (at position zero in the list), there is
+no preceding value, in which case the lower boundary is considered to be
+`-Inf`. Therefore, the custom bucket with index zero counts all observations
+between `-Inf` and the first custom value. In the common case that only
+positive observations are expected, the custom bucket with index zero SHOULD
+have an upper boundary of zero to clearly mark if there have been any
+observations at zero or below. (If there are indeed only positive observations,
+the custom bucket with index zero will stay unpopulated and therefore will
+never be represented explicitly. The only cost is the additional zero element
+at the beginning of the custom values list.)
+
+The last custom value MUST NOT be `+Inf`. Observations greater than the last
+custom value go into an overflow bucket with an upper boundary of `+Inf`. This
+overflow bucket is added with an index equal to the length of the custom
+values list.
+
+### Exemplars
+
+A native histogram sample can have zero, one, or more exemplars. They work in
+the same way as conventional exemplars, but they are organized in a list (as
+there can be more than one), and they MUST have a timestamp.
+
+Exemplars exposed as part of a classic histogram MAY be used by native
+histograms, if they have a timestamp.
+
+### Special cases of observed values
+
+Instrumented code SHOULD avoid observing values of `NaN` and `±Inf` because
+they make limited sense in the context of a histogram. However, those values
+MUST still be handled properly, as described in the following.
+
+The sum of observations is calculated as usual by adding the observation to the
+sum of observations, following normal floating point arithmetic. (For example,
+an observation of `NaN` will set the sum to `NaN`. An observation of `+Inf`
+will set the sum to `+Inf`, unless it is already `NaN` or `-Inf`, in which case
+the sum is set to `NaN`.)
+
+An observation of `NaN` goes into no bucket, but increments the count of
+observations. This implies that the count of observations can be greater than
+the sum of all buckets (negative, positive, and zero buckets), and the
+difference is the number of `NaN` observations. (For an integer histogram
+without any `NaN` observations, the sum of all buckets is equal to the count of
+observations. Within the usual floating point precision limits, the same is
+true for a float histogram without any `NaN` observations.)
+
+An observation of `+Inf` or `-Inf` increments the count of observations and
+increments a bucket chosen in the following way:
+- With a standard schema, a `+Inf` observation increments the
+  _positive overflow bucket_ as described above.
+- With a standard schema, a `-Inf` observation increments the
+  _negative overflow bucket_ as described above.
+- With schema -53 (custom buckets), a `+Inf` observation increments the
+  bucket with an index equal to the length of the custom values list.
+- With schema -53 (custom buckets), a `-Inf` observation increments the
+  bucket with index zero.
+
+### OpenTelemetry interoperability
+
+Prometheus (Prom) native histograms with a standard schema can be
+easily mapped into an OpenTelemetry (OTel) exponential histogram and vice
+versa, as detailed in the following.
+
+The Prom _schema_ is equal to the _scale_ in OTel, with the restriction that
+OTel allows lower values than -4 and higher values than +8. As described above,
+Prom has reserved more schema numbers to extend its range, should it ever by
+required in practice.
+
+The index is offset by one, i.e. a Prom bucket with index _n_ has index _n-1_
+for OTel.
+
+OTel has a dense rather than a sparse representation of buckets. One might see
+OTel as “Prom with only one span”.
+
+The Prom _zero bucket_ is called _zero count_ in OTel. (Prom also uses _zero
+count_ to name the field storing the count of observations in the zero bucket).
+Both work the same, including the existence of a _zero threshold_. Note that
+OTel implies a threshold of zero if none is given.
+
+(TODO: The OTel spec reads: “When zero_threshold is unset or 0, this bucket
+stores values that cannot be expressed using the standard exponential formula
+as well as values that have been rounded to zero.” Double-check if this really
+creates the same behavior. If there are problems close to zero, we could make
+Prom's spec more precise. If OTel counts NaN in the zero bucket, we have to add
+a note here.)
+
+OTel exponential histograms only support standard exponential bucketing schemas
+(as the name suggests). Therefore, NHCBs (or native histograms with other future
+bucketing schemas) cannot be cleanly converted to OTel exponential histograms.
+However, conversion to a conventional OTel histogram with fixed buckets is
+still possible.
+
+OTel histograms of any kind have optional fields for the minimum and maximum
+value observed in the histogram. These fields have no equivalent concept in
+Prometheus because counter histograms accumulate data over a long and
+unpredictable timespan and can be scraped at any time, so that tracking a
+minimum and maximum value is either infeasible or of limited use. Note, though,
+that native histograms enable a fairly accurate estimation of the maximum and
+minimum observation during arbitrary timespans, see the [PromQL
+section](#promql).
+
+## Exposition formats
+
+Metrics exposition in the classic Prometheus use case is dominated by strings
+because all the metric names, label names, and label values take much more
+space than the float64 sample values, even if the latter are represented in a
+potentially more verbose text form. This was one of the reasons why abandoning
+protobuf-based exposition seemed advantageous in the past.
+
+In contrast, a native histogram, following the data model described above,
+consists of a lot more numerical data. This amplifies the advantages of a
+protobuf based format. Therefore, the previously abandoned protobuf-based
+exposition was revived to efficiently expose and scrape native histograms.
+
+### Classic Prometheus formats
+
+At the time native histograms were conceived, OpenMetrics adoption was still
+lacking, and in particular, the protobuf version of OpenMetrics had no known
+applications at all. Therefore, the initial approach was to extend the classic
+Prometheus protobuf format to support native histograms. (An additional
+practical consideration was that the [Go instrumentation
+library](https://github.com/prometheus/client_golang) was still using the
+classic protobuf spec as its internal data model, simplifying the initial
+development.)
+
+The classic Prometheus text form was not extended for native histograms, and
+such an extension is not planned. (See also the [OpenMetrics](#open-metrics)
+section below.)
+
+There is a proto2 and a proto3 version of the protobuf specification, which
+both create the same wire format:
+
+- [proto2](https://github.com/prometheus/client_model/blob/master/io/prometheus/client/metrics.proto)
+- [proto3](https://github.com/prometheus/prometheus/blob/main/prompb/io/prometheus/client/metrics.proto)
+
+These files have comprehensive comments, which should enable an easy mapping
+from the proto spec to the data model described above.
+
+Here are relevant parts from the proto3 file:
+
+```protobuf
+// [...]
+
+message Histogram {
+  uint64 sample_count       = 1;
+  double sample_count_float = 4; // Overrides sample_count if > 0.
+  double sample_sum         = 2;
+  // Buckets for the classic histogram.
+  repeated Bucket bucket = 3 [(gogoproto.nullable) = false]; // Ordered in increasing order of upper_bound, +Inf bucket is optional.
+
+  google.protobuf.Timestamp created_timestamp = 15;
+
+  // Everything below here is for native histograms (also known as sparse histograms).
+  // Native histograms are an experimental feature without stability guarantees.
+
+  // schema defines the bucket schema. Currently, valid numbers are -4 <= n <= 8.
+  // They are all for base-2 bucket schemas, where 1 is a bucket boundary in each case, and
+  // then each power of two is divided into 2^n logarithmic buckets.
+  // Or in other words, each bucket boundary is the previous boundary times 2^(2^-n).
+  // In the future, more bucket schemas may be added using numbers < -4 or > 8.
+  sint32 schema           = 5;
+  double zero_threshold   = 6; // Breadth of the zero bucket.
+  uint64 zero_count       = 7; // Count in zero bucket.
+  double zero_count_float = 8; // Overrides sb_zero_count if > 0.
+
+  // Negative buckets for the native histogram.
+  repeated BucketSpan negative_span = 9 [(gogoproto.nullable) = false];
+  // Use either "negative_delta" or "negative_count", the former for
+  // regular histograms with integer counts, the latter for float
+  // histograms.
+  repeated sint64 negative_delta = 10; // Count delta of each bucket compared to previous one (or to zero for 1st bucket).
+  repeated double negative_count = 11; // Absolute count of each bucket.
+
+  // Positive buckets for the native histogram.
+  // Use a no-op span (offset 0, length 0) for a native histogram without any
+  // observations yet and with a zero_threshold of 0. Otherwise, it would be
+  // indistinguishable from a classic histogram.
+  repeated BucketSpan positive_span = 12 [(gogoproto.nullable) = false];
+  // Use either "positive_delta" or "positive_count", the former for
+  // regular histograms with integer counts, the latter for float
+  // histograms.
+  repeated sint64 positive_delta = 13; // Count delta of each bucket compared to previous one (or to zero for 1st bucket).
+  repeated double positive_count = 14; // Absolute count of each bucket.
+
+  // Only used for native histograms. These exemplars MUST have a timestamp.
+  repeated Exemplar exemplars = 16;
+}
+
+message Bucket {
+  uint64   cumulative_count       = 1; // Cumulative in increasing order.
+  double   cumulative_count_float = 4; // Overrides cumulative_count if > 0.
+  double   upper_bound            = 2; // Inclusive.
+  Exemplar exemplar               = 3;
+}
+
+// A BucketSpan defines a number of consecutive buckets in a native
+// histogram with their offset. Logically, it would be more
+// straightforward to include the bucket counts in the Span. However,
+// the protobuf representation is more compact in the way the data is
+// structured here (with all the buckets in a single array separate
+// from the Spans).
+message BucketSpan {
+  sint32 offset = 1; // Gap to previous span, or starting point for 1st span (which can be negative).
+  uint32 length = 2; // Length of consecutive buckets.
+}
+
+
+// A BucketSpan defines a number of consecutive buckets in a native
+// histogram with their offset. Logically, it would be more
+// straightforward to include the bucket counts in the Span. However,
+// the protobuf representation is more compact in the way the data is
+// structured here (with all the buckets in a single array separate
+// from the Spans).
+message BucketSpan {
+  sint32 offset = 1; // Gap to previous span, or starting point for 1st span (which can be negative).
+  uint32 length = 2; // Length of consecutive buckets.
+}
+
+// [...]
+```
+
+(TODO: The above does not yet contain the custom values needed for NHCBs. We do
+not need it right now because NHCB can be ingested via scraping classic
+histograms. However, it might still be useful to have custom buckets in the
+exposition format eventually, e.g. for federation, and for future schemas that
+might also utilize the custom values.)
+
+Note the following:
+
+- Both native histograms and classic histograms are encoded by the same
+  `Histogram` proto message, i.e. the existing `Histogram` message got extended
+  with fields for native histograms.
+- The fields for the sum and the count of observations and the
+  `created_timestamp` are shared between classic and native histograms and keep
+  working in the same way for both.
+- The format originally did not support classic float histograms. While
+  extending the format for native histograms, support for classic float
+  histograms was added as a byproduct (see fields `sample_count_float`,
+  `cumulative_count_float`).
+- The `Bucket` field and the `Bucket` message are used for the buckets of a
+  classic histogram. It is perfectly possible to create a `Histogram` message
+  that represents both a classic and a native version of the same histogram.
+  Parsers have the freedom to pick either or both versions (see also the
+  [scrape configuration section](#scrape-configuration)).
+- The bucket population is encoded as absolute numbers in case of float
+  histograms, and as deltas to the previous bucket (or to zero for the first
+  bucket) in case of integer histograms. The latter leads to smaller numbers,
+  which encode to a smaller message size because protobuf uses varint encoding
+  for the `sint64` type.
+- A native histogram that has received no observations yet and a classic
+  histogram that has no buckets configured would look exactly the same as a
+  protobuf message. Therefore, a `Histogram` message that is meant to be parsed
+  as a native histogram MUST contain a “no-op span”, i.e. a `BucketSpan` with
+  `offset` and `length` set to 0, in the repeated `positive_span` field.
+- Any number of exemplars for native histograms MAY be added in the repeated
+  `Exemplar` field of the `Histogram` message, but each one MUST have a
+  timestamp. If there are no exemplars provided in this way, a parser MAY use
+  timestamped exemplars provided for classic buckets (as at most one exemplar
+  per bucket in the `Exemplar` field of the `Bucket` message).
+- The number and distribution of native histogram exemplars SHOULD fit the use
+  case at hand. Generally, the exemplar payload SHOULD NOT be much larger than
+  the remaining part of the `Histogram` message, and the exemplars SHOULD fall
+  into different buckets and cover the whole spread of buckets approximately
+  evenly. (This is generally preferred over an exemplar distribution that
+  proportionally represents the distribution of observations, as the latter
+  will rarely yield exemplars from the long tail of a distribution, which are
+  often the most interesting exemplars to look at.)
+
+### OpenMetrics
+
+Currently (2024-11-03), OpenMetrics does not support native histograms.
+
+Adding support to the protobuf version of OpenMetrics is relatively
+straightforward due to its similarity to the classic Prometheus protobuf
+format. A [proposal in the form of a
+PR](https://github.com/OpenObservability/OpenMetrics/pull/256) is under review.
+
+Adding support to the text version of OpenMetrics is harder, but also highly
+desirable because there are many situations where the generation of protobuf is
+infeasible. A text format has to make a trade-off between readability for
+humans and efficient handling by machines (encoding, transport, decoding). Work
+on it is in progress. See the [design
+doc](https://github.com/prometheus/proposals/blob/main/proposals/2024-01-29_native_histograms_text_format.md)
+for more details.
+
+(TODO: Update section as progress is made.)
+
+## Instrumentation libraries
+
+The [protobuf specification](#classic-prometheus-formats) enables low-level
+creation of metrics exposition including native histograms using the language
+specific bindings created by the protobuf compiler. However, for direct code
+instrumentation, an instrumentation library is needed.
+
+Currently (2024-11-03), there are two official Prometheus instrumentation
+libraries supporting native histograms:
+
+- Go: [source](https://github.com/prometheus/client_golang) –
+  [documentation](https://pkg.go.dev/github.com/prometheus/client_golang/prometheus)
+- Java: [source](https://github.com/prometheus/client_java) –
+  [documentation](https://prometheus.github.io/client_java/)
+  
+Adding native histogram support to other instrumentation libraries is
+relatively easy if the library already supports protobuf exposition. For purely
+text based libraries, the completion of a [text based exposition
+format](#openmetrics) is a prerequisite. (TODO: Update this as needed.)
+
+This section does not cover details of how to use individual instrumentation
+libraries (see the documentation linked above for that) but focuses on the
+common usage patterns and also provides general guidelines how to implement
+native histogram support as part of an instrumentation library. The already
+existing [Go implementation](https://github.com/prometheus/client_golang) is
+used for examples. The sections about the [data model](#data-model) and the
+[exposition formats](#exposition-formats) are highly relevant for the
+implementation of instrumentation libraries (but not restated in this
+section!).
+
+The actual instrumentation API for histograms does not change for native
+histograms. Both classic histograms and native histograms receive observations
+in the same way (with subtle differences concerning exemplars, see next
+paragraph). Instrumentation libraries can even maintain a classic and a native
+version of the same histogram and expose them in parallel so that the scraper
+can choose which version to ingest (see the section about [exposition
+formats](#exposition-formats) for details). The user chooses whether to expose
+classic and/or native histograms via configuration settings.
+
+Exemplars for classic histograms are usually tracked by storing and exposing
+the most recent exemplar for each bucket. As long as classic buckets are
+defined, an instrumentation library MAY expose the same exemplars for the
+native version of the same histogram, as long as each exemplar has a timestamp.
+(In fact, a scraper MAY use the exemplars provided with the classic version of
+the histogram even if it is otherwise only ingesting the native version, see
+details in the [exposition formats](#exposition-formats) section.) However, a
+native histogram MAY be assigned any number of exemplars, and an
+instrumentation library SHOULD use this liberty to meet the best practices for
+exemplars as described in the [exposition formats](#exposition-formats)
+section.
+
+An instrumentation library SHOULD offer the following configuration parameters
+for native histograms following standard schemas. Names are
+examples from the Go library – they have to be adjusted to the idiomatic style
+in other languages. The value in parentheses is the default value that the
+library SHOULD offer.
+
+- `NativeHistogramBucketFactor` (1.1): A float greater than one to determine
+  the initial resolution. The library picks a starting schema that results in a
+  growth of the bucket width from one bucket to the next by a factor not larger
+  than the provided value. See table below for example values.
+- `NativeHistogramZeroThreshold` (2<sup>-128</sup>): A float of value zero or
+  greater to set the initial threshold for the zero bucket.
+
+The resolution is set via a growth factor rather than providing the schema
+directly because most users will not know the mathematics behind the schema
+numbers. The notion of an upper limit for the growth factor from bucket to
+bucket is understandable without knowing about the internal workings of native
+histograms. The following table lists an example factor for each valid schema.
+
+| `NativeHistogramBucketFactor` | resulting schema |
+|-------------------------------|------------------|
+|             65536             |    -4            |
+|               256             |    -3            |
+|                16             |    -2            |
+|                 4             |    -1            |
+|                 2             |     0            |
+|                 1.5           |     1            |
+|                 1.2           |     2            |
+|                 1.1           |     3            |
+|                 1.05          |     4            |
+|                 1.03          |     5            |
+|                 1.02          |     6            |
+|                 1.01          |     7            |
+|                 1.005         |     8            |
+
+### Limiting the bucket count
+
+Buckets of native histograms are created dynamically when they are populated
+for the first time. An unexpectedly broad distribution of observed values can
+lead to an unexpectedly high number of buckets, requiring more memory than
+anticipated. If the distribution of observed values can be manipulated from the
+outside, this could even be used as a DoS attack vector via exhausting all the
+memory available to the program. Therefore, an instrumentation library SHOULD
+offer a bucket limitation strategy. It MAY set one by default, depending on the
+typical use cases the library is used for. (TODO: Maybe we should say that a
+strategy SHOULD be set by default. The Go library is currently not limiting the
+buckets by default, and no issues have been reported with that so far.)
+
+The following describes the bucket limitation strategy implemented by the Go
+instrumentation library. Other libraries MAY follow this example, but other
+strategies might be feasible as well, depending on the typical usage pattern of
+the library.
+
+The strategy is defined by three parameters: an unsigned integer
+`NativeHistogramMaxBucketNumber`, a duration `NativeHistogramMinResetDuration`,
+and a float `NativeHistogramMaxZeroThreshold`. If
+`NativeHistogramMaxBucketNumber` is zero (which is the default), buckets are
+not limited at all, and the other two parameters are ignored. If
+`NativeHistogramMaxBucketNumber` is set to a positive value, the library
+attempts to keep the bucket count of each histogram to the provided value. A
+typical value for the limit is 160, which is also the default value used by
+OTel exponential histograms in a similar strategy. (Note that partitioning by
+labels will create a number of histograms. The limit applies to each of them
+individually, not to all of them in aggregate.) If the limit would be exceeded,
+a number of remedies are applied in order until the number of buckets is within
+the limit again:
+
+1. If at least `NativeHistogramMinResetDuration` has passed since the last
+   reset of the histogram (which includes the creation of the histogram), the
+   whole histogram is reset, i.e. all buckets are deleted and the sum and count
+   of observations as well as the zero bucket are set to zero. Prometheus
+   handles this as a normal counter reset, which means that some observations
+   will be lost between scrapes, so resetting should happen rarely compared to
+   the scraping interval. Additionally, frequent counter resets might lead to
+   less efficient storage in the TSDB (see the [TSDB section](#tsdb) for
+   details). A `NativeHistogramMinResetDuration` of one hour is a value that
+   should work well in most situations.
+2. If not enough time has passed since the last reset (or if
+   `NativeHistogramMinResetDuration` is set to zero, which is the default
+   value), no reset is performed. Instead, the zero threshold is increased to
+   merge buckets close to zero into the zero bucket, reducing the number of
+   buckets in that way. The increase of the threshold is limited by
+   `NativeHistogramMaxZeroThreshold`. If this value is already reached (or it
+   is set to zero, which is the default), nothing happens in this step.
+3. If the number of buckets still exceeds the limit, the resolution of the
+   histogram is reduced by converting it to the next lower schema, i.e. by
+   merging neighboring buckets, thereby doubling the width of the buckets. This
+   is repeated until the bucket count is within the configured limit or schema
+   -4 is reached.
+   
+If step 2 or 3 have changed the histogram, a reset will be performed once
+`NativeHistogramMinResetDuration` has passed since the last reset, not only to
+remove the buckets but also to return to the initial values for the zero
+threshold and the bucket resolution. Note that this is treated like a reset for
+other reasons in all aspects, including updating the so-called [created
+timestamp](#created-timestamp-handling).
+
+It is tempting to set a very low `NativeHistogramBucketFactor` (e.g. 1.005)
+together with a reasonable `NativeHistogramMaxBucketNumber` (e.g. 160). In this
+way, each histogram always has the highest possible resolution that is
+affordable within the given bucket count “budget”. (This is the default
+strategy used by the OTel exponential histogram. It starts with an even higher
+schema (20), which is currently not even available in Prometheus native
+histograms.) However, this strategy is generally _not_ recommended for the
+Prometheus use case. The resolution will be reduced quite often after creation
+and after each reset as observations come in. This creates churn both in the
+instrumented program as well as in the TSDB, which is particularly problematic
+for the latter. All of this effort is mostly in vain because the typical
+queries involving histograms require many histograms to get merged, during
+which the lowest common resolution is used so that the user ends up with a
+lower resolution anyway. The TSDB can be protected against the churn by
+limiting the resolution upon ingestion (see
+[below](#limit-bucket-count-and-resolution)), but if a reasonably low
+resolution will be enforced upon ingestion anyway, it is more straightforward
+to set this resolution during instrumentation already. However, this strategy
+might be worth the resource overhead within the instrumented program in
+specific cases where a reasonable resolution cannot be assumed at
+instrumentation time, and the scraper should have the flexibility to pick the
+desired resolution at scrape time.
+
+### Partitioning by labels
+
+While partitioning of a classic histogram with many buckets by labels has to be
+done judiciously, the situation is more relaxed with native histograms.
+Partitioning a native histograms still creates a multiplicity of individual
+histograms. However, the resulting partitioned histograms will often populate
+fewer buckets each than the original unpartitioned histogram. (For example, if
+a histogram tracking the duration of HTTP requests is partitioned by HTTP
+status code, the individual histogram tracking requests responded by status
+code 404 might have a very sharp bucket distribution around the typical
+duration it takes to identify an unknown path, populating only a few buckets.)
+The total number of populated buckets for all partitioned histograms will still
+go up, but by a smaller factor than the number of partitioned histograms. (For
+example, if adding labels to an already quite heavy classic histogram results
+in 100 labeled histograms, the total cost will go up by a factor of 100. In
+case of a native histogram, the cost for the single histogram might already be
+lower if the classic histogram featured a high resolution. After partitioning,
+the total number of populated buckets in the labeled native histograms will be
+signifcantly smaller than 100 times the number of buckets in the original
+native histogram.)
+
+### NHCB
+
+Currently (2024-11-03), instrumentation libraries offer no way to directly
+configure native histograms with custom bucket boundaries (NHCBs). The use case
+for NHCBs is to allow native-histogram enabled scrapers to convert classic
+histograms to NHCBs upon ingestion (see [next section](#scrape-configuration)).
+However, there are valid use cases where custom buckets are desirable directly
+during instrumentation. In those cases, the current approach is to instrument
+with a classic histogram and configure the scraper to convert it to an NHCB
+upon ingestion. However, a more direct treatment of NHCBs in instrumentation
+libraries might happen in the future.
+
+## Scrape configuration
+
+To enable the Prometheus server to scrape native histograms, the feature flag
+`--enable-feature=native-histograms` is required. This flag also changes the
+content negotiation to prefer the classic protobuf-based exposition format over
+the OpenMetrics text format. (TODO: This behavior will change once native
+histograms are a stable feature.)
+
+### Fine-tuning content negotiation
+
+With Prometheus v2.49 and later, it is possible to fine-tune the scrape
+protocol negotiation globally or per scrape config via the `scrape_protocols`
+config setting. It is a list defining the content negotiation priorities. Its
+default value depends on the `--enable-feature=native-histograms` flag. If the
+flag is set, it is `[ PrometheusProto, OpenMetricsText1.0.0,
+OpenMetricsText0.0.1, PrometheusText0.0.4 ]`, otherwise the first element,
+`PrometheusProto` is removed from the list, resulting in `[
+OpenMetricsText1.0.0, OpenMetricsText0.0.1, PrometheusText0.0.4 ]`. These
+default values result in the behavior described above, i.e. protobuf is unused
+without the `--enable-feature=native-histograms` flag, while it is the first
+priority with the flag set.
+
+The setting can be used to configure protobuf scrapes without ingesting native
+histograms or enforce a non-protobuf format for certain targets even with the
+`--enable-feature=native-histograms` flag set. As long as the classic
+Prometheus protobuf format (`PrometheusProto` in the configured list) is the
+only format supporting native histograms, both the feature flag and negotiation
+of protobuf is required to actually ingest native histograms.
+
+(TODO: Update this section once native histograms are a stable feature or native
+histograms are supported by other formats.)
+
+NOTE: Switching the used exposition format between text-based and
+protobuf-based has some non-obvious implications. Most importantly, certain
+implementation details result in the counter-intuitive effect that scraping
+with a text-based format is generally much less resource demanding than
+scraping with a protobuf-based format (see [tracking
+issue](https://github.com/prometheus/prometheus/issues/14668) for details).
+Even more subtle is the effect on the formatting of label values for `quantile`
+labels (used in summaries) and `le` labels (used in classic histograms). This
+problem only affects v2 of the Prometheus server (v3 has consistent formatting
+under all circumstances) and is not directly related to native histograms, but
+might show up in the same context because enabling native histograms requires
+the protobuf exposition format. See details in the [documentation for the
+`native-histograms` feature
+flag](https://prometheus.io/docs/prometheus/2.55/feature_flags/#native-histograms)
+for v2.55.
+
+### Limiting bucket count and resolution
+
+While [instrumentation libraries](#instrumentation-libraries) SHOULD offer
+configuration options to limit the resolution and bucket count of a native
+histogram, there is still a need to enforce those limits upon ingestion. Users
+might be unable to change the instrumentation of a given program, or a program
+might be deliberately instrumented with high-resolution histograms to give
+different scrapers the option to reduce the resolution as they see fit.
+
+The Prometheus scrape config offers two settings to address this need:
+
+1. The `native_histogram_bucket_limit` sets an upper inclusive limit for the
+   number of buckets in an individual histogram. If the limit is exceeded, the
+   resolution of a histogram with a standard schema is repeatedly
+   reduced (by doubling the width of the buckets, i.e. decreasing the schema)
+   until the limit is reached. In case an NHCB exceeds the limit, or in the rare
+   case that the limit cannot be satisfied even with schema -4, the scrape
+   fails.
+2. The `native_histogram_min_bucket_factor` sets a lower inclusive limit for
+   the growth factor from bucket to bucket. This setting is only relevant for
+   standard schemas and has no effect on NHCBs. Again, if the limit
+   is exceeded, the resolution of the histogram is repeatedly reduced (by
+   doubling the width of the buckets, i.e. decreasing the schema) until the
+   limit is reached. However, once schema -4 is reached, the scrape will still
+   succeed, even if a higher growth factor has been specified.
+
+Both settings accept zero as a valid value, which implies “no limit”. In case
+of the bucket limit, this means that the number of buckets are indeed not
+checked at all. In the case of the bucket factor, Prometheus will still ensure
+that a standard schema will not exceed the capabilities of the used
+storage backend. (TODO: This currently means the schema is at most +8, which is
+also the limit we allow in the exposition format. OTel allows higher
+exponential schemas, and Prometheus might therefore allow them in ingestion
+paths, too, but reduce the schema to +8 upon ingestion, or to whatever limit
+the current implementation requires. See
+https://github.com/prometheus/prometheus/issues/14168 for final clarification.)
+
+If both settings have a non-zero values, the schema is decreased sufficiently
+to satisfy both limits.
+
+Note that the bucket factor set during
+[instrumentation](#instrumentation-libraries) is an upper limit (exposed bucket
+growth factor ≤ configured value), while the bucket factor set in the
+scrape config is a lower limit (ingested bucket growth factor ≥ configured
+value). The schemas resulting from certain limits are therefore slightly
+different. Some examples:
+
+| `native_histogram_min_bucket_factor` | resulting max schema |
+|--------------------------------------|------------------|
+|             65536                    |    -4            |
+|               256                    |    -3            |
+|                16                    |    -2            |
+|                 4                    |    -1            |
+|                 2                    |     0            |
+|                 1.4                  |     1            |
+|                 1.1                  |     2            |
+|                 1.09                 |     3            |
+|                 1.04                 |     4            |
+|                 1.02                 |     5            |
+|                 1.01                 |     6            |
+|                 1.005                |     7            |
+|                 1.002                |     8            |
+
+General considerations about setting the limits:
+`native_histogram_bucket_limit` is suitable to set a hard limit for the cost of
+an individual histogram. The same cannot be accomplished by
+`native_histogram_min_bucket_factor` because histograms can have many buckets
+even with a low resolution if the distribution of observations is sufficiently
+broad. `native_histogram_min_bucket_factor` is well suited to avoid needless
+overall resource costs. For example, if the use case at hand only requires a
+certain resolution, setting a corresponding
+`native_histogram_min_bucket_factor` for all histograms might free up enough
+resources to accept a very high bucket count on a few histograms with broad
+distributions of observed values. Another example is the case where some
+histograms have low resolution for some reason (maybe already on the
+instrumentation side). If aggregations regularly include those low resolution
+histograms, the outcome will have that same low resolution (see the [PromQL
+details below](#compatibility-between-histograms)). Storing other histograms
+regularly aggregated with the low resolution histograms at higher resolution
+might not be of much use.
+
+### Scraping both classic and native histograms
+
+As described [above](#exposition-formats), a histogram exposed by an
+instrumented program might contain both a classic and a native histograms, and
+some parts are even shared (like the count and sum of observations). This
+section explains which parts will be scraped by Prometheus, and how to control
+the behavior.
+
+Without the `--enable-feature=native-histograms` flag, Prometheus will
+completely ignore the native histogram parts during scraping. (TODO: Update
+once the feature flag has been no-op'd.) With the flag set, Prometheus will
+prefer the native histogram parts over the classic histogram parts, even if
+both are exposed for the same histogram. Prometheus will still scrape the
+classic histogram parts for histograms with no native histogram data.
+
+In situations like [migration scenarios](#migration-considerations), it might
+be desired to scrape both versions, classic and native, for the same histogram,
+provided both versions are exposed by the instrumented program. To enable this
+behavior, there is a boolean setting `always_scrape_classic_histograms` in the
+scrape config. It defaults to false, but if set to true, both versions of each
+histogram will be scraped and ingested, provided there is at least one classic
+bucket and at least one native bucket span (which might be a no-op span). This
+will not cause any conflicts in the TSDB because classic histograms are
+ingested as a number of suffixed series, while native histograms are ingested
+as just one series with their unmodified name. (Example: A histogram called
+`rpc_latency_seconds` results in a native histogram series named
+`rpc_latency_seconds` and in a number of series for the classic part, namely
+`rpc_latency_seconds_sum`, `rpc_latency_seconds_count`, and a number of
+`rpc_latency_seconds_bucket` series with different `le` labels.)
+
+### Scraping classic histograms as NHCBs
+
+The aforementioned NHCB is capable of modeling a classic histogram as a native
+histogram. Via the boolean scrape config option
+`convert_classic_histograms_to_nhcb`, Prometheus can be configured to ingest
+classic histograms as NHCBs.
+
+NHCBs have the same issue with limited mergeability as classic histograms, but
+they are generally much less expensive to store.
+
+## TSDB
+
+NOTE: This section provides a high level overview of storing native histograms
+in the TSDB and also explains some important individual aspects that might be
+easy to miss. It is not meant to explain implementation details, define on-disk
+formats, or guide through the code base. There is a [detailed documentation of
+the various storage
+formats](https://github.com/prometheus/prometheus/tree/main/tsdb/docs/format)
+and of course the usual generated GoDoc, with the [tsdb
+package](https://pkg.go.dev/github.com/prometheus/prometheus/tsdb) and the
+[storage package](https://pkg.go.dev/github.com/prometheus/prometheus/storage)
+as suitable starting points. A helpful resource is also the aforementioned
+[Developer’s Guide to Prometheus Native
+Histograms](https://docs.google.com/document/d/1VhtB_cGnuO2q_zqEMgtoaLDvJ_kFSXRXoE0Wo74JlSY/edit).
+
+### Integer histograms vs. float histograms
+
+The TSDB stores integer histograms and float histograms differently. Generally,
+integer histograms are expected to compress better, so a TSDB implementation
+MAY store a float histogram as an integer histogram if all bucket counts and
+the count of observations have an integer value within the int64 range so that
+the conversion to an integer histogram creates a numerically precise
+representation of the original float histogram. (Note that the Prometheus TSDB
+is not utilizing this option yet.)
+
+### Encoding
+
+Native histograms require two new chunk encodings (Go type `chunkenc.Encoding`)
+in the TSDB: `chunkenc.EncHistogram` (string representation `histogram`,
+numerical value 2) for integer histograms, and `chunkenc.EncFloatHistogram`
+(string representation `floathistogram`, numerical value 3) for float
+histograms.
+
+Similarly, there are two new record types for the WAL and the in-memory
+snapshot (Go type `record.Type`): `record.HistogramSamples` (string
+representation `histogram_samples`, numerical value 9) for integer histograms,
+and `record.FloatHistogramSamples` (string representation
+`float_histogram_samples`, numerical value 10) for float histograms. For
+backwards compatibility reasons, there are two more histogram record types:
+`record.HistogramSamplesLegacy` (`histogram_samples_legacy`, 7) and
+`record.FloatHistogramSamplesLegacy` (`float_histogram_samples_legacy`, 8).
+They were used prior to the introduction of custom values needed for NHCB. They
+are supported so that reading old WALs is still possible.
+
+Prometheus identifies time series just by their labels. Whether a sample in a
+series is a float (and as such a counter or a gauge) or a histogram (no matter
+what flavor) does not contribute to the series's identity. Therefore, a series
+MAY contain a mix of samples of different types and flavors. Changes of the
+sample type within a time series are expected to be very rare in practice. They
+usually happen after changes in the instrumentation of a target (in the rare
+case that the same metric name is used for e.g. a gauge float prior to the
+change and a counter histogram after the change) or after a change of a
+recording rule (e.g. where the old version of a rule created a gauge float and
+the new version of the rule now creates a gauge histogram while retaining its
+name). Frequent changes of the sample type are usually the consequence of a
+misconfiguration (e.g. two different recording rules creating different sample
+types feeding into the same series). Therefore, a TSDB implementation MUST
+handle a change in sample type, but it MAY do so in a relatively inefficient
+way. When the Prometheus TSDB encounters a sample type that cannot be written
+to the currently used chunk, it closes that chunk and starts a new one with the
+appropriate encoding. (A time series that switches sample types back and forth
+for each sample will lead to a new chunk for each sample, which is indeed very
+inefficient.)
+
+Histogram chunks use a number of custom encodings for numerical values, in
+order to reduce the data size by encoding common values in fewer bits than less
+common values. The details of each custom encoding are described in the [low
+level chunk format
+documentation](https://github.com/prometheus/prometheus/blob/main/tsdb/docs/format/chunks.md)
+(and ultimately in the code linked from there). The following three encodings
+are used for a number of different fields and are therefore named here for
+later reference:
+
+- _varbit-int_ is a variable bitwidth encoding for signed integers. It uses
+  between 1 bit and 9 bytes. Numbers closer to zero need fewer bits. This is
+  similar to the timestamp encoding in chunks for float samples, but with a
+  different bucketing of the various bit lengths, optimized for the value
+  distribution commonly encountered in native histograms.
+- _varbit-uint_ is a similar encoding, but for unsigned integers.
+- _varbit-xor_ is a variable bitwidth encoding for a sequence of floats. It is
+  based on XOR'ing the current and the previous float value in the sequence. It
+  uses between 1 bit and 77 bits per float. This is exactly the same encoding
+  the TSDB already uses for float samples.
+
+Histogram chunks start as usual with the number of samples in the chunk (as a
+uint16), followed by one byte describing if the histogram is a gauge histogram
+or a counter histogram and providing counter reset information for the latter.
+See the [corresponding section](#counter-reset-considerations) below for
+details. This is followed by the so called chunk layout, which contains the
+following information, _shared by all histograms in the chunk_:
+
+- The threshold of the zero bucket, using a custom encoding that encodes common
+  values (zero or certain powers of two) in just one byte, but requires 9 bytes
+  for arbitrary values.
+- The schema, encoded as varbit-int.
+- The positive spans, encoded as the number of spans (varbit-uint), followed by
+  the length (varbit-uint) and the offset (varbit-int) of each span in a
+  repeated sequence.
+- The negative spans in the same way.
+- Only for schema -53 (NHCB) the custom values, encoded as the number of custom
+  values (varbit-uint), followed by the custom values in a repeated sequence,
+  using a custom encoding.
+
+The chunk layout is followed by a repeated sequence of sample data. The sample
+data is different for integer histograms and float histograms. For an integer
+histogram, the data of each sample contains the following:
+
+- The timestamp, encoded as varbit-int, with an absolute value in the 1st
+  sample, a delta between the 1st and 2nd sample for the 2nd sample, and a
+  “delta of deltas” for any further samples (i.e. the same “double delta”
+  encoding used for timestamps in conventional float chunks, just with a
+  different bit bucketing for the varbit-int encoding).
+- The count of observations, encoded as varbit-uint for the 1st sample and as
+  varbit-int for any further samples, using the same “delta of deltas” approach
+  as for timestamps.
+- The zero bucket population, encoded as varbit-uint for the 1st sample and as
+  varbit-int for any further samples, using the same “delta of deltas” approach
+  as for timestamps.
+- The sum of observations, encoded as a float64 for the 1st sample and as
+  varbit-xor for any further samples (XOR'ing between the current and previous
+  sample).
+- The bucket populations of the positive buckets, each as a delta to the
+  previous bucket (or as the absolute population in the 1st bucket), encoded as
+  varbit-int, using the same “delta of deltas” approach as for timestamps. (In
+  other words, the “double delta” encoding is applied to values that are
+  already deltas on their own, which is the reason why this is sometimes called
+  “triple delta“ encoding.)
+- The bucket populations of the negative buckets in the same way.
+
+The sample data of a float histogram has the following differences:
+
+- The count of observations and the zero bucket populations are floats now and
+  therefore encoded in the same way as the sum of observations (float64 in the
+  1st sample, varbit-xor for any further samples).
+- The bucket population are not only floats now, but also absolute population
+  counts rather than deltas between buckets. In the 1st sample, all bucket
+  populations are represented as plain float64's, while they are encoded as
+  varbit-xor for all further samples, XOR'ing corresponding buckets from the
+  current and the previous sample.
+
+The following events trigger cutting a new chunk (for the reasons described in
+parentheses):
+
+- A change of sample type between integer histogram and float histogram
+  (because both require different chunk encodings altogether).
+- A change of sample type between gauge histogram and counter histogram
+  (because the leading byte has to denote the different type).
+- A counter reset for a counter histogram (to be stored in the leading byte as
+  counter reset information, see details below).
+- A schema change (which means we need a new chunk layout, and a chunk can only
+  have one chunk layout).
+- A change of the zero threshold (which changes the chunk layout, see above).
+- A change of the custom values (which changes the chunk layout, see above).
+- A staleness marker is followed by a regular sample (which does not strictly
+  require a new chunk, but it can be assumed that most histograms will change
+  so much when they go away and come back that cutting a new chunk is the best
+  option).
+- The chunk size limit is exceeded (see [details below](#chunk-size-limit)).
+
+Differences in the spans would also change the chunk layout, but they are
+reconciled by adding (explicitly represented) unpopulated buckets as needed so
+that all histograms in a chunk share the same span structure. This is
+straightforward if a bucket disappears, because the missing bucket is simply
+added to the new histogram as an unpopulated bucket while the histogram is
+appended to the chunk. However, disappearance of a formerly populated bucket
+constitutes a counter reset (see [below](#counter-reset-considerations)), so
+this case can only happen for gauge histograms (which do not feature counter
+resets). The far more common case is that buckets exist in a newly appended
+histogram that did not exist in the previously appended histograms. In this
+case, these buckets have to be added as explicitly unpopulated buckets to all
+previously appended histograms. This requires a complete re-encoding of the
+entire chunk. (There is some optimization potential in only re-encoding the
+affected parts. Implementing this would be quite complicated. So far, the
+performance impact of the full re-encoding did not stick out as problematic.)
+
+### Staleness markers
+
+NOTE: To understand the following section, it is important to recall how
+staleness markers work in the TSDB. Staleness markers in float series are
+represented by one specific bit pattern among the many that can be used to
+represent the `NaN` value. This very specific float value is called “special
+stale `NaN` value” in the following section. It is (almost certainly) never
+returned by the usual arithmetic float operations and as such different from a
+“naturally occurring” `NaN` value, including those discussed in [Special cases
+of observed values](#special-cases-of-observed-values). In fact, the special
+stale `NaN` value is never returned directly when querying the TSDB, but it is
+handled internally before it reaches the caller.
+
+To mark staleness in histogram series, the usual special stale `NaN` value
+could be used. However, this would require cutting a new chunk, just for the
+purpose of marking the series as stale, because a float value following a
+histogram value has to be stored in a different chunk (see above). Therefore,
+there is also a histogram version of a stale marker where the field for the sum
+of observations is set to the special stale `NaN` value. In this case, all
+other fields are ignored, which enables setting them to values suitable for
+efficient storage (as the histogram version of a stale marker is essentially
+just a storage optimization). This works for both float and integer histograms
+(as the sum field is a float value even in an integer histogram), and the
+appropriate version can be used to avoid cutting a new chunk. All version of a
+stale marker (float, integer histogram, float histogram) MUST be treated as
+equivalent by the TSDB.
+
+### Chunk size limit
+
+The size of float chunks is limited to 1024 bytes. The same size limitation is
+generally used for histogram chunks, too. However, individual histograms can
+become very large if they have many buckets, so blindly enforcing the size
+limit could lead to chunks with very few histograms. (In the most extreme case,
+a single histogram could even take more than 1024 bytes so that the size limit
+could not be enforced at all.) With very few histograms per chunk, the
+compression ratio becomes worse. Therefore, a minimum number of 10 histograms
+per chunks has to be reached before the size limit of 1024 bytes kicks in. This
+implies that histogram chunks can be much larger than 1024 bytes.
+
+Requiring a minimum of 10 histograms per chunk is an initial, very simplistic
+approach, which might be improved in the future to find a better trade-off
+between chunk size and compression ratio.
+
+### Counter reset considerations
+
+Generally, Prometheus considers a counter to have reset whenever its value
+drops from one sample to the next (but see also the [next section about the
+created timestamp](#created-timestamp-handling)). The situation is more complex
+when detecting a counter reset between two histogram samples.
+
+First of all, gauge histograms and counter histograms are explicitly different
+(whereas Prometheus generally treats all float samples equally after ingestion,
+no matter if they were ingested as a gauge or a counter metric). Counter resets
+do not apply to gauge histograms.
+
+If a gauge histogram is followed by a counter histogram in a time series, a
+counter reset is assumed to have happened, because a change from gauge to
+counter is considered equivalent to the gauge being deleted and the counter
+being newly created from zero.
+
+The most common case is a counter histogram being followed by another counter
+histogram. In this case, a possible counter reset is detected by the following
+procedure:
+
+If the two histograms differ in schema or in the zero bucket width, these
+changes could be part of a compatible resolution reduction (which happens
+regularly to [reduce the bucket count of a
+histogram](#limit-the-bucket-count)). Both of the following is true for a
+compatible resolution reduction:
+
+- If the schema has changed, its number has decreased from one standard
+  exponential schema to another standard schema.
+- If the zero bucket width has changed, any populated regular bucket in the first
+  histogram is either completely included in the zero bucket of the second
+  histogram or not at all (i.e. no partial overlap of old regular buckets with
+  the new zero bucket).
+  
+If any of the conditions are not met, the change is not a compatible resolution
+reduction. Because such a change is only possible by resetting or newly 
+creating a histogram, it is considered a counter reset and the detection
+procedure is concluded.
+
+If both conditions are met, the first histogram has to be converted so that its
+schema and zero bucket width matches those of the second histogram. This
+happens in the same way as [previously described](#limit-the-bucket-count):
+Neighboring buckets are merged to reduce the schema, and regular buckets are
+merged with the zero bucket to increase the width of the zero bucket.
+
+At this point in the procedure, both histograms have the same schema and zero
+bucket width, either because this was the case from the beginning, or because
+the first histogram was converted accordingly. (Note that NHCBs do not use the
+zero bucket. Their zero bucket widths and population counts are considered
+equal for the sake of this procedure.) In this situation, any of the following
+constitutes a counter reset:
+
+- A drop in the count of observations (but notably _not_ a drop in the sum of
+  observations).
+- A drop in the population count of any bucket, including the zero bucket. This
+  includes the case where a populated bucket disappears, because a
+  non-represented bucket is equivalent to a bucket with a population of zero.
+- Any change of the custom values. This only applies for schemas that use
+  custom values (currently schema -53, i.e. NHCB). (TODO: In principle, there
+  could be a concept of compatible bucket changes in NHCBs, too, but such a
+  concept is not implemented yet.)
+
+If none of the above is the case, there is no counter reset.
+
+As this whole procedure is relatively involved, the counter reset detection
+preferably happens once during ingestion, with the result being persisted for
+later use. Counter reset detection during ingestion has to happen anyway
+because a counter reset is one of the triggers to cut a new chunk.
+
+Cutting a new chunk after a counter reset aims to improve the compression
+ratio. A counter reset sets all bucket populations to zero, so there are fewer
+buckets to represent. A chunk, however, has to represent the superset of all
+buckets of all histograms in the chunk, so cutting a new chunk enables a
+simpler set of buckets for the new chunk.
+
+This in turn implies that there will never be a counter reset after the first
+sample in a chunk. Therefore, the only counter reset information that has to be
+persisted is that of the 1st histogram in a chunk. This happens in the
+so-called _histogram flags_, a single byte stored directly after the the number
+of samples in the chunk. This byte is currently only used for the counter reset
+information, but it may be used for other flags in the future. The counter
+reset information uses the first two bits. The four possible bit patterns are
+represented as Go constants of type `CounterResetHeader` in the `chunkenc`
+package. Their names and meanings are the following:
+
+- `GaugeType` (bit pattern `11`): The chunk contains gauge histograms.
+  Counter resets are irrelevant for gauge histograms.
+- `CounterReset` (bit pattern `10`): A counter reset happened between the last
+  histogram of the previous chunk and the 1st histogram of this chunk. (It is
+  likely that the counter reset was actually the reason why the new chunk was
+  cut.)
+- `NotCounterReset` (bit pattern `01`): No counter reset happened between the
+  last histogram of the previous chunk and the 1st histogram of this chunk.
+  (This commonly happens if a new chunk is cut because the previous chunk hit
+  the size limit.)
+- `UnknownCounterReset` (bit pattern `00`): It is unknown if there was a
+  counter reset between the last histogram of the previous chunk and the 1st
+  histogram of this chunk.
+  
+`UnknownCounterReset` is always a safe choice. It does not prevent counter
+reset detection, but merely requires that the counter reset detection procedure
+has to be performed (again) whenever counter reset information is needed.
+
+The counter reset information is propagated to the caller when querying the
+TSDB (in the Go code as a field of type `CounterResetHint` in the Go types
+`Histogram` and `FloatHistogram`, using enumerated constants with the same
+names as the bit pattern constants above).
+
+For gauge histogram, the `CounterResetHint` is always `GaugeType`. Any other
+`CounterResetHint` value implies that the histogram in question is a counter
+histogram. In this way, queriers (including the PromQL engine, see
+[below](#promql)) obtain the information if a histogram is a gauge or a counter
+(which is notably different from float samples).
+
+As long as counter histograms are returned in order from a single chunk, the
+`CounterResetHint` for the 2nd and following histograms in a chunk is set to
+`NotCounterReset`. (Overlapping blocks and out-of-order ingestion may lead to
+histogram sequences coming from multiple chunks, which requires special
+treatment, see below.)
+
+When returning the 1st histogram from a counter histogram chunk, the
+`CounterResetHint` MUST be set to `UnknownCounterReset` _unless_ the TSDB
+implementation can ensure that the previously returned histogram was indeed the
+same histogram that was used as the preceding histogram to detect the counter
+reset at ingestion time. Only in the latter case, the counter reset information
+from the chunk MAY be used directly as the `CounterResetHint` of the returned
+histogram.
+
+This precaution is needed because there are various ways how chunks might get
+removed or inserted (e.g. deletion via tombstones or adding blocks for
+backfilling). A counter reset, while attributed to one sample, is in fact
+happening _between_ the marked sample and the preceding sample. Removing the
+preceding sample or inserting another sample in between the two samples
+invalidates the previously performed counter reset detection.
+
+TODO: Currently, the Prometheus TSDB has no means of ensuring that the
+preceding chunk is still the same chunk as during ingestion. Therefore,
+Prometheus currently returns `UnknownCounterReset` for _all_ 1st histograms
+from a counter histogram chunk. See [tracking
+issue](https://github.com/prometheus/prometheus/issues/15346) for efforts to
+change that.
+
+As already implied above, the querier MUST perform the counter reset detection
+procedure (again), if the `CounterResetHint` is set to `UnknownCounterReset`.
+
+Special caution has to be applied when processing overlapping blocks or
+out-of-order samples (for querying or during compaction). Both overdetection
+and underdetection of counter resets may happen in these cases, as illustrated
+by the following examples:
+
+- _Example for underdetection:_ One chunk contains samples ABC, without counter
+  resets. Another chunk contains samples DEF, again without counter resets. The
+  chunks are overlapping and refer to the same series. When querying them
+  together, the temporal order of samples turns out to be ADBECF. There might
+  now very well be a counter reset between some or even all of those samples.
+  This is in fact likely if the two samples are actually from unrelated series
+  and got merged into the same series by accident. However, even accidental
+  merges like this have to be handled correctly by the TSDB. If the overlapping
+  chunks are compacted into a new chunk, a new counter reset detection has to
+  happen, catching the new counter resets. If querying the overlapping chunks
+  directly (without prior compaction), a `CounterResetHint` of
+  `UnknownCounterReset` has to be set for each sample that comes from a
+  different chunk than the previously returned sample, which mandates a counter
+  reset detection by the querier (utilizing the safe fallback described above).
+- _Example for overdetection:_ There is a sequence of samples ABCD with a
+  counter reset happening between B and C. However, the initial ingestion
+  missed B and C so that only A and D were ingested, with a counter reset
+  detected between A and D. Later, B and C are ingested (via out-of-order
+  ingestion or as separate chunks later added to the TSDB as a separate block),
+  with a counter reset detected between B and C. In this case, each sample goes
+  into its own chunk, so when assembling all the chunks, they do not even
+  overlap. However, when returning the counter reset hints according to the
+  rules above, both C and D will be returned to the querier with a
+  `CounterResetHint` of `CounterReset`, although there is now no counter reset
+  between C and D. Similar to the situation in the previous example, a new
+  counter reset detection has to be performed between A and B, and another one
+  between C and D. Or both B and D have to be returned with a
+  `CounterResetHint` of `UnknownCounterReset`.
+  
+In summary, whenever the TSDB cannot safely establish that a counter reset
+detection between two samples has happened upon ingestion, it either has to
+perform another counter reset detection or it has to return a
+`CounterResetHint` of `UnknownCounterReset` for the second sample.
+
+Note that there is the possiblity of counter resets that are not detected by
+the procedure described above, namely if the counts in the reset histogram have
+increased quickly enough so that the 1st sample after the counter reset has no
+counts that have decreased compared to the last sample prior to the counter
+reset. (This is also a problem for float counters, where it is actually more
+likely to happen.) With the mechanisms explained above, it is possible to store
+a counter reset even in this case, provided that the counter reset was detected
+by other means. However, due to the complications caused by insertion and
+removal of chunks, out-of-order samples, and overlapping blocks (as explained
+above), this information MAY get lost if a second round of counter reset
+detection is required. (TODO: Currently, this information is reliably lost, see
+TODO above.) A better way to safely mark a counter reset is via created
+timestamps (see next section).
+
+### Created timestamp handling
+
+OpenMetrics introduced so-called created timestamps for counters, summaries,
+and classic counter histograms. (The term is probably short for “created-at
+timstamp”. The more appropriate term might have been “creation timestamp” or
+“reset timestamp”, but the term “created timestamp” is firmly established by
+now.)
+
+The created timestamp provides the most recent time the metric was created or
+reset. A [design
+doc](https://github.com/prometheus/proposals/blob/main/proposals/2023-06-13_created-timestamp.md)
+describes how Prometheus handles created timestamps.
+
+Created timestamps are also useful for native histograms. In the same way a
+synthetic zero sample is inserted for float counters, a zero value of a
+histogram sample is inserted for counter histograms. A zero value of a
+histogram has no populated buckets, and the sum of observations, the count of
+observations, and the zero bucket population are all zero. Schema, zero bucket
+width, custom values, and the float vs. integer flavor of the histogram SHOULD
+match the sample that directly follows the synthetic zero sample (to not
+trigger the detection of a spurious counter reset).
+
+The counter reset information of the synthetic zero sample is always set to
+`CounterReset`. (TODO: Currently, Prometheus probably sets it to
+`UnknownCounterReset` for the first sample of a series, which is not wrong, but
+I think setting it to `CounterReset` makes more sense.)
+
+### Exemplars
+
+Exemplars for native histograms are attached to the histogram sample as a
+whole, not to individual buckets. (See also the [exposition formats
+section](#exposition-formats).) Therefore, it is allowed (and in fact the
+common case) that a single native histogram sample comes with multiple
+exemplars attached.
+
+Exemplars may or may not change from one scrape to the next. Scrapers SHOULD
+detect unchanged exemplars to avoid storing many duplicate exemplars. Duplicate
+detection is potentially expensive, though, given that a single sample might
+have many exemplars, of which any subset could be repeated exemplars from the
+last scrape. The TSDB MAY rely on the assumption that any new exemplar has a
+more recent timestamp than any of the previously exposed exemplars. (Remember
+that exemplars of native histograms MUST have a timestamp.) Duplicate detection
+is then possible in an efficient way:
+
+1. The exemplars of a newly ingested native histogram are sorted by the
+   following fields: first timestamp, then value, then labels.
+2. The exemplars are appended to the exemplar storage in the sorted order.
+3. The append fails for exemplars that would be sorted before or are equal to
+   the last successfully appended exemplar (which might be from the previous
+   scrape for the same metric).
+4. The append succeeds for exemplars that would be sorted after the last
+   successfully appendend exemplar.
+
+Exemplars are only counted as out of order if all exemplars of an ingested
+histogram would be sorted before the last successfully appended exemplar. This
+does not detect out-of-order exemplars that are mixed with newer exemplars or
+with a duplicate of the last successfully appended exemplar, which is
+considered acceptable.
+
+## PromQL
+
+This section describes how PromQL handles native histograms. It focuses on
+general concepts rather than every single detail of individual operations. For
+the latter, refer to the PromQL documentation about
+[operators](https://prometheus.io/docs/prometheus/latest/querying/operators/)
+and
+[functions](https://prometheus.io/docs/prometheus/latest/querying/functions/).
+
+### Annotations
+
+The introduction of native histograms creates certain situations where a PromQL
+expression returns unexpected results, most commonly the case where some or all
+elements in the output vector are unexpectedly missing. To help users detect
+and understand those situations, operations acting on native histograms often use
+annotations. Annotations can have warn and info level and describe possible
+issues encountered during the evaluation. Warn level is used to mark situations
+that are most likely an actual problem the user has to act on. Info level is
+used for situations that might also be deliberate, but are still unusual enough
+to flag them.
+
+### Integer histograms vs. float histograms
+
+PromQL always acts on float histograms. Native histograms that are stored as
+integer histograms are automatically converted to float histograms when
+retrieved from the TSDB.
+
+### Compatibility between histograms
+
+When an operator or function acts on two or more native histograms, the
+histograms involved need to have the same schema and zero bucket width. Within
+certain limits, histograms can be converted on the fly to meet these
+compatibility criteria:
+
+- An NHCB (schema -53) is only ever compatible with other NHCBs that also MUST
+  have the exact same custom values. (In principle, there are possible
+  differences in custom values that could be reconciled, but PromQL doesn't yet
+  consider those.)
+- Histograms with standard schemas can always be converted to the
+  smallest (i.e. lowest resolution) common schema by decreasing the resolution
+  of the histograms with greater schemas (i.e. higher resolution). This happens
+  in the usual way by merging neighboring buckets into the larger buckets of
+  the smaller schema.
+- Different zero bucket widths are handled by expanding the smaller zero
+  buckets, merging any populated regular bucket into the expanded zero bucket
+  as appropriate. If the greatest common width happens to end up in the middle
+  of any populated bucket, it is further expanded to coincide with the bucket
+  boundary of that bucket. (See more details in the [zero bucket section
+  above](#zero-bucket).)
+
+If incompatibility prevents an operation, a warn-level annotation is added to
+the result.
+
+### Counter resets
+
+Counter resets are defined as described [above](#counter-reset-considerations).
+Counter reset hints returned from the TSDB MAY be taken into account to avoid
+explicit counter reset detection and to correctly process counter resets that
+are not detectable by the usual procedure. (This implies that these counter
+resets are only taken into account on a best effort basis. However, the same is
+true for the TSDB itself, see above.) A notable difference to the counter reset
+handling for classic histograms and summaries is that a decrease of the sum of
+observations does _not_ constitute a counter reset by itself. (For example,
+calculating the rate of a native histogram will still work correctly even if
+the histogram has observed negative values.)
+
+Note that the counter reset hints of counter histograms returned by sub-queries
+MUST NOT be taken into account to avoid explicit counter reset detection,
+unless the PromQL engine can safely detect that consecutive counter histograms
+returned from the sub-query are also consecutive in the TSDB.
+
+### Gauge histograms vs. counter histograms
+
+Via the counter reset hint returned from the TSDB, PromQL is aware if a native
+histogram is a gauge or a counter histogram. To mirror PromQL's treatment of
+float samples (where it cannot reliably distinguish between float counters and
+gauges), functions that act on counters will still process gauge histograms,
+and vice versa, but a warn-level annotation is returned with the result. Note
+that explicit counter reset detection has to be performed on a gauge histogram
+in that case, treating it as if it were a counter histogram.
+
+### Interpolation within a bucket
+
+When estimating quantiles or fractions, PromQL has to apply interpolation
+within a bucket. In classic histograms, this interpolation happens in a linear
+fashion. It is based on the assumption that observations are equally
+distributed within the bucket. In reality, this assumption might be far off.
+(For example, an API endpoint might respond to almost all request with a
+latency of 110ms. The median latency and maybe even the 90th percentile latency
+would then be close to 110ms. If a classic histogram has bucket boundaries at
+100ms and 200ms, it would see most observations in that range and estimate the
+median at 150ms and the 90th percentile at 190ms.) The worst case is an
+estimation at one end of a bucket where the actual value is at the other end of
+the bucket. Therefore, the maximum possible error is the whole width of a
+bucket. Not doing any interpolation and using some fixed midpoint within a
+bucket (for example the arithmetic mean or even the harmonic mean) would
+minimize the maximum possible error (which would then be half of the bucket
+width in case of the arithmetic mean), but in practice, the linear
+interpolation yields an error that is lower on average. Since the interpolation
+has worked well over many years of classic histogram usage, interpolation is
+also applied for native histograms.
+
+For NHCBs, PromQL applies the same interpolation method as for classic
+histograms to keep results consistent. (The main use case for NHCBs is a
+drop-in replacement for classic histograms.) However, for standard exponential
+schemas, linear interpolation can be seen as a misfit. While exponential
+schemas primarily intend to minimize the relative error of quantile
+estimations, they also benefit from a balanced usage of buckets, at least over
+certain ranges of observed values. The basic assumption is that for most
+practically occurring destributions, the density of observations tends to be
+higher for smaller observed values. Therefore, PromQL uses exponential
+extrapolation for the standard schemas, which models the assumption
+that dividing a bucket into two when increasing the schema number by one (i.e.
+doubling the resolution) will on average see similar populations in both new
+buckets. A more detailed explanation can be found in the [PR implementing the
+interpolation method](https://github.com/prometheus/prometheus/pull/14677).
+
+A special case is interpolation within the zero bucket. The zero bucket breaks
+the exponential bucketing schema. Therefore, linear interpolation is applied
+within the zero bucket. Furthermore, if all populated regular buckets of a
+histogram are positive, it is assumed that all observations in the zero bucket
+are also positive, i.e. the interpolation is done between zero and the upper
+bound of the zero bucket. In the case of a histogram where all populated
+regular buckets are negative, the situation is mirrored, i.e. the interpolation
+within the zero bucket is done between the lower bond of the zero bucket and
+zero.
+
+### Mixed series
+
+As already discussed above, neither the sample type nor the flavor of a native
+histogram is part of the identity of a series. Therefore, one and the same
+series might contain a mix of different sample types and flavors.
+
+A mix of counter histograms and gauge histograms doesn't prevent any PromQL
+operation, but a warn-level annotation is returned with the result if some of
+the input samples have an inappropriate flavor (see
+[above](#gauge-histograms-vs-counter-histograms)).
+
+A mix of float samples and histogram samples is more problematic. Many
+functions that operate on range vectors will remove elements from the result
+where the input elements contain a mix of floats and histograms. If this
+happens, a warn-level annotation is added to the result. Concrete examples can
+be found [below](#functions).
+
+### Unary minus and negative histograms
+
+The unary minus can be used on native histograms. It returns a histogram where
+all bucket populations and the count and the sum of observations have their
+sign inverted. Everything else stays the same, including the counter reset
+hint. Note, however, that explicit counter reset detection will be thrown off
+by the inverted signs. (TODO: Maybe we should mark all negative histograms as
+gauges?) Negative histograms do not really make sense on their own and are only
+supposed to act as intermediate results inside other expressions.
+
+### Binary operators
+
+Most binary operators do not work between two histograms or between a histogram
+and a float or between a histogram and a scalar. If an operator processes such
+an impossible combination, the corresponding element is removed from the output
+vector and an info-level annotation is added to the result. (This situation is
+somewhat similar to label matching, where the sample type plays a role similar
+to a label. Therefore, such a mismatch might be known and deliberate, which is
+the reason why the level of the annotation is only info.)
+
+The following describes all the operations that actually _do_ work.
+
+Addition (`+`) and subtraction (`-`) work between two compatible histograms.
+These operators add or subtract all matching bucket populations and the count
+and the sum of observations. Missing buckets are assumed to be empty and
+treated accordingly. Subtraction might result in negative histograms, see
+[notes above](#unary-minus-and-negative-histograms). Generally, both operands
+should be gauges. Adding and subtracting counter histograms requires caution,
+but PromQL allows it. Adding a gauge histogram and a counter histogram results
+in a gauge histogram. Adding two counter histograms with contradicting counter
+reset hints triggers a warn-level annotation. (TODO: The latter not yet
+implemented. Also, subtraction doesn't check/modify counter reset hints yet.
+This should be documented in detail in the PromQL docs.)
+
+Multiplication (`*`) works between a float sample or a scalar on the one side
+and a histogram on the other side, in any order. It multiplies all bucket
+populations and the count and the sum of observations by the float (sample or
+scalar). This will lead to “scaled” and sometimes even negative histograms,
+which is usually only useful as intermediate results inside other expressions
+(see also [notes above](#unary-minus-and-negative-histograms)). Multiplication
+works for both counter histograms and gauge histograms, and their flavor is left
+unchanged by the operation.
+
+Division (`/`) works between a histogram on the left hand side and a float
+sample or a scalar on the right hand side. It is equivalent to multiplication
+with the inverse of the float (sample or scalar). Division by zero results in a
+histogram with no regular buckets and the zero bucket population and the count
+and sum of observations all set to `+Inf`, `-Inf`, or `NaN`, depending on their
+values in the input histogram (positive, negative, or zero/`NaN`,
+respectively).
+
+Equality (`==`) and inequality (`!=`) work between two histograms, both in
+their filtering version as well as with the `bool` modifier. They compare the
+schema, the custom values, the zero threshold, all bucket populations, and the
+sum and count of observations. Whether the histograms have counter or gauge
+flavor is irrelevant for the comparison. (A counter histogram could be equal to
+a gauge histogram.)
+
+The logical/set binary operators (`and`, `or`, `unless`) work as expected even
+if histogram samples are involved. They only check for the existence of a
+vector element and don't change their behavior depending on the sample type or
+flavor of an element (float or histogram, counter or gauge).
+
+The “trim” operators `>/` and `</` were introduced specifically for native
+histograms. They only work for a histogram on the left hand side and a float
+sample or a scalar on the right hand side. (They do not work for float samples
+or scalars on _both_ sides. An info-level annotation is returned in this case.)
+These operators remove observations from the histogram that are greater or
+smaller than the float value on the right side, respectively, and return the
+resulting histogram. The removal is only precise if the threshold coincides
+with a bucket boundary. Otherwise, interpolation within the affected buckets
+has to be used, as described [above](#interpolation-within-a-bucket). The
+counter vs. gauge flavor of the histogram is preserved. (TODO: These operators
+are not yet implemented and might also change in detail, see [tracking
+issue](https://github.com/prometheus/prometheus/issues/14651).)
+
+### Aggregation operators
+
+The following aggregation operators work in the same way with float and
+histogram samples (for the reason stated in parentheses):
+
+- `group` (The result of this aggregation does not depend on the sample values.)
+- `count` (The result of this aggregation does not depend on the sample values.)
+- `count_values` (The text representation as produced by the Go
+  `FloatHistogram.String` method is used as the value of histograms.)
+- `limitk` (The sampled elements are returned unchanged.)
+- `limit_ratio` (The sampled elements are returned unchanged.)
+
+The `sum` aggregation operator work with native histograms by summing up the
+histogram to be aggregated (in the same way as described for the `+` operator
+above). The `avg` aggregation operator works in the same way, but divides the
+sum by the number of aggregated histogram (in the same way as described for the
+`/` operator above). Both aggregation operators remove elements from the output
+vector that would require the aggregation of float samples with histogram
+samples. Such a removal is flagged by a warn-level annotation.
+
+All other aggregation operators do _not_ work with native histograms.
+Histograms in the input vector are simply ignored, and an info-level annotation
+is added for each ignored histogram.
+
+### Functions
+
+The following functions operate on range vectors of native histograms by
+applying the usual float operation individually to matching buckets (including
+the zero bucket) and the sum and count of observations, resulting in a new
+native histogram:
+
+- `delta()` (For gauge histograms.)
+- `increase()` (For counter histograms.)
+- `rate()` (For counter histograms.)
+- `idelta()` (For gauge histograms.)
+- `irate()` (For counter histograms.)
+
+These functions SHOULD be applied to either gauge histograms or counter
+histograms as noted above. However, they all work with both flavors, but if at
+least one histogram of an unsuitable flavor is contained in the range vector, a
+warn-level annotation is added to the result.
+
+`delta()`, `increase()`, and `rate()` return no result for series that contain
+a mix of float samples and histogram samples within the range. `idelta()` and
+`irate()` return no result for series where the last two samples within the
+range are a mix of a float sample and a histogram sample. In either case, a
+warn-level annotation is added for each output element missing for these
+reasons.
+
+All these functions return gauge histograms as results.
+
+As usual, these functions attempt to reconcile different schemas by converting
+the schema to a common one as far as possible. However, the functions applied
+to counters (`increase()`, `rate()`, `irate()`) do not perform this conversion
+for the 1st sample if there is a counter reset between the 1st and 2nd sample.
+In this case, the 1st sample is not included in the calculation, so an
+incompatible bucket layout between the 1st sample and the other samples is
+simply ignored silently.
+
+TODO: Preventing [extrapolation below
+zero](https://github.com/prometheus/prometheus/blob/034d2b24bcae90fce3ac337b4ddd399bd2ff4bc4/promql/functions.go#L153-L159)
+is currently not yet implemented (and might actually not make sense) for native
+histograms. This may lead to slightly different results when comparing classic
+histograms with equivalent NHCBs.
+
+`avg_over_time()` and `sum_over_time()` work with native histograms in a way
+that corresponds to the respective aggregation operators. In particular, if a
+series contains a mix of float samples and histogram samples within the range,
+the corresponding result is removed entirely from the output vector. Such a
+removal is flagged by a warn-level annotation.
+
+The `changes()` and the `resets()` function work with native histogram samples
+in the same way as with float samples. They even work with a mix of float
+samples and histogram samples within the same series. In this case, a change
+from a float sample to a histogram sample and vice versa counts as a change for
+`changes()` and as a reset for `resets()`. A change in flavor from counter
+histogram to gauge histogram and vice versa does not count as a change for
+`changes()`. `resets()` SHOULD only be applied to counter floats and counter
+histograms, but the function still works with gauge histograms, applying
+explicit counter reset detection in this case. Furthermore, a change from
+counter histogram to gauge histogram and vice versa is counted as a reset.
+
+The `histogram_quantile()` function has a very special role as it is the only
+function that treats a specific “magic” label specially, namely the `le` label
+used by classic histograms. `histogram_quantile()` also works for native
+histograms in a similar way, but without the special role of the `le` label.
+The function keeps treating float samples in the known way, while it uses the
+new “native” way for native histogram samples.
+
+An example for a typical query for classic histograms (including `rate` and
+aggregation):
+
+```
+histogram_quantile(0.9, sum by (job, le) (rate(http_request_duration_seconds_bucket[10m])))
+```
+
+This is the corresponding query for a native histograms:
+```
+histogram_quantile(0.9, sum by (job) (rate(http_request_duration_seconds[10m])))
+```
+
+As with classic histograms, an estimation of the maximum and minimum
+observation in a histogram can be performed using 1 and 0, respectively, as the
+first parameter of `histogram_quantile`. However, native histograms with
+standard schemas enable much more useful results, not only because of the
+usually higher resolution of native histograms, but even more so because native
+histograms with standard schemas sustain the same resolution across the whole
+range of float64 numbers. With a classic histogram, the odds are that the
+maximum observation is in the +Inf bucket, so that the estimation simply
+returns the upper limit of the last bucket before the +Inf bucket. Similarly,
+the minimum observation will often be in the lowest bucket.
+
+`histogram_quantile` treats observations of value `NaN` (which SHOULD NOT
+happen, see [above](#special-cases-of-observed-values)) effectively as
+observations of `+Inf`. This follows the rationale that `NaN` is never less
+than any value that `histogram_quantile` returns and is consistent with how
+classic histograms usually treat `NaN` observations (which end up in the `+Inf`
+bucket in most implementations). (TODO: The correct implementation of this
+behavior still needs to be verified by tests.)
+
+The following functions have been introduced specifically for native
+histograms:
+
+- `histogram_avg()`
+- `histogram_count()`
+- `histogram_fraction()`
+- `histogram_sum()`
+- `histogram_stddev()`
+- `histogram_stdvar()`
+
+All these functions silently ignore float samples as input. Each function
+returns a vector of float samples.
+
+`histogram_count()` and `histogram_sum()` return the count of observations or the sum of
+observations, respectively, that are contained in a native histogram. As they are normal
+functions, their result cannot be used in a range selector. Instead of using
+sub-queries, the recommended way to calculate a rate of the count or the sum of
+observations is to first rate the histogram and then apply `histogram_count()`
+or `histogram_sum()` to the result. For example, the following query calculates
+the rate of observations (in this case corresponding to “requests per second”)
+from a native histogram:
+```
+histogram_count(rate(http_request_duration_seconds[10m]))
+```
+
+Note that the special counter reset detection for native histograms doesn't
+apply when using a sub-query on the result of `histogram_sum()`, i.e. negative
+observations may result in spurious counter resets.
+
+`histogram_avg()` returns the arithmetic average of the observed values
+in a native histogram. (This is notably different from applying the `avg`
+aggregation operator to a number of native histograms. The latter returns an
+averaged histogram.)
+
+Similarly, `histogram_stddev()` and `histogram_stdvar()` return the estimated
+standard deviation or standard variance, respectively, of the observations in a
+native histogram. For this estimation, all observations in a bucket are assumed to
+have the value of the mean of the bucket boundaries. For the zero bucket and for buckets with custom boundaries, the arithmetic mean is used. For standard exponential buckets, the geometric mean is used.
+
+`histogram_fraction(lower, upper, histogram)` returns the estimated fraction of
+observations in `histogram` between the provided boundaries, the scalar values
+`lower` and `upper`. The error of the estimation depends on the resolution of
+the underlying native histogram and how closely the provided boundaries are
+aligned with the bucket boundaries in the histogram. `+Inf` and `-Inf` are
+valid boundary values and useful to estimate the fraction of all observations
+above or below a certain value. However, observations of value `NaN` are always
+considered to be outside of the specified boundaries (even `+Inf` and `-Inf`).
+(TODO: Verify the correct implementation of this behavior with tests.) Whether
+the provided boundaries are inclusive or exclusive is only relevant if the
+provided boundaries are precisely aligned with bucket boundaries in the
+underlying native histogram. In this case, the behavior depends on the precise
+definition of the schema of the histogram.
+
+The following functions do not interact directly with sample values and
+therefore work with native histogram samples in the same way as they work with
+float samples:
+
+- `absent()`
+- `absent_over_time()`
+- `count_over_time()`
+- `info()`
+- `label_join()`
+- `label_replace()`
+- `last_over_time()`
+- `present_over_time()`
+- `sort_by_label()`
+- `sort_by_label_desc()`
+- `timestamp()`
+
+All remaining functions not mentioned in this section do _not_ work with native
+histograms. Histogram elements in the input vector are silently ignored. For
+`deriv()`, `double_exponential_smoothing()`, `predict_linear()`, and all the
+`<aggregation>_over_time()` functions not mentioned before, native histogram
+samples are removed from the input range vector. In case any series contains a
+mix of float samples and histogram samples within the range, the removal of
+histograms is flagged by an info-level annotation.
+
+### Recording rules
+
+Recording rules MAY result in native histogram values. They are stored back
+into the TSDB as during normal ingestion, including whether the histogram is a
+gauge histogram or a counter histogram. In the latter case, a counter reset
+explicitly marked by the counter reset hint is also stored, while a new counter
+reset detection is initiated during ingestion otherwise.
+
+TSDB implementations MAY convert the float histograms created by recording
+rules to integer histograms if this conversion precisely represents all the
+float values in the original histogram.
+
+### Alerting rules
+
+Alerts work as usual with native histograms. However, it is RECOMMENDED to
+avoid native histograms as output values for alerts. If native histogram
+samples are used in templates, they are [rendered in their simple text
+form](#template-expansion) (as producted by the Go `FloatHistogram.String`
+method), which is hard to read for humans.
+
+### Testing framework
+
+The PromQL testing framework has been extended so that both PromQL unit tests
+as well as rules unit tests via `promtool` can include native histograms. The
+histogram sample notation is complex and explained in the [documentation for
+rules unit
+testing](https://prometheus.io/docs/prometheus/latest/configuration/unit_testing_rules/#series).
+
+There is an alternative `load` command called `load_with_nhcb`, which converts
+classic histograms to NHCBs and loads both the float series of the classic
+histogram as well as the NHCB series resulting from the conversion.
+
+Not specific to native histograms, but very useful in their context, are the
+`eval_info` and `eval_warn` keywords that expect the evaluation to result in at
+least one info-level annotation or at least one warn-level annotation,
+respectively. It is currently neither possible to test for the presence of
+annotations of both levels nor to test for specific annotations.
+
+### Optimizations
+
+As usual, PromQL implementations MAY apply any optimizations they see fit as
+long as the behavior stays the same. Decoding native histograms can be quite
+expensive with the potentially many buckets. Similarly, deep-copying a
+histogram sample within the PromQL engine is much more expensive than copying a
+simple float sample. This creates a huge potential for optimization compared to
+a naive approach of always decoding everything and always copying everything.
+
+Prometheus currently tries to avoid needless copies (TODO: but a proper CoW
+like approach still has to be implemented, as it would be much cleaner and less
+bug prone) and skips decoding of the buckets for special cases where only the
+sum and count of observations is required.
+
+## Prometheus query API
+
+The [query API
+documentation](https://prometheus.io/docs/prometheus/latest/querying/api/#native-histograms)
+includes native histogram support. This section focuses on the parts relevant
+for native histograms and provides a bit of context not part of the API
+documentation.
+
+### Instant and range queries
+
+To return native histograms in the JSON response of instant (`query` endpoint)
+and range (`query_range` endpoint) queries, both the `vector` and `matrix`
+result type needs an extension by a new key.
+
+The `vector` result type gets a new key `histogram` at the same level as the
+existing `value` key. Both these keys are mutually exclusive, i.e. each element
+in a `vector` has either a `value` key (for a float result) or a `histogram`
+key (for a histogram result). The value of the `histogram` key is structured
+similarly to the value of the `value` key (a two-element array), with the
+difference that the string representing the float sample value is replaced by a
+specific histogram object described below.
+
+The `matrix` result type gets a new key `histograms` at the same level as the
+existing `values` key. These keys are _not_ mutually exclusive. A series may
+contain both float values and histogram values, but for a given timestamp,
+there must be only one sample, either a float or a histogram. The value of the
+`histograms` key is structured similarly to the value of the `values` key (an
+array of _n_ two-element arrays), with the difference that the strings
+representing float sample values are replaced by specific histogram objects
+described below.
+
+Note that a better naming of the keys would be `float`/`histogram` and
+`floats`/`histograms` because both float values and histogram values are
+values. The current naming has historical reasons. (In the past, there was only
+one value type, namely floats, so calling the keys simply `value` and `values`
+was the obvious choice.) The intention here is to not break existing consumers
+that do not know about native histograms.
+
+The histogram object mentioned above has the following structure:
+
+
+```
+{
+  "count": "<count_of_observations>",
+  "sum": "<sum_of_observations>",
+  "buckets": [ [ <boundary_rule>, "<left_boundary>", "<right_boundary>", "<count_in_bucket>" ], ... ]
+}
+```
+
+`count` and `sum` directly correspond to the histogram fields of the same name.
+Each bucket is represented explicitly with its boundaries and count, including
+the zero bucket. Spans and the schema are therefore not part of the response,
+and the structure of the histogram object does not depend on the used schema.
+
+The `<boundary_rule>` placeholder is an integer between 0 and 3 with the
+following meaning:
+
+* 0: “open left” (left boundary is exclusive, right boundary in inclusive)
+* 1: “open right” (left boundary is inclusive, right boundary in exclusive)
+* 2: “open both” (both boundaries are exclusive)
+* 3: “closed both” (both boundaries are inclusive)
+
+For standard schemas, positive buckets are “open left”, negative buckets are
+“open right”, and the zero bucket (with a negative left boundary and a positive
+right boundary) is “closed both”. For NHCBs, all buckets are “open left”
+(mirroring the behavior of classic histograms). Future schemas might utilize
+different boundary rules.
+
+### Metadata
+
+For the `series` endpoint, series containing native histograms are included in
+the same way as conventional series containing only floats. The endpoint does
+not provide any information what sample types are included (and in fact, _any_
+series may contain either or both sample types). Note in particular that a
+histogram exposed by a target under the name `request_duration_seconds` will
+lead to a series called `request_duration_seconds` if it is exposed and
+ingested as a native histogram, but if it is exposed and ingested as a classic
+histogram, it will lead to a set of series called
+`request_duration_seconds_sum`, `request_duration_seconds_count`, and
+`request_duration_seconds_bucket`. If the histogram is [ingested as _both_ a
+native histogram and a classic
+histogram](#scraping-both-classic-and-native-histograms), all of the series
+names above will be returned by the `series` endpoint.
+
+The target and metric metadata (endpoints `targets/metadata` and `metadata`)
+work a bit differently, as they are acting on the original name as exposed by
+the target. This means that a classic histogram called
+`request_duration_seconds` will be represented by these metadata endpoints
+only as `request_duration_seconds` (and not `request_duration_seconds_sum`,
+`request_duration_seconds_count`, or `request_duration_seconds_bucket`). A
+native histogram `request_duration_seconds` will also be represented under this
+name. Even in the case where `request_duration_seconds` is ingested as both a
+classic and a native histogram, there will be no collision as the metadata
+returned is actually the same (most notably the returned `type` will be
+`histogram`). In other words, there is currently no way of distinguishing
+native from classic histograms via the metadata endpoints alone. An additional
+look-up via the `series` endpoint is required. There are no plans to change
+this, as the existing metadata endpoints are anyway severely limited (no
+historical information, no metadata for metrics created by rules, limited
+ability to handle conflicting metadata between different targets). There are
+plans, though, to improve metadata handling in Prometheus in general. Those
+efforts will also take into account how to support native histograms properly.
+(TODO: Update as progress is made.)
+
+## Prometheus UI
+
+This section describes the rendering of histograms by Prometheus's own UI. This
+MAY be used as a guideline for third party graphing frontends.
+
+In the _Table_ view, a histogram data point is rendered graphically as a bar
+graph together with a textual representation of all the buckets with their
+lower and upper limit and the count and sum of observations. Each bar in the
+bar graph represents a bucket. The position of each bar on the _x_ axis is
+determined by the lower and upper limit of the corresponding bucket. The area
+of each bar is proportional to the population of the corresponding bucket
+(which is a core principle of rendering histograms in general).
+
+The graphical histogram allows a choice between an exponential and a linear _x_
+axis. The former is the default. It is a good fit for the standard schemas.
+(TODO: Consider linear as a default for non-exponential schemas.) Conveniently,
+all regular buckets of an exponential schema have the same width on an
+exponential _x_ axis. This means that the _y_ axis can display actual bucket
+populations without violating the above principle that the _area_ (not the
+height) of a bar is representative for the bucket population. The zero bucket
+is an exception to that. Technically, it has an infinite width. Prometheus
+simply renders it with the same width as the regular exponential buckets (which
+in turn means that the _x_ axis is not strictly exponential around the zero
+point). (TODO: How to do the rendering for non-exponential schemas.)
+
+With a linear _x_ axis, the buckets generally have varying width. Therefore,
+the _y_ axis displays the bucket population divided by its width. The
+Prometheus UI does not render values on the _y_ axis as they would be hard to
+interpret for humans anyway. The population can still be inspected in the text
+representation.
+
+In the _Graph_ view, Prometheus displays a heatmap (TODO: not yet, see below),
+which could be seen as a series of histograms over time, rotated by 90 degrees
+and encoding the bucket population as a color rather than the height of a bar.
+The typical query to render a counter-like histogram as a heatmap would be a
+`rate` query. A heatmap is an extremely powerful representation that allows
+humans to easily spot characteristics of distributions as they change over
+time.
+
+TODO: Heatmaps are not implemented yet. Instead, the UI plots just the sum of
+observations as a conventional graph. See [tracking
+issue](https://github.com/prometheus/prometheus/issues/11268). The same issue
+also discusses how to deal with the rendering of range vectors in the _Table_
+view.
+
+## Template expansion
+
+Native histograms work in template expansion. They are rendered in a text
+representation inspired by the mathematical notation of open and closed
+intervals. (This is generated by the `FloatHistogram.String` method in Go.) As
+native histograms can have a lot of buckets and bucket boundaries tend to have
+boundaries with a lot of decimal places, the representation isn't necessarily
+very readable. Use native histograms in template expansion judiciously.
+
+Example for the text representation of a float histogram:
+
+```
+{count:3493.3, sum:2.349209324e+06, [-22.62741699796952,-16):1000, [-16,-11.31370849898476):123400, [-4,-2.82842712474619):3, [-2.82842712474619,-2):3.1, [-0.01,0.01]:5.5, (0.35355339059327373,0.5]:1, (1,1.414213562373095]:3.3, (1.414213562373095,2]:4.2, (2,2.82842712474619]:0.1}
+```
+
+## Remote write & read
+
+The [protobuf specs for remote write &
+read](https://github.com/prometheus/prometheus/blob/main/prompb) were extended
+for native histograms as an experimental feature. Receivers not capable of
+processing native histograms will simply ignore the newly added fields.
+Nevertheless, Prometheus has to be configured to send native histograms via
+remote write (by setting the `send_native_histograms` remote write config
+setting to true).
+
+In [remote write v2](https://prometheus.io/docs/specs/remote_write_spec_2_0/),
+native histograms are a stable feature.
+
+It might appear tempting to convert classic histograms to NHCBs while sending
+or receiving them. However, this does not overcome the known consistency
+problems classic histograms suffer from when transmitted via remote write.
+Instead, classic histograms SHOULD be converted to NHCBs during scraping.
+Similarly, explicit OTel histograms SHOULD be converted to NHCBs during [OTLP
+ingestion](#otlp) already.
+
+TODO: A remaining possible problem with remote write is what to do if multiple
+exemplars originally ingested for the same native histogram are sent in
+different remote-write requests.
+
+## Federation
+
+Federation of native histograms works as expected, provided the federation
+scrape uses the protobuf format. A federation via OpenMetrics text format will
+be possible, at least in principle, once native histograms are supported in
+that format, but federation via protobuf is preferred for efficiency reasons
+anyway.
+
+TODO: Clarify state of federation of NHCBs. Update once OM supports NH.
+
+## OTLP
+
+The OTLP receiver built into Prometheus converts incoming OTel exponential
+histograms to Prometheus native histograms utilizing the compatibility
+described [above](#opentelemetry-interoperability). The resolution of a
+histogram using a schema (“scale” in OTel lingo) greater than 8 will be reduced
+to match schema 8. (In the unlikely case that a schema smaller than -4 is used,
+the ingestion will fail.)
+
+Explicit OTel histograms are the equivalent of Prometheus's classic histograms.
+Prometheus therefore converts them to classic histograms by default, but
+optionally offers direct conversion to NHCBs.
+
+## Pushgateway
+
+Native histogram support has been gradually added to the
+[Pushgateway](https://github.com/prometheus/pushgateway). Full support was
+reached in v1.9. The Pushgateway always has been based on the classic protobuf
+format as its internal data model, which made the necessary changes easy
+(mostly UI concerns). Combined histograms (with classic and native buckets) can
+be pushed and will be exposed as such via the `/metrics` endpoint. (However,
+the query API, which can be used to query the pushed metrics as JSON, will only
+be able to return one kind of buckets and will prefer native buckets if
+present.)
+
+## `promtool` 
+
+This section describes `promtool` commands added or changed to support native
+histograms. Commands not mentioned explicitly do not directly interact with
+native histograms and require no changes.
+
+The `promtool query ...` commands work with native histograms. See the [query
+API documentation](instant-and-range-queries) to learn about the output format.
+A new command `promtool query analyze` was specifically added to analyze
+classic and native histogram usage patterns returned by the query API.
+
+The rules unit testing via `promtool test rules` works with native histograms,
+using the format described [above](#testing-framework). 
+
+`promtool tsdb analyze` and `promtool tsdb list` work normally with native
+histograms. The `--extended` output of the former has specific sections for
+histogram chunks.
+
+`promtool tsdb dump` uses the usual text representation of native histograms
+(as produced by the Go method `FloatHistogram.String`).
+
+`promtool tsdb create-blocks-from rules` works with rules that emit native
+histograms.
+
+The `promtool promql ...` commands support all the PromQL features added for
+native histograms.
+
+While `promtool tsdb bench write` could in principle include native histograms,
+such a support is not planned at the moment.
+
+The following commands depend on the OpenMetrics text format and
+therefore cannot support native histograms as long as there is no native
+histogram support in OpenMetrics:
+
+- `promtool check metrics`
+- `promtool push metrics`
+- `promtool tsdb dump-openmetrics`
+- `promtool tsdb create-blocks-from openmetrics`
+
+TODO: Update as progress is made. See [tracking
+issue](https://github.com/prometheus/prometheus/issues/12146).
+
+## `prom2json`
+
+[`prom2json`](https://github.com/prometheus/prom2json) is a small tool that
+scrapes a Prometheus `/metrics` endpoint, converts the metrics to a bespoke
+JSON format, which it dumps to stdout. This is convenient for further
+processing with tools handling JSON, for example `jq`.
+
+`prom2json` v1.4 added support for native histograms. If a histogram in the
+exposition contains at least one bucket span, `prom2json` will replace the
+usual classic bucket in the JSON output with the buckets of the native
+histogram, following a format inspired by the [Prometheus query
+API](#prometheus-query-api).
+
+## Migration considerations
+
+When migrating from classic to native histograms, there are three important
+sources of issues to consider:
+
+1. Querying native histograms works differently from querying classic
+   histograms. In most cases, the changes are minimal and straightforward, but
+   there are tricky edge cases, which make it hard to perform a reliable
+   auto-conversion.
+2. Classic and native histograms cannot be aggregated with each other. A change
+   from classic to native histograms at a certain point in time makes it hard
+   to create dashboards that work across the transition point, and range
+   vectors that contain the transition point will inevitably be incomplete
+   (i.e. a range vector selecting classic histograms will only contain data
+   points in the earlier part of the range, and a range vector selecting native
+   histograms will only contain data points in the later part of the range).
+3. A classic histogram might be tailored to have bucket boundaries precisely at
+   the points of interest. Native histograms with a standard schema can have a
+   high resolution, but do not allow to set bucket boundaries at arbitrary
+   values. In those cases, the user experience with native histograms might
+   actually be worse.
+   
+To address (3), it is of course possible to not migrate the classic histogram
+in question and leave things as they are. Another option is to leave the
+instrumentation the same but convert classic histograms to NHCBs upon
+ingestion. This leverages the increased storage performance of native
+histograms, but still requires to address (1) and (2) in the same way as for a
+full migration to native histograms (see next paragraphs).
+
+The conservative way of addressing (1) and (2) is to allow a long transition
+period, which comes at the cost of collecting and storing classic and native
+histograms in parallel for a while.
+
+The first step is to update the instrumentation to expose classic and native
+histograms in parallel. (This step can be skipped if the plan is to stick with
+classic histogram in the instrumentation and simply convert them to NHCBs
+during scraping.)
+
+Then configure Prometheus to scrape both classic and native histograms, see
+section about [scraping both classic and native
+histograms](#scraping-both-classic-and-native-histograms) above. (If needed,
+also [activate the conversion of classic histograms to
+NHCB](#scraping-classic-histograms-as-nhcbs).)
+
+The existing queries involving classic histograms will continue to work, but
+from now on, users can start working with native histograms and start to change
+queries in dashboards, alerts, recording rules,… As already mentioned above, it
+is important to pay attention to queries with longer range vectors like
+`histogram_quantile(0.9, rate(rpc_duration_seconds[1d]))`. This query
+calculates the 90th percentile latency over the last day. Hoewever, if native
+histograms haven't been collected for at least one day, the query will only
+cover that shorter period. Thus, the query should only be used once native
+histograms have been collected for at least 1d. For a dashboard that displays
+the daily 90th percentile latency over the last month, it is tempting to craft
+a query that correctly switches from classic to native histograms at the right
+moment. While that is in principle possible, it is tricky. If feasible, the
+transition period during which classic and native histograms are collected in
+parallel, can be quite long to minimize the necessity to implement tricky
+switch-overs. For example, once classic and native histograms have been
+collected in parallel for a month, any dashboard not looking farther back than
+a month can simply be switched over from a classic histogram query to a native
+histogram query without any consideration about the right switch-over.
+
+Once there is confidence that all queries have been migrated correctly,
+configure Prometheus to only scrape native histograms (which is the “normal”
+setting). (It is also possible to incrementally remove classic histograms with
+relabel rules in the scrape config.) If everything still works, it is time to
+remove classic histograms from the instrumentation.
+
+The Grafana Mimir documentation contains [a detailed migration
+guide](https://grafana.com/docs/mimir/next/send/native-histograms/#migrate-from-classic-histograms)
+following the same philosophy as described in this section.
diff --git a/docs/specs/om/index.md b/docs/specs/om/index.md
new file mode 100644
index 00000000..8cab4af1
--- /dev/null
+++ b/docs/specs/om/index.md
@@ -0,0 +1,4 @@
+---
+title: "OpenMetrics"
+sort_rank: 3
+---
diff --git a/docs/specs/om/open_metrics_spec.md b/docs/specs/om/open_metrics_spec.md
new file mode 100644
index 00000000..8ed717aa
--- /dev/null
+++ b/docs/specs/om/open_metrics_spec.md
@@ -0,0 +1,1186 @@
+---
+title: "1.0"
+title_prefix: "OpenMetrics 1.0"
+sort_rank: 5
+
+author:
+- role: editor
+  ins: R. Hartmann
+  name: Richard Hartmann
+  organization: Grafana Labs
+  email: richih@richih.org
+- ins: B. Kochie
+  name: Ben Kochie
+  organization: GitLab
+  email: ben@nerp.net
+- ins: B. Brazil
+  name: Brian Brazil
+  organization: Robust Perception
+  email: brian.brazil@gmail.com
+- ins: R. Skillington
+  name: Rob Skillington
+  organization: Chronosphere
+  email: rob.skillington@gmail.com
+---
+
+# OpenMetrics
+
+- Version: 1.0
+- Status: Published
+- Date: March 2022
+- Authors: Richard Hartmann, Ben Kochie, Brian Brazil, Rob Skillington
+
+Created in 2012, Prometheus has been the default for cloud-native observability since 2015. A central part of Prometheus' design is its text metric exposition format, called the Prometheus exposition format 0.0.4, stable since 2014. In this format, special care has been taken to make it easy to generate, to ingest, and to understand by humans. As of 2020, there are more than 700 publicly listed exporters, an unknown number of unlisted exporters, and thousands of native library integrations using this format. Dozens of ingestors from various projects and companies support consuming it.
+
+With OpenMetrics, we are cleaning up and tightening the specification with the express purpose of bringing it into IETF. We are documenting a working standard with wide and organic adoption while introducing minimal, largely backwards-compatible, and well-considered changes. As of 2020, dozens of exporters, integrations, and ingestors use and preferentially negotiate OpenMetrics already.
+
+Given the wide adoption and significant coordination requirements in the ecosystem, sweeping changes to either the Prometheus exposition format 0.0.4 or OpenMetrics 1.0 are considered out of scope.
+
+> NOTE: OpenMetrics 2.0 development is in progress. Read [here](https://github.com/prometheus/OpenMetrics/issues/276) on how to join the Prometheus OM 2.0 work group.
+
+## Overview
+
+Metrics are a specific kind of telemetry data. They represent a snapshot of the current state for a set of data. They are distinct from logs or events, which focus on records or information about individual events.
+
+OpenMetrics is primarily a wire format, independent of any particular transport for that format. The format is expected to be consumed on a regular basis and to be meaningful over successive expositions.
+
+Implementers MUST expose metrics in the OpenMetrics text format in response to a simple HTTP GET request to a documented URL for a given process or device. This endpoint SHOULD be called "/metrics". Implementers MAY also expose OpenMetrics formatted metrics in other ways, such as by regularly pushing metric sets to an operator-configured endpoint over HTTP.
+
+### Metrics and Time Series
+
+This standard expresses all system states as numerical values; counts, current values, enumerations, and boolean states being common examples. Contrary to metrics, singular events occur at a specific time. Metrics tend to aggregate data temporally. While this can lose information, the reduction in overhead is an engineering trade-off commonly chosen in many modern monitoring systems.
+
+Time series are a record of changing information over time. While time series can support arbitrary strings or binary data, only numeric data is in scope for this RFC.
+
+Common examples of metric time series would be network interface counters, device temperatures, BGP connection states, and alert states.
+
+## Data Model
+
+This section MUST be read together with the ABNF section. In case of disagreements between the two, the  ABNF's restrictions MUST take precedence. This reduces repetition as the text wire format MUST be supported.
+
+### Data Types
+
+#### Values
+
+Metric values in OpenMetrics MUST be either floating points or integers. Note that ingestors of the format MAY only support float64. The non-real values NaN, +Inf and -Inf MUST be supported. NaN MUST NOT be considered a missing value, but it MAY be used to signal a division by zero.
+
+##### Booleans
+
+Boolean values MUST follow `1==true`, `0==false`.
+
+#### Timestamps
+
+Timestamps MUST be Unix Epoch in seconds. Negative timestamps MAY be used.
+
+#### Strings
+
+Strings MUST only consist of valid UTF-8 characters and MAY be zero length. NULL (ASCII 0x0) MUST be supported.
+
+#### Label
+
+Labels are key-value pairs consisting of strings.
+
+Label names beginning with underscores are RESERVED and MUST NOT be used unless specified by this standard. Label names MUST follow the restrictions in the ABNF section.
+
+Empty label values SHOULD be treated as if the label was not present.
+
+#### LabelSet
+
+A LabelSet MUST consist of Labels and MAY be empty. Label names MUST be unique within a LabelSet.
+
+#### MetricPoint
+
+Each MetricPoint consists of a set of values, depending on the MetricFamily type.
+
+#### Exemplars
+
+Exemplars are references to data outside of the MetricSet. A common use case are IDs of program traces.
+
+Exemplars MUST consist of a LabelSet and a value, and MAY have a timestamp. They MAY each be different from the MetricPoints' LabelSet and timestamp.
+
+The combined length of the label names and values of an Exemplar's LabelSet MUST NOT exceed 128 UTF-8 character code points. Other characters in the text rendering of an exemplar such as `",=` are not included in this limit for implementation simplicity and for consistency between the text and proto formats.
+
+Ingestors MAY discard exemplars.
+
+#### Metric
+
+Metrics are defined by a unique LabelSet within a MetricFamily. Metrics MUST contain a list of one or more MetricPoints. Metrics with the same name for a given MetricFamily SHOULD have the same set of label names in their LabelSet.
+
+MetricPoints SHOULD NOT have explicit timestamps.
+
+If more than one MetricPoint is exposed for a Metric, then its MetricPoints MUST have monotonically increasing timestamps.
+
+#### MetricFamily
+
+A MetricFamily MAY have zero or more Metrics. A MetricFamily MUST have a name, HELP, TYPE, and UNIT metadata. Every Metric within a MetricFamily MUST have a unique LabelSet.
+
+##### Name
+
+MetricFamily names are a string and MUST be unique within a MetricSet. Names SHOULD be in snake_case. Metric names MUST follow the restrictions in the ABNF section.
+
+Colons in MetricFamily names are RESERVED to signal that the MetricFamily is the result of a calculation or aggregation of a general purpose monitoring system.
+
+MetricFamily names beginning with underscores are RESERVED and MUST NOT be used unless specified by this standard.
+
+###### Suffixes
+
+The name of a MetricFamily MUST NOT result in a potential clash for sample metric names as per the ABNF with another MetricFamily in the Text Format within a MetricSet. An example would be a gauge called "foo_created" as a counter called "foo" could create a "foo_created" in the text format.
+
+Exposers SHOULD avoid names that could be confused with the suffixes that text format sample metric names use.
+
+* Suffixes for the respective types are:
+* Counter: `_total`, `_created`
+* Summary: `_count`, `_sum`, `_created`, `` (empty)
+* Histogram: `_count`, `_sum`, `_bucket`, `_created`
+* GaugeHistogram: `_gcount`, `_gsum`, `_bucket`
+* Info: `_info`
+* Gauge: `` (empty)
+* StateSet: `` (empty)
+* Unknown: `` (empty)
+
+##### Type
+
+Type specifies the MetricFamily type. Valid values are "unknown", "gauge", "counter", "stateset", "info", "histogram", "gaugehistogram", and "summary".
+
+##### Unit
+
+Unit specifies MetricFamily units. If non-empty, it MUST be a suffix of the MetricFamily name separated by an underscore. Be aware that further generation rules might make it an infix in the text format.
+
+##### Help
+
+Help is a string and SHOULD be non-empty. It is used to give a brief description of the MetricFamily for human consumption and SHOULD be short enough to be used as a tooltip.
+
+##### MetricSet
+
+A MetricSet is the top level object exposed by OpenMetrics. It MUST consist of MetricFamilies and MAY be empty.
+
+Each MetricFamily name MUST be unique. The same label name and value SHOULD NOT appear on every Metric within a MetricSet.
+
+There is no specific ordering of MetricFamilies required within a MetricSet. An exposer MAY make an exposition easier to read for humans, for example sort alphabetically if the performance tradeoff makes sense.
+
+If present, an Info MetricFamily called "target" per the "Supporting target metadata in both push-based and pull-based systems" section below SHOULD be first.
+
+### Metric Types
+
+#### Gauge
+
+Gauges are current measurements, such as bytes of memory currently used or the number of items in a queue. For gauges the absolute value is what is of interest to a user.
+
+A MetricPoint in a Metric with the type gauge MUST have a single value.
+
+Gauges MAY increase, decrease, or stay constant over time. Even if they only ever go in one direction, they might still be gauges and not counters. The size of a log file would usually only increase, a resource might decrease, and the limit of a queue size may be constant.
+
+A gauge MAY be used to encode an enum where the enum has many states and changes over time, it is the most efficient but least user friendly.
+
+#### Counter
+
+Counters measure discrete events. Common examples are the number of HTTP requests received, CPU seconds spent, or bytes sent. For counters how quickly they are increasing over time is what is of interest to a user.
+
+A MetricPoint in a Metric with the type Counter MUST have one value called Total. A Total is a non-NaN and MUST be monotonically non-decreasing over time, starting from 0.
+
+A MetricPoint in a Metric with the type Counter SHOULD have a Timestamp value called Created. This can help ingestors discern between new metrics and long-running ones it did not see before.
+
+A MetricPoint in a Metric's Counter's Total MAY reset to 0. If present, the corresponding Created time MUST also be set to the timestamp of the reset.
+
+A MetricPoint in a Metric's Counter's Total MAY have an exemplar.
+
+#### StateSet
+
+StateSets represent a series of related boolean values, also called a bitset. If ENUMs need to be encoded this MAY be done via StateSet.
+
+A point of a StateSet metric MAY contain multiple states and MUST contain one boolean per State. States have a name which are Strings.
+
+A StateSet Metric's LabelSet MUST NOT have a label name which is the same as the name of its MetricFamily.
+
+If encoded as a StateSet, ENUMs MUST have exactly one Boolean which is true within a MetricPoint.
+
+This is suitable where the enum value changes over time, and the number of States isn't much more than a handful.
+
+<!---
+# EDITOR’S NOTE: This might be better as Consideration
+-->
+
+MetricFamilies of type StateSets MUST have an empty Unit string.
+
+#### Info
+
+Info metrics are used to expose textual information which SHOULD NOT change during process lifetime. Common examples are an application's version, revision control commit, and the version of a compiler.
+
+A MetricPoint of an Info Metric contains a LabelSet. An Info MetricPoint's LabelSet MUST NOT have a label name which is the same as the name of a label of the LabelSet of its Metric.
+
+Info MAY be used to encode ENUMs whose values do not change over time, such as the type of a network interface.
+
+MetricFamilies of type Info MUST have an empty Unit string.
+
+#### Histogram
+
+Histograms measure distributions of discrete events. Common examples are the latency of HTTP requests, function runtimes, or I/O request sizes.
+
+A Histogram MetricPoint MUST contain at least one bucket, and SHOULD contain Sum, and Created values. Every bucket MUST have a threshold and a value.
+
+Histogram MetricPoints MUST have one bucket with an +Inf threshold. Buckets MUST be cumulative. As an example for a metric representing request latency in seconds its values for buckets with thresholds 1, 2, 3, and +Inf MUST follow value_1 <= value_2 <= value_3 <= value_+Inf. If ten requests took 1 second each, the values of the 1, 2, 3, and +Inf buckets MUST equal 10.
+
+The +Inf bucket counts all requests. If present, the Sum value MUST equal the Sum of all the measured event values. Bucket thresholds within a MetricPoint MUST be unique.
+
+Semantically, Sum, and buckets values are counters so MUST NOT be NaN or negative.
+Negative threshold buckets MAY be used, but then the Histogram MetricPoint MUST NOT contain a sum value as it would no longer be a counter semantically. Bucket thresholds MUST NOT equal NaN. Count and bucket values MUST be integers.
+
+A Histogram MetricPoint SHOULD have a Timestamp value called Created. This can help ingestors discern between new metrics and long-running ones it did not see before.
+
+A Histogram's Metric's LabelSet MUST NOT have a "le" label name.
+
+Bucket values MAY have exemplars. Buckets are cumulative to allow monitoring systems to drop any non-+Inf bucket for performance/anti-denial-of-service reasons in a way that loses granularity but is still a valid Histogram.
+
+<!---
+# EDITOR’S NOTE: The second sentence is a consideration, it can be moved if needed
+-->
+
+Each bucket covers the values less and or equal to it, and the value of the exemplar MUST be within this range. Exemplars SHOULD be put into the bucket with the highest value. A bucket MUST NOT have more than one exemplar.
+
+#### GaugeHistogram
+
+GaugeHistograms measure current distributions. Common examples are how long items have been waiting in a queue, or size of the requests in a queue.
+
+A GaugeHistogram MetricPoint MUST have one bucket with an +Inf threshold, and SHOULD contain a Gsum value. Every bucket MUST have a threshold and a value.
+
+The buckets for a GaugeHistogram follow all the same rules as for a Histogram.
+
+The bucket and Gsum of a GaugeHistogram are conceptually gauges, however bucket values MUST NOT be negative or NaN. If negative threshold buckets are present, then sum MAY be negative. Gsum MUST NOT be NaN. Bucket values MUST be integers.
+
+A GaugeHistogram's Metric's LabelSet MUST NOT have a "le" label name.
+
+Bucket values can have exemplars.
+
+Each bucket covers the values less and or equal to it, and the value of the exemplar MUST be within this range. Exemplars SHOULD be put into the bucket with the highest value. A bucket MUST NOT have more than one exemplar.
+
+#### Summary
+
+Summaries also measure distributions of discrete events and MAY be used when Histograms are too expensive and/or an average event size is sufficient.
+
+They MAY also be used for backwards compatibility, because some existing instrumentation libraries expose precomputed quantiles and do not support Histograms. Precomputed quantiles SHOULD NOT be used, because quantiles are not aggregatable and the user often can not deduce what timeframe they cover.
+
+A Summary MetricPoint MAY consist of a Count, Sum, Created, and a set of quantiles.
+
+Semantically, Count and Sum values are counters so MUST NOT be NaN or negative.
+Count MUST be an integer.
+
+A MetricPoint in a Metric with the type Summary which contains Count or Sum values SHOULD have a Timestamp value called Created. This can help ingestors discern between new metrics and long-running ones it did not see before. Created MUST NOT relate to the collection period of quantile values.
+
+Quantiles are a map from a quantile to a value. An example is a quantile 0.95 with value 0.2 in a metric called myapp_http_request_duration_seconds which means that the 95th percentile latency is 200ms over an unknown timeframe. If there are no events in the relevant timeframe, the value for a quantile MUST be NaN.
+A Quantile's Metric's LabelSet MUST NOT have "quantile" label name.
+Quantiles MUST be between 0 and 1 inclusive. Quantile values MUST NOT be negative. Quantile values SHOULD represent the recent values. Commonly this would be over the last 5-10 minutes.
+
+#### Unknown
+
+Unknown SHOULD NOT be used. Unknown MAY be used when it is impossible to determine the types of individual metrics from 3rd party systems.
+
+A point in a metric with the unknown type MUST have a single value.
+
+# Data transmission & wire formats
+
+The text wire format MUST be supported and is the default. The protobuf wire format MAY be supported and MUST ONLY be used after negotiation.
+
+The OpenMetrics formats are Regular Chomsky Grammars, making writing quick and small parsers possible.
+The text format compresses well, and protobuf is already binary and efficiently encoded.
+
+Partial or invalid expositions MUST be considered erroneous in their entirety.
+
+### Protocol Negotiation
+
+All ingestor implementations MUST be able to ingest data secured with TLS 1.2 or later. All exposers SHOULD be able to emit data secured with TLS 1.2 or later. ingestor implementations SHOULD be able to ingest data from HTTP without TLS. All implementations SHOULD use TLS to transmit data.
+
+Negotiation of what version of the OpenMetrics format to use is out-of-band. For example for pull-based exposition over HTTP standard HTTP content type negotiation is used, and MUST default to the oldest version of the standard (i.e. 1.0.0) if no newer version is requested.
+
+Push-based negotiation is inherently more complex, as the exposer typically initiates the connection. Producers MUST use the oldest version of the standard (i.e. 1.0.0) unless requested otherwise by the ingestor.
+
+### Text format
+
+#### ABNF
+
+ABNF as per RFC 5234
+
+<!---
+# EDITOR’S NOTE: Should we update to RFC 7405, in particular the case insensitive bits?
+-->
+
+"exposition" is the top level token of the ABNF.
+
+```abnf
+exposition = metricset HASH SP eof [ LF ]
+
+metricset = *metricfamily
+
+metricfamily = *metric-descriptor *metric
+
+metric-descriptor = HASH SP type SP metricname SP metric-type LF
+metric-descriptor =/ HASH SP help SP metricname SP escaped-string LF
+metric-descriptor =/ HASH SP unit SP metricname SP *metricname-char LF
+
+metric = *sample
+
+metric-type = counter / gauge / histogram / gaugehistogram / stateset
+metric-type =/ info / summary / unknown
+
+sample = metricname [labels] SP number [SP timestamp] [exemplar] LF
+
+exemplar = SP HASH SP labels SP number [SP timestamp]
+
+labels = "{" [label *(COMMA label)] "}"
+
+label = label-name EQ DQUOTE escaped-string DQUOTE
+
+number = realnumber
+; Case insensitive
+number =/ [SIGN] ("inf" / "infinity")
+number =/ "nan"
+
+timestamp = realnumber
+
+; Not 100% sure this captures all float corner cases.
+; Leading 0s explicitly okay
+realnumber = [SIGN] 1*DIGIT
+realnumber =/ [SIGN] 1*DIGIT ["." *DIGIT] [ "e" [SIGN] 1*DIGIT ]
+realnumber =/ [SIGN] *DIGIT "." 1*DIGIT [ "e" [SIGN] 1*DIGIT ]
+
+
+; RFC 5234 is case insensitive.
+; Uppercase
+eof = %d69.79.70
+type = %d84.89.80.69
+help = %d72.69.76.80
+unit = %d85.78.73.84
+; Lowercase
+counter = %d99.111.117.110.116.101.114
+gauge = %d103.97.117.103.101
+histogram = %d104.105.115.116.111.103.114.97.109
+gaugehistogram = gauge histogram
+stateset = %d115.116.97.116.101.115.101.116
+info = %d105.110.102.111
+summary = %d115.117.109.109.97.114.121
+unknown = %d117.110.107.110.111.119.110
+
+BS = "\"
+EQ = "="
+COMMA = ","
+HASH = "#"
+SIGN = "-" / "+"
+
+metricname = metricname-initial-char 0*metricname-char
+
+metricname-char = metricname-initial-char / DIGIT
+metricname-initial-char = ALPHA / "_" / ":"
+
+label-name = label-name-initial-char *label-name-char
+
+label-name-char = label-name-initial-char / DIGIT
+label-name-initial-char = ALPHA / "_"
+
+escaped-string = *escaped-char
+
+escaped-char = normal-char
+escaped-char =/ BS ("n" / DQUOTE / BS)
+escaped-char =/ BS normal-char
+
+; Any unicode character, except newline, double quote, and backslash
+normal-char = %x00-09 / %x0B-21 / %x23-5B / %x5D-D7FF / %xE000-10FFFF
+```
+
+#### Overall Structure
+
+UTF-8 MUST be used. Byte order markers (BOMs) MUST NOT be used. As an important reminder for implementers, byte 0 is valid UTF-8 while, for example, byte 255 is not.
+
+The content type MUST be:
+
+``` 
+application/openmetrics-text; version=1.0.0; charset=utf-8
+``` 
+
+Line endings MUST be signalled with line feed (\n) and MUST NOT contain carriage returns (\r). Expositions MUST end with EOF and SHOULD end with `EOF\n`.
+
+An example of a complete exposition:
+
+```
+# TYPE acme_http_router_request_seconds summary
+# UNIT acme_http_router_request_seconds seconds
+# HELP acme_http_router_request_seconds Latency though all of ACME's HTTP request router.
+acme_http_router_request_seconds_sum{path="/api/v1",method="GET"} 9036.32
+acme_http_router_request_seconds_count{path="/api/v1",method="GET"} 807283.0
+acme_http_router_request_seconds_created{path="/api/v1",method="GET"} 1605281325.0
+acme_http_router_request_seconds_sum{path="/api/v2",method="POST"} 479.3
+acme_http_router_request_seconds_count{path="/api/v2",method="POST"} 34.0
+acme_http_router_request_seconds_created{path="/api/v2",method="POST"} 1605281325.0
+# TYPE go_goroutines gauge
+# HELP go_goroutines Number of goroutines that currently exist.
+go_goroutines 69
+# TYPE process_cpu_seconds counter
+# UNIT process_cpu_seconds seconds
+# HELP process_cpu_seconds Total user and system CPU time spent in seconds.
+process_cpu_seconds_total 4.20072246e+06
+# EOF
+```
+
+##### Escaping
+
+Where the ABNF notes escaping, the following escaping MUST be applied
+Line feed, `\n` (0x0A) -> literally `\\n` (Bytecode 0x5c 0x6e)
+Double quotes -> `\\"` (Bytecode 0x5c 0x22)
+Backslash -> `\\\\` (Bytecode 0x5c 0x5c)
+
+A double backslash SHOULD be used to represent a backslash character.
+A single backslash SHOULD NOT be used for undefined escape sequences.
+As an example, `\\\\a` is equivalent and preferable to `\\a`.
+
+##### Numbers
+
+Integer numbers MUST NOT have a decimal point. Examples are `23`, `0042`, and `1341298465647914`.
+
+Floating point numbers MUST be represented either with a decimal point or using scientific notation. Examples are `8903.123421` and `1.89e-7`. Floating point numbers MUST fit within the range of a 64-bit floating point value as defined by IEEE 754, but MAY require so many bits in the mantissa that results in lost precision. This MAY be used to encode nanosecond resolution timestamps.
+
+Arbitrary integer and floating point rendering of numbers MUST NOT be used for "quantile" and "le" label values as in section "Canonical Numbers". They MAY be used anywhere else numbers are used.
+
+###### Considerations: Canonical Numbers
+
+Numbers in the "le" label values of histograms and "quantile" label values of summary metrics are special in that they're label values, and label values are intended to be opaque. As end users will likely directly interact with these string values, and as many monitoring systems lack the ability to deal with them as first-class numbers, it would be beneficial if a given number had the exact same text representation.
+
+Consistency is highly desirable, but real world implementations of languages and their runtimes make mandating this impractical. The most important common quantiles are 0.5, 0.95, 0.9, 0.99, 0.999 and bucket values representing values from a millisecond up to 10.0 seconds, because those cover cases like latency SLAs and Apdex for typical web services. Powers of ten are covered to try to ensure that the switch between fixed point and exponential rendering is consistent as this varies across runtimes. The target rendering is equivalent to the default Go rendering of float64 values (i.e. %g), with a .0 appended in case there is no decimal point or exponent to make clear that they are floats.
+
+Exposers MUST produce output for positive infinity as +Inf.
+
+Exposers SHOULD produce output for the values 0.0 up to 10.0 in 0.001 increments in line with the following examples:
+0.0 0.001 0.002 0.01 0.1 0.9 0.95 0.99 0.999 1.0 1.7 10.0
+
+Exposers SHOULD produce output for the values 1e-10 up to 1e+10 in powers of ten in line with the following examples:
+1e-10 1e-09 1e-05 0.0001 0.1 1.0 100000.0 1e+06 1e+10
+
+Parsers MUST NOT reject inputs which are outside of the canonical values merely because they are not consistent with the canonical values. For example 1.1e-4 must not be rejected, even though it is not the consistent rendering of 0.00011.
+
+Exposers SHOULD follow these patterns for non-canonical numbers, and the intention is by adjusting the rendering algorithm to be consistent for these values that the vast majority of other values will also have consistent rendering. Exposers using only a few particular le/quantile values could also hardcode. In languages such as C where a minimal floating point rendering algorithm such as Grisu3 is not readily available, exposers MAY use a different rendering.
+
+A warning to implementers in C and other languages that share its printf implementation: The standard precision of %f, %e and %g is only six significant digits. 17 significant digits are required for full precision, e.g. `printf("%.17g", d)`.
+
+##### Timestamps
+
+Timestamps SHOULD NOT use exponential float rendering for timestamps if nanosecond precision is needed as rendering of a float64 does not have sufficient precision, e.g. `1604676851.123456789`.
+
+#### MetricFamily
+
+There MUST NOT be an explicit separator between MetricFamilies. The next MetricFamily MUST be signalled with either metadata or a new sample metric name which cannot be part of the previous MetricFamily.
+
+
+MetricFamilies MUST NOT be interleaved.
+
+##### MetricFamily metadata
+
+There are four pieces of metadata: The MetricFamily name, TYPE, UNIT and HELP.  An example of the metadata for a counter Metric called foo is:
+
+```
+# TYPE foo counter
+```
+
+If no TYPE is exposed, the MetricFamily MUST be of type Unknown.
+
+If a unit is specified it MUST be provided in a UNIT metadata line. In addition, an underscore and the unit MUST be the suffix of the MetricFamily name.
+
+A valid example for a foo_seconds metric with a unit of "seconds":
+
+```
+# TYPE foo_seconds counter
+# UNIT foo_seconds seconds
+```
+
+An invalid example, where the unit is not a suffix on the name:
+
+```
+# TYPE foo counter
+# UNIT foo seconds
+```
+
+It is also valid to have:
+
+```
+# TYPE foo_seconds counter
+```
+
+If the unit is known it SHOULD be provided.
+
+The value of a UNIT or HELP line MAY be empty. This MUST be treated as if no metadata line for the MetricFamily existed.
+
+```
+# TYPE foo_seconds counter
+# UNIT foo_seconds seconds
+# HELP foo_seconds Some text and \n some \" escaping
+```
+
+There MUST NOT be more than one of each type of metadata line for a MetricFamily. The ordering SHOULD be TYPE, UNIT, HELP.
+
+Aside from this metadata and the EOF line at the end of the message, you MUST NOT expose lines beginning with a #.
+
+##### Metric
+
+Metrics MUST NOT be interleaved.
+
+See the example in "Text format -> MetricPoint".
+Labels
+A sample without labels or a timestamp and the value 0 MUST be rendered either like:
+
+```
+bar_seconds_count 0
+```
+
+or like
+
+```
+bar_seconds_count{} 0
+```
+
+Label values MAY be any valid UTF-8 value, so escaping MUST be applied as per the ABNF. A valid example with two labels:
+
+```
+bar_seconds_count{a="x",b="escaping\" example \n "} 0
+```
+
+The rendering of values for a MetricPoint can include additional labels (e.g. the "le" label for a Histogram type), which MUST be rendered in the same way as a Metric's own LabelSet.
+
+#### MetricPoint
+
+MetricPoints MUST NOT be interleaved.
+
+A correct example where there were multiple MetricPoints and Samples within a MetricFamily would be:
+
+```
+# TYPE foo_seconds summary
+# UNIT foo_seconds seconds
+foo_seconds_count{a="bb"} 0 123
+foo_seconds_sum{a="bb"} 0 123
+foo_seconds_count{a="bb"} 0 456
+foo_seconds_sum{a="bb"} 0 456
+foo_seconds_count{a="ccc"} 0 123
+foo_seconds_sum{a="ccc"} 0 123
+foo_seconds_count{a="ccc"} 0 456
+foo_seconds_sum{a="ccc"} 0 456
+```
+
+An incorrect example where Metrics are interleaved:
+
+```
+# TYPE foo_seconds summary
+# UNIT foo_seconds seconds
+foo_seconds_count{a="bb"} 0 123
+foo_seconds_count{a="ccc"} 0 123
+foo_seconds_count{a="bb"} 0 456
+foo_seconds_count{a="ccc"} 0 456
+```
+
+An incorrect example where MetricPoints are interleaved:
+
+```
+# TYPE foo_seconds summary
+# UNIT foo_seconds seconds
+foo_seconds_count{a="bb"} 0 123
+foo_seconds_count{a="bb"} 0 456
+foo_seconds_sum{a="bb"} 0 123
+foo_seconds_sum{a="bb"} 0 456
+```
+
+#### Metric types
+
+##### Gauge
+
+The Sample MetricName for the value of a MetricPoint for a MetricFamily of type Gauge MUST NOT have a suffix.
+
+An example MetricFamily with a Metric with no labels and a MetricPoint with no timestamp:
+
+```
+# TYPE foo gauge
+foo 17.0
+```
+
+An example of a MetricFamily with two Metrics with a label and MetricPoints with no timestamp:
+
+```
+# TYPE foo gauge
+foo{a="bb"} 17.0
+foo{a="ccc"} 17.0
+```
+
+An example of a MetricFamily with no Metrics:
+
+```
+# TYPE foo gauge
+```
+
+An example with a Metric with a  label and a MetricPoint with a timestamp:
+
+```
+# TYPE foo gauge
+foo{a="b"} 17.0 1520879607.789
+```
+
+An example with a Metric with no labels and MetricPoint with a timestamp:
+
+```
+# TYPE foo gauge
+foo 17.0 1520879607.789
+```
+
+An example with a Metric with no labels and two MetricPoints with timestamps:
+
+```
+# TYPE foo gauge
+foo 17.0 123
+foo 18.0 456
+```
+
+##### Counter
+
+The MetricPoint's Total Value Sample MetricName MUST have the suffix `_total`. If present the MetricPoint's Created Value Sample MetricName MUST have the suffix `_created`.
+
+An example with a Metric with no labels, and a MetricPoint with no timestamp and no created:
+
+```
+# TYPE foo counter
+foo_total 17.0
+```
+
+An example with a Metric with no labels, and a MetricPoint with a timestamp and no created:
+
+```
+# TYPE foo counter
+foo_total 17.0 1520879607.789
+```
+
+An example with a Metric with no labels, and a MetricPoint with no timestamp and a created:
+
+```
+# TYPE foo counter
+foo_total 17.0
+foo_created 1520430000.123
+```
+
+An example with a Metric with no labels, and a MetricPoint with a timestamp and a created:
+
+```
+# TYPE foo counter
+foo_total 17.0 1520879607.789
+foo_created 1520430000.123 1520879607.789
+```
+
+Exemplars MAY be attached to the MetricPoint's Total sample.
+
+##### StateSet
+
+The Sample MetricName for the value of a MetricPoint for a MetricFamily of type StateSet MUST NOT have a suffix.
+
+StateSets MUST have one sample per State in the MetricPoint. Each State's sample MUST have a label with the MetricFamily name as the label name and the State name as the label value. The State sample's value MUST be 1 if the State is true and MUST be 0 if the State is false.
+
+An example with the states "a", "bb", and "ccc" in which only the value bb is enabled and the metric name is foo:
+
+```
+# TYPE foo stateset
+foo{foo="a"} 0
+foo{foo="bb"} 1
+foo{foo="ccc"} 0
+```
+
+An example of an "entity" label on the Metric:
+
+```
+# TYPE foo stateset
+foo{entity="controller",foo="a"} 1.0
+foo{entity="controller",foo="bb"} 0.0
+foo{entity="controller",foo="ccc"} 0.0
+foo{entity="replica",foo="a"} 1.0
+foo{entity="replica",foo="bb"} 0.0
+foo{entity="replica",foo="ccc"} 1.0
+```
+
+##### Info
+
+The Sample MetricName for the value of a MetricPoint for a MetricFamily of type Info MUST have the suffix `_info`. The Sample value MUST always be 1.
+
+An example of a Metric with no labels, and one MetricPoint value with "name" and "version" labels:
+
+```
+# TYPE foo info
+foo_info{name="pretty name",version="8.2.7"} 1
+```
+
+An example of a Metric with label "entity" and one MetricPoint value with “name” and “version” labels:
+
+```
+# TYPE foo info
+foo_info{entity="controller",name="pretty name",version="8.2.7"} 1.0
+foo_info{entity="replica",name="prettier name",version="8.1.9"} 1.0
+```
+
+Metric labels and MetricPoint value labels MAY be in any order.
+
+##### Summary
+
+If present, the MetricPoint's Sum Value Sample MetricName MUST have the suffix `_sum`. If present, the MetricPoint's Count Value Sample MetricName MUST have the suffix `_count`. If present, the MetricPoint's Created Value Sample MetricName MUST have the suffix `_created`. If present, the MetricPoint's Quantile Values MUST specify the quantile measured using a label with a label name of "quantile" and with a label value of the quantile measured.
+
+An example of a Metric with no labels and a MetricPoint with Sum, Count and Created values:
+
+```
+# TYPE foo summary
+foo_count 17.0
+foo_sum 324789.3
+foo_created 1520430000.123
+```
+
+An example of a Metric with no labels and a MetricPoint with two quantiles:
+
+```
+# TYPE foo summary
+foo{quantile="0.95"} 123.7
+foo{quantile="0.99"} 150.0
+```
+
+Quantiles MAY be in any order.
+
+##### Histogram
+
+The MetricPoint's Bucket Values Sample MetricNames MUST have the suffix `_bucket`. If present, the MetricPoint's Sum Value Sample MetricName MUST have the suffix `_sum`. If present, the MetricPoint's Created Value Sample MetricName MUST have the suffix `_created`.
+If and only if a Sum Value is present in a MetricPoint, then the MetricPoint's +Inf Bucket value MUST also appear in a Sample with a MetricName with the suffix "_count".
+
+Buckets MUST be sorted in number increasing order of "le", and the value of the "le" label MUST follow the rules for Canonical Numbers.
+
+An example of a Metric with no labels and a MetricPoint with Sum, Count, and Created values, and with 12 buckets. A wide and atypical but valid variety of “le” values is shown on purpose:
+
+```
+# TYPE foo histogram
+foo_bucket{le="0.0"} 0
+foo_bucket{le="1e-05"} 0
+foo_bucket{le="0.0001"} 5
+foo_bucket{le="0.1"} 8
+foo_bucket{le="1.0"} 10
+foo_bucket{le="10.0"} 11
+foo_bucket{le="100000.0"} 11
+foo_bucket{le="1e+06"} 15
+foo_bucket{le="1e+23"} 16
+foo_bucket{le="1.1e+23"} 17
+foo_bucket{le="+Inf"} 17
+foo_count 17
+foo_sum 324789.3
+foo_created 1520430000.123
+```
+
+###### Exemplars
+
+Exemplars without Labels MUST represent an empty LabelSet as {}.
+
+An example of Exemplars showcasing several valid cases:
+The "0.01" bucket has no Exemplar. The 0.1 bucket has an Exemplar with no Labels. The 1 bucket has an Exemplar with one Label. The 10 bucket has an Exemplar with a Label and a timestamp. In practice all buckets SHOULD have the same style of Exemplars.
+
+```
+# TYPE foo histogram
+foo_bucket{le="0.01"} 0
+foo_bucket{le="0.1"} 8 # {} 0.054
+foo_bucket{le="1"} 11 # {trace_id="KOO5S4vxi0o"} 0.67
+foo_bucket{le="10"} 17 # {trace_id="oHg5SJYRHA0"} 9.8 1520879607.789
+foo_bucket{le="+Inf"} 17
+foo_count 17
+foo_sum 324789.3
+foo_created  1520430000.123
+```
+
+##### GaugeHistogram
+
+The MetricPoint's Bucket Values Sample MetricNames MUST have the suffix `_bucket`. If present, the MetricPoint's Sum Value Sample MetricName MUST have the suffix `_gsum`.
+If and only if a Sum Value is present in a MetricPoint, then the MetricPoint's +Inf Bucket value MUST also appear in a Sample with a MetricName with the suffix `_gcount`.
+
+Buckets MUST be sorted in number increasing order of "le", and the value of the "le" label MUST follow the rules for Canonical Numbers.
+
+An example of a Metric with no labels, and one MetricPoint value with no Exemplar with no Exemplars in the buckets:
+
+```
+# TYPE foo gaugehistogram
+foo_bucket{le="0.01"} 20.0
+foo_bucket{le="0.1"} 25.0
+foo_bucket{le="1"} 34.0
+foo_bucket{le="10"} 34.0
+foo_bucket{le="+Inf"} 42.0
+foo_gcount 42.0
+foo_gsum 3289.3
+```
+
+##### Unknown
+
+The sample metric name for the value of the MetricPoint for a MetricFamily of type Unknown MUST NOT have a suffix.
+
+An example with a Metric with no labels and a MetricPoint with no timestamp:
+
+```
+# TYPE foo unknown
+foo 42.23
+```
+
+### Protobuf format
+
+#### Overall Structure
+
+Protobuf messages MUST be encoded in binary and MUST have `application/openmetrics-protobuf; version=1.0.0` as their content type.
+
+All payloads MUST be a single binary encoded MetricSet message, as defined by the OpenMetrics protobuf schema.
+
+##### Version
+
+The protobuf format MUST follow the proto3 version of the protocol buffer language.
+
+##### Strings
+
+All string fields MUST be UTF-8 encoded.
+
+##### Timestamps
+
+Timestamp representations in the OpenMetrics protobuf schema MUST follow the published google.protobuf.Timestamp [timestamp] message. The timestamp message MUST be in Unix epoch seconds as an int64 and a non-negative fraction of a second at nanosecond resolution as an int32 that counts forward from the seconds timestamp component. It MUST be within 0 to 999,999,999 inclusive.
+
+#### Protobuf schema
+
+Protobuf schema is currently available [here](https://github.com/prometheus/OpenMetrics/blob/3bb328ab04d26b25ac548d851619f90d15090e5d/proto/openmetrics_data_model.proto).
+
+> NOTE: Prometheus and ecosystem does not support OpenMetrics protobuf schema, instead it uses similar `io.prometheus.client` [format](https://github.com/prometheus/client_model/blob/master/io/prometheus/client/metrics.proto). Discussions about the future of the protobuf schema in OpenMetrics 2.0 [are in progress](https://github.com/prometheus/OpenMetrics/issues/296).
+
+## Design Considerations
+
+### Scope
+
+OpenMetrics is intended to provide telemetry for online systems. It runs over protocols which do not provide hard or soft real time guarantees, so it can not make any real time guarantees itself. Latency and jitter properties of OpenMetrics are as imprecise as the underlying network, operating systems, CPUs, and the like. It is sufficiently accurate for aggregations to be used as a basis for decision-making, but not to reflect individual events.
+
+Systems of all sizes should be supported, from applications that receive a few requests an hour up to monitoring bandwidth usage on a 400Gb network port. Aggregation and analysis of transmitted telemetry should be possible over arbitrary time periods.
+
+It is intended to transport snapshots of state at the time of data transmission at a regular cadence.
+
+#### Out of scope
+
+How ingestors discover which exposers exist, and vice-versa, is out of scope for and thus not defined in this standard.
+
+### Extensions and Improvements
+
+This first version of OpenMetrics is based upon well established and de facto standard Prometheus text format 0.0.4, deliberately without adding major syntactic or semantic extensions, or optimisations on top of it. For example no attempt has been made to make the text representation of Histogram buckets more compact, relying on compression in the underlying stack to deal with their repetitive nature.
+
+This is a deliberate choice, so that the standard can take advantage of the adoption and momentum of the existing user base. This ensures a relatively easy transition from the Prometheus text format 0.0.4.
+
+It also ensures that there is a basic standard which is easy to implement. This can be built upon in future versions of the standard. The intention is that future versions of the standard will always require support for this 1.0 version, both syntactically and semantically.
+
+We want to allow monitoring systems to get usable information from an OpenMetrics exposition without undue burden. If one were to strip away all metadata and structure and just look at an OpenMetrics exposition as an unordered set of samples that should be usable on its own. As such, there are also no opaque binary types, such as sketches or t-digests which could not be expressed as a mix of gauges and counters as they would require custom parsing and handling.
+
+This principle is applied consistently throughout the standard. For example a MetricFamily's unit is duplicated in the name so that the unit is available for systems that don't understand the unit metadata. The "le" label is a normal label value, rather than getting its own special syntax, so that ingestors don't have to add special histogram handling code to ingest them. As a further example, there are no composite data types. For example, there is no geolocation type for latitude/longitude as this can be done with separate gauge metrics.
+
+### Units and Base Units
+
+For consistency across systems and to avoid confusion, units are largely based on SI base units. Base units include seconds, bytes, joules, grams, meters, ratios, volts, amperes, and celsius. Units should be provided where they are applicable.
+
+For example, having all duration metrics in seconds, there is no risk of having to guess whether a given metric is nanoseconds, microseconds, milliseconds, seconds, minutes, hours, days or weeks nor having to deal with mixed units. By choosing unprefixed units, we avoid situations like ones in which kilomilliseconds were the result of emergent behaviour of complex systems.
+
+As values can be floating point, sub-base-unit precision is built into the standard.
+
+Similarly, mixing bits and bytes is confusing, so bytes are chosen as the base. While Kelvin is a better base unit in theory, in practice most existing hardware exposes Celsius. Kilograms are the SI base unit, however the kilo prefix is problematic so grams are chosen as the base unit.
+
+While base units SHOULD be used in all possible cases, Kelvin is a well-established unit which MAY be used instead of Celsius for use cases such as color or black body temperatures where a comparison between a Celsius and Kelvin metric are unlikely.
+
+Ratios are the base unit, not percentages. Where possible, raw data in the form of gauges or counters for the given numerator and denominator should be exposed. This has better mathematical properties for analysis and aggregation in the ingestors.
+
+Decibels are not a base unit as firstly, deci is a SI prefix and secondly, bels are logarithmic. To expose signal/energy/power ratios exposing the ratio directly would be better, or better still the raw power/energy if possible. Floating point exponents are more than sufficient to cover even extreme scientific uses. An electron volt (~1e-19 J) all the way up to the energy emitted by a supernova (~1e44 J) is 63 orders of magnitude, and a 64-bit floating point number can cover over 2000 orders of magnitude.
+
+If non-base units can not be avoided and conversion is not feasible, the actual unit should still be included in the metric name for clarity. For example, joule is the base unit for both energy and power, as watts can be expressed as a counter with a joule unit. In practice a given 3rd party system may only expose watts, so a gauge expressed in watts would be the only realistic choice in that case.
+
+Not all MetricFamilies have units. For example a count of HTTP requests wouldn't have a unit. Technically the unit would be HTTP requests, but in that sense the entire MetricFamily name is the unit. Going to that extreme would not be useful. The possibility of having good axes on graphs in downstream systems for human consumption should always be kept in mind.
+
+### Statelessness
+
+The wire format defined by OpenMetrics is stateless across expositions. What information has been exposed before MUST have no impact on future expositions. Each exposition is a self-contained snapshot of the current state of the exposer.
+
+The same self-contained exposition MUST be provided to existing and new ingestors.
+
+A core design choice is that exposers MUST NOT exclude a metric merely because it has had no recent changes, or observations. An exposer must not make any assumptions about how often ingestors are consuming expositions.
+
+### Exposition Across Time and Metric Evolution
+
+Metrics are most useful when their evolution over time can be analysed, so accordingly expositions must make sense over time. Thus, it is not sufficient for one single exposition on its own to be useful and valid. Some changes to metric semantics can also break downstream users.
+
+Parsers commonly optimize by caching previous results. Thus, changing the order in which labels are exposed across expositions SHOULD be avoided even though it is technically not breaking This also tends to make writing unit tests for exposition easier.
+
+Metrics and samples SHOULD NOT appear and disappear from exposition to exposition, for example a counter is only useful if it has history. In principle, a given Metric should be present in exposition from when the process starts until the process terminates. It is often not possible to know in advance what Metrics a MetricFamily will have over the lifetime of a given process (e.g. a label value of a latency histogram is a HTTP path, which is provided by an end user at runtime), but once a counter-like Metric is exposed it should continue to be exposed until the process terminates. That a counter is not getting increments doesn't invalidate that it still has its current value. There are cases where it may make sense to stop exposing a given Metric; see the section on Missing Data.
+
+In general changing a MetricFamily's type, or adding or removing a label from its Metrics will be breaking to ingestors.
+
+A notable exception is that adding a label to the value of an Info MetricPoints is not breaking. This is so that you can add additional information to an existing Info MetricFamily where it makes sense to be, rather than being forced to create a brand new info metric with an additional label value. ingestor systems should ensure that they are resilient to such additions.
+
+Changing a MetricFamily's Help is not breaking. For values where it is possible, switching between floats and ints is not breaking. Adding a new state to a stateset is not breaking. Adding unit metadata where it doesn't change the metric name is not breaking.
+
+Histogram buckets SHOULD NOT change from exposition to exposition, as this is likely to both cause performance issues and break ingestors and cause. Similarly all expositions from any consistent binary and environment of an application SHOULD have the same buckets for a given Histogram MetricFamily, so that they can be aggregated by all ingestors without ingestors having to implement histogram merging logic for heterogeneous buckets.
+An exception might be occasional manual changes to buckets which are considered breaking, but may be a valid tradeoff when performance characteristics change due to a new software release.
+
+Even if changes are not technically breaking, they still carry a cost. For example frequent changes may cause performance issues for ingestors. A Help string that varies from exposition to exposition may cause each Help value to be stored. Frequently switching between int and float values could prevent efficient compression.
+
+### NaN
+
+NaN is a number like any other in OpenMetrics, usually resulting from a division by zero such as for a summary quantile if there have been no observations recently. NaN does not have any special meaning in OpenMetrics, and in particular MUST NOT be used as a marker for missing or otherwise bad data.
+
+### Missing Data
+
+There are valid cases when data stops being present. For example a filesystem can be unmounted and thus its Gauge Metric for free disk space no longer exists. There is no special marker or signal for this situation. Subsequent expositions simply do not include this Metric.
+
+### Exposition Performance
+
+Metrics are only useful if they can be collected in reasonable time frames. Metrics that take minutes to expose are not considered useful.
+
+As a rule of thumb, exposition SHOULD take no more than a second.
+
+Metrics from legacy systems serialized through OpenMetrics may take longer. For this reason, no hard performance assumptions can be made.
+
+Exposition SHOULD be of the most recent state. For example, a thread serving the exposition request SHOULD NOT rely on cached values, to the extent it is able to bypass any such caching
+
+### Concurrency
+
+For high availability and ad-hoc access a common approach is to have multiple ingestors. To support this, concurrent expositions MUST be supported. All BCPs for concurrent systems SHOULD be followed, common pitfalls include deadlocks, race conditions, and overly-coarse grained locking preventing expositions progressing concurrently.
+
+### Metric Naming and Namespaces
+
+<!---
+# EDITOR’S NOTE:  This section might be good for a BCP paper.
+-->
+
+We aim for a balance between understandability, avoiding clashes, and succinctness in the naming of metrics and label names. Names are separated through underscores, so metric names end up being in “snake_case”.
+
+To take an example "http_request_seconds" is succinct but would clash between large numbers of applications, and it's also unclear exactly what this metric is measuring. For example, it might be before or after auth middleware in a complex system.
+
+Metric names should indicate what piece of code they come from. So a company called A Company Manufacturing Everything might prefix all metrics in their code with "acme_", and if they had a HTTP router library measuring latency it might have a metric such as "acme_http_router_request_seconds" with a Help string indicating that it is the overall latency.
+
+It is not the aim to prevent all potential clashes across all applications, as that would require heavy handed solutions such as a global registry of metric namespaces or very long namespaces based on DNS. Rather the aim is to keep to a lightweight informal approach, so that for a given application that it is very unlikely that there is clash across its constituent libraries.
+
+Across a given deployment of a monitoring system as a whole the aim is that clashes where the same metric name means different things are uncommon. For example acme_http_router_request_seconds might end up in hundreds of different applications developed by A Company Manufacturing Everything, which is normal. If Another Corporation Making Entities also used the metric name acme_http_router_request_seconds in their HTTP router that's also fine. If applications from both companies were being monitored by the same monitoring system the clash is undesirable, but acceptable as no application is trying to expose both names and no one target is trying to (incorrectly) expose the same metric name twice. If an application wished to contain both My Example Company's and Mega Exciting Company's HTTP router libraries that would be a problem, and one of the metric names would need to be changed somehow.
+
+As a corollary, the more public a library is the better namespaced its metric names should be to reduce the risk of such scenarios arising. acme_ is not a bad choice for internal use within a company, but these companies might for example choose the prefixes acmeverything_ or acorpme_ for code shared outside their company.
+
+After namespacing by company or organisation, namespacing and naming should continue by library/subsystem/application fractally as needed such as the http_router library above. The goal is that if you are familiar with the overall structure of a codebase, you could make a good guess at where the instrumentation for a given metric is given its metric name.
+
+For a common very well known existing piece of software, the name of the software itself may be sufficiently distinguishing. For example bind_ is probably sufficient for the DNS software, even though isc_bind_ would be the more usual naming.
+
+
+Metric names prefixed by scrape_ are used by ingestors to attach information related to individual expositions, so should not be exposed by applications directly. Metrics that have already been consumed and passed through a general purpose monitoring system may include such metric names on subsequent expositions.
+If an exposer wishes to provide information about an individual exposition, a metric prefix such as myexposer_scrape_ may be used. A common example is a gauge myexposer_scrape_duration_seconds for how long that exposition took from the exposer's standpoint.
+
+Within the Prometheus ecosystem a set of per-process metrics has emerged that are consistent across all implementations, prefixed with process_. For example for open file ulimits the MetricFamiles process_open_fds and process_max_fds gauges provide both the current and maximum value. (These names are legacy, if such metrics were defined today they would be more likely called process_fds_open and process_fds_limit). In general it is very challengings to get names with identical semantics like this, which is why different instrumentation should use different names.
+
+
+Avoid redundancy in metric names. Avoid substrings like "metric", "timer", "stats", "counter", "total", "float64" and so on - by virtue of being a metric with a given type (and possibly unit) exposed via OpenMetrics information like this is already implied so should not be included explicitly. You should not include label names of a metric in the metric name for the same reasons, and in addition subsequent aggregation of the metric by a monitoring system could make such information incorrect.
+
+
+Avoid including implementation details from other layers of your monitoring system in the metric names contained in your instrumentation. For example a MetricFamily name should not contain the string "openmetrics" merely because it happens to be currently exposed via OpenMetrics somewhere, or "prometheus" merely because your current monitoring system is Prometheus.
+
+### Label Namespacing
+
+For label names no explicit namespacing by company or library is recommended, namespacing from the metric name is sufficient for this when considered against the length increase of the label name. However some minimal care to avoid common clashes is recommended.
+
+There are label names such as region, zone, cluster, availability_zone, az, datacenter, dc, owner, customer, stage, service, team, job, instance, environment, and env which are highly likely to clash with labels used to identify targets which a general purpose monitoring system may add. Try to avoid them, adding minimal namespacing may be appropriate in these cases.
+
+The label name "type" is highly generic and should be avoided. For example for HTTP-related metrics "method" would be a better label name if you were distinguishing between GET, POST, and PUT requests.
+
+While there is metadata about metric names such as HELP, TYPE and UNIT there is no metadata for label names. This is as it would be bloating the format for little gain. Out-of-band documentation is one way for exposers could present this their ingestors.
+
+### Metric Names versus Labels
+
+There are situations in which both using multiple Metrics within a MetricFamily or multiple MetricFamilies seem to make sense. Summing or averaging aMetricFamily should be meaningful even if it's not always useful. For example, mixing voltage and fan speed is not meaningful.
+
+As a reminder, OpenMetrics is built with the assumption that ingestors can process and perform aggregations on data.
+
+Exposing a total sum alongside other metrics is wrong, as this would result in double-counting upon aggregation in downstream ingestors.
+
+```
+wrong_metric{label="a"} 1
+wrong_metric{label="b"} 6
+wrong_metric{label="total"} 7
+```
+
+Labels of a Metric should be to the minimum needed to ensure uniqueness as every extra label is one more that users need to consider when determining what Labels to work with downstream. Labels which could be applied many MetricFamilies are candidates for being moved into _info metrics similar to database {{normalization}}. If virtually all users of a Metric could be expected to want the additional label, it may be a better trade-off to add it to all MetricFamilies. For example if you had a MetricFamily relating to different SQL statements where uniqueness was provided by a label containing a hash of the full SQL statements, it would be okay to have another label with the first 500 characters of the SQL statement for human readability.
+
+Experience has shown that downstream ingestors find it easier to work with separate total and failure MetricFamiles rather than using {result="success"} and {result="failure"} Labels within one MetricFamily. Also it is usually better to expose separate read & write and send & receive MetricFamiles as full duplex systems are common and downstream ingestors are more likely to care about those values separately than in aggregate.
+
+All of this is not as easy as it may sound. It's an area where experience and engineering trade-offs by domain-specific experts in both exposition and the exposed system are required to find a good balance.
+Metric and Label Name Characters
+
+OpenMetrics builds on the existing widely adopted Prometheus text exposition format and the ecosystem which formed around it. Backwards compatibility is a core design goal. Expanding or contracting the set of characters that are supported by the Prometheus text format would work against that goal. Breaking backwards compatibility would have wider implications than just the wire format. In particular, the query languages created or adopted to work with data transmitted within the Prometheus ecosystem rely on these precise character sets. Label values support full UTF-8, so the format can represent multi-lingual metrics.
+
+### Types of Metadata
+
+Metadata can come from different sources. Over the years, two main sources have emerged. While they are often functionally the same, it helps in understanding to talk about their conceptual differences.
+
+"Target metadata" is metadata commonly external to an exposer.  Common examples would be data coming from service discovery, a CMDB, or similar, like information about a datacenter region, if a service is part of a particular deployment, or production or testing. This can be  achieved by either the exposer or the ingestor adding labels to all Metrics that capture this metadata. Doing this through the ingestor is preferred as it is more flexible and carries less overhead. On flexibility, the hardware maintenance team might care about which server rack a machine is located in, whereas the database team using that same machine might care that it contains replica number 2 of the production database. On overhead, hardcoding or configuring this information needs an additional distribution path.
+
+"Exposer metadata" is coming from within an exposer. Common examples would be software version, compiler version, or Git commit SHA.
+
+#### Supporting Target Metadata in both Push-based and Pull-based Systems
+
+In push-based consumption, it is typical for the exposer to provide the relevant target metadata to the ingestor. In pull-based consumption the push-based approach could be taken, but more typically the ingestor already knows the metadata of the target a-priori such as from a machine database or service discovery system, and associates it with the metrics as it consumes the exposition.
+
+OpenMetrics is stateless and provides the same exposition to all ingestors, which is in conflict with the push-style approach. In addition the push-style approach would break pull-style ingestors, as unwanted metadata would be exposed.
+
+One approach would be for push-style ingestors to provide target metadata based on operator configuration out-of-band, for example as a HTTP header. While this would transport target metadata for push-style ingestors, and is not precluded by this standard, it has the disadvantage that even though pull-style ingestors should use their own target metadata, it is still often useful to have access to the metadata the exposer itself is aware of.
+
+The preferred solution is to provide this target metadata as part of the exposition, but in a way that does not impact on the exposition as a whole. Info MetricFamilies are designed for this. An exposer may include an Info MetricFamily called "target" with a single Metric with no labels with the metadata. An example in the text format might be:
+
+```
+# TYPE target info
+# HELP target Target metadata
+target_info{env="prod",hostname="myhost",datacenter="sdc",region="europe",owner="frontend"} 1
+```
+
+When an exposer is providing this metric for this purpose it SHOULD be first in the exposition. This is for efficiency, so that ingestors relying on it for target metadata don't have to buffer up the rest of the exposition before applying business logic based on its content.
+
+Exposers MUST NOT add target metadata labels to all Metrics from an exposition, unless explicitly configured for a specific ingestor. Exposers MUST NOT prefix MetricFamily names or otherwise vary MetricFamily names based on target metadata.
+Generally, the same Label should not appear on every Metric of an exposition, but there are rare cases where this can be the result of emergent behaviour. Similarly all MetricFamily names from an exposer may happen to share a prefix in very small expositions. For example an application written in the Go language by A Company Manufacturing Everything would likely include metrics with prefixes of acme_, go_, process_, and metric prefixes from any 3rd party libraries in use.
+
+Exposers can expose exposer metadata as Info MetricFamilies.
+
+The above discussion is in the context of individual exposers. An exposition from a general purpose monitoring system may contain metrics from many individual targets, and thus may expose multiple target info Metrics. The metrics may already have had target metadata added to them as labels as part of ingestion. The metric names MUST NOT be varied based on target metadata. For example it would be incorrect for all metrics to end up being prefixed with staging_ even if they all originated from targets in a staging environment).
+
+### Client Calculations and Derived Metrics
+
+Exposers should leave any math or calculation up to ingestors. A notable exception is the  Summary quantile which is unfortunately required for backwards compatibility. Exposition should be of raw values which are useful over arbitrary time periods.
+
+As an example, you should not expose a gauge with the average rate of increase of a counter over the last 5 minutes. Letting the ingestor calculate the increase over the data points they have consumed across expositions has better mathematical properties and is more resilient to scrape failures.
+
+Another example is the average event size of a histogram/summary. Exposing the average rate of increase of a counter since an application started or since a Metric was created has the problems from the earlier example and it also prevents aggregation.
+
+Standard deviation also falls into this category. Exposing a sum of squares as a counter would be the correct approach. It was not included in this standard as a Histogram value because 64bit floating point precision is not sufficient for this to work in practice. Due to the squaring only half the 53bit mantissa would be available in terms of precision. As an example a histogram observing 10k events per second would lose precision within 2 hours. Using 64bit integers would be no better due to the loss of the floating decimal point because a nanosecond resolution integer typically tracking events of a second in length would overflow after 19 observations.
+This design decision can be revisited when 128bit floating point numbers become common.
+
+Another example is to avoid exposing a request failure ratio, exposing separate counters for failed requests and total requests instead.
+
+### Number Types
+
+For a counter that was incremented a million times per second it would take over a century to begin to lose precision with a float64 as it has a 53 bit mantissa. Yet a 100 Gbps network interface's octet throughput precision could begin to be lost with a float64 within around 20 hours. While losing 1KB of precision over the course of years for a 100Gbps network interface is unlikely to be a problem in practice, int64s are an option for integral data with such a high throughput.
+
+Summary quantiles must be float64, as they are estimates and thus fundamentally inaccurate.
+
+### Exposing Timestamps
+
+One of the core assumptions of OpenMetrics is that exposers expose the most up to date snapshot of what they're exposing.
+
+While there are limited use cases for attaching timestamps to exposed data, these are very uncommon. Data which had timestamps previously attached, in particular data which has been ingested into a general purpose monitoring system may carry timestamps. Live or raw data should not carry timestamps. It is valid to expose the same metric MetricPoint value with the same timestamp across expositions, however it is invalid to do so if the underlying metric is now missing.
+
+Time synchronization is a hard problem and data should be internally consistent in each system. As such, ingestors should be able to attach the current timestamp from their perspective to data rather than based on the system time of the exposer device.
+
+With timestamped metrics it is not generally possible to detect the time when a Metric went missing across expositions. However with non-timestamped metrics the ingestor can use its own timestamp from the exposition where the Metric is no longer present.
+
+All of this is to say that, in general, MetricPoint timestamps should not be exposed, as it should be up to the ingestor to apply their own timestamps to samples they ingest.
+
+#### Tracking When Metrics Last Changed
+
+Presume you had a counter my_counter which was initialized, and then later incremented by 1 at time 123. This would be a correct way to expose it in the text format:
+
+```
+# HELP my_counter Good increment example
+# TYPE my_counter counter
+my_counter_total 1
+```
+
+As per the parent section, ingestors should be free to attach their own timestamps, so this would be incorrect:
+
+```
+# HELP my_counter Bad increment example
+# TYPE my_counter counter
+my_counter_total 1 123
+```
+
+
+In case the specific time of the last change of a counter matters, this would be the correct way:
+
+```
+# HELP my_counter Good increment example
+# TYPE my_counter counter
+my_counter_total 1
+# HELP my_counter_last_increment_timestamp_seconds When my_counter was last incremented
+# TYPE my_counter_last_increment_timestamp_seconds gauge
+# UNIT my_counter_last_increment_timestamp_seconds seconds
+my_counter_last_increment_timestamp_seconds 123
+```
+
+By putting the timestamp of last change into its own Gauge as a value, ingestors are free to attach their own timestamp to both Metrics.
+
+
+Experience has shown that exposing absolute timestamps (epoch is considered absolute here) is more robust than time elapsed, seconds since, or similar. In either case, they would be gauges. For example:
+
+```
+# TYPE my_boot_time_seconds gauge
+# HELP my_boot_time_seconds Boot time of the machine
+# UNIT my_boot_time_seconds seconds
+my_boot_time_seconds 1256060124
+```
+
+Is better than:
+
+```
+# TYPE my_time_since_boot_seconds gauge
+# HELP my_time_since_boot_seconds Time elapsed since machine booted
+# UNIT my_time_since_boot_seconds seconds
+my_time_since_boot_seconds 123
+```
+
+Conversely, there are no best practice restrictions on exemplars timestamps.
+Keep in mind that due to race conditions or time not being perfectly synced across devices, that an exemplar timestamp may appear to be slightly in the future relative to a ingestor's system clock or other metrics from the same exposition. Similarly it is possible that a "_created" for a MetricPoint could appear to be slightly after an exemplar or sample timestamp for that same MetricPoint.
+
+Keep in mind that there are monitoring systems in common use which support everything from nanosecond to second resolution, so having two MetricPoints that have the same timestamp when truncated to second resolution may cause an apparent duplicate in the ingestor. In this case the MetricPoint with the earliest timestamp MUST be used.
+
+### Thresholds
+
+Exposing desired bounds for a system can make sense, but proper care needs to be taken. For values which are universally true, it can make sense to emit Gauge metrics for such thresholds. For example, a data center HVAC system knows the current measurements, the setpoints, and the alert setpoints. It has a globally valid and correct view of the desired system state.
+As a counter example, some thresholds can change with scale, deployment model, or over time. A certain amount of CPU usage may be acceptable in one setting and undesirable in another. Aggregation of values can further change acceptable values. In such a system, exposing bounds could be counter-productive.
+
+For example the maximum size of a queue may be exposed alongside the number of items currently in the queue like:
+
+```
+# HELP acme_notifications_queue_capacity The capacity of the notifications queue.
+# TYPE acme_notifications_queue_capacity gauge
+acme_notifications_queue_capacity 10000
+# HELP acme_notifications_queue_length The number of notifications in the queue.
+# TYPE acme_notifications_queue_length gauge
+acme_notifications_queue_length 42
+```
+
+### Size Limits
+
+This standard does not prescribe any particular limits on the number of samples exposed by a single exposition, the number of labels that may be present, the number of states a stateset may have, the number of labels in an info value, or metric name/label name/label value/help character limits.
+
+Specific limits run the risk of preventing reasonable use cases, for example while a given exposition may have an appropriate number of labels after passing through a general purpose monitoring system a few target labels may have been added that would push it over the limit. Specific limits on numbers such as these would also not capture where the real costs are for general purpose monitoring systems. These guidelines are thus both to aid exposers and ingestors in understanding what is reasonable.
+
+On the other hand, an exposition which is too large in some dimension could cause significant performance problems compared to the benefit of the metrics exposed. Thus some guidelines on the size of any single exposition would be useful.
+
+ingestors may choose to impose limits themselves, for in particular to prevent attacks or outages. Still, ingestors need to consider reasonable use cases and try not to  disproportionately impact them. If any single value/metric/exposition exceeds such limits then the whole exposition must be rejected.
+
+In general there are three things which impact the performance of a general purpose monitoring system ingestion time series data: the number of unique time series, the number of samples over time in those series, and the number of unique strings such as metric names, label names, label values, and HELP. ingestors can control how often they ingest, so that aspect does not need further consideration.
+
+The number of unique time series is roughly equivalent to the number of non-comment lines in the text format. As of 2020, 10 million time series in total is considered a large amount and is commonly the order of magnitude of the upper bound of any single-instance ingestor. Any single exposition should not go above 10k time series without due diligence. One common consideration is horizontal scaling: What happens if you scale your instance count by 1-2 orders of magnitude? Having a thousand top-of-rack switches in a single deployment would have been hard to imagine 30 years ago. If a target was a singleton (e.g. exposing metrics relating to an entire cluster) then several hundred thousand time series may be reasonable. It is not the number of unique MetricFamilies or the cardinality of individual labels/buckets/statesets that matters, it is the total order of magnitude of the time series. 1,000 gauges with one Metric each are as costly as a single gauge with 1,000 Metrics.
+
+If all targets of a particular type are exposing the same set of time series, then each additional targets' strings poses no incremental cost to most reasonably modern monitoring systems. If however each target has unique strings, there is such a cost. As an extreme example, a single 10k character metric name used by many targets is on its own very unlikely to be a problem in practice. To the contrary, a thousand targets each exposing a unique 36 character UUID is over three times as expensive as that single 10k character metric name in terms of strings to be stored assuming modern approaches. In addition, if these strings change over time older strings will still need to be stored for at least some time, incurring extra cost. Assuming the 10 million times series from the last paragraph, 100MB of unique strings per hour might indicate a use case for then the use case may be more like event logging, not metric time series.
+
+There is a hard 128 UTF-8 character limit on exemplar length, to prevent misuse of the feature for tracing span data and other event logging.
+
+## Security
+
+Implementors MAY choose to offer authentication, authorization, and accounting; if they so choose, this SHOULD be handled outside of OpenMetrics.
+
+All exposer implementations SHOULD be able to secure their HTTP traffic with TLS 1.2 or later.
+If an exposer implementation does not support encryption, operators SHOULD use reverse proxies, firewalling, and/or ACLs where feasible.
+
+Metric exposition should be independent of production services exposed to end users; as such, having a /metrics endpoint on ports like TCP/80, TCP/443, TCP/8080, and TCP/8443 is generally discouraged for publicly exposed services using OpenMetrics.
+
+## IANA
+
+While currently most implementations of the Prometheus exposition format are using non-IANA-registered ports from an informal registry at {{PrometheusPorts}}, OpenMetrics can be found on a well-defined port.
+
+The port assigned by IANA for clients exposing data is <9099 requested for historical consistency>.
+
+If more than one metric endpoint needs to be reachable at a common IP address and port, operators might consider using a reverse proxy that communicates with exposers over localhost addresses. To ease multiplexing, endpoints SHOULD carry their own name in their path, i.e. `/node_exporter/metrics`. Expositions SHOULD NOT be combined into one exposition, for the reasons covered under "Supporting target metadata in both push-based and pull-based systems" and to allow for independent ingestion without a single point of failure.
+
+OpenMetrics would like to register two MIME types, `application/openmetrics-text` and `application/openmetrics-proto`.
+
+<!---
+# EDITOR’S NOTE: `application/openmetrics-text` is in active use since 2018, `application/openmetrics-proto` is not yet in active use.
+-->
+
+<!---
+# EDITOR’S NOTE: We would like to thank Sumeer Bhola, but kramdown 2.x does not support `Contributor:` any more so we will add this by hand once consensus has been achieved.
+-->
diff --git a/docs/specs/om/open_metrics_spec_2_0.md b/docs/specs/om/open_metrics_spec_2_0.md
new file mode 100644
index 00000000..bc8b9838
--- /dev/null
+++ b/docs/specs/om/open_metrics_spec_2_0.md
@@ -0,0 +1,1188 @@
+---
+title: "2.0"
+title_prefix: "OpenMetrics 2.0"
+sort_rank: 10
+
+is_hidden: true
+
+author:
+- role: editor
+  ins: R. Hartmann
+  name: Richard Hartmann
+  organization: Grafana Labs
+  email: richih@richih.org
+- ins: B. Kochie
+  name: Ben Kochie
+  organization: GitLab
+  email: ben@nerp.net
+- ins: B. Brazil
+  name: Brian Brazil
+  organization: Robust Perception
+  email: brian.brazil@gmail.com
+- ins: R. Skillington
+  name: Rob Skillington
+  organization: Chronosphere
+  email: rob.skillington@gmail.com
+---
+
+# OpenMetrics
+
+- Version: 2.0
+- Status: Draft
+- Date: TBD
+- Authors: Richard Hartmann, Ben Kochie, Brian Brazil, Rob Skillington
+
+Created in 2012, Prometheus has been the default for cloud-native observability since 2015. A central part of Prometheus' design is its text metric exposition format, called the Prometheus exposition format 0.0.4, stable since 2014. In this format, special care has been taken to make it easy to generate, to ingest, and to understand by humans. As of 2020, there are more than 700 publicly listed exporters, an unknown number of unlisted exporters, and thousands of native library integrations using this format. Dozens of ingestors from various projects and companies support consuming it.
+
+With OpenMetrics, we are cleaning up and tightening the specification with the express purpose of bringing it into IETF. We are documenting a working standard with wide and organic adoption while introducing minimal, largely backwards-compatible, and well-considered changes. As of 2020, dozens of exporters, integrations, and ingestors use and preferentially negotiate OpenMetrics already.
+
+Given the wide adoption and significant coordination requirements in the ecosystem, sweeping changes to either the Prometheus exposition format 0.0.4 or OpenMetrics 1.0 are considered out of scope.
+
+> NOTE: this document is an early draft, major changes expected. Read [here](https://github.com/prometheus/OpenMetrics/issues/276) on how to join the Prometheus OM 2.0 work group.
+
+## Overview
+
+Metrics are a specific kind of telemetry data. They represent a snapshot of the current state for a set of data. They are distinct from logs or events, which focus on records or information about individual events.
+
+OpenMetrics is primarily a wire format, independent of any particular transport for that format. The format is expected to be consumed on a regular basis and to be meaningful over successive expositions.
+
+Implementers MUST expose metrics in the OpenMetrics text format in response to a simple HTTP GET request to a documented URL for a given process or device. This endpoint SHOULD be called "/metrics". Implementers MAY also expose OpenMetrics formatted metrics in other ways, such as by regularly pushing metric sets to an operator-configured endpoint over HTTP.
+
+### Metrics and Time Series
+
+This standard expresses all system states as numerical values; counts, current values, enumerations, and boolean states being common examples. Contrary to metrics, singular events occur at a specific time. Metrics tend to aggregate data temporally. While this can lose information, the reduction in overhead is an engineering trade-off commonly chosen in many modern monitoring systems.
+
+Time series are a record of changing information over time. While time series can support arbitrary strings or binary data, only numeric data is in scope for this RFC.
+
+Common examples of metric time series would be network interface counters, device temperatures, BGP connection states, and alert states.
+
+## Data Model
+
+This section MUST be read together with the ABNF section. In case of disagreements between the two, the  ABNF's restrictions MUST take precedence. This reduces repetition as the text wire format MUST be supported.
+
+### Data Types
+
+#### Values
+
+Metric values in OpenMetrics MUST be either floating points or integers. Note that ingestors of the format MAY only support float64. The non-real values NaN, +Inf and -Inf MUST be supported. NaN MUST NOT be considered a missing value, but it MAY be used to signal a division by zero.
+
+##### Booleans
+
+Boolean values MUST follow `1==true`, `0==false`.
+
+#### Timestamps
+
+Timestamps MUST be Unix Epoch in seconds. Negative timestamps MAY be used.
+
+#### Strings
+
+Strings MUST only consist of valid UTF-8 characters and MAY be zero length. NULL (ASCII 0x0) MUST be supported.
+
+#### Label
+
+Labels are key-value pairs consisting of strings.
+
+Label names beginning with underscores are RESERVED and MUST NOT be used unless specified by this standard. Label names MUST follow the restrictions in the ABNF section.
+
+Empty label values SHOULD be treated as if the label was not present.
+
+#### LabelSet
+
+A LabelSet MUST consist of Labels and MAY be empty. Label names MUST be unique within a LabelSet.
+
+#### MetricPoint
+
+Each MetricPoint consists of a set of values, depending on the MetricFamily type.
+
+#### Exemplars
+
+Exemplars are references to data outside of the MetricSet. A common use case are IDs of program traces.
+
+Exemplars MUST consist of a LabelSet and a value, and MAY have a timestamp. They MAY each be different from the MetricPoints' LabelSet and timestamp.
+
+The combined length of the label names and values of an Exemplar's LabelSet MUST NOT exceed 128 UTF-8 character code points. Other characters in the text rendering of an exemplar such as `",=` are not included in this limit for implementation simplicity and for consistency between the text and proto formats.
+
+Ingestors MAY discard exemplars.
+
+#### Metric
+
+Metrics are defined by a unique LabelSet within a MetricFamily. Metrics MUST contain a list of one or more MetricPoints. Metrics with the same name for a given MetricFamily SHOULD have the same set of label names in their LabelSet.
+
+MetricPoints SHOULD NOT have explicit timestamps.
+
+If more than one MetricPoint is exposed for a Metric, then its MetricPoints MUST have monotonically increasing timestamps.
+
+#### MetricFamily
+
+A MetricFamily MAY have zero or more Metrics. A MetricFamily MUST have a name, HELP, TYPE, and UNIT metadata. Every Metric within a MetricFamily MUST have a unique LabelSet.
+
+##### Name
+
+MetricFamily names are a string and MUST be unique within a MetricSet. Names SHOULD be in snake_case. Metric names MUST follow the restrictions in the ABNF section.
+
+Colons in MetricFamily names are RESERVED to signal that the MetricFamily is the result of a calculation or aggregation of a general purpose monitoring system.
+
+MetricFamily names beginning with underscores are RESERVED and MUST NOT be used unless specified by this standard.
+
+###### Suffixes
+
+The name of a MetricFamily MUST NOT result in a potential clash for sample metric names as per the ABNF with another MetricFamily in the Text Format within a MetricSet. An example would be a gauge called "foo_created" as a counter called "foo" could create a "foo_created" in the text format.
+
+Exposers SHOULD avoid names that could be confused with the suffixes that text format sample metric names use.
+
+* Suffixes for the respective types are:
+* Counter: `_total`, `_created`
+* Summary: `_count`, `_sum`, `_created`, `` (empty)
+* Histogram: `_count`, `_sum`, `_bucket`, `_created`
+* GaugeHistogram: `_gcount`, `_gsum`, `_bucket`
+* Info: `_info`
+* Gauge: `` (empty)
+* StateSet: `` (empty)
+* Unknown: `` (empty)
+
+##### Type
+
+Type specifies the MetricFamily type. Valid values are "unknown", "gauge", "counter", "stateset", "info", "histogram", "gaugehistogram", and "summary".
+
+##### Unit
+
+Unit specifies MetricFamily units. If non-empty, it MUST be a suffix of the MetricFamily name separated by an underscore. Be aware that further generation rules might make it an infix in the text format.
+
+##### Help
+
+Help is a string and SHOULD be non-empty. It is used to give a brief description of the MetricFamily for human consumption and SHOULD be short enough to be used as a tooltip.
+
+##### MetricSet
+
+A MetricSet is the top level object exposed by OpenMetrics. It MUST consist of MetricFamilies and MAY be empty.
+
+Each MetricFamily name MUST be unique. The same label name and value SHOULD NOT appear on every Metric within a MetricSet.
+
+There is no specific ordering of MetricFamilies required within a MetricSet. An exposer MAY make an exposition easier to read for humans, for example sort alphabetically if the performance tradeoff makes sense.
+
+If present, an Info MetricFamily called "target" per the "Supporting target metadata in both push-based and pull-based systems" section below SHOULD be first.
+
+### Metric Types
+
+#### Gauge
+
+Gauges are current measurements, such as bytes of memory currently used or the number of items in a queue. For gauges the absolute value is what is of interest to a user.
+
+A MetricPoint in a Metric with the type gauge MUST have a single value.
+
+Gauges MAY increase, decrease, or stay constant over time. Even if they only ever go in one direction, they might still be gauges and not counters. The size of a log file would usually only increase, a resource might decrease, and the limit of a queue size may be constant.
+
+A gauge MAY be used to encode an enum where the enum has many states and changes over time, it is the most efficient but least user friendly.
+
+#### Counter
+
+Counters measure discrete events. Common examples are the number of HTTP requests received, CPU seconds spent, or bytes sent. For counters how quickly they are increasing over time is what is of interest to a user.
+
+A MetricPoint in a Metric with the type Counter MUST have one value called Total. A Total is a non-NaN and MUST be monotonically non-decreasing over time, starting from 0.
+
+A MetricPoint in a Metric with the type Counter SHOULD have a Timestamp value called Created. This can help ingestors discern between new metrics and long-running ones it did not see before.
+
+A MetricPoint in a Metric's Counter's Total MAY reset to 0. If present, the corresponding Created time MUST also be set to the timestamp of the reset.
+
+A MetricPoint in a Metric's Counter's Total MAY have an exemplar.
+
+#### StateSet
+
+StateSets represent a series of related boolean values, also called a bitset. If ENUMs need to be encoded this MAY be done via StateSet.
+
+A point of a StateSet metric MAY contain multiple states and MUST contain one boolean per State. States have a name which are Strings.
+
+A StateSet Metric's LabelSet MUST NOT have a label name which is the same as the name of its MetricFamily.
+
+If encoded as a StateSet, ENUMs MUST have exactly one Boolean which is true within a MetricPoint.
+
+This is suitable where the enum value changes over time, and the number of States isn't much more than a handful.
+
+<!---
+# EDITOR’S NOTE: This might be better as Consideration
+-->
+
+MetricFamilies of type StateSets MUST have an empty Unit string.
+
+#### Info
+
+Info metrics are used to expose textual information which SHOULD NOT change during process lifetime. Common examples are an application's version, revision control commit, and the version of a compiler.
+
+A MetricPoint of an Info Metric contains a LabelSet. An Info MetricPoint's LabelSet MUST NOT have a label name which is the same as the name of a label of the LabelSet of its Metric.
+
+Info MAY be used to encode ENUMs whose values do not change over time, such as the type of a network interface.
+
+MetricFamilies of type Info MUST have an empty Unit string.
+
+#### Histogram
+
+Histograms measure distributions of discrete events. Common examples are the latency of HTTP requests, function runtimes, or I/O request sizes.
+
+A Histogram MetricPoint MUST contain at least one bucket, and SHOULD contain Sum, and Created values. Every bucket MUST have a threshold and a value.
+
+Histogram MetricPoints MUST have one bucket with an +Inf threshold. Buckets MUST be cumulative. As an example for a metric representing request latency in seconds its values for buckets with thresholds 1, 2, 3, and +Inf MUST follow value_1 <= value_2 <= value_3 <= value_+Inf. If ten requests took 1 second each, the values of the 1, 2, 3, and +Inf buckets MUST equal 10.
+
+The +Inf bucket counts all requests. If present, the Sum value MUST equal the Sum of all the measured event values. Bucket thresholds within a MetricPoint MUST be unique.
+
+Semantically, Sum, and buckets values are counters so MUST NOT be NaN or negative.
+Negative threshold buckets MAY be used, but then the Histogram MetricPoint MUST NOT contain a sum value as it would no longer be a counter semantically. Bucket thresholds MUST NOT equal NaN. Count and bucket values MUST be integers.
+
+A Histogram MetricPoint SHOULD have a Timestamp value called Created. This can help ingestors discern between new metrics and long-running ones it did not see before.
+
+A Histogram's Metric's LabelSet MUST NOT have a "le" label name.
+
+Bucket values MAY have exemplars. Buckets are cumulative to allow monitoring systems to drop any non-+Inf bucket for performance/anti-denial-of-service reasons in a way that loses granularity but is still a valid Histogram.
+
+<!---
+# EDITOR’S NOTE: The second sentence is a consideration, it can be moved if needed
+-->
+
+Each bucket covers the values less and or equal to it, and the value of the exemplar MUST be within this range. Exemplars SHOULD be put into the bucket with the highest value. A bucket MUST NOT have more than one exemplar.
+
+#### GaugeHistogram
+
+GaugeHistograms measure current distributions. Common examples are how long items have been waiting in a queue, or size of the requests in a queue.
+
+A GaugeHistogram MetricPoint MUST have one bucket with an +Inf threshold, and SHOULD contain a Gsum value. Every bucket MUST have a threshold and a value.
+
+The buckets for a GaugeHistogram follow all the same rules as for a Histogram.
+
+The bucket and Gsum of a GaugeHistogram are conceptually gauges, however bucket values MUST NOT be negative or NaN. If negative threshold buckets are present, then sum MAY be negative. Gsum MUST NOT be NaN. Bucket values MUST be integers.
+
+A GaugeHistogram's Metric's LabelSet MUST NOT have a "le" label name.
+
+Bucket values can have exemplars.
+
+Each bucket covers the values less and or equal to it, and the value of the exemplar MUST be within this range. Exemplars SHOULD be put into the bucket with the highest value. A bucket MUST NOT have more than one exemplar.
+
+#### Summary
+
+Summaries also measure distributions of discrete events and MAY be used when Histograms are too expensive and/or an average event size is sufficient.
+
+They MAY also be used for backwards compatibility, because some existing instrumentation libraries expose precomputed quantiles and do not support Histograms. Precomputed quantiles SHOULD NOT be used, because quantiles are not aggregatable and the user often can not deduce what timeframe they cover.
+
+A Summary MetricPoint MAY consist of a Count, Sum, Created, and a set of quantiles.
+
+Semantically, Count and Sum values are counters so MUST NOT be NaN or negative.
+Count MUST be an integer.
+
+A MetricPoint in a Metric with the type Summary which contains Count or Sum values SHOULD have a Timestamp value called Created. This can help ingestors discern between new metrics and long-running ones it did not see before. Created MUST NOT relate to the collection period of quantile values.
+
+Quantiles are a map from a quantile to a value. An example is a quantile 0.95 with value 0.2 in a metric called myapp_http_request_duration_seconds which means that the 95th percentile latency is 200ms over an unknown timeframe. If there are no events in the relevant timeframe, the value for a quantile MUST be NaN.
+A Quantile's Metric's LabelSet MUST NOT have "quantile" label name.
+Quantiles MUST be between 0 and 1 inclusive. Quantile values MUST NOT be negative. Quantile values SHOULD represent the recent values. Commonly this would be over the last 5-10 minutes.
+
+#### Unknown
+
+Unknown SHOULD NOT be used. Unknown MAY be used when it is impossible to determine the types of individual metrics from 3rd party systems.
+
+A point in a metric with the unknown type MUST have a single value.
+
+# Data transmission & wire formats
+
+The text wire format MUST be supported and is the default. The protobuf wire format MAY be supported and MUST ONLY be used after negotiation.
+
+The OpenMetrics formats are Regular Chomsky Grammars, making writing quick and small parsers possible.
+The text format compresses well, and protobuf is already binary and efficiently encoded.
+
+Partial or invalid expositions MUST be considered erroneous in their entirety.
+
+### Protocol Negotiation
+
+All ingestor implementations MUST be able to ingest data secured with TLS 1.2 or later. All exposers SHOULD be able to emit data secured with TLS 1.2 or later. ingestor implementations SHOULD be able to ingest data from HTTP without TLS. All implementations SHOULD use TLS to transmit data.
+
+Negotiation of what version of the OpenMetrics format to use is out-of-band. For example for pull-based exposition over HTTP standard HTTP content type negotiation is used, and MUST default to the oldest version of the standard (i.e. 1.0.0) if no newer version is requested.
+
+Push-based negotiation is inherently more complex, as the exposer typically initiates the connection. Producers MUST use the oldest version of the standard (i.e. 1.0.0) unless requested otherwise by the ingestor.
+
+### Text format
+
+#### ABNF
+
+ABNF as per RFC 5234
+
+<!---
+# EDITOR’S NOTE: Should we update to RFC 7405, in particular the case insensitive bits?
+-->
+
+"exposition" is the top level token of the ABNF.
+
+```abnf
+exposition = metricset HASH SP eof [ LF ]
+
+metricset = *metricfamily
+
+metricfamily = *metric-descriptor *metric
+
+metric-descriptor = HASH SP type SP metricname SP metric-type LF
+metric-descriptor =/ HASH SP help SP metricname SP escaped-string LF
+metric-descriptor =/ HASH SP unit SP metricname SP *metricname-char LF
+
+metric = *sample
+
+metric-type = counter / gauge / histogram / gaugehistogram / stateset
+metric-type =/ info / summary / unknown
+
+sample = metricname [labels] SP number [SP timestamp] [exemplar] LF
+
+exemplar = SP HASH SP labels SP number [SP timestamp]
+
+labels = "{" [label *(COMMA label)] "}"
+
+label = label-name EQ DQUOTE escaped-string DQUOTE
+
+number = realnumber
+; Case insensitive
+number =/ [SIGN] ("inf" / "infinity")
+number =/ "nan"
+
+timestamp = realnumber
+
+; Not 100% sure this captures all float corner cases.
+; Leading 0s explicitly okay
+realnumber = [SIGN] 1*DIGIT
+realnumber =/ [SIGN] 1*DIGIT ["." *DIGIT] [ "e" [SIGN] 1*DIGIT ]
+realnumber =/ [SIGN] *DIGIT "." 1*DIGIT [ "e" [SIGN] 1*DIGIT ]
+
+
+; RFC 5234 is case insensitive.
+; Uppercase
+eof = %d69.79.70
+type = %d84.89.80.69
+help = %d72.69.76.80
+unit = %d85.78.73.84
+; Lowercase
+counter = %d99.111.117.110.116.101.114
+gauge = %d103.97.117.103.101
+histogram = %d104.105.115.116.111.103.114.97.109
+gaugehistogram = gauge histogram
+stateset = %d115.116.97.116.101.115.101.116
+info = %d105.110.102.111
+summary = %d115.117.109.109.97.114.121
+unknown = %d117.110.107.110.111.119.110
+
+BS = "\"
+EQ = "="
+COMMA = ","
+HASH = "#"
+SIGN = "-" / "+"
+
+metricname = metricname-initial-char 0*metricname-char
+
+metricname-char = metricname-initial-char / DIGIT
+metricname-initial-char = ALPHA / "_" / ":"
+
+label-name = label-name-initial-char *label-name-char
+
+label-name-char = label-name-initial-char / DIGIT
+label-name-initial-char = ALPHA / "_"
+
+escaped-string = *escaped-char
+
+escaped-char = normal-char
+escaped-char =/ BS ("n" / DQUOTE / BS)
+escaped-char =/ BS normal-char
+
+; Any unicode character, except newline, double quote, and backslash
+normal-char = %x00-09 / %x0B-21 / %x23-5B / %x5D-D7FF / %xE000-10FFFF
+```
+
+#### Overall Structure
+
+UTF-8 MUST be used. Byte order markers (BOMs) MUST NOT be used. As an important reminder for implementers, byte 0 is valid UTF-8 while, for example, byte 255 is not.
+
+The content type MUST be:
+
+``` 
+application/openmetrics-text; version=1.0.0; charset=utf-8
+``` 
+
+Line endings MUST be signalled with line feed (\n) and MUST NOT contain carriage returns (\r). Expositions MUST end with EOF and SHOULD end with `EOF\n`.
+
+An example of a complete exposition:
+
+```
+# TYPE acme_http_router_request_seconds summary
+# UNIT acme_http_router_request_seconds seconds
+# HELP acme_http_router_request_seconds Latency though all of ACME's HTTP request router.
+acme_http_router_request_seconds_sum{path="/api/v1",method="GET"} 9036.32
+acme_http_router_request_seconds_count{path="/api/v1",method="GET"} 807283.0
+acme_http_router_request_seconds_created{path="/api/v1",method="GET"} 1605281325.0
+acme_http_router_request_seconds_sum{path="/api/v2",method="POST"} 479.3
+acme_http_router_request_seconds_count{path="/api/v2",method="POST"} 34.0
+acme_http_router_request_seconds_created{path="/api/v2",method="POST"} 1605281325.0
+# TYPE go_goroutines gauge
+# HELP go_goroutines Number of goroutines that currently exist.
+go_goroutines 69
+# TYPE process_cpu_seconds counter
+# UNIT process_cpu_seconds seconds
+# HELP process_cpu_seconds Total user and system CPU time spent in seconds.
+process_cpu_seconds_total 4.20072246e+06
+# EOF
+```
+
+##### Escaping
+
+Where the ABNF notes escaping, the following escaping MUST be applied
+Line feed, `\n` (0x0A) -> literally `\\n` (Bytecode 0x5c 0x6e)
+Double quotes -> `\\"` (Bytecode 0x5c 0x22)
+Backslash -> `\\\\` (Bytecode 0x5c 0x5c)
+
+A double backslash SHOULD be used to represent a backslash character.
+A single backslash SHOULD NOT be used for undefined escape sequences.
+As an example, `\\\\a` is equivalent and preferable to `\\a`.
+
+##### Numbers
+
+Integer numbers MUST NOT have a decimal point. Examples are `23`, `0042`, and `1341298465647914`.
+
+Floating point numbers MUST be represented either with a decimal point or using scientific notation. Examples are `8903.123421` and `1.89e-7`. Floating point numbers MUST fit within the range of a 64-bit floating point value as defined by IEEE 754, but MAY require so many bits in the mantissa that results in lost precision. This MAY be used to encode nanosecond resolution timestamps.
+
+Arbitrary integer and floating point rendering of numbers MUST NOT be used for "quantile" and "le" label values as in section "Canonical Numbers". They MAY be used anywhere else numbers are used.
+
+###### Considerations: Canonical Numbers
+
+Numbers in the "le" label values of histograms and "quantile" label values of summary metrics are special in that they're label values, and label values are intended to be opaque. As end users will likely directly interact with these string values, and as many monitoring systems lack the ability to deal with them as first-class numbers, it would be beneficial if a given number had the exact same text representation.
+
+Consistency is highly desirable, but real world implementations of languages and their runtimes make mandating this impractical. The most important common quantiles are 0.5, 0.95, 0.9, 0.99, 0.999 and bucket values representing values from a millisecond up to 10.0 seconds, because those cover cases like latency SLAs and Apdex for typical web services. Powers of ten are covered to try to ensure that the switch between fixed point and exponential rendering is consistent as this varies across runtimes. The target rendering is equivalent to the default Go rendering of float64 values (i.e. %g), with a .0 appended in case there is no decimal point or exponent to make clear that they are floats.
+
+Exposers MUST produce output for positive infinity as +Inf.
+
+Exposers SHOULD produce output for the values 0.0 up to 10.0 in 0.001 increments in line with the following examples:
+0.0 0.001 0.002 0.01 0.1 0.9 0.95 0.99 0.999 1.0 1.7 10.0
+
+Exposers SHOULD produce output for the values 1e-10 up to 1e+10 in powers of ten in line with the following examples:
+1e-10 1e-09 1e-05 0.0001 0.1 1.0 100000.0 1e+06 1e+10
+
+Parsers MUST NOT reject inputs which are outside of the canonical values merely because they are not consistent with the canonical values. For example 1.1e-4 must not be rejected, even though it is not the consistent rendering of 0.00011.
+
+Exposers SHOULD follow these patterns for non-canonical numbers, and the intention is by adjusting the rendering algorithm to be consistent for these values that the vast majority of other values will also have consistent rendering. Exposers using only a few particular le/quantile values could also hardcode. In languages such as C where a minimal floating point rendering algorithm such as Grisu3 is not readily available, exposers MAY use a different rendering.
+
+A warning to implementers in C and other languages that share its printf implementation: The standard precision of %f, %e and %g is only six significant digits. 17 significant digits are required for full precision, e.g. `printf("%.17g", d)`.
+
+##### Timestamps
+
+Timestamps SHOULD NOT use exponential float rendering for timestamps if nanosecond precision is needed as rendering of a float64 does not have sufficient precision, e.g. `1604676851.123456789`.
+
+#### MetricFamily
+
+There MUST NOT be an explicit separator between MetricFamilies. The next MetricFamily MUST be signalled with either metadata or a new sample metric name which cannot be part of the previous MetricFamily.
+
+
+MetricFamilies MUST NOT be interleaved.
+
+##### MetricFamily metadata
+
+There are four pieces of metadata: The MetricFamily name, TYPE, UNIT and HELP.  An example of the metadata for a counter Metric called foo is:
+
+```
+# TYPE foo counter
+```
+
+If no TYPE is exposed, the MetricFamily MUST be of type Unknown.
+
+If a unit is specified it MUST be provided in a UNIT metadata line. In addition, an underscore and the unit MUST be the suffix of the MetricFamily name.
+
+A valid example for a foo_seconds metric with a unit of "seconds":
+
+```
+# TYPE foo_seconds counter
+# UNIT foo_seconds seconds
+```
+
+An invalid example, where the unit is not a suffix on the name:
+
+```
+# TYPE foo counter
+# UNIT foo seconds
+```
+
+It is also valid to have:
+
+```
+# TYPE foo_seconds counter
+```
+
+If the unit is known it SHOULD be provided.
+
+The value of a UNIT or HELP line MAY be empty. This MUST be treated as if no metadata line for the MetricFamily existed.
+
+```
+# TYPE foo_seconds counter
+# UNIT foo_seconds seconds
+# HELP foo_seconds Some text and \n some \" escaping
+```
+
+There MUST NOT be more than one of each type of metadata line for a MetricFamily. The ordering SHOULD be TYPE, UNIT, HELP.
+
+Aside from this metadata and the EOF line at the end of the message, you MUST NOT expose lines beginning with a #.
+
+##### Metric
+
+Metrics MUST NOT be interleaved.
+
+See the example in "Text format -> MetricPoint".
+Labels
+A sample without labels or a timestamp and the value 0 MUST be rendered either like:
+
+```
+bar_seconds_count 0
+```
+
+or like
+
+```
+bar_seconds_count{} 0
+```
+
+Label values MAY be any valid UTF-8 value, so escaping MUST be applied as per the ABNF. A valid example with two labels:
+
+```
+bar_seconds_count{a="x",b="escaping\" example \n "} 0
+```
+
+The rendering of values for a MetricPoint can include additional labels (e.g. the "le" label for a Histogram type), which MUST be rendered in the same way as a Metric's own LabelSet.
+
+#### MetricPoint
+
+MetricPoints MUST NOT be interleaved.
+
+A correct example where there were multiple MetricPoints and Samples within a MetricFamily would be:
+
+```
+# TYPE foo_seconds summary
+# UNIT foo_seconds seconds
+foo_seconds_count{a="bb"} 0 123
+foo_seconds_sum{a="bb"} 0 123
+foo_seconds_count{a="bb"} 0 456
+foo_seconds_sum{a="bb"} 0 456
+foo_seconds_count{a="ccc"} 0 123
+foo_seconds_sum{a="ccc"} 0 123
+foo_seconds_count{a="ccc"} 0 456
+foo_seconds_sum{a="ccc"} 0 456
+```
+
+An incorrect example where Metrics are interleaved:
+
+```
+# TYPE foo_seconds summary
+# UNIT foo_seconds seconds
+foo_seconds_count{a="bb"} 0 123
+foo_seconds_count{a="ccc"} 0 123
+foo_seconds_count{a="bb"} 0 456
+foo_seconds_count{a="ccc"} 0 456
+```
+
+An incorrect example where MetricPoints are interleaved:
+
+```
+# TYPE foo_seconds summary
+# UNIT foo_seconds seconds
+foo_seconds_count{a="bb"} 0 123
+foo_seconds_count{a="bb"} 0 456
+foo_seconds_sum{a="bb"} 0 123
+foo_seconds_sum{a="bb"} 0 456
+```
+
+#### Metric types
+
+##### Gauge
+
+The Sample MetricName for the value of a MetricPoint for a MetricFamily of type Gauge MUST NOT have a suffix.
+
+An example MetricFamily with a Metric with no labels and a MetricPoint with no timestamp:
+
+```
+# TYPE foo gauge
+foo 17.0
+```
+
+An example of a MetricFamily with two Metrics with a label and MetricPoints with no timestamp:
+
+```
+# TYPE foo gauge
+foo{a="bb"} 17.0
+foo{a="ccc"} 17.0
+```
+
+An example of a MetricFamily with no Metrics:
+
+```
+# TYPE foo gauge
+```
+
+An example with a Metric with a  label and a MetricPoint with a timestamp:
+
+```
+# TYPE foo gauge
+foo{a="b"} 17.0 1520879607.789
+```
+
+An example with a Metric with no labels and MetricPoint with a timestamp:
+
+```
+# TYPE foo gauge
+foo 17.0 1520879607.789
+```
+
+An example with a Metric with no labels and two MetricPoints with timestamps:
+
+```
+# TYPE foo gauge
+foo 17.0 123
+foo 18.0 456
+```
+
+##### Counter
+
+The MetricPoint's Total Value Sample MetricName MUST have the suffix `_total`. If present the MetricPoint's Created Value Sample MetricName MUST have the suffix `_created`.
+
+An example with a Metric with no labels, and a MetricPoint with no timestamp and no created:
+
+```
+# TYPE foo counter
+foo_total 17.0
+```
+
+An example with a Metric with no labels, and a MetricPoint with a timestamp and no created:
+
+```
+# TYPE foo counter
+foo_total 17.0 1520879607.789
+```
+
+An example with a Metric with no labels, and a MetricPoint with no timestamp and a created:
+
+```
+# TYPE foo counter
+foo_total 17.0
+foo_created 1520430000.123
+```
+
+An example with a Metric with no labels, and a MetricPoint with a timestamp and a created:
+
+```
+# TYPE foo counter
+foo_total 17.0 1520879607.789
+foo_created 1520430000.123 1520879607.789
+```
+
+Exemplars MAY be attached to the MetricPoint's Total sample.
+
+##### StateSet
+
+The Sample MetricName for the value of a MetricPoint for a MetricFamily of type StateSet MUST NOT have a suffix.
+
+StateSets MUST have one sample per State in the MetricPoint. Each State's sample MUST have a label with the MetricFamily name as the label name and the State name as the label value. The State sample's value MUST be 1 if the State is true and MUST be 0 if the State is false.
+
+An example with the states "a", "bb", and "ccc" in which only the value bb is enabled and the metric name is foo:
+
+```
+# TYPE foo stateset
+foo{foo="a"} 0
+foo{foo="bb"} 1
+foo{foo="ccc"} 0
+```
+
+An example of an "entity" label on the Metric:
+
+```
+# TYPE foo stateset
+foo{entity="controller",foo="a"} 1.0
+foo{entity="controller",foo="bb"} 0.0
+foo{entity="controller",foo="ccc"} 0.0
+foo{entity="replica",foo="a"} 1.0
+foo{entity="replica",foo="bb"} 0.0
+foo{entity="replica",foo="ccc"} 1.0
+```
+
+##### Info
+
+The Sample MetricName for the value of a MetricPoint for a MetricFamily of type Info MUST have the suffix `_info`. The Sample value MUST always be 1.
+
+An example of a Metric with no labels, and one MetricPoint value with "name" and "version" labels:
+
+```
+# TYPE foo info
+foo_info{name="pretty name",version="8.2.7"} 1
+```
+
+An example of a Metric with label "entity" and one MetricPoint value with “name” and “version” labels:
+
+```
+# TYPE foo info
+foo_info{entity="controller",name="pretty name",version="8.2.7"} 1.0
+foo_info{entity="replica",name="prettier name",version="8.1.9"} 1.0
+```
+
+Metric labels and MetricPoint value labels MAY be in any order.
+
+##### Summary
+
+If present, the MetricPoint's Sum Value Sample MetricName MUST have the suffix `_sum`. If present, the MetricPoint's Count Value Sample MetricName MUST have the suffix `_count`. If present, the MetricPoint's Created Value Sample MetricName MUST have the suffix `_created`. If present, the MetricPoint's Quantile Values MUST specify the quantile measured using a label with a label name of "quantile" and with a label value of the quantile measured.
+
+An example of a Metric with no labels and a MetricPoint with Sum, Count and Created values:
+
+```
+# TYPE foo summary
+foo_count 17.0
+foo_sum 324789.3
+foo_created 1520430000.123
+```
+
+An example of a Metric with no labels and a MetricPoint with two quantiles:
+
+```
+# TYPE foo summary
+foo{quantile="0.95"} 123.7
+foo{quantile="0.99"} 150.0
+```
+
+Quantiles MAY be in any order.
+
+##### Histogram
+
+The MetricPoint's Bucket Values Sample MetricNames MUST have the suffix `_bucket`. If present, the MetricPoint's Sum Value Sample MetricName MUST have the suffix `_sum`. If present, the MetricPoint's Created Value Sample MetricName MUST have the suffix `_created`.
+If and only if a Sum Value is present in a MetricPoint, then the MetricPoint's +Inf Bucket value MUST also appear in a Sample with a MetricName with the suffix "_count".
+
+Buckets MUST be sorted in number increasing order of "le", and the value of the "le" label MUST follow the rules for Canonical Numbers.
+
+An example of a Metric with no labels and a MetricPoint with Sum, Count, and Created values, and with 12 buckets. A wide and atypical but valid variety of “le” values is shown on purpose:
+
+```
+# TYPE foo histogram
+foo_bucket{le="0.0"} 0
+foo_bucket{le="1e-05"} 0
+foo_bucket{le="0.0001"} 5
+foo_bucket{le="0.1"} 8
+foo_bucket{le="1.0"} 10
+foo_bucket{le="10.0"} 11
+foo_bucket{le="100000.0"} 11
+foo_bucket{le="1e+06"} 15
+foo_bucket{le="1e+23"} 16
+foo_bucket{le="1.1e+23"} 17
+foo_bucket{le="+Inf"} 17
+foo_count 17
+foo_sum 324789.3
+foo_created 1520430000.123
+```
+
+###### Exemplars
+
+Exemplars without Labels MUST represent an empty LabelSet as {}.
+
+An example of Exemplars showcasing several valid cases:
+The "0.01" bucket has no Exemplar. The 0.1 bucket has an Exemplar with no Labels. The 1 bucket has an Exemplar with one Label. The 10 bucket has an Exemplar with a Label and a timestamp. In practice all buckets SHOULD have the same style of Exemplars.
+
+```
+# TYPE foo histogram
+foo_bucket{le="0.01"} 0
+foo_bucket{le="0.1"} 8 # {} 0.054
+foo_bucket{le="1"} 11 # {trace_id="KOO5S4vxi0o"} 0.67
+foo_bucket{le="10"} 17 # {trace_id="oHg5SJYRHA0"} 9.8 1520879607.789
+foo_bucket{le="+Inf"} 17
+foo_count 17
+foo_sum 324789.3
+foo_created  1520430000.123
+```
+
+##### GaugeHistogram
+
+The MetricPoint's Bucket Values Sample MetricNames MUST have the suffix `_bucket`. If present, the MetricPoint's Sum Value Sample MetricName MUST have the suffix `_gsum`.
+If and only if a Sum Value is present in a MetricPoint, then the MetricPoint's +Inf Bucket value MUST also appear in a Sample with a MetricName with the suffix `_gcount`.
+
+Buckets MUST be sorted in number increasing order of "le", and the value of the "le" label MUST follow the rules for Canonical Numbers.
+
+An example of a Metric with no labels, and one MetricPoint value with no Exemplar with no Exemplars in the buckets:
+
+```
+# TYPE foo gaugehistogram
+foo_bucket{le="0.01"} 20.0
+foo_bucket{le="0.1"} 25.0
+foo_bucket{le="1"} 34.0
+foo_bucket{le="10"} 34.0
+foo_bucket{le="+Inf"} 42.0
+foo_gcount 42.0
+foo_gsum 3289.3
+```
+
+##### Unknown
+
+The sample metric name for the value of the MetricPoint for a MetricFamily of type Unknown MUST NOT have a suffix.
+
+An example with a Metric with no labels and a MetricPoint with no timestamp:
+
+```
+# TYPE foo unknown
+foo 42.23
+```
+
+### Protobuf format
+
+#### Overall Structure
+
+Protobuf messages MUST be encoded in binary and MUST have `application/openmetrics-protobuf; version=1.0.0` as their content type.
+
+All payloads MUST be a single binary encoded MetricSet message, as defined by the OpenMetrics protobuf schema.
+
+##### Version
+
+The protobuf format MUST follow the proto3 version of the protocol buffer language.
+
+##### Strings
+
+All string fields MUST be UTF-8 encoded.
+
+##### Timestamps
+
+Timestamp representations in the OpenMetrics protobuf schema MUST follow the published google.protobuf.Timestamp [timestamp] message. The timestamp message MUST be in Unix epoch seconds as an int64 and a non-negative fraction of a second at nanosecond resolution as an int32 that counts forward from the seconds timestamp component. It MUST be within 0 to 999,999,999 inclusive.
+
+#### Protobuf schema
+
+Protobuf schema is currently available [here](https://github.com/prometheus/OpenMetrics/blob/3bb328ab04d26b25ac548d851619f90d15090e5d/proto/openmetrics_data_model.proto).
+
+> NOTE: Prometheus and ecosystem does not support OpenMetrics protobuf schema, instead it uses similar `io.prometheus.client` [format](https://github.com/prometheus/client_model/blob/master/io/prometheus/client/metrics.proto). Discussions about the future of the protobuf schema in OpenMetrics 2.0 [are in progress](https://github.com/prometheus/OpenMetrics/issues/296).
+
+## Design Considerations
+
+### Scope
+
+OpenMetrics is intended to provide telemetry for online systems. It runs over protocols which do not provide hard or soft real time guarantees, so it can not make any real time guarantees itself. Latency and jitter properties of OpenMetrics are as imprecise as the underlying network, operating systems, CPUs, and the like. It is sufficiently accurate for aggregations to be used as a basis for decision-making, but not to reflect individual events.
+
+Systems of all sizes should be supported, from applications that receive a few requests an hour up to monitoring bandwidth usage on a 400Gb network port. Aggregation and analysis of transmitted telemetry should be possible over arbitrary time periods.
+
+It is intended to transport snapshots of state at the time of data transmission at a regular cadence.
+
+#### Out of scope
+
+How ingestors discover which exposers exist, and vice-versa, is out of scope for and thus not defined in this standard.
+
+### Extensions and Improvements
+
+This first version of OpenMetrics is based upon well established and de facto standard Prometheus text format 0.0.4, deliberately without adding major syntactic or semantic extensions, or optimisations on top of it. For example no attempt has been made to make the text representation of Histogram buckets more compact, relying on compression in the underlying stack to deal with their repetitive nature.
+
+This is a deliberate choice, so that the standard can take advantage of the adoption and momentum of the existing user base. This ensures a relatively easy transition from the Prometheus text format 0.0.4.
+
+It also ensures that there is a basic standard which is easy to implement. This can be built upon in future versions of the standard. The intention is that future versions of the standard will always require support for this 1.0 version, both syntactically and semantically.
+
+We want to allow monitoring systems to get usable information from an OpenMetrics exposition without undue burden. If one were to strip away all metadata and structure and just look at an OpenMetrics exposition as an unordered set of samples that should be usable on its own. As such, there are also no opaque binary types, such as sketches or t-digests which could not be expressed as a mix of gauges and counters as they would require custom parsing and handling.
+
+This principle is applied consistently throughout the standard. For example a MetricFamily's unit is duplicated in the name so that the unit is available for systems that don't understand the unit metadata. The "le" label is a normal label value, rather than getting its own special syntax, so that ingestors don't have to add special histogram handling code to ingest them. As a further example, there are no composite data types. For example, there is no geolocation type for latitude/longitude as this can be done with separate gauge metrics.
+
+### Units and Base Units
+
+For consistency across systems and to avoid confusion, units are largely based on SI base units. Base units include seconds, bytes, joules, grams, meters, ratios, volts, amperes, and celsius. Units should be provided where they are applicable.
+
+For example, having all duration metrics in seconds, there is no risk of having to guess whether a given metric is nanoseconds, microseconds, milliseconds, seconds, minutes, hours, days or weeks nor having to deal with mixed units. By choosing unprefixed units, we avoid situations like ones in which kilomilliseconds were the result of emergent behaviour of complex systems.
+
+As values can be floating point, sub-base-unit precision is built into the standard.
+
+Similarly, mixing bits and bytes is confusing, so bytes are chosen as the base. While Kelvin is a better base unit in theory, in practice most existing hardware exposes Celsius. Kilograms are the SI base unit, however the kilo prefix is problematic so grams are chosen as the base unit.
+
+While base units SHOULD be used in all possible cases, Kelvin is a well-established unit which MAY be used instead of Celsius for use cases such as color or black body temperatures where a comparison between a Celsius and Kelvin metric are unlikely.
+
+Ratios are the base unit, not percentages. Where possible, raw data in the form of gauges or counters for the given numerator and denominator should be exposed. This has better mathematical properties for analysis and aggregation in the ingestors.
+
+Decibels are not a base unit as firstly, deci is a SI prefix and secondly, bels are logarithmic. To expose signal/energy/power ratios exposing the ratio directly would be better, or better still the raw power/energy if possible. Floating point exponents are more than sufficient to cover even extreme scientific uses. An electron volt (~1e-19 J) all the way up to the energy emitted by a supernova (~1e44 J) is 63 orders of magnitude, and a 64-bit floating point number can cover over 2000 orders of magnitude.
+
+If non-base units can not be avoided and conversion is not feasible, the actual unit should still be included in the metric name for clarity. For example, joule is the base unit for both energy and power, as watts can be expressed as a counter with a joule unit. In practice a given 3rd party system may only expose watts, so a gauge expressed in watts would be the only realistic choice in that case.
+
+Not all MetricFamilies have units. For example a count of HTTP requests wouldn't have a unit. Technically the unit would be HTTP requests, but in that sense the entire MetricFamily name is the unit. Going to that extreme would not be useful. The possibility of having good axes on graphs in downstream systems for human consumption should always be kept in mind.
+
+### Statelessness
+
+The wire format defined by OpenMetrics is stateless across expositions. What information has been exposed before MUST have no impact on future expositions. Each exposition is a self-contained snapshot of the current state of the exposer.
+
+The same self-contained exposition MUST be provided to existing and new ingestors.
+
+A core design choice is that exposers MUST NOT exclude a metric merely because it has had no recent changes, or observations. An exposer must not make any assumptions about how often ingestors are consuming expositions.
+
+### Exposition Across Time and Metric Evolution
+
+Metrics are most useful when their evolution over time can be analysed, so accordingly expositions must make sense over time. Thus, it is not sufficient for one single exposition on its own to be useful and valid. Some changes to metric semantics can also break downstream users.
+
+Parsers commonly optimize by caching previous results. Thus, changing the order in which labels are exposed across expositions SHOULD be avoided even though it is technically not breaking This also tends to make writing unit tests for exposition easier.
+
+Metrics and samples SHOULD NOT appear and disappear from exposition to exposition, for example a counter is only useful if it has history. In principle, a given Metric should be present in exposition from when the process starts until the process terminates. It is often not possible to know in advance what Metrics a MetricFamily will have over the lifetime of a given process (e.g. a label value of a latency histogram is a HTTP path, which is provided by an end user at runtime), but once a counter-like Metric is exposed it should continue to be exposed until the process terminates. That a counter is not getting increments doesn't invalidate that it still has its current value. There are cases where it may make sense to stop exposing a given Metric; see the section on Missing Data.
+
+In general changing a MetricFamily's type, or adding or removing a label from its Metrics will be breaking to ingestors.
+
+A notable exception is that adding a label to the value of an Info MetricPoints is not breaking. This is so that you can add additional information to an existing Info MetricFamily where it makes sense to be, rather than being forced to create a brand new info metric with an additional label value. ingestor systems should ensure that they are resilient to such additions.
+
+Changing a MetricFamily's Help is not breaking. For values where it is possible, switching between floats and ints is not breaking. Adding a new state to a stateset is not breaking. Adding unit metadata where it doesn't change the metric name is not breaking.
+
+Histogram buckets SHOULD NOT change from exposition to exposition, as this is likely to both cause performance issues and break ingestors and cause. Similarly all expositions from any consistent binary and environment of an application SHOULD have the same buckets for a given Histogram MetricFamily, so that they can be aggregated by all ingestors without ingestors having to implement histogram merging logic for heterogeneous buckets.
+An exception might be occasional manual changes to buckets which are considered breaking, but may be a valid tradeoff when performance characteristics change due to a new software release.
+
+Even if changes are not technically breaking, they still carry a cost. For example frequent changes may cause performance issues for ingestors. A Help string that varies from exposition to exposition may cause each Help value to be stored. Frequently switching between int and float values could prevent efficient compression.
+
+### NaN
+
+NaN is a number like any other in OpenMetrics, usually resulting from a division by zero such as for a summary quantile if there have been no observations recently. NaN does not have any special meaning in OpenMetrics, and in particular MUST NOT be used as a marker for missing or otherwise bad data.
+
+### Missing Data
+
+There are valid cases when data stops being present. For example a filesystem can be unmounted and thus its Gauge Metric for free disk space no longer exists. There is no special marker or signal for this situation. Subsequent expositions simply do not include this Metric.
+
+### Exposition Performance
+
+Metrics are only useful if they can be collected in reasonable time frames. Metrics that take minutes to expose are not considered useful.
+
+As a rule of thumb, exposition SHOULD take no more than a second.
+
+Metrics from legacy systems serialized through OpenMetrics may take longer. For this reason, no hard performance assumptions can be made.
+
+Exposition SHOULD be of the most recent state. For example, a thread serving the exposition request SHOULD NOT rely on cached values, to the extent it is able to bypass any such caching
+
+### Concurrency
+
+For high availability and ad-hoc access a common approach is to have multiple ingestors. To support this, concurrent expositions MUST be supported. All BCPs for concurrent systems SHOULD be followed, common pitfalls include deadlocks, race conditions, and overly-coarse grained locking preventing expositions progressing concurrently.
+
+### Metric Naming and Namespaces
+
+<!---
+# EDITOR’S NOTE:  This section might be good for a BCP paper.
+-->
+
+We aim for a balance between understandability, avoiding clashes, and succinctness in the naming of metrics and label names. Names are separated through underscores, so metric names end up being in “snake_case”.
+
+To take an example "http_request_seconds" is succinct but would clash between large numbers of applications, and it's also unclear exactly what this metric is measuring. For example, it might be before or after auth middleware in a complex system.
+
+Metric names should indicate what piece of code they come from. So a company called A Company Manufacturing Everything might prefix all metrics in their code with "acme_", and if they had a HTTP router library measuring latency it might have a metric such as "acme_http_router_request_seconds" with a Help string indicating that it is the overall latency.
+
+It is not the aim to prevent all potential clashes across all applications, as that would require heavy handed solutions such as a global registry of metric namespaces or very long namespaces based on DNS. Rather the aim is to keep to a lightweight informal approach, so that for a given application that it is very unlikely that there is clash across its constituent libraries.
+
+Across a given deployment of a monitoring system as a whole the aim is that clashes where the same metric name means different things are uncommon. For example acme_http_router_request_seconds might end up in hundreds of different applications developed by A Company Manufacturing Everything, which is normal. If Another Corporation Making Entities also used the metric name acme_http_router_request_seconds in their HTTP router that's also fine. If applications from both companies were being monitored by the same monitoring system the clash is undesirable, but acceptable as no application is trying to expose both names and no one target is trying to (incorrectly) expose the same metric name twice. If an application wished to contain both My Example Company's and Mega Exciting Company's HTTP router libraries that would be a problem, and one of the metric names would need to be changed somehow.
+
+As a corollary, the more public a library is the better namespaced its metric names should be to reduce the risk of such scenarios arising. acme_ is not a bad choice for internal use within a company, but these companies might for example choose the prefixes acmeverything_ or acorpme_ for code shared outside their company.
+
+After namespacing by company or organisation, namespacing and naming should continue by library/subsystem/application fractally as needed such as the http_router library above. The goal is that if you are familiar with the overall structure of a codebase, you could make a good guess at where the instrumentation for a given metric is given its metric name.
+
+For a common very well known existing piece of software, the name of the software itself may be sufficiently distinguishing. For example bind_ is probably sufficient for the DNS software, even though isc_bind_ would be the more usual naming.
+
+
+Metric names prefixed by scrape_ are used by ingestors to attach information related to individual expositions, so should not be exposed by applications directly. Metrics that have already been consumed and passed through a general purpose monitoring system may include such metric names on subsequent expositions.
+If an exposer wishes to provide information about an individual exposition, a metric prefix such as myexposer_scrape_ may be used. A common example is a gauge myexposer_scrape_duration_seconds for how long that exposition took from the exposer's standpoint.
+
+Within the Prometheus ecosystem a set of per-process metrics has emerged that are consistent across all implementations, prefixed with process_. For example for open file ulimits the MetricFamiles process_open_fds and process_max_fds gauges provide both the current and maximum value. (These names are legacy, if such metrics were defined today they would be more likely called process_fds_open and process_fds_limit). In general it is very challengings to get names with identical semantics like this, which is why different instrumentation should use different names.
+
+
+Avoid redundancy in metric names. Avoid substrings like "metric", "timer", "stats", "counter", "total", "float64" and so on - by virtue of being a metric with a given type (and possibly unit) exposed via OpenMetrics information like this is already implied so should not be included explicitly. You should not include label names of a metric in the metric name for the same reasons, and in addition subsequent aggregation of the metric by a monitoring system could make such information incorrect.
+
+
+Avoid including implementation details from other layers of your monitoring system in the metric names contained in your instrumentation. For example a MetricFamily name should not contain the string "openmetrics" merely because it happens to be currently exposed via OpenMetrics somewhere, or "prometheus" merely because your current monitoring system is Prometheus.
+
+### Label Namespacing
+
+For label names no explicit namespacing by company or library is recommended, namespacing from the metric name is sufficient for this when considered against the length increase of the label name. However some minimal care to avoid common clashes is recommended.
+
+There are label names such as region, zone, cluster, availability_zone, az, datacenter, dc, owner, customer, stage, service, team, job, instance, environment, and env which are highly likely to clash with labels used to identify targets which a general purpose monitoring system may add. Try to avoid them, adding minimal namespacing may be appropriate in these cases.
+
+The label name "type" is highly generic and should be avoided. For example for HTTP-related metrics "method" would be a better label name if you were distinguishing between GET, POST, and PUT requests.
+
+While there is metadata about metric names such as HELP, TYPE and UNIT there is no metadata for label names. This is as it would be bloating the format for little gain. Out-of-band documentation is one way for exposers could present this their ingestors.
+
+### Metric Names versus Labels
+
+There are situations in which both using multiple Metrics within a MetricFamily or multiple MetricFamilies seem to make sense. Summing or averaging aMetricFamily should be meaningful even if it's not always useful. For example, mixing voltage and fan speed is not meaningful.
+
+As a reminder, OpenMetrics is built with the assumption that ingestors can process and perform aggregations on data.
+
+Exposing a total sum alongside other metrics is wrong, as this would result in double-counting upon aggregation in downstream ingestors.
+
+```
+wrong_metric{label="a"} 1
+wrong_metric{label="b"} 6
+wrong_metric{label="total"} 7
+```
+
+Labels of a Metric should be to the minimum needed to ensure uniqueness as every extra label is one more that users need to consider when determining what Labels to work with downstream. Labels which could be applied many MetricFamilies are candidates for being moved into _info metrics similar to database {{normalization}}. If virtually all users of a Metric could be expected to want the additional label, it may be a better trade-off to add it to all MetricFamilies. For example if you had a MetricFamily relating to different SQL statements where uniqueness was provided by a label containing a hash of the full SQL statements, it would be okay to have another label with the first 500 characters of the SQL statement for human readability.
+
+Experience has shown that downstream ingestors find it easier to work with separate total and failure MetricFamiles rather than using {result="success"} and {result="failure"} Labels within one MetricFamily. Also it is usually better to expose separate read & write and send & receive MetricFamiles as full duplex systems are common and downstream ingestors are more likely to care about those values separately than in aggregate.
+
+All of this is not as easy as it may sound. It's an area where experience and engineering trade-offs by domain-specific experts in both exposition and the exposed system are required to find a good balance.
+Metric and Label Name Characters
+
+OpenMetrics builds on the existing widely adopted Prometheus text exposition format and the ecosystem which formed around it. Backwards compatibility is a core design goal. Expanding or contracting the set of characters that are supported by the Prometheus text format would work against that goal. Breaking backwards compatibility would have wider implications than just the wire format. In particular, the query languages created or adopted to work with data transmitted within the Prometheus ecosystem rely on these precise character sets. Label values support full UTF-8, so the format can represent multi-lingual metrics.
+
+### Types of Metadata
+
+Metadata can come from different sources. Over the years, two main sources have emerged. While they are often functionally the same, it helps in understanding to talk about their conceptual differences.
+
+"Target metadata" is metadata commonly external to an exposer.  Common examples would be data coming from service discovery, a CMDB, or similar, like information about a datacenter region, if a service is part of a particular deployment, or production or testing. This can be  achieved by either the exposer or the ingestor adding labels to all Metrics that capture this metadata. Doing this through the ingestor is preferred as it is more flexible and carries less overhead. On flexibility, the hardware maintenance team might care about which server rack a machine is located in, whereas the database team using that same machine might care that it contains replica number 2 of the production database. On overhead, hardcoding or configuring this information needs an additional distribution path.
+
+"Exposer metadata" is coming from within an exposer. Common examples would be software version, compiler version, or Git commit SHA.
+
+#### Supporting Target Metadata in both Push-based and Pull-based Systems
+
+In push-based consumption, it is typical for the exposer to provide the relevant target metadata to the ingestor. In pull-based consumption the push-based approach could be taken, but more typically the ingestor already knows the metadata of the target a-priori such as from a machine database or service discovery system, and associates it with the metrics as it consumes the exposition.
+
+OpenMetrics is stateless and provides the same exposition to all ingestors, which is in conflict with the push-style approach. In addition the push-style approach would break pull-style ingestors, as unwanted metadata would be exposed.
+
+One approach would be for push-style ingestors to provide target metadata based on operator configuration out-of-band, for example as a HTTP header. While this would transport target metadata for push-style ingestors, and is not precluded by this standard, it has the disadvantage that even though pull-style ingestors should use their own target metadata, it is still often useful to have access to the metadata the exposer itself is aware of.
+
+The preferred solution is to provide this target metadata as part of the exposition, but in a way that does not impact on the exposition as a whole. Info MetricFamilies are designed for this. An exposer may include an Info MetricFamily called "target" with a single Metric with no labels with the metadata. An example in the text format might be:
+
+```
+# TYPE target info
+# HELP target Target metadata
+target_info{env="prod",hostname="myhost",datacenter="sdc",region="europe",owner="frontend"} 1
+```
+
+When an exposer is providing this metric for this purpose it SHOULD be first in the exposition. This is for efficiency, so that ingestors relying on it for target metadata don't have to buffer up the rest of the exposition before applying business logic based on its content.
+
+Exposers MUST NOT add target metadata labels to all Metrics from an exposition, unless explicitly configured for a specific ingestor. Exposers MUST NOT prefix MetricFamily names or otherwise vary MetricFamily names based on target metadata.
+Generally, the same Label should not appear on every Metric of an exposition, but there are rare cases where this can be the result of emergent behaviour. Similarly all MetricFamily names from an exposer may happen to share a prefix in very small expositions. For example an application written in the Go language by A Company Manufacturing Everything would likely include metrics with prefixes of acme_, go_, process_, and metric prefixes from any 3rd party libraries in use.
+
+Exposers can expose exposer metadata as Info MetricFamilies.
+
+The above discussion is in the context of individual exposers. An exposition from a general purpose monitoring system may contain metrics from many individual targets, and thus may expose multiple target info Metrics. The metrics may already have had target metadata added to them as labels as part of ingestion. The metric names MUST NOT be varied based on target metadata. For example it would be incorrect for all metrics to end up being prefixed with staging_ even if they all originated from targets in a staging environment).
+
+### Client Calculations and Derived Metrics
+
+Exposers should leave any math or calculation up to ingestors. A notable exception is the  Summary quantile which is unfortunately required for backwards compatibility. Exposition should be of raw values which are useful over arbitrary time periods.
+
+As an example, you should not expose a gauge with the average rate of increase of a counter over the last 5 minutes. Letting the ingestor calculate the increase over the data points they have consumed across expositions has better mathematical properties and is more resilient to scrape failures.
+
+Another example is the average event size of a histogram/summary. Exposing the average rate of increase of a counter since an application started or since a Metric was created has the problems from the earlier example and it also prevents aggregation.
+
+Standard deviation also falls into this category. Exposing a sum of squares as a counter would be the correct approach. It was not included in this standard as a Histogram value because 64bit floating point precision is not sufficient for this to work in practice. Due to the squaring only half the 53bit mantissa would be available in terms of precision. As an example a histogram observing 10k events per second would lose precision within 2 hours. Using 64bit integers would be no better due to the loss of the floating decimal point because a nanosecond resolution integer typically tracking events of a second in length would overflow after 19 observations.
+This design decision can be revisited when 128bit floating point numbers become common.
+
+Another example is to avoid exposing a request failure ratio, exposing separate counters for failed requests and total requests instead.
+
+### Number Types
+
+For a counter that was incremented a million times per second it would take over a century to begin to lose precision with a float64 as it has a 53 bit mantissa. Yet a 100 Gbps network interface's octet throughput precision could begin to be lost with a float64 within around 20 hours. While losing 1KB of precision over the course of years for a 100Gbps network interface is unlikely to be a problem in practice, int64s are an option for integral data with such a high throughput.
+
+Summary quantiles must be float64, as they are estimates and thus fundamentally inaccurate.
+
+### Exposing Timestamps
+
+One of the core assumptions of OpenMetrics is that exposers expose the most up to date snapshot of what they're exposing.
+
+While there are limited use cases for attaching timestamps to exposed data, these are very uncommon. Data which had timestamps previously attached, in particular data which has been ingested into a general purpose monitoring system may carry timestamps. Live or raw data should not carry timestamps. It is valid to expose the same metric MetricPoint value with the same timestamp across expositions, however it is invalid to do so if the underlying metric is now missing.
+
+Time synchronization is a hard problem and data should be internally consistent in each system. As such, ingestors should be able to attach the current timestamp from their perspective to data rather than based on the system time of the exposer device.
+
+With timestamped metrics it is not generally possible to detect the time when a Metric went missing across expositions. However with non-timestamped metrics the ingestor can use its own timestamp from the exposition where the Metric is no longer present.
+
+All of this is to say that, in general, MetricPoint timestamps should not be exposed, as it should be up to the ingestor to apply their own timestamps to samples they ingest.
+
+#### Tracking When Metrics Last Changed
+
+Presume you had a counter my_counter which was initialized, and then later incremented by 1 at time 123. This would be a correct way to expose it in the text format:
+
+```
+# HELP my_counter Good increment example
+# TYPE my_counter counter
+my_counter_total 1
+```
+
+As per the parent section, ingestors should be free to attach their own timestamps, so this would be incorrect:
+
+```
+# HELP my_counter Bad increment example
+# TYPE my_counter counter
+my_counter_total 1 123
+```
+
+
+In case the specific time of the last change of a counter matters, this would be the correct way:
+
+```
+# HELP my_counter Good increment example
+# TYPE my_counter counter
+my_counter_total 1
+# HELP my_counter_last_increment_timestamp_seconds When my_counter was last incremented
+# TYPE my_counter_last_increment_timestamp_seconds gauge
+# UNIT my_counter_last_increment_timestamp_seconds seconds
+my_counter_last_increment_timestamp_seconds 123
+```
+
+By putting the timestamp of last change into its own Gauge as a value, ingestors are free to attach their own timestamp to both Metrics.
+
+
+Experience has shown that exposing absolute timestamps (epoch is considered absolute here) is more robust than time elapsed, seconds since, or similar. In either case, they would be gauges. For example:
+
+```
+# TYPE my_boot_time_seconds gauge
+# HELP my_boot_time_seconds Boot time of the machine
+# UNIT my_boot_time_seconds seconds
+my_boot_time_seconds 1256060124
+```
+
+Is better than:
+
+```
+# TYPE my_time_since_boot_seconds gauge
+# HELP my_time_since_boot_seconds Time elapsed since machine booted
+# UNIT my_time_since_boot_seconds seconds
+my_time_since_boot_seconds 123
+```
+
+Conversely, there are no best practice restrictions on exemplars timestamps.
+Keep in mind that due to race conditions or time not being perfectly synced across devices, that an exemplar timestamp may appear to be slightly in the future relative to a ingestor's system clock or other metrics from the same exposition. Similarly it is possible that a "_created" for a MetricPoint could appear to be slightly after an exemplar or sample timestamp for that same MetricPoint.
+
+Keep in mind that there are monitoring systems in common use which support everything from nanosecond to second resolution, so having two MetricPoints that have the same timestamp when truncated to second resolution may cause an apparent duplicate in the ingestor. In this case the MetricPoint with the earliest timestamp MUST be used.
+
+### Thresholds
+
+Exposing desired bounds for a system can make sense, but proper care needs to be taken. For values which are universally true, it can make sense to emit Gauge metrics for such thresholds. For example, a data center HVAC system knows the current measurements, the setpoints, and the alert setpoints. It has a globally valid and correct view of the desired system state.
+As a counter example, some thresholds can change with scale, deployment model, or over time. A certain amount of CPU usage may be acceptable in one setting and undesirable in another. Aggregation of values can further change acceptable values. In such a system, exposing bounds could be counter-productive.
+
+For example the maximum size of a queue may be exposed alongside the number of items currently in the queue like:
+
+```
+# HELP acme_notifications_queue_capacity The capacity of the notifications queue.
+# TYPE acme_notifications_queue_capacity gauge
+acme_notifications_queue_capacity 10000
+# HELP acme_notifications_queue_length The number of notifications in the queue.
+# TYPE acme_notifications_queue_length gauge
+acme_notifications_queue_length 42
+```
+
+### Size Limits
+
+This standard does not prescribe any particular limits on the number of samples exposed by a single exposition, the number of labels that may be present, the number of states a stateset may have, the number of labels in an info value, or metric name/label name/label value/help character limits.
+
+Specific limits run the risk of preventing reasonable use cases, for example while a given exposition may have an appropriate number of labels after passing through a general purpose monitoring system a few target labels may have been added that would push it over the limit. Specific limits on numbers such as these would also not capture where the real costs are for general purpose monitoring systems. These guidelines are thus both to aid exposers and ingestors in understanding what is reasonable.
+
+On the other hand, an exposition which is too large in some dimension could cause significant performance problems compared to the benefit of the metrics exposed. Thus some guidelines on the size of any single exposition would be useful.
+
+ingestors may choose to impose limits themselves, for in particular to prevent attacks or outages. Still, ingestors need to consider reasonable use cases and try not to  disproportionately impact them. If any single value/metric/exposition exceeds such limits then the whole exposition must be rejected.
+
+In general there are three things which impact the performance of a general purpose monitoring system ingestion time series data: the number of unique time series, the number of samples over time in those series, and the number of unique strings such as metric names, label names, label values, and HELP. ingestors can control how often they ingest, so that aspect does not need further consideration.
+
+The number of unique time series is roughly equivalent to the number of non-comment lines in the text format. As of 2020, 10 million time series in total is considered a large amount and is commonly the order of magnitude of the upper bound of any single-instance ingestor. Any single exposition should not go above 10k time series without due diligence. One common consideration is horizontal scaling: What happens if you scale your instance count by 1-2 orders of magnitude? Having a thousand top-of-rack switches in a single deployment would have been hard to imagine 30 years ago. If a target was a singleton (e.g. exposing metrics relating to an entire cluster) then several hundred thousand time series may be reasonable. It is not the number of unique MetricFamilies or the cardinality of individual labels/buckets/statesets that matters, it is the total order of magnitude of the time series. 1,000 gauges with one Metric each are as costly as a single gauge with 1,000 Metrics.
+
+If all targets of a particular type are exposing the same set of time series, then each additional targets' strings poses no incremental cost to most reasonably modern monitoring systems. If however each target has unique strings, there is such a cost. As an extreme example, a single 10k character metric name used by many targets is on its own very unlikely to be a problem in practice. To the contrary, a thousand targets each exposing a unique 36 character UUID is over three times as expensive as that single 10k character metric name in terms of strings to be stored assuming modern approaches. In addition, if these strings change over time older strings will still need to be stored for at least some time, incurring extra cost. Assuming the 10 million times series from the last paragraph, 100MB of unique strings per hour might indicate a use case for then the use case may be more like event logging, not metric time series.
+
+There is a hard 128 UTF-8 character limit on exemplar length, to prevent misuse of the feature for tracing span data and other event logging.
+
+## Security
+
+Implementors MAY choose to offer authentication, authorization, and accounting; if they so choose, this SHOULD be handled outside of OpenMetrics.
+
+All exposer implementations SHOULD be able to secure their HTTP traffic with TLS 1.2 or later.
+If an exposer implementation does not support encryption, operators SHOULD use reverse proxies, firewalling, and/or ACLs where feasible.
+
+Metric exposition should be independent of production services exposed to end users; as such, having a /metrics endpoint on ports like TCP/80, TCP/443, TCP/8080, and TCP/8443 is generally discouraged for publicly exposed services using OpenMetrics.
+
+## IANA
+
+While currently most implementations of the Prometheus exposition format are using non-IANA-registered ports from an informal registry at {{PrometheusPorts}}, OpenMetrics can be found on a well-defined port.
+
+The port assigned by IANA for clients exposing data is <9099 requested for historical consistency>.
+
+If more than one metric endpoint needs to be reachable at a common IP address and port, operators might consider using a reverse proxy that communicates with exposers over localhost addresses. To ease multiplexing, endpoints SHOULD carry their own name in their path, i.e. `/node_exporter/metrics`. Expositions SHOULD NOT be combined into one exposition, for the reasons covered under "Supporting target metadata in both push-based and pull-based systems" and to allow for independent ingestion without a single point of failure.
+
+OpenMetrics would like to register two MIME types, `application/openmetrics-text` and `application/openmetrics-proto`.
+
+<!---
+# EDITOR’S NOTE: `application/openmetrics-text` is in active use since 2018, `application/openmetrics-proto` is not yet in active use.
+-->
+
+<!---
+# EDITOR’S NOTE: We would like to thank Sumeer Bhola, but kramdown 2.x does not support `Contributor:` any more so we will add this by hand once consensus has been achieved.
+-->
diff --git a/docs/specs/prw/index.md b/docs/specs/prw/index.md
new file mode 100644
index 00000000..3a800945
--- /dev/null
+++ b/docs/specs/prw/index.md
@@ -0,0 +1,4 @@
+---
+title: "Remote Write"
+sort_rank: 4
+---
diff --git a/docs/specs/prw/remote_write_spec.md b/docs/specs/prw/remote_write_spec.md
new file mode 100644
index 00000000..18cedc01
--- /dev/null
+++ b/docs/specs/prw/remote_write_spec.md
@@ -0,0 +1,219 @@
+---
+title: "1.0"
+title_prefix: "Remote Write 1.0"
+sort_rank: 5
+---
+
+# Prometheus Remote-Write Specification
+
+- Version: 1.0
+- Status: Published
+- Date: April 2023
+
+This document is intended to define and standardise the API, wire format, protocol and semantics of the existing, widely and organically adopted protocol, and not to propose anything new.
+
+The remote write specification is intended to document the standard for how Prometheus and Prometheus remote-write-compatible agents send data to a Prometheus or Prometheus remote-write compatible receiver.
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
+
+> NOTE: This specification has a 2.0 version available, see [here](./remote_write_spec_2_0.md).
+
+## Introduction
+### Background
+
+The remote write protocol is designed to make it possible to reliably propagate samples in real-time from a sender to a receiver, without loss.
+
+The Remote-Write protocol is designed to be stateless; there is strictly no inter-message communication. As such the protocol is not considered "streaming". To achieve a streaming effect multiple messages should be sent over the same connection using e.g. HTTP/1.1 or HTTP/2. "Fancy" technologies such as gRPC were considered, but at the time were not widely adopted, and it was challenging to expose gRPC services to the internet behind load balancers such as an AWS EC2 ELB.
+
+The remote write protocol contains opportunities for batching, e.g. sending multiple samples for different series in a single request.  It is not expected that multiple samples for the same series will be commonly sent in the same request, although there is support for this in the protocol.
+
+The remote write protocol is not intended for use by applications to push metrics to Prometheus remote-write-compatible receivers.  It is intended that a Prometheus remote-write-compatible sender scrapes instrumented applications or exporters and sends remote write messages to a server.
+
+A test suite can be found at https://github.com/prometheus/compliance/tree/main/remotewrite/sender.
+
+### Glossary
+
+For the purposes of this document the following definitions MUST be followed:
+
+- a "Sender" is something that sends Prometheus Remote Write data.
+- a "Receiver" is something that receives Prometheus Remote Write data.
+- a "Sample" is a pair of (timestamp, value).
+- a "Label" is a pair of (key, value).
+- a "Series" is a list of samples, identified by a unique set of labels.
+
+## Definitions
+### Protocol
+
+The Remote Write Protocol MUST consist of RPCs with the following signature:
+
+```
+func Send(WriteRequest)
+
+message WriteRequest {
+  repeated TimeSeries timeseries = 1;
+  // Cortex uses this field to determine the source of the write request.
+  // We reserve it to avoid any compatibility issues.
+  reserved  2;
+
+  // Prometheus uses this field to send metadata, but this is
+  // omitted from v1 of the spec as it is experimental.
+  reserved  3;
+}
+
+message TimeSeries {
+  repeated Label labels   = 1;
+  repeated Sample samples = 2;
+}
+
+message Label {
+  string name  = 1;
+  string value = 2;
+}
+
+message Sample {
+  double value    = 1;
+  int64 timestamp = 2;
+}
+```
+
+Remote write Senders MUST encode the Write Request in the body of a HTTP POST request and send it to the Receivers via HTTP at a provided URL path.  The Receiver MAY specify any HTTP URL path to receive metrics.
+
+Timestamps MUST be int64 counted as milliseconds since the Unix epoch.  Values MUST be float64.
+
+The following headers MUST be sent with the HTTP request:
+
+- `Content-Encoding: snappy`
+- `Content-Type: application/x-protobuf`
+- `User-Agent: <name & version of the sender>`
+- `X-Prometheus-Remote-Write-Version: 0.1.0`
+
+Clients MAY allow users to send custom HTTP headers; they MUST NOT allow users to configure them in such a way as to send reserved headers.  For more info see https://github.com/prometheus/prometheus/pull/8416.
+
+The remote write request in the body of the HTTP POST MUST be compressed with [Google’s Snappy](https://github.com/google/snappy).  The block format MUST be used - the framed format MUST NOT be used.
+
+The remote write request MUST be encoded using Google Protobuf 3, and MUST use the schema defined above.  Note [the Prometheus implementation](https://github.com/prometheus/prometheus/blob/v2.24.0/prompb/remote.proto) uses [gogoproto optimisations](https://github.com/gogo/protobuf) - for receivers written in languages other than Golang the gogoproto types MAY be substituted for line-level equivalents.
+
+The response body from the remote write receiver SHOULD be empty; clients MUST ignore the response body. The response body is RESERVED for future use.
+
+### Backward and forward compatibility
+
+The protocol follows [semantic versioning 2.0](https://semver.org/): any 1.x compatible receivers MUST be able to read any 1.x compatible sender and so on.  Breaking/backwards incompatible changes will result in a 2.x version of the spec.
+
+The proto format itself is forward / backward compatible, in some respects:
+
+- Removing fields from the proto will mean a major version bump.
+- Adding (optional) fields will be a minor version bump.
+
+Negotiation:
+
+- Senders MUST send the version number in a headers.
+- Receivers MAY return the highest version number they support in a response header ("X-Prometheus-Remote-Write-Version").
+- Senders who wish to send in a format >1.x MUST start by sending an empty 1.x, and see if the response says the receiver supports something else.  The Sender MAY use any supported version .  If there is no version header in the response, senders MUST assume 1.x compatibility only.
+
+### Labels
+
+The complete set of labels MUST be sent with each sample. Whatsmore, the label set associated with samples:
+
+- SHOULD contain a `__name__` label.
+- MUST NOT contain repeated label names.
+- MUST have label names sorted in lexicographical order.
+- MUST NOT contain any empty label names or values.
+
+Senders MUST only send valid metric names, label names, and label values:
+
+- Metric names MUST adhere to the regex `[a-zA-Z_:]([a-zA-Z0-9_:])*`.
+- Label names MUST adhere to the regex `[a-zA-Z_]([a-zA-Z0-9_])*`.
+- Label values MAY be any sequence of UTF-8 characters .
+
+Receivers MAY impose limits on the number and length of labels, but this will be receiver-specific and is out of scope for this document.
+
+Label names beginning with "__" are RESERVED for system usage and SHOULD NOT be used, see [Prometheus Data Model](https://prometheus.io/docs/concepts/data_model/).
+
+Remote write Receivers MAY ingest valid samples within a write request that otherwise contains invalid samples. Receivers MUST return a HTTP 400 status code ("Bad Request") for write requests that contain any invalid samples. Receivers SHOULD provide a human readable error message in the response body. Senders MUST NOT try and interpret the error message, and SHOULD log it as is.
+
+### Ordering
+Prometheus Remote Write compatible senders MUST send samples for any given series in timestamp order. Prometheus Remote Write compatible Senders MAY send multiple requests for different series in parallel.
+
+### Retries & Backoff
+Prometheus Remote Write compatible senders MUST retry write requests on HTTP 5xx responses and MUST use a backoff algorithm to prevent overwhelming the server. They MUST NOT retry write requests on HTTP 2xx and 4xx responses other than 429. They MAY retry on HTTP 429 responses, which could result in senders "falling behind" if the server cannot keep up. This is done to ensure data is not lost when there are server side errors, and progress is made when there are client side errors.
+
+Prometheus remote Write compatible receivers MUST respond with a HTTP 2xx status code when the write is successful. They MUST respond with HTTP status code 5xx when the write fails and SHOULD be retried. They MUST respond with HTTP status code 4xx when the request is invalid, will never be able to succeed and should not be retried.
+
+### Stale Markers
+Prometheus remote write compatible senders MUST send stale markers when a time series will no longer be appended to.
+
+Stale markers MUST be signalled by  the special NaN value 0x7ff0000000000002. This value MUST NOT be used otherwise.
+
+Typically the sender can detect when a time series will no longer be appended to using the following techniques:
+
+1. Detecting, using service discovery, that the target exposing the series has gone away
+1. Noticing the target is no longer exposing the time series between successive scrapes
+1. Failing to scrape the target that originally exposed a time series
+1. Tracking configuration and evaluation for recording and alerting rules
+
+## Out of Scope
+This document does not intend to explain all the features required for a fully Prometheus-compatible monitoring system.  In particular, the following areas are out of scope for the first version of the spec:
+
+**The "up" metric** The definition and semantics of the "up" metric are beyond the scope of the remote write protocol and should be documented separately.
+
+**HTTP Path** The path for HTTP handler can be anything - and MUST be provided by the sender.  Generally we expect the whole URL to be specified in config.
+
+**Persistence** It is recommended that Prometheus Remote Write compatible senders should persistently buffer sample data in the event of outages in the receiver. 
+
+**Authentication & Encryption** as remote write uses HTTP, we consider authentication & encryption to be a transport-layer problem.  Senders and receivers should support all the usual suspects (Basic auth, TLS etc) and are free to add potentially custom authentication options.  Support for custom authentication in the Prometheus remote write sender and eventual agent should not be assumed, but we will endeavour to support common and widely used auth protocols, where feasible.
+
+**Remote Read** this is a separate interface that has already seen some iteration, and is less widely used.
+
+**Sharding** the current sharding scheme in Prometheus for remote write parallelisation is very much an implementation detail, and isn’t part of the spec.  When senders do implement parallelisation they MUST preserve per-series sample ordering.
+
+**Backfill** The specification does not place a limit on how old series can be pushed, however server/implementation specific constraints may exist.
+
+**Limits** Limits on the number and length of labels, batch sizes etc are beyond the scope of this document, however it is expected that implementation will impose reasonable limits.
+
+**Push-based Prometheus** Applications pushing metrics to Prometheus Remote Write compatible receivers was not a design goal of this system, and should be explored in a separate doc.
+
+**Labels** Every series MAY include a "job" and/or "instance" label, as these are typically added by service discovery in the Sender. These are not mandatory.
+
+## Future Plans
+This section contains speculative plans that are not considered part of protocol specification, but are mentioned here for completeness.
+
+**Transactionality** Prometheus aims at being "transactional" - i.e. to never expose a partially scraped target to a query. We intend to do the same with remote write -  for instance, in the future we would like to "align" remote write with scrapes, perhaps such that all the samples, metadata and exemplars for a single scrape are sent in a single remote write request.  This is yet to be designed.
+
+**Metadata** and Exemplars In line with above, we also send metadata (type information, help text) and exemplars along with the scraped samples. We plan to package this up in a single remote write request - future versions of the spec may insist on this.  Prometheus currently has experimental support for sending metadata and exemplars.
+
+**Optimizations** We would like to investigate various optimizations to reduce message size by eliminating repetition of label names and values.
+
+## Related
+### Compatible Senders and Receivers
+
+The spec is intended to describe how the following components interact (as of April 2023):
+
+- [Prometheus](https://github.com/prometheus/prometheus/tree/master/storage/remote) (as both a "sender" and a "receiver")
+- [Avalanche](https://github.com/prometheus-community/avalanche) (as a "sender") - A Load Testing Tool Prometheus Metrics.
+- [Cortex](https://github.com/cortexproject/cortex/blob/master/pkg/util/push/push.go#L20) (as a "receiver")
+- [Elastic Agent](https://docs.elastic.co/integrations/prometheus#prometheus-server-remote-write) (as a "receiver")
+- [Grafana Agent](https://github.com/grafana/agent) (as both a "sender" and a "receiver")
+- [GreptimeDB](https://github.com/greptimeTeam/greptimedb) (as a ["receiver"](https://docs.greptime.com/user-guide/ingest-data/for-observerbility/prometheus))
+- InfluxData’s Telegraf agent. ([as a sender](https://github.com/influxdata/telegraf/tree/master/plugins/serializers/prometheusremotewrite), and [as a receiver](https://github.com/influxdata/telegraf/pull/8967))
+- [M3](https://m3db.io/docs/integrations/prometheus/#prometheus-configuration) (as a "receiver")
+- [Mimir](https://github.com/grafana/mimir) (as a "receiver")
+- [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector-releases/) (as a ["sender"](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/prometheusremotewriteexporter#readme) and eventually as a "receiver")
+- [Thanos](https://thanos.io/tip/components/receive.md/) (as a "receiver")
+- Vector (as a ["sender"](https://vector.dev/docs/reference/configuration/sinks/prometheus_remote_write/) and a ["receiver"](https://vector.dev/docs/reference/configuration/sources/prometheus_remote_write/))
+- [VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics) (as a ["receiver"](https://docs.victoriametrics.com/#prometheus-setup))
+
+### FAQ
+
+**Why did you not use gRPC?**
+Funnily enough we initially used gRPC, but switched to Protos atop HTTP as in 2016 it was hard to get them past ELBs: https://github.com/prometheus/prometheus/issues/1982
+
+**Why not streaming protobuf messages?**
+If you use persistent HTTP/1.1 connections, they are pretty close to streaming…  Of course headers have to be re-sent, but yes that is less expensive than a new TCP set up.
+
+**Why do we send samples in order?**
+The in-order constraint comes from the encoding we use for time series data in Prometheus, the implementation of which is append only. It is possible to remove this constraint, for instance by buffering samples and reordering them before encoding.  We can investigate this in future versions of the protocol.
+
+**How can we parallelise requests with the in-order constraint?**
+Samples must be in-order _for a given series_.  Remote write requests can be sent in parallel as long as they are for different series. In Prometheus, we shard the samples by their labels into separate queues, and then writes happen sequentially in each queue.  This guarantees samples for the same series are delivered in order, but samples for different series are sent in parallel - and potentially "out of order" between different series.
+
+We believe this is necessary as, even if the receiver could support out-of-order samples, we can't have agents sending out of order as they would never be able to send to Prometheus, Cortex and Thanos.  We’re doing this to ensure the integrity of the ecosystem and to prevent confusing/forking the community into "prometheus-agents-that-can-write-to-prometheus" and those that can’t.
diff --git a/docs/specs/prw/remote_write_spec_2_0.md b/docs/specs/prw/remote_write_spec_2_0.md
new file mode 100644
index 00000000..d224ad2c
--- /dev/null
+++ b/docs/specs/prw/remote_write_spec_2_0.md
@@ -0,0 +1,484 @@
+---
+title: "2.0 [EXPERIMENTAL]"
+title_prefix: "Remote Write 2.0"
+sort_rank: 4
+---
+
+# Prometheus Remote-Write Specification
+
+* Version: 2.0-rc.3
+* Status: **Experimental**
+* Date: May 2024
+
+The Remote-Write specification, in general, is intended to document the standard for how Prometheus and Prometheus Remote-Write compatible senders send data to Prometheus or Prometheus Remote-Write compatible receivers.
+
+This document is intended to define a second version of the [Prometheus Remote-Write](/docs/specs/remote_write_spec) API with minor changes to protocol and semantics. This second version adds a new Protobuf Message with new features enabling more use cases and wider adoption on top of performance and cost savings. The second version also deprecates the previous Protobuf Message from a [1.0 Remote-Write specification](/docs/specs/remote_write_spec/#protocol) and adds mandatory [`X-Prometheus-Remote-Write-*-Written` HTTP response headers](#required-written-response-headers)for reliability purposes. Finally, this spec outlines how to implement backwards-compatible senders and receivers (even under a single endpoint) using existing basic content negotiation request headers. More advanced, automatic content negotiation mechanisms might come in a future minor version if needed. For the rationales behind the 2.0 specification, see [the formal proposal](https://github.com/prometheus/proposals/pull/35).
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
+
+> NOTE: This is a release candidate for Remote-Write 2.0 specification. This means that this specification is currently in an experimental state--no major changes are expected, but we reserve the right to break the compatibility if it's necessary, based on the early adopters' feedback. The potential feedback, questions and suggestions should be added as comments to the [PR with the open proposal](https://github.com/prometheus/proposals/pull/35).
+
+## Introduction
+
+### Background
+
+The Remote-Write protocol is designed to make it possible to reliably propagate samples in real-time from a sender to a receiver, without loss.
+
+<!---
+For the detailed rationales behind each 2.0 Remote-Write decision, see: https://github.com/prometheus/proposals/blob/alexg/remote-write-20-proposal/proposals/2024-04-09_remote-write-20.md
+-->
+The Remote-Write protocol is designed to be stateless; there is strictly no inter-message communication. As such the protocol is not considered "streaming". To achieve a streaming effect multiple messages should be sent over the same connection using e.g. HTTP/1.1 or HTTP/2. "Fancy" technologies such as gRPC were considered, but at the time were not widely adopted, and it was challenging to expose gRPC services to the internet behind load balancers such as an AWS EC2 ELB.
+
+The Remote-Write protocol contains opportunities for batching, e.g. sending multiple samples for different series in a single request. It is not expected that multiple samples for the same series will be commonly sent in the same request, although there is support for this in the Protobuf Message.
+
+A test suite can be found at https://github.com/prometheus/compliance/tree/main/remote_write_sender. The compliance tests for remote write 2.0 compatibility are still [in progress](https://github.com/prometheus/compliance/issues/101).
+
+### Glossary
+
+In this document, the following definitions are followed:
+
+* `Remote-Write` is the name of this Prometheus protocol.
+* a `Protocol` is a communication specification that enables the client and server to transfer metrics.
+* a `Protobuf Message` (or Proto Message) refers to the [content type](https://www.rfc-editor.org/rfc/rfc9110.html#name-content-type) definition of the data structure for this Protocol. Since the specification uses [Google Protocol Buffers ("protobuf")](https://protobuf.dev/) exclusively, the schema is defined in a ["proto" file](https://protobuf.dev/programming-guides/proto3/) and represented by a single Protobuf ["message"](https://protobuf.dev/programming-guides/proto3/#simple).
+* a `Wire Format` is the format of the data as it travels on the wire (i.e. in a network). In the case of Remote-Write, this is always the compressed binary protobuf format.
+* a `Sender` is something that sends Remote-Write data.
+* a `Receiver` is something that receives (writes) Remote-Write data. The meaning of `Written` is up to the Receiver e.g. usually it means storing received data in a database, but also just validating, splitting or enhancing it.
+* `Written` refers to data the `Receiver` has received and is accepting. Whether or not it has ingested this data to persistent storage, written it to a WAL, etc. is up to the `Receiver`. The only distinction is that the `Receiver` has accepted this data rather than explicitly rejecting it with an error response.
+* a `Sample` is a pair of (timestamp, value).
+* a `Histogram` is a pair of (timestamp, [histogram value](https://github.com/prometheus/docs/blob/b9657b5f5b264b81add39f6db2f1df36faf03efe/content/docs/concepts/native_histograms.md)).
+* a `Label` is a pair of (key, value).
+* a `Series` is a list of samples, identified by a unique set of labels.
+
+## Definitions
+
+### Protocol
+
+The Remote-Write Protocol MUST consist of RPCs with the request body serialized using a Google Protocol Buffers and then compressed.
+
+<!---
+Rationales: https://github.com/prometheus/proposals/blob/alexg/remote-write-20-proposal/proposals/2024-04-09_remote-write-20.md#a-new-protobuf-message-identified-by-fully-qualified-name-old-one-deprecated
+-->
+The protobuf serialization MUST use either of the following Protobuf Messages:
+
+* The `prometheus.WriteRequest` introduced in [the Remote-Write 1.0 specification](./remote_write_spec.md#protocol). As of 2.0, this message is deprecated. It SHOULD be used only for compatibility reasons. Senders and Receivers MAY NOT support the `prometheus.WriteRequest`.
+* The `io.prometheus.write.v2.Request` introduced in this specification and defined [below](#protobuf-message). Senders and Receivers SHOULD use this message when possible. Senders and Receivers MUST support the `io.prometheus.write.v2.Request`.
+
+Protobuf Message MUST use binary Wire Format. Then, MUST be compressed with [Google’s Snappy](https://github.com/google/snappy). Snappy's [block format](https://github.com/google/snappy/blob/2c94e11145f0b7b184b831577c93e5a41c4c0346/format_description.txt) MUST be used -- [the framed format](https://github.com/google/snappy/blob/2c94e11145f0b7b184b831577c93e5a41c4c0346/framing_format.txt) MUST NOT be used.
+
+Senders MUST send a serialized and compressed Protobuf Message in the body of an HTTP POST request and send it to the Receiver via HTTP at the provided URL path. Receivers MAY specify any HTTP URL path to receive metrics.
+
+<!---
+Rationales: https://github.com/prometheus/proposals/blob/alexg/remote-write-20-proposal/proposals/2024-04-09_remote-write-20.md#basic-content-negotiation-built-on-what-we-have
+-->
+Senders MUST send the following reserved headers with the HTTP request:
+
+- `Content-Encoding`
+- `Content-Type`
+- `X-Prometheus-Remote-Write-Version`
+- `User-Agent`
+
+Senders MAY allow users to add custom HTTP headers; they MUST NOT allow users to configure them in such a way as to send reserved headers.
+
+#### Content-Encoding
+
+```
+Content-Encoding: <compression>
+```
+
+<!---
+Rationales: https://github.com/prometheus/proposals/blob/alexg/remote-write-20-proposal/proposals/2024-04-09_remote-write-20.md#no-new-compression-added--yet-
+-->
+Content encoding request header MUST follow [the RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-content-encoding). Senders MUST use the `snappy` value. Receivers MUST support `snappy` compression. New, optional compression algorithms might come in 2.x or beyond.
+
+#### Content-Type
+
+```
+Content-Type: application/x-protobuf
+Content-Type: application/x-protobuf;proto=<fully qualified name>
+```
+
+Content type request header MUST follow [the RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-content-type). Senders MUST use `application/x-protobuf` as the only media type. Senders MAY add `;proto=` parameter to the header's value to indicate the fully qualified name of the Protobuf Message that was used, from the two mentioned above. As a result, Senders MUST send any of the three supported header values:
+
+For the deprecated message introduced in PRW 1.0, identified by `prometheus.WriteRequest`:
+
+* `Content-Type: application/x-protobuf`
+* `Content-Type: application/x-protobuf;proto=prometheus.WriteRequest`
+
+For the message introduced in PRW 2.0, identified by `io.prometheus.write.v2.Request`:
+
+* `Content-Type: application/x-protobuf;proto=io.prometheus.write.v2.Request`
+
+When talking to 1.x Receivers, Senders SHOULD use `Content-Type: application/x-protobuf` for backward compatibility. Otherwise, Senders SHOULD use `Content-Type: application/x-protobuf;proto=io.prometheus.write.v2.Request`. More Protobuf Messages might come in 2.x or beyond.
+
+Receivers MUST use the content type header to identify the Protobuf Message schema to use. Accidental wrong schema choices may result in non-deterministic behaviour (e.g. corruptions).
+
+> NOTE: Thanks to reserved fields in [`io.prometheus.write.v2.Request`](#protobuf-message), Receiver accidental use of wrong schema with `prometheus.WriteRequest` will result in empty message. This is generally for convenience to avoid surprising errors, but don't rely on it -- future Protobuf Messages might not have this feature.
+
+#### X-Prometheus-Remote-Write-Version
+
+```
+X-Prometheus-Remote-Write-Version: <Remote-Write spec major and minor version>
+```
+
+When talking to 1.x Receivers, Senders MUST use `X-Prometheus-Remote-Write-Version: 0.1.0` for backward compatibility. Otherwise, Senders SHOULD use the newest Remote-Write version it is compatible with e.g. `X-Prometheus-Remote-Write-Version: 2.0.0`.
+
+#### User-Agent
+
+```
+User-Agent: <name & version of the Sender>
+```
+
+Senders MUST include a user agent header that SHOULD follow [the RFC 9110 User-Agent header format](https://www.rfc-editor.org/rfc/rfc9110.html#name-user-agent).
+
+### Response
+
+Receivers that written all data successfully MUST return a [success 2xx HTTP status code](https://www.rfc-editor.org/rfc/rfc9110.html#name-successful-2xx). In such a successful case, the response body from the Receiver SHOULD be empty and the status code SHOULD be [204 HTTP No Content](https://www.rfc-editor.org/rfc/rfc9110.html#name-204-no-content); Senders MUST ignore the response body. The response body is RESERVED for future use.
+
+Receivers MUST NOT return a 2xx HTTP status code if any of the pieces of sent data known to the Receiver (e.g. Samples, Histograms, Exemplars) were NOT written successfully (both [partial write](#partial-write) or full write rejection). In such a case, the Receiver MUST provide a human-readable error message in the response body. The Receiver's error SHOULD contain information about the amount of the samples being rejected and for what reasons. Senders MUST NOT try and interpret the error message and SHOULD log it as is.
+
+The following subsections specify Sender and Receiver semantics around headers and different write error cases.
+
+#### Required `Written` Response Headers
+
+<!---
+Rationales: https://github.com/prometheus/prometheus/issues/14359
+-->
+Upon a successful content negotiation, Receivers process (write) the received batch of data. Once completed (with success or failure) for each important piece of data (currently Samples, Histograms and Exemplars) Receivers MUST send a dedicated HTTP `X-Prometheus-Remote-Write-*-Written` response header with the precise number of successfully written elements.
+
+Each header value MUST be a single 64-bit integer. The header names MUST be as follows:
+
+```
+X-Prometheus-Remote-Write-Samples-Written <count of all successfully written Samples>
+X-Prometheus-Remote-Write-Histograms-Written <count of all successfully written Histogram samples>
+X-Prometheus-Remote-Write-Exemplars-Written <count of all successfully written Exemplars>
+```
+
+Upon receiving a 2xx or a 4xx status code, Senders CAN assume that any missing `X-Prometheus-Remote-Write-*-Written` response header means no element from this category (e.g. Sample) was written by the Receiver (count of `0`). Senders MUST NOT assume the same when using the deprecated `prometheus.WriteRequest` Protobuf Message due to the risk of hitting 1.0 Receiver without this feature.
+
+Senders MAY use those headers to confirm which parts of data were successfully written by the Receiver. Common use cases:
+
+* Better handling of the [Partial Write](#partial-write) failure situations: Senders MAY use those headers for more accurate client instrumentation and error handling.
+* Detecting broken 1.0 Receiver implementations: Senders SHOULD assume [415 HTTP Unsupported Media Type](https://www.rfc-editor.org/rfc/rfc9110.html#name-415-unsupported-media-type) status code when sending the data using `io.prometheus.write.v2.Request` request and receiving 2xx HTTP status code, but none of the `X-Prometheus-Remote-Write-*-Written` response headers from the Receiver. This is a common issue for the 1.0 Receivers that do not check the `Content-Type` request header; accidental decoding of the `io.prometheus.write.v2.Request` payload with `prometheus.WriteRequest` schema results in empty result and no decoding errors.
+* Detecting other broken implementations or issues: Senders MAY use those headers to detect broken Sender and Receiver implementations or other problems.
+
+Senders MUST NOT assume what Remote Write specification version the Receiver implements from the remote write response headers.
+
+More (optional) headers might come in the future, e.g. when more entities or fields are added and worth confirming.
+
+#### Partial Write
+
+<!---
+Rationales: https://github.com/prometheus/proposals/blob/alexg/remote-write-20-proposal/proposals/2024-04-09_remote-write-20.md#partial-writes
+-->
+Senders SHOULD use Remote-Write to send samples for multiple series in a single request. As a result, Receivers MAY write valid samples within a write request that also contains some invalid or otherwise unwritten samples, which represents a partial write case. In such a case, the Receiver MUST return non-2xx status code following the [Invalid Samples](#invalid-samples) and [Retry on Partial Writes](#retries-on-partial-writes) sections.
+
+#### Unsupported Request Content
+
+Receivers MUST return [415 HTTP Unsupported Media Type](https://www.rfc-editor.org/rfc/rfc9110.html#name-415-unsupported-media-type) status code if they don't support a given content type or encoding provided by Senders.
+
+Senders SHOULD expect [400 HTTP Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) for the above reasons from 1.x Receivers, for backwards compatibility.
+
+#### Invalid Samples
+
+Receivers MAY NOT support certain metric types or samples (e.g. a Receiver might reject sample without metadata type specified or without created timestamp, while another Receiver might accept such sample.). It’s up to the Receiver what sample is invalid. Receivers MUST return a [400 HTTP Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) status code for write requests that contain any invalid samples unless the [partial retriable write](#retries-on-partial-writes) occurs.
+
+Senders MUST NOT retry on a 4xx HTTP status codes (other than [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429)), which MUST be used by Receivers to indicate that the write operation will never be able to succeed and should not be retried. Senders MAY retry on the 415 HTTP status code with a different content type or encoding to see if the Receiver supports it.
+
+### Retries & Backoff
+
+Receivers MAY return a [429 HTTP Too Many Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) status code to indicate the overloaded server situation. Receivers MAY return [the Retry-After](https://www.rfc-editor.org/rfc/rfc9110.html#name-retry-after) header to indicate the time for the next write attempt. Receivers MAY return a 5xx HTTP status code to represent internal server errors.
+
+Senders MAY retry on a 429 HTTP status code. Senders MUST retry write requests on 5xx HTTP. Senders MUST use a backoff algorithm to prevent overwhelming the server. Senders MAY handle [the Retry-After response header](https://www.rfc-editor.org/rfc/rfc9110.html#name-retry-after) to estimate the next retry time.
+
+The difference between 429 vs 5xx handling is due to the potential situation of a Sender “falling behind” when the Receiver cannot keep up with the request volume, or the Receiver choosing to rate limit the Sender to protect its availability. As a result, Senders has the option to NOT retry on 429, which allows progress to be made when there are Sender side errors (e.g. too much traffic), while the data is not lost when there are Receiver side errors (5xx).
+
+#### Retries on Partial Writes
+
+Receivers MAY return a 5xx HTTP or 429 HTTP status code on partial write or [partial invalid sample cases](#partial-write) when it expects Senders to retry the whole request. In that case, the Receiver MUST support idempotency as Senders MAY retry with the same request.
+
+### Backward and Forward Compatibility
+
+The protocol follows [semantic versioning 2.0](https://semver.org/): any 2.x compatible Receiver MUST be able to read any 2.x compatible Senders and vice versa. Breaking or backwards incompatible changes will result in a 3.x version of the spec.
+
+The Protobuf Messages (in Wire Format) themselves are forward / backward compatible, in some respects:
+
+* Removing fields from the Protobuf Message requires a major version bump.
+* Adding (optional) fields can be done in a minor version bump.
+
+In other words, this means that future minor versions of 2.x MAY add new optional fields to `io.prometheus.write.v2.Request`, new compressions, Protobuf Messages and negotiation mechanisms, as long as they are backwards compatible (e.g. optional to both Receiver and Sender).
+
+#### 2.x vs 1.x Compatibility
+
+The 2.x protocol is breaking compatibility with 1.x by introducing a new, mandatory `io.prometheus.write.v2.Request` Protobuf Message and deprecating the `prometheus.WriteRequest`.
+
+2.x Senders MAY support 1.x Receivers by allowing users to configure what content type Senders should use. 2.x Senders also MAY automatically fall back to different content types, if the Receiver returns 415 HTTP status code.
+
+## Protobuf Message
+
+### `io.prometheus.write.v2.Request`
+
+The `io.prometheus.write.v2.Request` references the new Protobuf Message that's meant to replace and deprecate the Remote-Write 1.0's `prometheus.WriteRequest` message.
+
+<!---
+TODO(bwplotka): Move link to the one on Prometheus main or even buf.
+-->
+The full schema and source of the truth is in Prometheus repository in [`prompb/io/prometheus/write/v2/types.proto`](https://github.com/prometheus/prometheus/blob/remote-write-2.0/prompb/io/prometheus/write/v2/types.proto#L32). The `gogo` dependency and options CAN be ignored ([will be removed eventually](https://github.com/prometheus/prometheus/issues/11908)). They are not part of the specification as they don't impact the serialized format.
+
+The simplified version of the new `io.prometheus.write.v2.Request` is presented below.
+
+```
+// Request represents a request to write the given timeseries to a remote destination.
+message Request {
+  // Since Request supersedes 1.0 spec's prometheus.WriteRequest, we reserve the top-down message
+  // for the deterministic interop between those two.
+  // Generally it's not needed, because Receivers must use the Content-Type header, but we want to
+  // be sympathetic to adopters with mistaken implementations and have deterministic error (empty
+  // message if you use the wrong proto schema).
+  reserved 1 to 3;
+
+  // symbols contains a de-duplicated array of string elements used for various
+  // items in a Request message, like labels and metadata items. For the sender's convenience
+  // around empty values for optional fields like unit_ref, symbols array MUST start with
+  // empty string.
+  //
+  // To decode each of the symbolized strings, referenced, by "ref(s)" suffix, you
+  // need to lookup the actual string by index from symbols array. The order of
+  // strings is up to the sender. The receiver should not assume any particular encoding.
+  repeated string symbols = 4;
+  // timeseries represents an array of distinct series with 0 or more samples.
+  repeated TimeSeries timeseries = 5;
+}
+
+// TimeSeries represents a single series.
+message TimeSeries {
+  // labels_refs is a list of label name-value pair references, encoded
+  // as indices to the Request.symbols array. This list's length is always
+  // a multiple of two, and the underlying labels should be sorted lexicographically.
+  //
+  // Note that there might be multiple TimeSeries objects in the same
+  // Requests with the same labels e.g. for different exemplars, metadata
+  // or created timestamp.
+  repeated uint32 labels_refs = 1;
+
+  // Timeseries messages can either specify samples or (native) histogram samples
+  // (histogram field), but not both. For a typical sender (real-time metric
+  // streaming), in healthy cases, there will be only one sample or histogram.
+  //
+  // Samples and histograms are sorted by timestamp (older first).
+  repeated Sample samples = 2;
+  repeated Histogram histograms = 3;
+
+  // exemplars represents an optional set of exemplars attached to this series' samples.
+  repeated Exemplar exemplars = 4;
+
+  // metadata represents the metadata associated with the given series' samples.
+  Metadata metadata = 5;
+
+  // created_timestamp represents an optional created timestamp associated with
+  // this series' samples in ms format, typically for counter or histogram type
+  // metrics. Created timestamp represents the time when the counter started
+  // counting (sometimes referred to as start timestamp), which can increase
+  // the accuracy of query results.
+  //
+  // Note that some receivers might require this and in return fail to
+  // write such samples within the Request.
+  //
+  // For Go, see github.com/prometheus/prometheus/model/timestamp/timestamp.go
+  // for conversion from/to time.Time to Prometheus timestamp.
+  //
+  // Note that the "optional" keyword is omitted due to
+  // https://cloud.google.com/apis/design/design_patterns.md#optional_primitive_fields
+  // Zero value means value not set. If you need to use exactly zero value for
+  // the timestamp, use 1 millisecond before or after.
+  int64 created_timestamp = 6;
+}
+
+// Exemplar represents additional information attached to some series' samples.
+message Exemplar {
+  // labels_refs is an optional list of label name-value pair references, encoded
+  // as indices to the Request.symbols array. This list's len is always
+  // a multiple of 2, and the underlying labels should be sorted lexicographically.
+  // If the exemplar references a trace it should use the `trace_id` label name, as a best practice.
+  repeated uint32 labels_refs = 1;
+  // value represents an exact example value. This can be useful when the exemplar
+  // is attached to a histogram, which only gives an estimated value through buckets.
+  double value = 2;
+  // timestamp represents the timestamp of the exemplar in ms.
+  // For Go, see github.com/prometheus/prometheus/model/timestamp/timestamp.go
+  // for conversion from/to time.Time to Prometheus timestamp.
+  int64 timestamp = 3;
+}
+
+// Sample represents series sample.
+message Sample {
+  // value of the sample.
+  double value = 1;
+  // timestamp represents timestamp of the sample in ms.
+  int64 timestamp = 2;
+}
+
+// Metadata represents the metadata associated with the given series' samples.
+message Metadata {
+  enum MetricType {
+    METRIC_TYPE_UNSPECIFIED    = 0;
+    METRIC_TYPE_COUNTER        = 1;
+    METRIC_TYPE_GAUGE          = 2;
+    METRIC_TYPE_HISTOGRAM      = 3;
+    METRIC_TYPE_GAUGEHISTOGRAM = 4;
+    METRIC_TYPE_SUMMARY        = 5;
+    METRIC_TYPE_INFO           = 6;
+    METRIC_TYPE_STATESET       = 7;
+  }
+  MetricType type = 1;
+  // help_ref is a reference to the Request.symbols array representing help
+  // text for the metric. Help is optional, reference should point to an empty string in
+  // such a case.
+  uint32 help_ref = 3;
+  // unit_ref is a reference to the Request.symbols array representing a unit
+  // for the metric. Unit is optional, reference should point to an empty string in
+  // such a case.
+  uint32 unit_ref = 4;
+}
+
+// A native histogram, also known as a sparse histogram.
+// See https://github.com/prometheus/prometheus/blob/remote-write-2.0/prompb/io/prometheus/write/v2/types.proto#L142
+// for a full message that follows the native histogram spec for both sparse
+// and exponential, as well as, custom bucketing.
+message Histogram { ... }
+```
+
+All timestamps MUST be int64 counted as milliseconds since the Unix epoch. Sample's values MUST be float64.
+
+For every `TimeSeries` message:
+
+* `labels_refs` MUST be provided.
+
+<!---
+Rationales: https://github.com/prometheus/proposals/blob/alexg/remote-write-20-proposal/proposals/2024-04-09_remote-write-20.md#partial-writes#samples-vs-native-histogram-samples
+-->
+* At least one element in `samples` or in `histograms` MUST be provided. A `TimeSeries` MUST NOT include both `samples` and `histograms`. For series which (rarely) would mix float and histogram samples, a separate `TimeSeries` message MUST be used.
+
+<!---
+Rationales: https://github.com/prometheus/proposals/blob/alexg/remote-write-20-proposal/proposals/2024-04-09_remote-write-20.md#always-on-metadata
+-->
+* `metadata` sub-fields SHOULD be provided. Receivers MAY reject series with unspecified `Metadata.type`.
+* Exemplars SHOULD be provided if they exist for a series.
+* `created_timestamp` SHOULD be provided for metrics that follow counter semantics (e.g. counters and histograms). Receivers MAY reject those series without `created_timestamp` being set.
+
+The following subsections define some schema elements in detail.
+
+#### Symbols
+
+<!---
+Rationales: https://github.com/prometheus/proposals/blob/alexg/remote-write-20-proposal/proposals/2024-04-09_remote-write-20.md#partial-writes#string-interning
+-->
+The `io.prometheus.write.v2.Request` Protobuf Message is designed to [intern all strings](https://en.wikipedia.org/wiki/String_interning) for the proven additional compression and memory efficiency gains on top of the standard compressions.
+
+The `symbols` table MUST be provided and it MUST contain deduplicated strings used in series, exemplar labels, and metadata strings. The first element of the `symbols` table MUST be an empty string, which is used to represent empty or unspecified values such as when `Metadata.unit_ref` or `Metadata.help_ref` are not provided. References MUST point to the existing index in the `symbols` string array.
+
+#### Series Labels
+
+<!---
+Rationales: https://github.com/prometheus/proposals/blob/alexg/remote-write-20-proposal/proposals/2024-04-09_remote-write-20.md#labels-and-utf-8
+-->
+The complete set of labels MUST be sent with each `Sample` or `Histogram` sample. Additionally, the label set associated with samples:
+
+* SHOULD contain a `__name__` label.
+* MUST NOT contain repeated label names.
+* MUST have label names sorted in lexicographical order.
+* MUST NOT contain any empty label names or values.
+
+Metric names, label names, and label values MUST be any sequence of UTF-8 characters.
+
+Metric names SHOULD adhere to the regex `[a-zA-Z_:]([a-zA-Z0-9_:])*`.
+
+Label names SHOULD adhere to the regex `[a-zA-Z_]([a-zA-Z0-9_])*`.
+
+Names that do not adhere to the above, might be harder to use for PromQL users (see [the UTF-8 proposal for more details](https://github.com/prometheus/proposals/blob/main/proposals/2023-08-21-utf8.md)).
+
+Label names beginning with "__" are RESERVED for system usage and SHOULD NOT be used, see [Prometheus Data Model](https://prometheus.io/docs/concepts/data_model/).
+
+Receivers also MAY impose limits on the number and length of labels, but this is receiver-specific and is out of the scope of this document.
+
+#### Samples and Histogram Samples
+
+<!---
+Rationales: https://github.com/prometheus/proposals/blob/alexg/remote-write-20-proposal/proposals/2024-04-09_remote-write-20.md#partial-writes#native-histograms
+-->
+Senders MUST send `samples` (or `histograms`) for any given `TimeSeries` in timestamp order. Senders MAY send multiple requests for different series in parallel.
+
+<!---
+Rationales: https://github.com/prometheus/proposals/blob/alexg/remote-write-20-proposal/proposals/2024-04-09_remote-write-20.md#partial-writes#being-pull-vs-push-agnostic
+-->
+Senders SHOULD send stale markers when a time series will no longer be appended to.
+Senders MUST send stale markers if the discontinuation of time series is possible to detect, for example:
+
+* For series that were pulled (scraped), unless explicit timestamp was used.
+* For series that is resulted by a recording rule evaluation.
+
+Generally, not sending stale markers for series that are discontinued can lead to the Receiver [non-trivial query time alignment issues](https://prometheus.io/docs/prometheus/latest/querying/basics/#staleness).
+
+Stale markers MUST be signalled by the special NaN value `0x7ff0000000000002`. This value MUST NOT be used otherwise.
+
+Typically, Senders can detect when a time series will no longer be appended using the following techniques:
+
+1. Detecting, using service discovery, that the target exposing the series has gone away.
+1. Noticing the target is no longer exposing the time series between successive scrapes.
+1. Failing to scrape the target that originally exposed a time series.
+1. Tracking configuration and evaluation for recording and alerting rules.
+1. Tracking discontinuation of metrics for non-scrape source of metric (e.g. in k6 when the benchmark has finished for series per benchmark, it could emit a stale marker).
+
+#### Metadata
+
+Metadata SHOULD follow the official Prometheus guidelines for [Type](https://prometheus.io/docs/instrumenting/writing_exporters/#types) and [Help](https://prometheus.io/docs/instrumenting/writing_exporters/#help-strings).
+
+Metadata MAY follow the official OpenMetrics guidelines for [Unit](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#unit).
+
+#### Exemplars
+
+Each exemplar, if attached to a `TimeSeries`:
+
+* MUST contain a value.
+
+<!---
+Rationales: https://github.com/prometheus/proposals/blob/alexg/remote-write-20-proposal/proposals/2024-04-09_remote-write-20.md#partial-writes#exemplars
+-->
+* MAY contain labels e.g. referencing trace or request ID. If the exemplar references a trace it SHOULD use the `trace_id` label name, as a best practice.
+* MUST contain a timestamp. While exemplar timestamps are optional in Prometheus/Open Metrics exposition formats, the assumption is that a timestamp is assigned at scrape time in the same way a timestamp is assigned to the scrape sample. Receivers require exemplar timestamps to reliably handle (e.g. deduplicate) incoming exemplars.
+
+## Out of Scope
+
+The same as in [1.0](./remote_write_spec.md#out-of-scope).
+
+## Future Plans
+
+This section contains speculative plans that are not considered part of protocol specification yet but are mentioned here for completeness. Note that 2.0 specification completed [2 of 3 future plans in the 1.0](./remote_write_spec.md#future-plans).
+
+* **Transactionality** There is still no transactionality defined for 2.0 specification, mostly because it makes a scalable Sender implementation difficult. Prometheus Sender aims at being "transactional" - i.e. to never expose a partially scraped target to a query. We intend to do the same with Remote-Write -- for instance, in the future we would like to "align" Remote-Write with scrapes, perhaps such that all the samples, metadata and exemplars for a single scrape are sent in a single Remote-Write request.
+
+  However, Remote-Write 2.0 specification solves an important transactionality problem for [the classic histogram buckets](https://docs.google.com/document/d/1mpcSWH1B82q-BtJza-eJ8xMLlKt6EJ9oFGH325vtY1Q/edit#heading=h.ueg7q07wymku). This is done thanks to the native histograms supporting custom bucket-ing possible with the `io.prometheus.write.v2.Request` wire format. Senders might translate all classic histograms to native histograms this way, but it's out of this specification to mandate this. However, for this reason, Receivers MAY ignore certain metric types (e.g. classic histograms).
+
+* **Alternative wire formats**. The OpenTelemetry community has shown the validity of Apache Arrow (and potentially other columnar formats) for over-wire data transfer with their OTLP protocol. We would like to do experiments to confirm the compatibility of a similar format with Prometheus’ data model and include benchmarks of any resource usage changes. We would potentially maintain both a protobuf and columnar format long term for compatibility reasons and use our content negotiation to add different Protobuf Messages for this purpose.
+
+* **Global symbols**. Pre-defined string dictionary for interning The protocol could pre-define a static dictionary of ref->symbol that includes strings that are considered common, e.g. “namespace”, “le”, “job”, “seconds”, “bytes”, etc. Senders could refer to these without the need to include them in the request’s symbols table. This dictionary could incrementally grow with minor version releases of this protocol.
+
+## Related
+
+### FAQ
+
+**Why did you not use gRPC?**
+Because the 1.0 protocol does not use gRPC, breaking it would increase friction in the adoption. See 1.0 [reason](./remote_write_spec.md#faq).
+
+**Why not stream protobuf messages?**
+If you use persistent HTTP/1.1 connections, they are pretty close to streaming. Of course, headers have to be re-sent, but that is less expensive than a new TCP set up.
+
+**Why do we send samples in order?**
+The in-order constraint comes from the encoding we use for time series data in Prometheus, the implementation of which is optimized for append-only workloads. However, this requirement is also shared across many other databases and vendors in the ecosystem. In fact, [Prometheus with OOO feature enabled](https://youtu.be/qYsycK3nTSQ?t=1321), allows out-of-order writes, but with the performance penalty, thus reserved for rare events. To sum up, Receivers may support out-of-order write, though it is not permitted by the specification. In the future e.g. 2.x spec versions, we could extend content type to negotiate the out-of-order writes, if needed.
+
+**How can we parallelise requests with the in-order constraint?**
+Samples must be in-order _for a given series_. However, even if a Receiver does not support out-of-order write, the Remote-Write requests can be sent in parallel as long as they are for different series. Prometheus shards the samples by their labels into separate queues, and then writes happen sequentially in each queue. This guarantees samples for the same series are delivered in order, but samples for different series are sent in parallel - and potentially "out of order" between different series.
+
+**What are the differences between Remote-Write 2.0 and OpenTelemetry's OTLP protocol?**
+[OpenTelemetry OTLP](https://github.com/open-telemetry/opentelemetry-proto/blob/a05597bff803d3d9405fcdd1e1fb1f42bed4eb7a/docs/specification.md) is a protocol for transporting of telemetry data (such as metrics, logs, traces and profiles) between telemetry sources, intermediate nodes and telemetry backends. The recommended transport involves gRPC with protobuf, but HTTP with protobuf or JSON are also described. It was designed from scratch with the intent to support a variety of different observability signals, data types and extra information. For [metrics](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/metrics/v1/metrics.proto) that means additional non-identifying labels, flags, temporal aggregations types, resource or scoped metrics, schema URLs and more. OTLP also requires [the semantic convention](https://opentelemetry.io/docs/concepts/semantic-conventions/) to be used.
+
+Remote-Write was designed for simplicity, efficiency and organic growth. The first version was officially released in 2023, when already [dozens of battle-tested adopters in the CNCF ecosystem](./remote_write_spec.md#compatible-senders-and-receivers) had been using this protocol for years. Remote-Write 2.0 iterates on the previous protocol by adding a few new elements (metadata, exemplars, created timestamp and native histograms) and string interning. Remote-Write 2.0 is always stateless, focuses only on metrics and is opinionated; as such it is scoped down to elements that the Prometheus community considers enough to have a robust metric solution. The intention is to ensure the Remote-Write is a stable protocol that is cheaper and simpler to adopt and use than the alternatives in the observability ecosystem.
diff --git a/docs/tutorials/alerting_based_on_metrics.md b/docs/tutorials/alerting_based_on_metrics.md
new file mode 100644
index 00000000..5d7335b1
--- /dev/null
+++ b/docs/tutorials/alerting_based_on_metrics.md
@@ -0,0 +1,86 @@
+---
+title: Alerting based on metrics.
+sort_rank: 5
+---
+
+# Alerting based on metrics
+
+In this tutorial we will create alerts on the `ping_request_count` metric that we instrumented earlier in the
+[Instrumenting HTTP server written in Go](../instrumenting_http_server_in_go/) tutorial.
+
+For the sake of this tutorial we will alert when the `ping_request_count` metric is greater than 5, Checkout real world [best practices](../../practices/alerting) to learn more about alerting principles.
+
+Download the latest release of Alertmanager for your operating system from [here](https://github.com/prometheus/alertmanager/releases)
+
+Alertmanager supports various receivers like `email`, `webhook`, `pagerduty`, `slack` etc through which it can notify when an alert is firing. You can find the list of receivers and how to configure them [here](../../alerting/latest/configuration). We will use `webhook` as a receiver for this tutorial, head over to [webhook.site](https://webhook.site) and copy the webhook URL which we will use later to configure the Alertmanager.
+
+First let's setup Alertmanager with webhook receiver.
+
+> alertmanager.yml
+
+```yaml
+global:
+  resolve_timeout: 5m
+route:
+  receiver: webhook_receiver
+receivers:
+    - name: webhook_receiver
+      webhook_configs:
+        - url: '<INSERT-YOUR-WEBHOOK>'
+          send_resolved: false
+```
+Replace `<INSERT-YOUR-WEBHOOK>` with the webhook that we copied earlier in the alertmanager.yml file and run the Alertmanager using the following command.
+
+`alertmanager --config.file=alertmanager.yml`
+
+Once the Alertmanager is up and running navigate to [http://localhost:9093](http://localhost:9093) and you should be able to access it.
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/RKXwHhQZ5RE" frameborder="0" allowfullscreen></iframe>
+
+Now that we have configured the Alertmanager with webhook receiver let's add the rules to the Prometheus config.
+
+> prometheus.yml
+
+```yaml
+global:
+ scrape_interval: 15s
+ evaluation_interval: 10s
+rule_files:
+  - rules.yml
+alerting:
+  alertmanagers:
+  - static_configs:
+    - targets:
+       - localhost:9093
+scrape_configs:
+ - job_name: prometheus
+   static_configs:
+       - targets: ["localhost:9090"]
+ - job_name: simple_server
+   static_configs:
+       - targets: ["localhost:8090"]
+```
+
+If you notice the `evaluation_interval`,`rule_files` and `alerting` sections are added to the Prometheus config, the `evaluation_interval` defines the intervals at which the rules are evaluated, `rule_files` accepts an array of yaml files that defines the rules and the `alerting` section defines the Alertmanager configuration. As mentioned in the beginning of this tutorial we will create a basic rule where we want to
+raise an alert when the `ping_request_count` value is greater than 5.
+
+> rules.yml
+
+```yaml
+groups:
+ - name: Count greater than 5
+   rules:
+   - alert: CountGreaterThan5
+     expr: ping_request_count > 5
+     for: 10s
+```
+
+Now let's run Prometheus using the following command.
+
+`prometheus --config.file=./prometheus.yml`
+
+Open [http://localhost:9090/rules](http://localhost:9090/rules) in your browser to see the rules. Next run the instrumented ping server and visit the [http://localhost:8090/ping](http://localhost:8090/ping) endpoint and refresh the page atleast 6 times. You can check the ping count by navigating to [http://localhost:8090/metrics](http://localhost:8090/metrics) endpoint. To see the status of the alert visit [http://localhost:9090/alerts](http://localhost:9090/alerts). Once the condition `ping_request_count > 5` is true for more than 10s the `state` will become `FIRING`. Now if you navigate back to your `webhook.site` URL you will see the alert message.
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/xaMXVrle98M" frameborder="0" allowfullscreen></iframe>
+
+Similarly Alertmanager can be configured with other receivers to notify when an alert is firing.
diff --git a/docs/tutorials/getting_started.md b/docs/tutorials/getting_started.md
new file mode 100644
index 00000000..69fdc6e5
--- /dev/null
+++ b/docs/tutorials/getting_started.md
@@ -0,0 +1,104 @@
+---
+title: Getting Started with Prometheus
+sort_rank: 1
+---
+
+# What is Prometheus ?
+
+Prometheus is a system monitoring and alerting system. It was opensourced by SoundCloud in 2012 and is the second project both to join and to graduate within Cloud Native Computing Foundation after Kubernetes. Prometheus stores all metrics data as time series, i.e metrics information is stored along with the timestamp at which it was recorded, optional key-value pairs called as labels can also be stored along with metrics.
+# What are metrics and why is it important?
+
+Metrics in layperson terms is a standard for measurement. What we want to measure depends from application to application. For a web server it can be request times, for a database it can be CPU usage or number of active connections etc.
+
+Metrics play an important role in understanding why your application is working in a certain way. If you run a web application and someone comes up to you and says that the application is slow, you will need some information to find out what is happening with your application. For example the application can become slow when the number of requests are high. If you have the request count metric you can spot the reason and increase the number of servers to handle the heavy load. Whenever you are defining the metrics for your application you must put on your detective hat and ask this question **what all information will be important for me to debug if any issue occurs in my application?**
+
+# Basic Architecture of Prometheus
+
+The basic components of a Prometheus setup are:
+
+- Prometheus Server (the server which scrapes and stores the metrics data).
+- Targets to be scraped, for example an instrumented application that exposes its metrics, or an exporter that exposes metrics of another application.
+- Alertmanager to raise alerts based on preset rules.
+
+(Note: Apart from this Prometheus has push_gateway which is not covered here).
+
+[![Architecture](/assets/tutorial/architecture.png)](/assets/tutorial/architecture.png)
+
+Let's consider a web server as an example application and we want to extract a certain metric like the number of API calls processed by the web server. So we add certain instrumentation code using the Prometheus client library and expose the metrics information. Now that our web server exposes its metrics we can configure Prometheus to scrape it. Now Prometheus is configured to fetch the metrics from the web server which is listening on xyz IP address port 7500 at a specific time interval, say, every minute.
+
+At 11:00:00 when I make the server public for consumption, the application calculates the request count and exposes it, Prometheus simultaneously scrapes the count metric and stores the value as 0.
+
+By 11:01:00 one request is processed. The instrumentation logic in the server increments the count to 1. When Prometheus scrapes the metric the value of count is 1 now.
+
+By 11:02:00 two more requests are processed and the request count is 1+2 = 3 now. Similarly metrics are scraped and stored.
+
+The user can control the frequency at which metrics are scraped by Prometheus.
+
+| Time Stamp | Request Count (metric) |
+| ---------- | ---------------------- |
+| 11:00:00   | 0                      |
+| 11:01:00   | 1                      |
+| 11:02:00   | 3                      |
+
+(Note: This table is just a representation for understanding purposes. Prometheus doesn’t store the values in this exact format)
+
+Prometheus also has an API which allows to query metrics which have been stored by scraping. This API is used to query the metrics, create dashboards/charts on it etc. PromQL is used to query these metrics.
+
+A simple Line chart created on the Request Count metric will look like this
+
+[![Graph](/assets/tutorial/sample_graph.png)](/assets/tutorial/sample_graph.png)
+
+One can scrape multiple useful metrics to understand what is happening in the application and create multiple charts on them. Group the charts into a dashboard and use it to get an overview of the application.
+
+# Show me how it is done
+
+Let’s get our hands dirty and setup Prometheus. Prometheus is written using [Go](https://golang.org/) and all you need is the binary compiled for your operating system. Download the binary corresponding to your operating system from [here](https://prometheus.io/download/) and add the binary to your path.
+
+Prometheus exposes its own metrics which can be consumed by itself or another Prometheus server.
+
+Now that we have Prometheus installed, the next step is to run it. All that we need is just the binary and a configuration file. Prometheus uses yaml files for configuration.
+
+
+```yaml
+global:
+  scrape_interval: 15s
+
+scrape_configs:
+  - job_name: prometheus
+    static_configs:
+      - targets: ["localhost:9090"]
+```
+
+In the above configuration file we have mentioned the `scrape_interval`, i.e how frequently we want Prometheus to scrape the metrics. We have added `scrape_configs` which has a name and target to scrape the metrics from. Prometheus by default listens on port 9090. So add it to targets.
+
+> prometheus --config.file=prometheus.yml
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/ioa0eISf1Q0" frameborder="0" allowfullscreen></iframe>
+
+Now we have Prometheus up and running and scraping its own metrics every 15s. Prometheus has standard exporters available to export metrics. Next we will run a node exporter which is an exporter for machine metrics and scrape the same using Prometheus. ([Download node metrics exporter.](https://prometheus.io/download/#node_exporter))
+
+Run the node exporter in a terminal.
+
+<code>./node_exporter</code>
+
+[![Node exporter](/assets/tutorial/node_exporter.png)](/assets/tutorial/node_exporter.png)
+
+Next, add node exporter to the list of scrape_configs:
+
+```yaml
+global:
+  scrape_interval: 15s
+
+scrape_configs:
+  - job_name: prometheus
+    static_configs:
+      - targets: ["localhost:9090"]
+  - job_name: node_exporter
+    static_configs:
+      - targets: ["localhost:9100"]
+```
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/hM5bp53C7Y8" frameborder="0" allowfullscreen></iframe>
+
+In this tutorial we discussed what are metrics and why they are important, basic architecture of Prometheus and how to
+run Prometheus.
diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md
new file mode 100644
index 00000000..ad4fb3a3
--- /dev/null
+++ b/docs/tutorials/index.md
@@ -0,0 +1,5 @@
+---
+title: Tutorials
+sort_rank: 10
+nav_icon: book
+---
diff --git a/docs/tutorials/instrumenting_http_server_in_go.md b/docs/tutorials/instrumenting_http_server_in_go.md
new file mode 100644
index 00000000..9f95292f
--- /dev/null
+++ b/docs/tutorials/instrumenting_http_server_in_go.md
@@ -0,0 +1,146 @@
+---
+title: Instrumenting HTTP server written in Go  
+sort_rank: 3
+---
+
+In this tutorial we will create a simple Go HTTP server and instrumentation it by adding a counter
+metric to keep count of the total number of requests processed by the server.
+
+Here we have a simple HTTP server with `/ping` endpoint which returns `pong` as response.
+
+```go
+package main
+
+import (
+   "fmt"
+   "net/http"
+)
+
+func ping(w http.ResponseWriter, req *http.Request){
+   fmt.Fprintf(w,"pong")
+}
+
+func main() {
+   http.HandleFunc("/ping",ping)
+
+   http.ListenAndServe(":8090", nil)
+}
+```
+
+Compile and run the server
+
+```bash
+go build server.go
+./server
+```
+
+Now open `http://localhost:8090/ping` in your browser and you must see `pong`.
+
+[![Server](/assets/tutorial/server.png)](/assets/tutorial/server.png)
+
+
+Now lets add a metric to the server which will instrument the number of requests made to the ping endpoint,the counter metric type is suitable for this as we know the request count doesn’t go down and only increases.
+
+Create a Prometheus counter
+
+```go
+var pingCounter = prometheus.NewCounter(
+   prometheus.CounterOpts{
+       Name: "ping_request_count",
+       Help: "No of request handled by Ping handler",
+   },
+)
+```
+
+Next lets update the ping Handler to increase the count of the counter using `pingCounter.Inc()`.
+
+```go
+func ping(w http.ResponseWriter, req *http.Request) {
+   pingCounter.Inc()
+   fmt.Fprintf(w, "pong")
+}
+```
+
+Then register the counter to the Default Register and expose the metrics.
+
+```go
+func main() {
+   prometheus.MustRegister(pingCounter)
+   http.HandleFunc("/ping", ping)
+   http.Handle("/metrics", promhttp.Handler())
+   http.ListenAndServe(":8090", nil)
+}
+```
+
+The `prometheus.MustRegister` function registers the pingCounter to the default Register.
+To expose the metrics the Go Prometheus client library provides the promhttp package.
+`promhttp.Handler()` provides a `http.Handler` which exposes the metrics registered in the Default Register.
+
+The sample code depends on the  
+
+```go
+package main
+
+import (
+   "fmt"
+   "net/http"
+
+   "github.com/prometheus/client_golang/prometheus"
+   "github.com/prometheus/client_golang/prometheus/promhttp"
+)
+
+var pingCounter = prometheus.NewCounter(
+   prometheus.CounterOpts{
+       Name: "ping_request_count",
+       Help: "No of request handled by Ping handler",
+   },
+)
+
+func ping(w http.ResponseWriter, req *http.Request) {
+   pingCounter.Inc()
+   fmt.Fprintf(w, "pong")
+}
+
+func main() {
+   prometheus.MustRegister(pingCounter)
+
+   http.HandleFunc("/ping", ping)
+   http.Handle("/metrics", promhttp.Handler())
+   http.ListenAndServe(":8090", nil)
+}
+```
+
+Run the example
+
+```sh
+go mod init prom_example
+go mod tidy
+go run server.go
+```
+
+Now hit the localhost:8090/ping endpoint a couple of times and sending a request to localhost:8090 will provide the metrics.
+
+[![Ping Metric](/assets/tutorial/ping_metric.png)](/assets/tutorial/ping_metric.png)
+
+Here the `ping_request_count` shows that `/ping` endpoint was called 3 times.
+
+The Default Register comes with a collector for go runtime metrics and that is why we see other metrics like `go_threads`, `go_goroutines` etc.
+
+We have built our first metric exporter. Let’s update our Prometheus config to scrape the metrics from our server.
+
+```yaml
+global:
+  scrape_interval: 15s
+
+scrape_configs:
+  - job_name: prometheus
+    static_configs:
+      - targets: ["localhost:9090"]
+  - job_name: simple_server
+    static_configs:
+      - targets: ["localhost:8090"]
+```
+
+<code>prometheus --config.file=prometheus.yml</code>
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/yQIWgZoiW0o" frameborder="0" allowfullscreen></iframe>
diff --git a/docs/tutorials/understanding_metric_types.md b/docs/tutorials/understanding_metric_types.md
new file mode 100644
index 00000000..5a016092
--- /dev/null
+++ b/docs/tutorials/understanding_metric_types.md
@@ -0,0 +1,100 @@
+---
+title: Understanding metric types  
+sort_rank: 2
+---
+
+# Types of metrics.
+
+Prometheus supports four types of metrics, which are
+    - Counter
+    - Gauge
+    - Histogram
+    - Summary 
+
+## Counter
+
+Counter is a metric value that can only increase or reset i.e. the value cannot reduce than the previous value. It can be used for metrics like the number of requests, no of errors, etc.
+
+Type the below query in the query bar and click execute.
+
+<code>go\_gc\_duration\_seconds\_count</code>
+
+
+[![Counter](/assets/tutorial/counter_example.png)](/assets/tutorial/counter_example.png)
+
+The rate() function in PromQL takes the history of metrics over a time frame and calculates how fast the value is increasing per second. Rate is applicable on counter values only.
+
+<code> rate(go\_gc\_duration\_seconds\_count[5m])</code>
+[![Rate Counter](/assets/tutorial/rate_example.png)](/assets/tutorial/rate_example.png)
+
+## Gauge
+
+Gauge is a number which can either go up or down. It can be used for metrics like the number of pods in a cluster, the number of events in a queue, etc.
+
+<code> go\_memstats\_heap\_alloc\_bytes</code>
+[![Gauge](/assets/tutorial/gauge_example.png)](/assets/tutorial/gauge_example.png)
+
+PromQL functions like `max_over_time`, `min_over_time` and `avg_over_time` can be used on gauge metrics
+
+## Histogram
+
+Histogram is a more complex metric type when compared to the previous two. Histogram can be used for any calculated value which is counted based on bucket values. Bucket boundaries can be configured by the developer. A common example would be the time it takes to reply to a request, called latency.
+
+Example: Let's assume we want to observe the time taken to process API requests. Instead of storing the request time for each request, histograms allow us to store them in buckets. We define buckets for time taken, for example `lower or equal 0.3`, `le 0.5`, `le 0.7`, `le 1`, and `le 1.2`. So these are our buckets and once the time taken for a request is calculated it is added to the count of all the buckets whose bucket boundaries are higher than the measured value.
+
+Let's say Request 1 for endpoint “/ping” takes 0.25 s. The count values for the buckets will be.
+
+> /ping
+
+| Bucket    | Count |
+| --------- | ----- |
+| 0 - 0.3   | 1     |
+| 0 - 0.5   | 1     |
+| 0 - 0.7   | 1     |
+| 0 - 1     | 1     |
+| 0 - 1.2   | 1     |
+| 0 - +Inf  | 1     |
+
+Note: +Inf bucket is added by default.
+
+(Since the histogram is a cumulative frequency 1 is added to all the buckets that are greater than the value)
+
+Request 2 for endpoint “/ping” takes 0.4s The count values for the buckets will be this.
+
+> /ping
+
+| Bucket    | Count |
+| --------- | ----- |
+| 0 - 0.3   | 1     |
+| 0 - 0.5   | 2     |
+| 0 - 0.7   | 2     |
+| 0 - 1     | 2     |
+| 0 - 1.2   | 2     |
+| 0 - +Inf  | 2     |
+
+Since 0.4 is below 0.5, all buckets up to that boundary increase their counts.
+
+Let's explore a histogram metric from the Prometheus UI and apply a few functions.
+
+<code>prometheus\_http\_request\_duration\_seconds\_bucket{handler="/graph"}</code>
+
+[![Histogram](/assets/tutorial/histogram_example.png)](/assets/tutorial/histogram_example.png)
+
+`histogram_quantile()` function can be used to calculate quantiles from a histogram
+
+<code>histogram\_quantile(0.9,prometheus\_http\_request\_duration\_seconds\_bucket{handler="/graph"})</code>
+
+[![Histogram Quantile](/assets/tutorial/histogram_quantile_example.png)](/assets/tutorial/histogram_quantile_example.png)
+
+The graph shows that the 90th percentile is 0.09, To find the histogram_quantile over the last 5m you can use the rate() and time frame
+
+<code>histogram_quantile(0.9, rate(prometheus\_http\_request\_duration\_seconds\_bucket{handler="/graph"}[5m]))</code>
+
+[![Histogram Quantile Rate](/assets/tutorial/histogram_rate_example.png)](/assets/tutorial/histogram_rate_example.png)
+
+
+## Summary
+
+Summaries also measure events and are an alternative to histograms. They are cheaper but lose more data. They are calculated on the application level hence aggregation of metrics from multiple instances of the same process is not possible. They are used when the buckets of a metric are not known beforehand, but it is highly recommended to use histograms over summaries whenever possible.
+
+In this tutorial, we covered the types of metrics in detail and a few PromQL operations like rate, histogram_quantile, etc.
diff --git a/docs/tutorials/visualizing_metrics_using_grafana.md b/docs/tutorials/visualizing_metrics_using_grafana.md
new file mode 100644
index 00000000..4002e8a7
--- /dev/null
+++ b/docs/tutorials/visualizing_metrics_using_grafana.md
@@ -0,0 +1,43 @@
+---
+title: Visualizing metrics using Grafana
+sort_rank: 4
+---
+
+# Visualizing metrics.
+
+In this tutorial we will create a simple dashboard using [Grafana](https://github.com/grafana/grafana) to visualize the `ping_request_count` metric that we instrumented in the [previous tutorial](../instrumenting_http_server_in_go).
+
+If you are wondering why one should use a tool like Grafana when one can query and see the graphs using Prometheus, the answer is that the graph that we see when we run queries on Prometheus is to run ad-hoc queries. 
+Grafana and [Console Templates](https://prometheus.io/docs/visualization/consoles/) are two recommended ways of creating graphs.
+
+
+## Installing and Setting up Grafana.
+
+Install and Run Grafana by following the steps from [here](https://grafana.com/docs/grafana/latest/installation/requirements/#supported-operating-systems) for your operating system.
+
+Once Grafana is installed and run, navigate to [http://localhost:3000](http://localhost:3000) in your browser. Use the default credentials, username as `admin` and password as `admin` to log in and setup new credentials.
+
+
+## Adding Prometheus as a Data Source in Grafana.
+Let's add a datasource to Grafana by clicking on the gear icon in the side bar and select `Data Sources`
+> ⚙ > Data Sources
+
+In the Data Sources screen you can see that Grafana supports multiple data sources like Graphite, PostgreSQL etc. Select Prometheus to set it up.
+
+Enter the URL as [http://localhost:9090](http://localhost:9090) under the HTTP section and click on `Save and Test`.
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/QT66dU_h9lo" frameborder="0" allowfullscreen></iframe>
+
+## Creating our first dashboard.
+
+Now we have successfully added Prometheus as a data source, Next we will create our first dashboard for the `ping_request_count` metric that we instrumented in the previous tutorial.
+
+1. Click on the `+` icon in the side bar and select `Dashboard`.
+2. In the next screen, Click on the `Add new panel` button.
+3. In the `Query` tab type the PromQL query, in this case just type `ping_request_count`.
+4. Access the `ping` endpoint few times and refresh the Graph to verify if it is working as expected.
+4. In the right hand section under `Panel Options` set the `Title` as `Ping Request Count`.
+5. Click on the Save Icon in the right corner to Save the dashboard.
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/giVZHO6akRA" frameborder="0" allowfullscreen></iframe>
+
diff --git a/docs/visualization/browser.md b/docs/visualization/browser.md
new file mode 100644
index 00000000..36a2f012
--- /dev/null
+++ b/docs/visualization/browser.md
@@ -0,0 +1,12 @@
+---
+title: Expression browser
+sort_rank: 1
+---
+
+# Expression browser
+
+The expression browser is available at `/graph` on the Prometheus server, allowing you
+to enter any expression and see its result either in a table or graphed over time.
+
+This is primarily useful for ad-hoc queries and debugging. For graphs, use
+[Grafana](/docs/visualization/grafana/) or [Console templates](/docs/visualization/consoles/).
diff --git a/docs/visualization/consoles.md b/docs/visualization/consoles.md
new file mode 100644
index 00000000..47118f59
--- /dev/null
+++ b/docs/visualization/consoles.md
@@ -0,0 +1,176 @@
+---
+title: Console templates
+sort_rank: 3
+---
+
+# Console templates
+
+Console templates allow for creation of arbitrary consoles using the [Go
+templating language](http://golang.org/pkg/text/template/). These are served
+from the Prometheus server.
+
+Console templates are the most powerful way to create templates that can be
+easily managed in source control. There is a learning curve though, so users new
+to this style of monitoring should try out
+[Grafana](/docs/visualization/grafana/) first.
+
+## Getting started
+
+Prometheus comes with an example set of consoles to get you going. These can be
+found at `/consoles/index.html.example` on a running Prometheus and will
+display Node Exporter consoles if Prometheus is scraping Node Exporters with a
+`job="node"` label.
+
+The example consoles have 5 parts:
+
+1. A navigation bar on top
+1. A menu on the left
+1. Time controls on the bottom
+1. The main content in the center, usually graphs
+1. A table on the right
+
+The navigation bar is for links to other systems, such as other Prometheis
+<sup>[1](/docs/introduction/faq/#what-is-the-plural-of-prometheus)</sup>,
+documentation, and whatever else makes sense to you. The menu is for navigation
+inside the same Prometheus server, which is very useful to be able to quickly
+open a console in another tab to correlate information. Both are configured in
+`console_libraries/menu.lib`.
+
+The time controls allow changing of the duration and range of the graphs.
+Console URLs can be shared and will show the same graphs for others.
+
+The main content is usually graphs. There is a configurable JavaScript graphing
+library provided that will handle requesting data from Prometheus, and rendering
+it via [Rickshaw](https://shutterstock.github.io/rickshaw/).
+
+Finally, the table on the right can be used to display statistics in a more
+compact form than graphs.
+
+## Example Console
+
+This is a basic console. It shows the number of tasks, how many of them are up,
+the average CPU usage, and the average memory usage in the right-hand-side
+table. The main content has a queries-per-second graph.
+
+```
+{{template "head" .}}
+
+{{template "prom_right_table_head"}}
+<tr>
+  <th>MyJob</th>
+  <th>{{ template "prom_query_drilldown" (args "sum(up{job='myjob'})") }}
+      / {{ template "prom_query_drilldown" (args "count(up{job='myjob'})") }}
+  </th>
+</tr>
+<tr>
+  <td>CPU</td>
+  <td>{{ template "prom_query_drilldown" (args
+      "avg by(job)(rate(process_cpu_seconds_total{job='myjob'}[5m]))"
+      "s/s" "humanizeNoSmallPrefix") }}
+  </td>
+</tr>
+<tr>
+  <td>Memory</td>
+  <td>{{ template "prom_query_drilldown" (args
+       "avg by(job)(process_resident_memory_bytes{job='myjob'})"
+       "B" "humanize1024") }}
+  </td>
+</tr>
+{{template "prom_right_table_tail"}}
+
+
+{{template "prom_content_head" .}}
+<h1>MyJob</h1>
+
+<h3>Queries</h3>
+<div id="queryGraph"></div>
+<script>
+new PromConsole.Graph({
+  node: document.querySelector("#queryGraph"),
+  expr: "sum(rate(http_query_count{job='myjob'}[5m]))",
+  name: "Queries",
+  yAxisFormatter: PromConsole.NumberFormatter.humanizeNoSmallPrefix,
+  yHoverFormatter: PromConsole.NumberFormatter.humanizeNoSmallPrefix,
+  yUnits: "/s",
+  yTitle: "Queries"
+})
+</script>
+
+{{template "prom_content_tail" .}}
+
+{{template "tail"}}
+```
+
+The `prom_right_table_head` and `prom_right_table_tail` templates contain the
+right-hand-side table. This is optional.
+
+`prom_query_drilldown` is a template that will evaluate the expression passed to it, format it,
+and link to the expression in the [expression browser](/docs/visualization/browser/). The first
+argument is the expression. The second argument is the unit to use. The third
+argument is how to format the output. Only the first argument is required.
+
+Valid output formats for the third argument to `prom_query_drilldown`:
+
+* Not specified: Default Go display output.
+* `humanize`: Display the result using [metric prefixes](http://en.wikipedia.org/wiki/Metric_prefix).
+* `humanizeNoSmallPrefix`: For absolute values greater than 1, display the
+  result using [metric prefixes](http://en.wikipedia.org/wiki/Metric_prefix). For
+  absolute values less than 1, display 3 significant digits. This is useful
+  to avoid units such as milliqueries per second that can be produced by
+  `humanize`.
+* `humanize1024`: Display the humanized result using a base of 1024 rather than 1000.
+  This is usually used with `B` as the second argument to produce units such as `KiB` and `MiB`.
+* `printf.3g`: Display 3 significant digits.
+
+Custom formats can be defined. See
+[prom.lib](https://github.com/prometheus/prometheus/blob/main/console_libraries/prom.lib) for examples.
+
+## Graph Library
+
+The graph library is invoked as:
+
+```
+<div id="queryGraph"></div>
+<script>
+new PromConsole.Graph({
+  node: document.querySelector("#queryGraph"),
+  expr: "sum(rate(http_query_count{job='myjob'}[5m]))"
+})
+</script>
+```
+
+The `head` template loads the required Javascript and CSS.
+
+Parameters to the graph library:
+
+| Name          | Description
+| ------------- | -------------
+| expr          | Required. Expression to graph. Can be a list.
+| node          | Required. DOM node to render into.
+| duration      | Optional. Duration of the graph. Defaults to 1 hour.
+| endTime       | Optional. Unixtime the graph ends at. Defaults to now.
+| width         | Optional. Width of the graph, excluding titles. Defaults to auto-detection.
+| height        | Optional. Height of the graph, excluding titles and legends. Defaults to 200 pixels.
+| min           | Optional. Minimum x-axis value. Defaults to lowest data value.
+| max           | Optional. Maximum y-axis value. Defaults to highest data value.
+| renderer      | Optional. Type of graph. Options are `line` and `area` (stacked graph). Defaults to `line`.
+| name          | Optional. Title of plots in legend and hover detail. If passed a string, `[[ label ]]` will be substituted with the label value. If passed a function, it will be passed a map of labels and should return the name as a string. Can be a list.
+| xTitle        | Optional. Title of the x-axis. Defaults to `Time`.
+| yUnits        | Optional. Units of the y-axis. Defaults to empty.
+| yTitle        | Optional. Title of the y-axis. Defaults to empty.
+| yAxisFormatter | Optional. Number formatter for the y-axis. Defaults to `PromConsole.NumberFormatter.humanize`.
+| yHoverFormatter | Optional. Number formatter for the hover detail. Defaults to `PromConsole.NumberFormatter.humanizeExact`.
+| colorScheme   | Optional. Color scheme to be used by the plots. Can be either a list of hex color codes or one of the [color scheme names](https://github.com/shutterstock/rickshaw/blob/master/src/js/Rickshaw.Fixtures.Color.js) supported by Rickshaw. Defaults to `'colorwheel'`.
+
+If both `expr` and `name` are lists, they must be of the same length. The name
+will be applied to the plots for the corresponding expression.
+
+Valid options for the `yAxisFormatter` and `yHoverFormatter`:
+
+* `PromConsole.NumberFormatter.humanize`: Format using [metric prefixes](http://en.wikipedia.org/wiki/Metric_prefix).
+* `PromConsole.NumberFormatter.humanizeNoSmallPrefix`: For absolute values
+  greater than 1, format using using [metric prefixes](http://en.wikipedia.org/wiki/Metric_prefix).
+  For absolute values less than 1, format with 3 significant digits. This is
+  useful to avoid units such as milliqueries per second that can be produced by
+  `PromConsole.NumberFormatter.humanize`.
+* `PromConsole.NumberFormatter.humanize1024`: Format the humanized result using a base of 1024 rather than 1000.
diff --git a/docs/visualization/grafana.md b/docs/visualization/grafana.md
new file mode 100644
index 00000000..1049c4b7
--- /dev/null
+++ b/docs/visualization/grafana.md
@@ -0,0 +1,73 @@
+---
+title: Grafana
+sort_rank: 2
+---
+
+# Grafana support for Prometheus
+
+[Grafana](http://grafana.com/) supports querying Prometheus.
+The Grafana data source for Prometheus is included since Grafana 2.5.0 (2015-10-28).
+
+The following shows an example Grafana dashboard which queries Prometheus for data:
+
+[![Grafana screenshot](/assets/grafana_prometheus.png)](/assets/grafana_prometheus.png)
+
+## Installing
+
+To install Grafana see the [official Grafana
+documentation](https://grafana.com/grafana/download/).
+
+## Using
+
+By default, Grafana will be listening on
+[http://localhost:3000](http://localhost:3000). The default login is "admin" /
+"admin".
+
+### Creating a Prometheus data source
+
+To create a Prometheus data source in Grafana:
+
+1. Click on the "cogwheel" in the sidebar to open the Configuration menu.
+2. Click on "Data Sources".
+3. Click on "Add data source".
+4. Select "Prometheus" as the type.
+5. Set the appropriate Prometheus server URL (for example, `http://localhost:9090/`)
+6. Adjust other data source settings as desired (for example, choosing the right Access method).
+7. Click "Save & Test" to save the new data source.
+
+The following shows an example data source configuration:
+
+[![Data source configuration](/assets/grafana_configuring_datasource.png)](/assets/grafana_configuring_datasource.png)
+
+### Creating a Prometheus graph
+
+Follow the standard way of adding a new Grafana graph. Then:
+
+1. Click the graph title, then click "Edit".
+2. Under the "Metrics" tab, select your Prometheus data source (bottom right).
+3. Enter any Prometheus expression into the "Query" field, while using the
+   "Metric" field to lookup metrics via autocompletion.
+4. To format the legend names of time series, use the "Legend format" input. For
+   example, to show only the `method` and `status` labels of a returned query
+   result, separated by a dash, you could use the legend format string
+   `{{method}} - {{status}}`.
+5. Tune other graph settings until you have a working graph.
+
+The following shows an example Prometheus graph configuration:
+[![Prometheus graph creation](/assets/grafana_qps_graph.png)](/assets/grafana_qps_graph.png)
+
+In Grafana 7.2 and later, the `$__rate_interval` variable is
+[recommended](https://grafana.com/docs/grafana/latest/datasources/prometheus/#using-__rate_interval)
+for use in the `rate`and `increase` functions.
+
+### Importing pre-built dashboards from Grafana.com
+
+Grafana.com maintains [a collection of shared dashboards](https://grafana.com/dashboards)
+which can be downloaded and used with standalone instances of Grafana.  Use
+the Grafana.com "Filter" option to browse dashboards for the "Prometheus"
+data source only.
+
+You must currently manually edit the downloaded JSON files and correct the
+`datasource:` entries to reflect the Grafana data source name which you
+chose for your Prometheus server.  Use the "Dashboards" → "Home" → "Import"
+option to import the edited dashboard file into your Grafana install.
diff --git a/docs/visualization/index.md b/docs/visualization/index.md
new file mode 100644
index 00000000..7ad4e18d
--- /dev/null
+++ b/docs/visualization/index.md
@@ -0,0 +1,5 @@
+---
+title: Visualization
+sort_rank: 4
+nav_icon: chart-line
+---
diff --git a/eslint.config.mjs b/eslint.config.mjs
index c85fb67c..3b910158 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -11,6 +11,11 @@ const compat = new FlatCompat({
 
 const eslintConfig = [
   ...compat.extends("next/core-web-vitals", "next/typescript"),
+  {
+    rules: {
+      "@next/next/no-img-element": "off",
+    },
+  },
 ];
 
 export default eslintConfig;
diff --git a/next.config.ts b/next.config.ts
index e9ffa308..53433574 100644
--- a/next.config.ts
+++ b/next.config.ts
@@ -1,7 +1,13 @@
 import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
-  /* config options here */
+  output: "export",
+  // Optional: Change links `/me` -> `/me/` and emit `/me.html` -> `/me/index.html`
+  // trailingSlash: true,
+  // Optional: Prevent automatic `/me` -> `/me/`, instead preserve `href`
+  // skipTrailingSlashRedirect: true,
+  // Optional: Change the output directory `out` -> `dist`
+  // distDir: 'dist',
 };
 
 export default nextConfig;
diff --git a/package-lock.json b/package-lock.json
index e31a4504..0e76614f 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -8,20 +8,50 @@
       "name": "prometheus-next",
       "version": "0.1.0",
       "dependencies": {
+        "@mantine/code-highlight": "^8.0.0",
+        "@mantine/core": "^8.0.0",
+        "@mantine/hooks": "^8.0.0",
+        "@tabler/icons-react": "^3.31.0",
+        "gray-matter": "^4.0.3",
+        "hast-util-from-html": "^2.0.3",
+        "hast-util-select": "^6.0.4",
+        "hastscript": "^9.0.1",
         "next": "15.3.1",
+        "octokit": "^4.1.3",
         "react": "^19.0.0",
-        "react-dom": "^19.0.0"
+        "react-dom": "^19.0.0",
+        "react-markdown": "^10.1.0",
+        "rehype-autolink-headings": "^7.1.0",
+        "rehype-slug": "^6.0.0",
+        "remark-frontmatter": "^5.0.0",
+        "remark-gfm": "^4.0.1",
+        "shiki": "^3.4.0"
       },
       "devDependencies": {
         "@eslint/eslintrc": "^3",
+        "@shikijs/rehype": "^3.4.0",
         "@types/node": "^20",
         "@types/react": "^19",
         "@types/react-dom": "^19",
+        "dotenv": "^16.5.0",
         "eslint": "^9",
         "eslint-config-next": "15.3.1",
+        "postcss": "^8.5.3",
+        "postcss-preset-mantine": "^1.17.0",
+        "postcss-simple-vars": "^7.0.1",
+        "tsx": "^4.19.4",
         "typescript": "^5"
       }
     },
+    "node_modules/@babel/runtime": {
+      "version": "7.27.1",
+      "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.27.1.tgz",
+      "integrity": "sha512-1x3D2xEk2fRo3PAhwQwu5UubzgiVWSXTBfWpVd2Mx2AzRqJuDJCsgaDVZ7HB5iGzDW1Hl1sWN2mFyKjmR9uAog==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
     "node_modules/@emnapi/core": {
       "version": "1.4.3",
       "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.4.3.tgz",
@@ -55,6 +85,431 @@
         "tslib": "^2.4.0"
       }
     },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.4.tgz",
+      "integrity": "sha512-1VCICWypeQKhVbE9oW/sJaAmjLxhVqacdkvPLEjwlttjfwENRSClS8EjBz0KzRyFSCPDIkuXW34Je/vk7zdB7Q==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.25.4.tgz",
+      "integrity": "sha512-QNdQEps7DfFwE3hXiU4BZeOV68HHzYwGd0Nthhd3uCkkEKK7/R6MTgM0P7H7FAs5pU/DIWsviMmEGxEoxIZ+ZQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.25.4.tgz",
+      "integrity": "sha512-bBy69pgfhMGtCnwpC/x5QhfxAz/cBgQ9enbtwjf6V9lnPI/hMyT9iWpR1arm0l3kttTr4L0KSLpKmLp/ilKS9A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.25.4.tgz",
+      "integrity": "sha512-TVhdVtQIFuVpIIR282btcGC2oGQoSfZfmBdTip2anCaVYcqWlZXGcdcKIUklfX2wj0JklNYgz39OBqh2cqXvcQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.25.4.tgz",
+      "integrity": "sha512-Y1giCfM4nlHDWEfSckMzeWNdQS31BQGs9/rouw6Ub91tkK79aIMTH3q9xHvzH8d0wDru5Ci0kWB8b3up/nl16g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.25.4.tgz",
+      "integrity": "sha512-CJsry8ZGM5VFVeyUYB3cdKpd/H69PYez4eJh1W/t38vzutdjEjtP7hB6eLKBoOdxcAlCtEYHzQ/PJ/oU9I4u0A==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.25.4.tgz",
+      "integrity": "sha512-yYq+39NlTRzU2XmoPW4l5Ifpl9fqSk0nAJYM/V/WUGPEFfek1epLHJIkTQM6bBs1swApjO5nWgvr843g6TjxuQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.25.4.tgz",
+      "integrity": "sha512-0FgvOJ6UUMflsHSPLzdfDnnBBVoCDtBTVyn/MrWloUNvq/5SFmh13l3dvgRPkDihRxb77Y17MbqbCAa2strMQQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.25.4.tgz",
+      "integrity": "sha512-kro4c0P85GMfFYqW4TWOpvmF8rFShbWGnrLqlzp4X1TNWjRY3JMYUfDCtOxPKOIY8B0WC8HN51hGP4I4hz4AaQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.25.4.tgz",
+      "integrity": "sha512-+89UsQTfXdmjIvZS6nUnOOLoXnkUTB9hR5QAeLrQdzOSWZvNSAXAtcRDHWtqAUtAmv7ZM1WPOOeSxDzzzMogiQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.25.4.tgz",
+      "integrity": "sha512-yTEjoapy8UP3rv8dB0ip3AfMpRbyhSN3+hY8mo/i4QXFeDxmiYbEKp3ZRjBKcOP862Ua4b1PDfwlvbuwY7hIGQ==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.25.4.tgz",
+      "integrity": "sha512-NeqqYkrcGzFwi6CGRGNMOjWGGSYOpqwCjS9fvaUlX5s3zwOtn1qwg1s2iE2svBe4Q/YOG1q6875lcAoQK/F4VA==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.25.4.tgz",
+      "integrity": "sha512-IcvTlF9dtLrfL/M8WgNI/qJYBENP3ekgsHbYUIzEzq5XJzzVEV/fXY9WFPfEEXmu3ck2qJP8LG/p3Q8f7Zc2Xg==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.25.4.tgz",
+      "integrity": "sha512-HOy0aLTJTVtoTeGZh4HSXaO6M95qu4k5lJcH4gxv56iaycfz1S8GO/5Jh6X4Y1YiI0h7cRyLi+HixMR+88swag==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.25.4.tgz",
+      "integrity": "sha512-i8JUDAufpz9jOzo4yIShCTcXzS07vEgWzyX3NH2G7LEFVgrLEhjwL3ajFE4fZI3I4ZgiM7JH3GQ7ReObROvSUA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.25.4.tgz",
+      "integrity": "sha512-jFnu+6UbLlzIjPQpWCNh5QtrcNfMLjgIavnwPQAfoGx4q17ocOU9MsQ2QVvFxwQoWpZT8DvTLooTvmOQXkO51g==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.25.4.tgz",
+      "integrity": "sha512-6e0cvXwzOnVWJHq+mskP8DNSrKBr1bULBvnFLpc1KY+d+irZSgZ02TGse5FsafKS5jg2e4pbvK6TPXaF/A6+CA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.25.4.tgz",
+      "integrity": "sha512-vUnkBYxZW4hL/ie91hSqaSNjulOnYXE1VSLusnvHg2u3jewJBz3YzB9+oCw8DABeVqZGg94t9tyZFoHma8gWZQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.25.4.tgz",
+      "integrity": "sha512-XAg8pIQn5CzhOB8odIcAm42QsOfa98SBeKUdo4xa8OvX8LbMZqEtgeWE9P/Wxt7MlG2QqvjGths+nq48TrUiKw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.25.4.tgz",
+      "integrity": "sha512-Ct2WcFEANlFDtp1nVAXSNBPDxyU+j7+tId//iHXU2f/lN5AmO4zLyhDcpR5Cz1r08mVxzt3Jpyt4PmXQ1O6+7A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.25.4.tgz",
+      "integrity": "sha512-xAGGhyOQ9Otm1Xu8NT1ifGLnA6M3sJxZ6ixylb+vIUVzvvd6GOALpwQrYrtlPouMqd/vSbgehz6HaVk4+7Afhw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.25.4.tgz",
+      "integrity": "sha512-Mw+tzy4pp6wZEK0+Lwr76pWLjrtjmJyUB23tHKqEDP74R3q95luY/bXqXZeYl4NYlvwOqoRKlInQialgCKy67Q==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.25.4.tgz",
+      "integrity": "sha512-AVUP428VQTSddguz9dO9ngb+E5aScyg7nOeJDrF1HPYu555gmza3bDGMPhmVXL8svDSoqPCsCPjb265yG/kLKQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.25.4.tgz",
+      "integrity": "sha512-i1sW+1i+oWvQzSgfRcxxG2k4I9n3O9NRqy8U+uugaT2Dy7kLO9Y7wI72haOahxceMX8hZAzgGou1FhndRldxRg==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.25.4.tgz",
+      "integrity": "sha512-nOT2vZNw6hJ+z43oP1SPea/G/6AbN6X+bGNhNuq8NtRHy4wsMhw765IKLNmnjek7GvjWBYQ8Q5VBoYTFg9y1UQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/@eslint-community/eslint-utils": {
       "version": "4.7.0",
       "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.7.0.tgz",
@@ -193,6 +648,59 @@
         "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
       }
     },
+    "node_modules/@floating-ui/core": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/@floating-ui/core/-/core-1.7.0.tgz",
+      "integrity": "sha512-FRdBLykrPPA6P76GGGqlex/e7fbe0F1ykgxHYNXQsH/iTEtjMj/f9bpY5oQqbjt5VgZvgz/uKXbGuROijh3VLA==",
+      "license": "MIT",
+      "dependencies": {
+        "@floating-ui/utils": "^0.2.9"
+      }
+    },
+    "node_modules/@floating-ui/dom": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/@floating-ui/dom/-/dom-1.7.0.tgz",
+      "integrity": "sha512-lGTor4VlXcesUMh1cupTUTDoCxMb0V6bm3CnxHzQcw8Eaf1jQbgQX4i02fYgT0vJ82tb5MZ4CZk1LRGkktJCzg==",
+      "license": "MIT",
+      "dependencies": {
+        "@floating-ui/core": "^1.7.0",
+        "@floating-ui/utils": "^0.2.9"
+      }
+    },
+    "node_modules/@floating-ui/react": {
+      "version": "0.26.28",
+      "resolved": "https://registry.npmjs.org/@floating-ui/react/-/react-0.26.28.tgz",
+      "integrity": "sha512-yORQuuAtVpiRjpMhdc0wJj06b9JFjrYF4qp96j++v2NBpbi6SEGF7donUJ3TMieerQ6qVkAv1tgr7L4r5roTqw==",
+      "license": "MIT",
+      "dependencies": {
+        "@floating-ui/react-dom": "^2.1.2",
+        "@floating-ui/utils": "^0.2.8",
+        "tabbable": "^6.0.0"
+      },
+      "peerDependencies": {
+        "react": ">=16.8.0",
+        "react-dom": ">=16.8.0"
+      }
+    },
+    "node_modules/@floating-ui/react-dom": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/@floating-ui/react-dom/-/react-dom-2.1.2.tgz",
+      "integrity": "sha512-06okr5cgPzMNBy+Ycse2A6udMi4bqwW/zgBF/rwjcNqWkyr82Mcg8b0vjX8OJpZFy/FKjJmw6wV7t44kK6kW7A==",
+      "license": "MIT",
+      "dependencies": {
+        "@floating-ui/dom": "^1.0.0"
+      },
+      "peerDependencies": {
+        "react": ">=16.8.0",
+        "react-dom": ">=16.8.0"
+      }
+    },
+    "node_modules/@floating-ui/utils": {
+      "version": "0.2.9",
+      "resolved": "https://registry.npmjs.org/@floating-ui/utils/-/utils-0.2.9.tgz",
+      "integrity": "sha512-MDWhGtE+eHw5JW7lq4qhc5yRLS11ERl1c7Z6Xd0a58DozHES6EnNNwUWbMiG4J9Cgj053Bhk8zvlhFYKVhULwg==",
+      "license": "MIT"
+    },
     "node_modules/@humanfs/core": {
       "version": "0.19.1",
       "resolved": "https://registry.npmjs.org/@humanfs/core/-/core-0.19.1.tgz",
@@ -636,6 +1144,50 @@
         "url": "https://opencollective.com/libvips"
       }
     },
+    "node_modules/@mantine/code-highlight": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/@mantine/code-highlight/-/code-highlight-8.0.0.tgz",
+      "integrity": "sha512-vYMBRWRXpUwLdDbpdPiCwXJ75uXi9gIWWcgbiRiFysglFzO5VhGhnyXYtCocIdqRyQAZLfhz6Q0mYWzqJ3XgmQ==",
+      "license": "MIT",
+      "dependencies": {
+        "clsx": "^2.1.1",
+        "highlight.js": "^11.10.0"
+      },
+      "peerDependencies": {
+        "@mantine/core": "8.0.0",
+        "@mantine/hooks": "8.0.0",
+        "react": "^18.x || ^19.x",
+        "react-dom": "^18.x || ^19.x"
+      }
+    },
+    "node_modules/@mantine/core": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/@mantine/core/-/core-8.0.0.tgz",
+      "integrity": "sha512-TskeJS2/+DbmUe85fXDoUAyErkSvR4YlbUl8MLqhjFBJUqwc72ZrLynmN13wuKtlVPakDYYjq4/IEDMReh3CYA==",
+      "license": "MIT",
+      "dependencies": {
+        "@floating-ui/react": "^0.26.28",
+        "clsx": "^2.1.1",
+        "react-number-format": "^5.4.3",
+        "react-remove-scroll": "^2.6.2",
+        "react-textarea-autosize": "8.5.9",
+        "type-fest": "^4.27.0"
+      },
+      "peerDependencies": {
+        "@mantine/hooks": "8.0.0",
+        "react": "^18.x || ^19.x",
+        "react-dom": "^18.x || ^19.x"
+      }
+    },
+    "node_modules/@mantine/hooks": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/@mantine/hooks/-/hooks-8.0.0.tgz",
+      "integrity": "sha512-hrcgZMHUPsgu+VBfUVcJOqMG7Qi+AshYjFyc/qo0Cz8TEhqWmD0I1yJW+qj4sDTTDWRQC6kvI5c1h+87/9MvoA==",
+      "license": "MIT",
+      "peerDependencies": {
+        "react": "^18.x || ^19.x"
+      }
+    },
     "node_modules/@modelcontextprotocol/sdk": {
       "version": "1.11.0",
       "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.11.0.tgz",
@@ -863,6 +1415,347 @@
         "node": ">=12.4.0"
       }
     },
+    "node_modules/@octokit/app": {
+      "version": "15.1.6",
+      "resolved": "https://registry.npmjs.org/@octokit/app/-/app-15.1.6.tgz",
+      "integrity": "sha512-WELCamoCJo9SN0lf3SWZccf68CF0sBNPQuLYmZ/n87p5qvBJDe9aBtr5dHkh7T9nxWZ608pizwsUbypSzZAiUw==",
+      "license": "MIT",
+      "dependencies": {
+        "@octokit/auth-app": "^7.2.1",
+        "@octokit/auth-unauthenticated": "^6.1.3",
+        "@octokit/core": "^6.1.5",
+        "@octokit/oauth-app": "^7.1.6",
+        "@octokit/plugin-paginate-rest": "^12.0.0",
+        "@octokit/types": "^14.0.0",
+        "@octokit/webhooks": "^13.6.1"
+      },
+      "engines": {
+        "node": ">= 18"
+      }
+    },
+    "node_modules/@octokit/auth-app": {
+      "version": "7.2.1",
+      "resolved": "https://registry.npmjs.org/@octokit/auth-app/-/auth-app-7.2.1.tgz",
+      "integrity": "sha512-4jaopCVOtWN0V8qCx/1s2pkRqC6tcvIQM3kFB99eIpsP53GfsoIKO08D94b83n/V3iGihHmxWR2lXzE0NicUGg==",
+      "license": "MIT",
+      "dependencies": {
+        "@octokit/auth-oauth-app": "^8.1.4",
+        "@octokit/auth-oauth-user": "^5.1.4",
+        "@octokit/request": "^9.2.3",
+        "@octokit/request-error": "^6.1.8",
+        "@octokit/types": "^14.0.0",
+        "toad-cache": "^3.7.0",
+        "universal-github-app-jwt": "^2.2.0",
+        "universal-user-agent": "^7.0.0"
+      },
+      "engines": {
+        "node": ">= 18"
+      }
+    },
+    "node_modules/@octokit/auth-oauth-app": {
+      "version": "8.1.4",
+      "resolved": "https://registry.npmjs.org/@octokit/auth-oauth-app/-/auth-oauth-app-8.1.4.tgz",
+      "integrity": "sha512-71iBa5SflSXcclk/OL3lJzdt4iFs56OJdpBGEBl1wULp7C58uiswZLV6TdRaiAzHP1LT8ezpbHlKuxADb+4NkQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@octokit/auth-oauth-device": "^7.1.5",
+        "@octokit/auth-oauth-user": "^5.1.4",
+        "@octokit/request": "^9.2.3",
+        "@octokit/types": "^14.0.0",
+        "universal-user-agent": "^7.0.0"
+      },
+      "engines": {
+        "node": ">= 18"
+      }
+    },
+    "node_modules/@octokit/auth-oauth-device": {
+      "version": "7.1.5",
+      "resolved": "https://registry.npmjs.org/@octokit/auth-oauth-device/-/auth-oauth-device-7.1.5.tgz",
+      "integrity": "sha512-lR00+k7+N6xeECj0JuXeULQ2TSBB/zjTAmNF2+vyGPDEFx1dgk1hTDmL13MjbSmzusuAmuJD8Pu39rjp9jH6yw==",
+      "license": "MIT",
+      "dependencies": {
+        "@octokit/oauth-methods": "^5.1.5",
+        "@octokit/request": "^9.2.3",
+        "@octokit/types": "^14.0.0",
+        "universal-user-agent": "^7.0.0"
+      },
+      "engines": {
+        "node": ">= 18"
+      }
+    },
+    "node_modules/@octokit/auth-oauth-user": {
+      "version": "5.1.4",
+      "resolved": "https://registry.npmjs.org/@octokit/auth-oauth-user/-/auth-oauth-user-5.1.4.tgz",
+      "integrity": "sha512-4tJRofMHm6ZCd3O2PVgboBbQ/lNtacREeaihet0+wCATZmvPK+jjg2K6NjBfY69An3yzQdmkcMeiaOOoxOPr7Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@octokit/auth-oauth-device": "^7.1.5",
+        "@octokit/oauth-methods": "^5.1.5",
+        "@octokit/request": "^9.2.3",
+        "@octokit/types": "^14.0.0",
+        "universal-user-agent": "^7.0.0"
+      },
+      "engines": {
+        "node": ">= 18"
+      }
+    },
+    "node_modules/@octokit/auth-token": {
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/@octokit/auth-token/-/auth-token-5.1.2.tgz",
+      "integrity": "sha512-JcQDsBdg49Yky2w2ld20IHAlwr8d/d8N6NiOXbtuoPCqzbsiJgF633mVUw3x4mo0H5ypataQIX7SFu3yy44Mpw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 18"
+      }
+    },
+    "node_modules/@octokit/auth-unauthenticated": {
+      "version": "6.1.3",
+      "resolved": "https://registry.npmjs.org/@octokit/auth-unauthenticated/-/auth-unauthenticated-6.1.3.tgz",
+      "integrity": "sha512-d5gWJla3WdSl1yjbfMpET+hUSFCE15qM0KVSB0H1shyuJihf/RL1KqWoZMIaonHvlNojkL9XtLFp8QeLe+1iwA==",
+      "license": "MIT",
+      "dependencies": {
+        "@octokit/request-error": "^6.1.8",
+        "@octokit/types": "^14.0.0"
+      },
+      "engines": {
+        "node": ">= 18"
+      }
+    },
+    "node_modules/@octokit/core": {
+      "version": "6.1.5",
+      "resolved": "https://registry.npmjs.org/@octokit/core/-/core-6.1.5.tgz",
+      "integrity": "sha512-vvmsN0r7rguA+FySiCsbaTTobSftpIDIpPW81trAmsv9TGxg3YCujAxRYp/Uy8xmDgYCzzgulG62H7KYUFmeIg==",
+      "license": "MIT",
+      "dependencies": {
+        "@octokit/auth-token": "^5.0.0",
+        "@octokit/graphql": "^8.2.2",
+        "@octokit/request": "^9.2.3",
+        "@octokit/request-error": "^6.1.8",
+        "@octokit/types": "^14.0.0",
+        "before-after-hook": "^3.0.2",
+        "universal-user-agent": "^7.0.0"
+      },
+      "engines": {
+        "node": ">= 18"
+      }
+    },
+    "node_modules/@octokit/endpoint": {
+      "version": "10.1.4",
+      "resolved": "https://registry.npmjs.org/@octokit/endpoint/-/endpoint-10.1.4.tgz",
+      "integrity": "sha512-OlYOlZIsfEVZm5HCSR8aSg02T2lbUWOsCQoPKfTXJwDzcHQBrVBGdGXb89dv2Kw2ToZaRtudp8O3ZIYoaOjKlA==",
+      "license": "MIT",
+      "dependencies": {
+        "@octokit/types": "^14.0.0",
+        "universal-user-agent": "^7.0.2"
+      },
+      "engines": {
+        "node": ">= 18"
+      }
+    },
+    "node_modules/@octokit/graphql": {
+      "version": "8.2.2",
+      "resolved": "https://registry.npmjs.org/@octokit/graphql/-/graphql-8.2.2.tgz",
+      "integrity": "sha512-Yi8hcoqsrXGdt0yObxbebHXFOiUA+2v3n53epuOg1QUgOB6c4XzvisBNVXJSl8RYA5KrDuSL2yq9Qmqe5N0ryA==",
+      "license": "MIT",
+      "dependencies": {
+        "@octokit/request": "^9.2.3",
+        "@octokit/types": "^14.0.0",
+        "universal-user-agent": "^7.0.0"
+      },
+      "engines": {
+        "node": ">= 18"
+      }
+    },
+    "node_modules/@octokit/oauth-app": {
+      "version": "7.1.6",
+      "resolved": "https://registry.npmjs.org/@octokit/oauth-app/-/oauth-app-7.1.6.tgz",
+      "integrity": "sha512-OMcMzY2WFARg80oJNFwWbY51TBUfLH4JGTy119cqiDawSFXSIBujxmpXiKbGWQlvfn0CxE6f7/+c6+Kr5hI2YA==",
+      "license": "MIT",
+      "dependencies": {
+        "@octokit/auth-oauth-app": "^8.1.3",
+        "@octokit/auth-oauth-user": "^5.1.3",
+        "@octokit/auth-unauthenticated": "^6.1.2",
+        "@octokit/core": "^6.1.4",
+        "@octokit/oauth-authorization-url": "^7.1.1",
+        "@octokit/oauth-methods": "^5.1.4",
+        "@types/aws-lambda": "^8.10.83",
+        "universal-user-agent": "^7.0.0"
+      },
+      "engines": {
+        "node": ">= 18"
+      }
+    },
+    "node_modules/@octokit/oauth-authorization-url": {
+      "version": "7.1.1",
+      "resolved": "https://registry.npmjs.org/@octokit/oauth-authorization-url/-/oauth-authorization-url-7.1.1.tgz",
+      "integrity": "sha512-ooXV8GBSabSWyhLUowlMIVd9l1s2nsOGQdlP2SQ4LnkEsGXzeCvbSbCPdZThXhEFzleGPwbapT0Sb+YhXRyjCA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 18"
+      }
+    },
+    "node_modules/@octokit/oauth-methods": {
+      "version": "5.1.5",
+      "resolved": "https://registry.npmjs.org/@octokit/oauth-methods/-/oauth-methods-5.1.5.tgz",
+      "integrity": "sha512-Ev7K8bkYrYLhoOSZGVAGsLEscZQyq7XQONCBBAl2JdMg7IT3PQn/y8P0KjloPoYpI5UylqYrLeUcScaYWXwDvw==",
+      "license": "MIT",
+      "dependencies": {
+        "@octokit/oauth-authorization-url": "^7.0.0",
+        "@octokit/request": "^9.2.3",
+        "@octokit/request-error": "^6.1.8",
+        "@octokit/types": "^14.0.0"
+      },
+      "engines": {
+        "node": ">= 18"
+      }
+    },
+    "node_modules/@octokit/openapi-types": {
+      "version": "25.0.0",
+      "resolved": "https://registry.npmjs.org/@octokit/openapi-types/-/openapi-types-25.0.0.tgz",
+      "integrity": "sha512-FZvktFu7HfOIJf2BScLKIEYjDsw6RKc7rBJCdvCTfKsVnx2GEB/Nbzjr29DUdb7vQhlzS/j8qDzdditP0OC6aw==",
+      "license": "MIT"
+    },
+    "node_modules/@octokit/openapi-webhooks-types": {
+      "version": "11.0.0",
+      "resolved": "https://registry.npmjs.org/@octokit/openapi-webhooks-types/-/openapi-webhooks-types-11.0.0.tgz",
+      "integrity": "sha512-ZBzCFj98v3SuRM7oBas6BHZMJRadlnDoeFfvm1olVxZnYeU6Vh97FhPxyS5aLh5pN51GYv2I51l/hVUAVkGBlA==",
+      "license": "MIT"
+    },
+    "node_modules/@octokit/plugin-paginate-graphql": {
+      "version": "5.2.4",
+      "resolved": "https://registry.npmjs.org/@octokit/plugin-paginate-graphql/-/plugin-paginate-graphql-5.2.4.tgz",
+      "integrity": "sha512-pLZES1jWaOynXKHOqdnwZ5ULeVR6tVVCMm+AUbp0htdcyXDU95WbkYdU4R2ej1wKj5Tu94Mee2Ne0PjPO9cCyA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 18"
+      },
+      "peerDependencies": {
+        "@octokit/core": ">=6"
+      }
+    },
+    "node_modules/@octokit/plugin-paginate-rest": {
+      "version": "12.0.0",
+      "resolved": "https://registry.npmjs.org/@octokit/plugin-paginate-rest/-/plugin-paginate-rest-12.0.0.tgz",
+      "integrity": "sha512-MPd6WK1VtZ52lFrgZ0R2FlaoiWllzgqFHaSZxvp72NmoDeZ0m8GeJdg4oB6ctqMTYyrnDYp592Xma21mrgiyDA==",
+      "license": "MIT",
+      "dependencies": {
+        "@octokit/types": "^14.0.0"
+      },
+      "engines": {
+        "node": ">= 18"
+      },
+      "peerDependencies": {
+        "@octokit/core": ">=6"
+      }
+    },
+    "node_modules/@octokit/plugin-rest-endpoint-methods": {
+      "version": "14.0.0",
+      "resolved": "https://registry.npmjs.org/@octokit/plugin-rest-endpoint-methods/-/plugin-rest-endpoint-methods-14.0.0.tgz",
+      "integrity": "sha512-iQt6ovem4b7zZYZQtdv+PwgbL5VPq37th1m2x2TdkgimIDJpsi2A6Q/OI/23i/hR6z5mL0EgisNR4dcbmckSZQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@octokit/types": "^14.0.0"
+      },
+      "engines": {
+        "node": ">= 18"
+      },
+      "peerDependencies": {
+        "@octokit/core": ">=6"
+      }
+    },
+    "node_modules/@octokit/plugin-retry": {
+      "version": "7.2.1",
+      "resolved": "https://registry.npmjs.org/@octokit/plugin-retry/-/plugin-retry-7.2.1.tgz",
+      "integrity": "sha512-wUc3gv0D6vNHpGxSaR3FlqJpTXGWgqmk607N9L3LvPL4QjaxDgX/1nY2mGpT37Khn+nlIXdljczkRnNdTTV3/A==",
+      "license": "MIT",
+      "dependencies": {
+        "@octokit/request-error": "^6.1.8",
+        "@octokit/types": "^14.0.0",
+        "bottleneck": "^2.15.3"
+      },
+      "engines": {
+        "node": ">= 18"
+      },
+      "peerDependencies": {
+        "@octokit/core": ">=6"
+      }
+    },
+    "node_modules/@octokit/plugin-throttling": {
+      "version": "10.0.0",
+      "resolved": "https://registry.npmjs.org/@octokit/plugin-throttling/-/plugin-throttling-10.0.0.tgz",
+      "integrity": "sha512-Kuq5/qs0DVYTHZuBAzCZStCzo2nKvVRo/TDNhCcpC2TKiOGz/DisXMCvjt3/b5kr6SCI1Y8eeeJTHBxxpFvZEg==",
+      "license": "MIT",
+      "dependencies": {
+        "@octokit/types": "^14.0.0",
+        "bottleneck": "^2.15.3"
+      },
+      "engines": {
+        "node": ">= 18"
+      },
+      "peerDependencies": {
+        "@octokit/core": "^6.1.3"
+      }
+    },
+    "node_modules/@octokit/request": {
+      "version": "9.2.3",
+      "resolved": "https://registry.npmjs.org/@octokit/request/-/request-9.2.3.tgz",
+      "integrity": "sha512-Ma+pZU8PXLOEYzsWf0cn/gY+ME57Wq8f49WTXA8FMHp2Ps9djKw//xYJ1je8Hm0pR2lU9FUGeJRWOtxq6olt4w==",
+      "license": "MIT",
+      "dependencies": {
+        "@octokit/endpoint": "^10.1.4",
+        "@octokit/request-error": "^6.1.8",
+        "@octokit/types": "^14.0.0",
+        "fast-content-type-parse": "^2.0.0",
+        "universal-user-agent": "^7.0.2"
+      },
+      "engines": {
+        "node": ">= 18"
+      }
+    },
+    "node_modules/@octokit/request-error": {
+      "version": "6.1.8",
+      "resolved": "https://registry.npmjs.org/@octokit/request-error/-/request-error-6.1.8.tgz",
+      "integrity": "sha512-WEi/R0Jmq+IJKydWlKDmryPcmdYSVjL3ekaiEL1L9eo1sUnqMJ+grqmC9cjk7CA7+b2/T397tO5d8YLOH3qYpQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@octokit/types": "^14.0.0"
+      },
+      "engines": {
+        "node": ">= 18"
+      }
+    },
+    "node_modules/@octokit/types": {
+      "version": "14.0.0",
+      "resolved": "https://registry.npmjs.org/@octokit/types/-/types-14.0.0.tgz",
+      "integrity": "sha512-VVmZP0lEhbo2O1pdq63gZFiGCKkm8PPp8AUOijlwPO6hojEVjspA0MWKP7E4hbvGxzFKNqKr6p0IYtOH/Wf/zA==",
+      "license": "MIT",
+      "dependencies": {
+        "@octokit/openapi-types": "^25.0.0"
+      }
+    },
+    "node_modules/@octokit/webhooks": {
+      "version": "13.8.2",
+      "resolved": "https://registry.npmjs.org/@octokit/webhooks/-/webhooks-13.8.2.tgz",
+      "integrity": "sha512-NgKpxIVp9MnEukvTF9s871v11bYTDZwpuyIYkU0ZIEM3d+DBOeiciIJPuCdjFMC1pQgv05MNKtdhbl8+Q+i3GA==",
+      "license": "MIT",
+      "dependencies": {
+        "@octokit/openapi-webhooks-types": "11.0.0",
+        "@octokit/request-error": "^6.1.7",
+        "@octokit/webhooks-methods": "^5.1.1"
+      },
+      "engines": {
+        "node": ">= 18"
+      }
+    },
+    "node_modules/@octokit/webhooks-methods": {
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/@octokit/webhooks-methods/-/webhooks-methods-5.1.1.tgz",
+      "integrity": "sha512-NGlEHZDseJTCj8TMMFehzwa9g7On4KJMPVHDSrHxCQumL6uSQR8wIkP/qesv52fXqV1BPf4pTxwtS31ldAt9Xg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 18"
+      }
+    },
     "node_modules/@rtsao/scc": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/@rtsao/scc/-/scc-1.1.0.tgz",
@@ -877,6 +1770,88 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@shikijs/core": {
+      "version": "3.4.0",
+      "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-3.4.0.tgz",
+      "integrity": "sha512-0YOzTSRDn/IAfQWtK791gs1u8v87HNGToU6IwcA3K7nPoVOrS2Dh6X6A6YfXgPTSkTwR5y6myk0MnI0htjnwrA==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/types": "3.4.0",
+        "@shikijs/vscode-textmate": "^10.0.2",
+        "@types/hast": "^3.0.4",
+        "hast-util-to-html": "^9.0.5"
+      }
+    },
+    "node_modules/@shikijs/engine-javascript": {
+      "version": "3.4.0",
+      "resolved": "https://registry.npmjs.org/@shikijs/engine-javascript/-/engine-javascript-3.4.0.tgz",
+      "integrity": "sha512-1ywDoe+z/TPQKj9Jw0eU61B003J9DqUFRfH+DVSzdwPUFhR7yOmfyLzUrFz0yw8JxFg/NgzXoQyyykXgO21n5Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/types": "3.4.0",
+        "@shikijs/vscode-textmate": "^10.0.2",
+        "oniguruma-to-es": "^4.3.3"
+      }
+    },
+    "node_modules/@shikijs/engine-oniguruma": {
+      "version": "3.4.0",
+      "resolved": "https://registry.npmjs.org/@shikijs/engine-oniguruma/-/engine-oniguruma-3.4.0.tgz",
+      "integrity": "sha512-zwcWlZ4OQuJ/+1t32ClTtyTU1AiDkK1lhtviRWoq/hFqPjCNyLj22bIg9rB7BfoZKOEOfrsGz7No33BPCf+WlQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/types": "3.4.0",
+        "@shikijs/vscode-textmate": "^10.0.2"
+      }
+    },
+    "node_modules/@shikijs/langs": {
+      "version": "3.4.0",
+      "resolved": "https://registry.npmjs.org/@shikijs/langs/-/langs-3.4.0.tgz",
+      "integrity": "sha512-bQkR+8LllaM2duU9BBRQU0GqFTx7TuF5kKlw/7uiGKoK140n1xlLAwCgXwSxAjJ7Htk9tXTFwnnsJTCU5nDPXQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/types": "3.4.0"
+      }
+    },
+    "node_modules/@shikijs/rehype": {
+      "version": "3.4.0",
+      "resolved": "https://registry.npmjs.org/@shikijs/rehype/-/rehype-3.4.0.tgz",
+      "integrity": "sha512-wm7RTSmrcmjZg+F9JRrsH0Brwi36joUMXkUWIDmBGW+XExNEi8Xjmmp2NOBXa3DujZtnL6Dbcg7V6gtZabGoXw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/types": "3.4.0",
+        "@types/hast": "^3.0.4",
+        "hast-util-to-string": "^3.0.1",
+        "shiki": "3.4.0",
+        "unified": "^11.0.5",
+        "unist-util-visit": "^5.0.0"
+      }
+    },
+    "node_modules/@shikijs/themes": {
+      "version": "3.4.0",
+      "resolved": "https://registry.npmjs.org/@shikijs/themes/-/themes-3.4.0.tgz",
+      "integrity": "sha512-YPP4PKNFcFGLxItpbU0ZW1Osyuk8AyZ24YEFaq04CFsuCbcqydMvMUTi40V2dkc0qs1U2uZFrnU6s5zI6IH+uA==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/types": "3.4.0"
+      }
+    },
+    "node_modules/@shikijs/types": {
+      "version": "3.4.0",
+      "resolved": "https://registry.npmjs.org/@shikijs/types/-/types-3.4.0.tgz",
+      "integrity": "sha512-EUT/0lGiE//7j5N/yTMNMT3eCWNcHJLrRKxT0NDXWIfdfSmFJKfPX7nMmRBrQnWboAzIsUziCThrYMMhjbMS1A==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/vscode-textmate": "^10.0.2",
+        "@types/hast": "^3.0.4"
+      }
+    },
+    "node_modules/@shikijs/vscode-textmate": {
+      "version": "10.0.2",
+      "resolved": "https://registry.npmjs.org/@shikijs/vscode-textmate/-/vscode-textmate-10.0.2.tgz",
+      "integrity": "sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==",
+      "license": "MIT"
+    },
     "node_modules/@swc/counter": {
       "version": "0.1.3",
       "resolved": "https://registry.npmjs.org/@swc/counter/-/counter-0.1.3.tgz",
@@ -892,6 +1867,32 @@
         "tslib": "^2.8.0"
       }
     },
+    "node_modules/@tabler/icons": {
+      "version": "3.31.0",
+      "resolved": "https://registry.npmjs.org/@tabler/icons/-/icons-3.31.0.tgz",
+      "integrity": "sha512-dblAdeKY3+GA1U+Q9eziZ0ooVlZMHsE8dqP0RkwvRtEsAULoKOYaCUOcJ4oW1DjWegdxk++UAt2SlQVnmeHv+g==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/codecalm"
+      }
+    },
+    "node_modules/@tabler/icons-react": {
+      "version": "3.31.0",
+      "resolved": "https://registry.npmjs.org/@tabler/icons-react/-/icons-react-3.31.0.tgz",
+      "integrity": "sha512-2rrCM5y/VnaVKnORpDdAua9SEGuJKVqPtWxeQ/vUVsgaUx30LDgBZph7/lterXxDY1IKR6NO//HDhWiifXTi3w==",
+      "license": "MIT",
+      "dependencies": {
+        "@tabler/icons": "3.31.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/codecalm"
+      },
+      "peerDependencies": {
+        "react": ">= 16"
+      }
+    },
     "node_modules/@tybys/wasm-util": {
       "version": "0.9.0",
       "resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.9.0.tgz",
@@ -903,13 +1904,45 @@
         "tslib": "^2.4.0"
       }
     },
+    "node_modules/@types/aws-lambda": {
+      "version": "8.10.149",
+      "resolved": "https://registry.npmjs.org/@types/aws-lambda/-/aws-lambda-8.10.149.tgz",
+      "integrity": "sha512-NXSZIhfJjnXqJgtS7IwutqIF/SOy1Wz5Px4gUY1RWITp3AYTyuJS4xaXr/bIJY1v15XMzrJ5soGnPM+7uigZjA==",
+      "license": "MIT"
+    },
+    "node_modules/@types/debug": {
+      "version": "4.1.12",
+      "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.12.tgz",
+      "integrity": "sha512-vIChWdVG3LG1SMxEvI/AK+FWJthlrqlTu7fbrlywTkkaONwk/UAGaULXRlf8vkzFBLVm0zkMdCquhL5aOjhXPQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/ms": "*"
+      }
+    },
     "node_modules/@types/estree": {
       "version": "1.0.7",
       "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.7.tgz",
       "integrity": "sha512-w28IoSUCJpidD/TGviZwwMJckNESJZXFu7NBZ5YJ4mEUnNraUn9Pm8HSZm/jDF1pDWYKspWE7oVphigUPRakIQ==",
-      "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/estree-jsx": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/@types/estree-jsx/-/estree-jsx-1.0.5.tgz",
+      "integrity": "sha512-52CcUVNFyfb1A2ALocQw/Dd1BQFNmSdkuC3BkZ6iqhdMfQz7JWOFRuJFloOzjk+6WijU56m9oKXFAXc7o3Towg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "*"
+      }
+    },
+    "node_modules/@types/hast": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/@types/hast/-/hast-3.0.4.tgz",
+      "integrity": "sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "*"
+      }
+    },
     "node_modules/@types/json-schema": {
       "version": "7.0.15",
       "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.15.tgz",
@@ -924,6 +1957,21 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/mdast": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/@types/mdast/-/mdast-4.0.4.tgz",
+      "integrity": "sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "*"
+      }
+    },
+    "node_modules/@types/ms": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@types/ms/-/ms-2.1.0.tgz",
+      "integrity": "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==",
+      "license": "MIT"
+    },
     "node_modules/@types/node": {
       "version": "20.17.32",
       "resolved": "https://registry.npmjs.org/@types/node/-/node-20.17.32.tgz",
@@ -938,7 +1986,6 @@
       "version": "19.1.2",
       "resolved": "https://registry.npmjs.org/@types/react/-/react-19.1.2.tgz",
       "integrity": "sha512-oxLPMytKchWGbnQM9O7D67uPa9paTNxO7jVoNMXgkkErULBPhPARCfkKL9ytcIJJRGjbsVwW4ugJzyFFvm/Tiw==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "csstype": "^3.0.2"
@@ -954,6 +2001,12 @@
         "@types/react": "^19.0.0"
       }
     },
+    "node_modules/@types/unist": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz",
+      "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==",
+      "license": "MIT"
+    },
     "node_modules/@typescript-eslint/eslint-plugin": {
       "version": "8.31.1",
       "resolved": "https://registry.npmjs.org/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.31.1.tgz",
@@ -1190,6 +2243,12 @@
         "url": "https://opencollective.com/typescript-eslint"
       }
     },
+    "node_modules/@ungap/structured-clone": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/@ungap/structured-clone/-/structured-clone-1.3.0.tgz",
+      "integrity": "sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g==",
+      "license": "ISC"
+    },
     "node_modules/@unrs/resolver-binding-darwin-arm64": {
       "version": "1.7.2",
       "resolved": "https://registry.npmjs.org/@unrs/resolver-binding-darwin-arm64/-/resolver-binding-darwin-arm64-1.7.2.tgz",
@@ -1729,6 +2788,16 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/bail": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/bail/-/bail-2.0.2.tgz",
+      "integrity": "sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/balanced-match": {
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
@@ -1736,6 +2805,22 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/bcp-47-match": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/bcp-47-match/-/bcp-47-match-2.0.3.tgz",
+      "integrity": "sha512-JtTezzbAibu8G0R9op9zb3vcWZd9JF6M0xOYGPn0fNCd7wOpRB1mU2mH9T8gaBGbAAyIIVgB2G7xG0GP98zMAQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/before-after-hook": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/before-after-hook/-/before-after-hook-3.0.2.tgz",
+      "integrity": "sha512-Nik3Sc0ncrMK4UUdXQmAnRtzmNQTAAXmXIopizwZ1W1t8QmfJj+zL4OA2I7XPTPW5z5TDqv4hRo/JzouDJnX3A==",
+      "license": "Apache-2.0"
+    },
     "node_modules/body-parser": {
       "version": "2.2.0",
       "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.0.tgz",
@@ -1757,6 +2842,18 @@
         "node": ">=18"
       }
     },
+    "node_modules/boolbase": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/boolbase/-/boolbase-1.0.0.tgz",
+      "integrity": "sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww==",
+      "license": "ISC"
+    },
+    "node_modules/bottleneck": {
+      "version": "2.19.5",
+      "resolved": "https://registry.npmjs.org/bottleneck/-/bottleneck-2.19.5.tgz",
+      "integrity": "sha512-VHiNCbI1lKdl44tGrhNfU3lup0Tj/ZBMJB5/2ZbNXRCPuRCO7ed2mgcK4r17y+KB2EfuYuRaVlwNbAeaWGSpbw==",
+      "license": "MIT"
+    },
     "node_modules/brace-expansion": {
       "version": "1.1.11",
       "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
@@ -1862,6 +2959,16 @@
         "node": ">=6"
       }
     },
+    "node_modules/camelcase-css": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/camelcase-css/-/camelcase-css-2.0.1.tgz",
+      "integrity": "sha512-QOSvevhslijgYwRx6Rv7zKdMF8lbRmx+uQGx2+vDc+KI/eBnsy9kit5aj23AgGu3pa4t9AgwbnXWqS+iOY+2aA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 6"
+      }
+    },
     "node_modules/caniuse-lite": {
       "version": "1.0.30001716",
       "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001716.tgz",
@@ -1882,6 +2989,16 @@
       ],
       "license": "CC-BY-4.0"
     },
+    "node_modules/ccount": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/ccount/-/ccount-2.0.1.tgz",
+      "integrity": "sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/chalk": {
       "version": "4.1.2",
       "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz",
@@ -1899,12 +3016,61 @@
         "url": "https://github.com/chalk/chalk?sponsor=1"
       }
     },
+    "node_modules/character-entities": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/character-entities/-/character-entities-2.0.2.tgz",
+      "integrity": "sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/character-entities-html4": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/character-entities-html4/-/character-entities-html4-2.1.0.tgz",
+      "integrity": "sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/character-entities-legacy": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/character-entities-legacy/-/character-entities-legacy-3.0.0.tgz",
+      "integrity": "sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/character-reference-invalid": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/character-reference-invalid/-/character-reference-invalid-2.0.1.tgz",
+      "integrity": "sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/client-only": {
       "version": "0.0.1",
       "resolved": "https://registry.npmjs.org/client-only/-/client-only-0.0.1.tgz",
       "integrity": "sha512-IV3Ou0jSMzZrd3pZ48nLkT9DA7Ag1pnPzaiQhpW7c3RbcqqzvzzVu+L8gfqMp/8IM2MQtSiqaCxrrcfu8I8rMA==",
       "license": "MIT"
     },
+    "node_modules/clsx": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/clsx/-/clsx-2.1.1.tgz",
+      "integrity": "sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/color": {
       "version": "4.2.3",
       "resolved": "https://registry.npmjs.org/color/-/color-4.2.3.tgz",
@@ -1950,6 +3116,16 @@
         "simple-swizzle": "^0.2.2"
       }
     },
+    "node_modules/comma-separated-tokens": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/comma-separated-tokens/-/comma-separated-tokens-2.0.3.tgz",
+      "integrity": "sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/concat-map": {
       "version": "0.0.1",
       "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
@@ -2029,11 +3205,39 @@
         "node": ">= 8"
       }
     },
+    "node_modules/css-selector-parser": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/css-selector-parser/-/css-selector-parser-3.1.2.tgz",
+      "integrity": "sha512-WfUcL99xWDs7b3eZPoRszWVfbNo8ErCF15PTvVROjkShGlAfjIkG6hlfj/sl6/rfo5Q9x9ryJ3VqVnAZDA+gcw==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/mdevils"
+        },
+        {
+          "type": "patreon",
+          "url": "https://patreon.com/mdevils"
+        }
+      ],
+      "license": "MIT"
+    },
+    "node_modules/cssesc": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/cssesc/-/cssesc-3.0.0.tgz",
+      "integrity": "sha512-/Tb/JcjK111nNScGob5MNtsntNM1aCNUDipB/TkwZFhyDrrE47SOx/18wF2bbjgc3ZzCSKW1T5nt5EbFoAz/Vg==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "cssesc": "bin/cssesc"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
     "node_modules/csstype": {
       "version": "3.1.3",
       "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.1.3.tgz",
       "integrity": "sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/damerau-levenshtein": {
@@ -2101,7 +3305,6 @@
       "version": "4.4.0",
       "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.0.tgz",
       "integrity": "sha512-6WTZ/IxCY/T6BALoZHaE4ctp9xm+Z5kY/pzYaCHRFeyVhojxlrm+46y68HA6hr0TcwEssoxNiDEUJQjfPZ/RYA==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "ms": "^2.1.3"
@@ -2115,6 +3318,19 @@
         }
       }
     },
+    "node_modules/decode-named-character-reference": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/decode-named-character-reference/-/decode-named-character-reference-1.1.0.tgz",
+      "integrity": "sha512-Wy+JTSbFThEOXQIR2L6mxJvEs+veIzpmqD7ynWxMXGpnk3smkHQOp6forLdHsKpAMW9iJpaBBIxz285t1n1C3w==",
+      "license": "MIT",
+      "dependencies": {
+        "character-entities": "^2.0.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/deep-is": {
       "version": "0.1.4",
       "resolved": "https://registry.npmjs.org/deep-is/-/deep-is-0.1.4.tgz",
@@ -2168,6 +3384,15 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/dequal": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/dequal/-/dequal-2.0.3.tgz",
+      "integrity": "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/detect-libc": {
       "version": "2.0.4",
       "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.0.4.tgz",
@@ -2178,6 +3403,38 @@
         "node": ">=8"
       }
     },
+    "node_modules/detect-node-es": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/detect-node-es/-/detect-node-es-1.1.0.tgz",
+      "integrity": "sha512-ypdmJU/TbBby2Dxibuv7ZLW3Bs1QEmM7nHjEANfohJLvE0XVujisn1qPJcZxg+qDucsr+bP6fLD1rPS3AhJ7EQ==",
+      "license": "MIT"
+    },
+    "node_modules/devlop": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/devlop/-/devlop-1.1.0.tgz",
+      "integrity": "sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==",
+      "license": "MIT",
+      "dependencies": {
+        "dequal": "^2.0.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/direction": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/direction/-/direction-2.0.1.tgz",
+      "integrity": "sha512-9S6m9Sukh1cZNknO1CWAr2QAWsbKLafQiyM5gZ7VgXHeuaoUwffKN4q6NC4A/Mf9iiPlOXQEKW/Mv/mh9/3YFA==",
+      "license": "MIT",
+      "bin": {
+        "direction": "cli.js"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/doctrine": {
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/doctrine/-/doctrine-2.1.0.tgz",
@@ -2191,6 +3448,19 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/dotenv": {
+      "version": "16.5.0",
+      "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-16.5.0.tgz",
+      "integrity": "sha512-m/C+AwOAr9/W1UOIZUo232ejMNnJAJtYQjUbHoNTBNTJSvqzzDh7vnrei3o3r3m9blf6ZoDkvcw0VmozNRFJxg==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://dotenvx.com"
+      }
+    },
     "node_modules/dunder-proto": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
@@ -2230,6 +3500,18 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/entities": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-6.0.0.tgz",
+      "integrity": "sha512-aKstq2TDOndCn4diEyp9Uq/Flu2i1GlLkc6XIDQSDMuaFE3OPW5OphLCyQ5SpSJZTb4reN+kTcYru5yIfXoRPw==",
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=0.12"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
     "node_modules/es-abstract": {
       "version": "1.23.9",
       "resolved": "https://registry.npmjs.org/es-abstract/-/es-abstract-1.23.9.tgz",
@@ -2404,6 +3686,47 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/esbuild": {
+      "version": "0.25.4",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.25.4.tgz",
+      "integrity": "sha512-8pgjLUcUjcgDg+2Q4NYXnPbo/vncAY4UmyaCm0jZevERqCHZIaWwdJHkf8XQtu4AxSKCdvrUbT0XUr1IdZzI8Q==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.25.4",
+        "@esbuild/android-arm": "0.25.4",
+        "@esbuild/android-arm64": "0.25.4",
+        "@esbuild/android-x64": "0.25.4",
+        "@esbuild/darwin-arm64": "0.25.4",
+        "@esbuild/darwin-x64": "0.25.4",
+        "@esbuild/freebsd-arm64": "0.25.4",
+        "@esbuild/freebsd-x64": "0.25.4",
+        "@esbuild/linux-arm": "0.25.4",
+        "@esbuild/linux-arm64": "0.25.4",
+        "@esbuild/linux-ia32": "0.25.4",
+        "@esbuild/linux-loong64": "0.25.4",
+        "@esbuild/linux-mips64el": "0.25.4",
+        "@esbuild/linux-ppc64": "0.25.4",
+        "@esbuild/linux-riscv64": "0.25.4",
+        "@esbuild/linux-s390x": "0.25.4",
+        "@esbuild/linux-x64": "0.25.4",
+        "@esbuild/netbsd-arm64": "0.25.4",
+        "@esbuild/netbsd-x64": "0.25.4",
+        "@esbuild/openbsd-arm64": "0.25.4",
+        "@esbuild/openbsd-x64": "0.25.4",
+        "@esbuild/sunos-x64": "0.25.4",
+        "@esbuild/win32-arm64": "0.25.4",
+        "@esbuild/win32-ia32": "0.25.4",
+        "@esbuild/win32-x64": "0.25.4"
+      }
+    },
     "node_modules/escape-html": {
       "version": "1.0.3",
       "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz",
@@ -2806,6 +4129,19 @@
         "url": "https://opencollective.com/eslint"
       }
     },
+    "node_modules/esprima": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz",
+      "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==",
+      "license": "BSD-2-Clause",
+      "bin": {
+        "esparse": "bin/esparse.js",
+        "esvalidate": "bin/esvalidate.js"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
     "node_modules/esquery": {
       "version": "1.6.0",
       "resolved": "https://registry.npmjs.org/esquery/-/esquery-1.6.0.tgz",
@@ -2842,6 +4178,16 @@
         "node": ">=4.0"
       }
     },
+    "node_modules/estree-util-is-identifier-name": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/estree-util-is-identifier-name/-/estree-util-is-identifier-name-3.0.0.tgz",
+      "integrity": "sha512-hFtqIDZTIUZ9BXLb8y4pYGyk6+wekIivNVTcmvk8NoOh+VeRn5y6cEHzbURrWbfp1fIqdVipilzj+lfaadNZmg==",
+      "license": "MIT",
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/esutils": {
       "version": "2.0.3",
       "resolved": "https://registry.npmjs.org/esutils/-/esutils-2.0.3.tgz",
@@ -2944,6 +4290,40 @@
         "express": "^4.11 || 5 || ^5.0.0-beta.1"
       }
     },
+    "node_modules/extend": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz",
+      "integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==",
+      "license": "MIT"
+    },
+    "node_modules/extend-shallow": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/extend-shallow/-/extend-shallow-2.0.1.tgz",
+      "integrity": "sha512-zCnTtlxNoAiDc3gqY2aYAWFx7XWWiasuF2K8Me5WbN8otHKTUKBwjPtNpRs/rbUZm7KxWAaNj7P1a/p52GbVug==",
+      "license": "MIT",
+      "dependencies": {
+        "is-extendable": "^0.1.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/fast-content-type-parse": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/fast-content-type-parse/-/fast-content-type-parse-2.0.1.tgz",
+      "integrity": "sha512-nGqtvLrj5w0naR6tDPfB4cUmYCqouzyQiz6C5y/LtcDllJdrcc6WaWW6iXyIIOErTa/XRybj28aasdn4LkVk6Q==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "MIT"
+    },
     "node_modules/fast-deep-equal": {
       "version": "3.1.3",
       "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
@@ -3005,6 +4385,19 @@
         "reusify": "^1.0.4"
       }
     },
+    "node_modules/fault": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/fault/-/fault-2.0.1.tgz",
+      "integrity": "sha512-WtySTkS4OKev5JtpHXnib4Gxiurzh5NCGvWrFaZ34m6JehfTUhKZvn9njTfw48t6JumVQOmrKqpmGcdwxnhqBQ==",
+      "license": "MIT",
+      "dependencies": {
+        "format": "^0.2.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/file-entry-cache": {
       "version": "8.0.0",
       "resolved": "https://registry.npmjs.org/file-entry-cache/-/file-entry-cache-8.0.0.tgz",
@@ -3103,6 +4496,14 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/format": {
+      "version": "0.2.2",
+      "resolved": "https://registry.npmjs.org/format/-/format-0.2.2.tgz",
+      "integrity": "sha512-wzsgA6WOq+09wrU1tsJ09udeR/YZRaeArL9e1wPbFg3GG2yDnC2ldKpxs4xunpFF9DgqCqOIra3bc1HWrJ37Ww==",
+      "engines": {
+        "node": ">=0.4.x"
+      }
+    },
     "node_modules/forwarded": {
       "version": "0.2.0",
       "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz",
@@ -3123,6 +4524,21 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
     "node_modules/function-bind": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz",
@@ -3189,6 +4605,15 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/get-nonce": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/get-nonce/-/get-nonce-1.0.1.tgz",
+      "integrity": "sha512-FJhYRoDaiatfEkUK8HKlicmu/3SGFD51q3itKDGoSTysQJBnfOcxU5GxnhE1E6soB76MbT0MBtnKJuXyAx+96Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/get-proto": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz",
@@ -3234,6 +4659,12 @@
         "url": "https://github.com/privatenumber/get-tsconfig?sponsor=1"
       }
     },
+    "node_modules/github-slugger": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/github-slugger/-/github-slugger-2.0.0.tgz",
+      "integrity": "sha512-IaOQ9puYtjrkq7Y0Ygl9KDZnrf/aiUJYUpVf89y8kyaxbRG7Y1SrX/jaumrv81vc61+kiMempujsM3Yw7w5qcw==",
+      "license": "ISC"
+    },
     "node_modules/glob-parent": {
       "version": "6.0.2",
       "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-6.0.2.tgz",
@@ -3297,6 +4728,43 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/gray-matter": {
+      "version": "4.0.3",
+      "resolved": "https://registry.npmjs.org/gray-matter/-/gray-matter-4.0.3.tgz",
+      "integrity": "sha512-5v6yZd4JK3eMI3FqqCouswVqwugaA9r4dNZB1wwcmrD02QkV5H0y7XBQW8QwQqEaZY1pM9aqORSORhJRdNK44Q==",
+      "license": "MIT",
+      "dependencies": {
+        "js-yaml": "^3.13.1",
+        "kind-of": "^6.0.2",
+        "section-matter": "^1.0.0",
+        "strip-bom-string": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=6.0"
+      }
+    },
+    "node_modules/gray-matter/node_modules/argparse": {
+      "version": "1.0.10",
+      "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz",
+      "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==",
+      "license": "MIT",
+      "dependencies": {
+        "sprintf-js": "~1.0.2"
+      }
+    },
+    "node_modules/gray-matter/node_modules/js-yaml": {
+      "version": "3.14.1",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.1.tgz",
+      "integrity": "sha512-okMH7OXXJ7YrN9Ok3/SXrnu4iX9yOk+25nqX4imS2npuvTYDmo/QEZoqwZkYaIDk3jVvBOTOIEgEhaLOynBS9g==",
+      "license": "MIT",
+      "dependencies": {
+        "argparse": "^1.0.7",
+        "esprima": "^4.0.0"
+      },
+      "bin": {
+        "js-yaml": "bin/js-yaml.js"
+      }
+    },
     "node_modules/has-bigints": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/has-bigints/-/has-bigints-1.1.0.tgz",
@@ -3391,6 +4859,245 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/hast-util-from-html": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/hast-util-from-html/-/hast-util-from-html-2.0.3.tgz",
+      "integrity": "sha512-CUSRHXyKjzHov8yKsQjGOElXy/3EKpyX56ELnkHH34vDVw1N1XSQ1ZcAvTyAPtGqLTuKP/uxM+aLkSPqF/EtMw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "devlop": "^1.1.0",
+        "hast-util-from-parse5": "^8.0.0",
+        "parse5": "^7.0.0",
+        "vfile": "^6.0.0",
+        "vfile-message": "^4.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-from-parse5": {
+      "version": "8.0.3",
+      "resolved": "https://registry.npmjs.org/hast-util-from-parse5/-/hast-util-from-parse5-8.0.3.tgz",
+      "integrity": "sha512-3kxEVkEKt0zvcZ3hCRYI8rqrgwtlIOFMWkbclACvjlDw8Li9S2hk/d51OI0nr/gIpdMHNepwgOKqZ/sy0Clpyg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "@types/unist": "^3.0.0",
+        "devlop": "^1.0.0",
+        "hastscript": "^9.0.0",
+        "property-information": "^7.0.0",
+        "vfile": "^6.0.0",
+        "vfile-location": "^5.0.0",
+        "web-namespaces": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-has-property": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/hast-util-has-property/-/hast-util-has-property-3.0.0.tgz",
+      "integrity": "sha512-MNilsvEKLFpV604hwfhVStK0usFY/QmM5zX16bo7EjnAEGofr5YyI37kzopBlZJkHD4t887i+q/C8/tr5Q94cA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-heading-rank": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/hast-util-heading-rank/-/hast-util-heading-rank-3.0.0.tgz",
+      "integrity": "sha512-EJKb8oMUXVHcWZTDepnr+WNbfnXKFNf9duMesmr4S8SXTJBJ9M4Yok08pu9vxdJwdlGRhVumk9mEhkEvKGifwA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-is-element": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/hast-util-is-element/-/hast-util-is-element-3.0.0.tgz",
+      "integrity": "sha512-Val9mnv2IWpLbNPqc/pUem+a7Ipj2aHacCwgNfTiK0vJKl0LF+4Ba4+v1oPHFpf3bLYmreq0/l3Gud9S5OH42g==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-parse-selector": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/hast-util-parse-selector/-/hast-util-parse-selector-4.0.0.tgz",
+      "integrity": "sha512-wkQCkSYoOGCRKERFWcxMVMOcYE2K1AaNLU8DXS9arxnLOUEWbOXKXiJUNzEpqZ3JOKpnha3jkFrumEjVliDe7A==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-select": {
+      "version": "6.0.4",
+      "resolved": "https://registry.npmjs.org/hast-util-select/-/hast-util-select-6.0.4.tgz",
+      "integrity": "sha512-RqGS1ZgI0MwxLaKLDxjprynNzINEkRHY2i8ln4DDjgv9ZhcYVIHN9rlpiYsqtFwrgpYU361SyWDQcGNIBVu3lw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "@types/unist": "^3.0.0",
+        "bcp-47-match": "^2.0.0",
+        "comma-separated-tokens": "^2.0.0",
+        "css-selector-parser": "^3.0.0",
+        "devlop": "^1.0.0",
+        "direction": "^2.0.0",
+        "hast-util-has-property": "^3.0.0",
+        "hast-util-to-string": "^3.0.0",
+        "hast-util-whitespace": "^3.0.0",
+        "nth-check": "^2.0.0",
+        "property-information": "^7.0.0",
+        "space-separated-tokens": "^2.0.0",
+        "unist-util-visit": "^5.0.0",
+        "zwitch": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-to-html": {
+      "version": "9.0.5",
+      "resolved": "https://registry.npmjs.org/hast-util-to-html/-/hast-util-to-html-9.0.5.tgz",
+      "integrity": "sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "@types/unist": "^3.0.0",
+        "ccount": "^2.0.0",
+        "comma-separated-tokens": "^2.0.0",
+        "hast-util-whitespace": "^3.0.0",
+        "html-void-elements": "^3.0.0",
+        "mdast-util-to-hast": "^13.0.0",
+        "property-information": "^7.0.0",
+        "space-separated-tokens": "^2.0.0",
+        "stringify-entities": "^4.0.0",
+        "zwitch": "^2.0.4"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-to-jsx-runtime": {
+      "version": "2.3.6",
+      "resolved": "https://registry.npmjs.org/hast-util-to-jsx-runtime/-/hast-util-to-jsx-runtime-2.3.6.tgz",
+      "integrity": "sha512-zl6s8LwNyo1P9uw+XJGvZtdFF1GdAkOg8ujOw+4Pyb76874fLps4ueHXDhXWdk6YHQ6OgUtinliG7RsYvCbbBg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0",
+        "@types/hast": "^3.0.0",
+        "@types/unist": "^3.0.0",
+        "comma-separated-tokens": "^2.0.0",
+        "devlop": "^1.0.0",
+        "estree-util-is-identifier-name": "^3.0.0",
+        "hast-util-whitespace": "^3.0.0",
+        "mdast-util-mdx-expression": "^2.0.0",
+        "mdast-util-mdx-jsx": "^3.0.0",
+        "mdast-util-mdxjs-esm": "^2.0.0",
+        "property-information": "^7.0.0",
+        "space-separated-tokens": "^2.0.0",
+        "style-to-js": "^1.0.0",
+        "unist-util-position": "^5.0.0",
+        "vfile-message": "^4.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-to-string": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/hast-util-to-string/-/hast-util-to-string-3.0.1.tgz",
+      "integrity": "sha512-XelQVTDWvqcl3axRfI0xSeoVKzyIFPwsAGSLIsKdJKQMXDYJS4WYrBNF/8J7RdhIcFI2BOHgAifggsvsxp/3+A==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-whitespace": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/hast-util-whitespace/-/hast-util-whitespace-3.0.0.tgz",
+      "integrity": "sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hastscript": {
+      "version": "9.0.1",
+      "resolved": "https://registry.npmjs.org/hastscript/-/hastscript-9.0.1.tgz",
+      "integrity": "sha512-g7df9rMFX/SPi34tyGCyUBREQoKkapwdY/T04Qn9TDWfHhAYt4/I0gMVirzK5wEzeUqIjEB+LXC/ypb7Aqno5w==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "comma-separated-tokens": "^2.0.0",
+        "hast-util-parse-selector": "^4.0.0",
+        "property-information": "^7.0.0",
+        "space-separated-tokens": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/highlight.js": {
+      "version": "11.11.1",
+      "resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-11.11.1.tgz",
+      "integrity": "sha512-Xwwo44whKBVCYoliBQwaPvtd/2tYFkRQtXDWj1nackaV2JPXx3L0+Jvd8/qCJ2p+ML0/XVkJ2q+Mr+UVdpJK5w==",
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
+    "node_modules/html-url-attributes": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/html-url-attributes/-/html-url-attributes-3.0.1.tgz",
+      "integrity": "sha512-ol6UPyBWqsrO6EJySPz2O7ZSr856WDrEzM5zMqp+FJJLGMW35cLYmmZnl0vztAZxRUoNZJFTCohfjuIJ8I4QBQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/html-void-elements": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/html-void-elements/-/html-void-elements-3.0.0.tgz",
+      "integrity": "sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/http-errors": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.0.tgz",
@@ -3465,6 +5172,12 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/inline-style-parser": {
+      "version": "0.2.4",
+      "resolved": "https://registry.npmjs.org/inline-style-parser/-/inline-style-parser-0.2.4.tgz",
+      "integrity": "sha512-0aO8FkhNZlj/ZIbNi7Lxxr12obT7cL1moPfE4tg1LkX7LlLfC6DeX4l2ZEud1ukP9jNQyNnfzQVqwbwmAATY4Q==",
+      "license": "MIT"
+    },
     "node_modules/internal-slot": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/internal-slot/-/internal-slot-1.1.0.tgz",
@@ -3490,6 +5203,30 @@
         "node": ">= 0.10"
       }
     },
+    "node_modules/is-alphabetical": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/is-alphabetical/-/is-alphabetical-2.0.1.tgz",
+      "integrity": "sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/is-alphanumerical": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/is-alphanumerical/-/is-alphanumerical-2.0.1.tgz",
+      "integrity": "sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw==",
+      "license": "MIT",
+      "dependencies": {
+        "is-alphabetical": "^2.0.0",
+        "is-decimal": "^2.0.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/is-array-buffer": {
       "version": "3.0.5",
       "resolved": "https://registry.npmjs.org/is-array-buffer/-/is-array-buffer-3.0.5.tgz",
@@ -3642,6 +5379,25 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/is-decimal": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/is-decimal/-/is-decimal-2.0.1.tgz",
+      "integrity": "sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/is-extendable": {
+      "version": "0.1.1",
+      "resolved": "https://registry.npmjs.org/is-extendable/-/is-extendable-0.1.1.tgz",
+      "integrity": "sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/is-extglob": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz",
@@ -3700,6 +5456,16 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/is-hexadecimal": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/is-hexadecimal/-/is-hexadecimal-2.0.1.tgz",
+      "integrity": "sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/is-map": {
       "version": "2.0.3",
       "resolved": "https://registry.npmjs.org/is-map/-/is-map-2.0.3.tgz",
@@ -3740,6 +5506,18 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/is-plain-obj": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/is-plain-obj/-/is-plain-obj-4.1.0.tgz",
+      "integrity": "sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/is-promise": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/is-promise/-/is-promise-4.0.0.tgz",
@@ -4004,6 +5782,15 @@
         "json-buffer": "3.0.1"
       }
     },
+    "node_modules/kind-of": {
+      "version": "6.0.3",
+      "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.3.tgz",
+      "integrity": "sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/language-subtag-registry": {
       "version": "0.3.23",
       "resolved": "https://registry.npmjs.org/language-subtag-registry/-/language-subtag-registry-0.3.23.tgz",
@@ -4061,6 +5848,16 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/longest-streak": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/longest-streak/-/longest-streak-3.1.0.tgz",
+      "integrity": "sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/loose-envify": {
       "version": "1.4.0",
       "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz",
@@ -4074,6 +5871,16 @@
         "loose-envify": "cli.js"
       }
     },
+    "node_modules/markdown-table": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/markdown-table/-/markdown-table-3.0.4.tgz",
+      "integrity": "sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/math-intrinsics": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
@@ -4084,6 +5891,318 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/mdast-util-find-and-replace": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/mdast-util-find-and-replace/-/mdast-util-find-and-replace-3.0.2.tgz",
+      "integrity": "sha512-Tmd1Vg/m3Xz43afeNxDIhWRtFZgM2VLyaf4vSTYwudTyeuTneoL3qtWMA5jeLyz/O1vDJmmV4QuScFCA2tBPwg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "escape-string-regexp": "^5.0.0",
+        "unist-util-is": "^6.0.0",
+        "unist-util-visit-parents": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-find-and-replace/node_modules/escape-string-regexp": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-5.0.0.tgz",
+      "integrity": "sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/mdast-util-from-markdown": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/mdast-util-from-markdown/-/mdast-util-from-markdown-2.0.2.tgz",
+      "integrity": "sha512-uZhTV/8NBuw0WHkPTrCqDOl0zVe1BIng5ZtHoDk49ME1qqcjYmmLmOf0gELgcRMxN4w2iuIeVso5/6QymSrgmA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "@types/unist": "^3.0.0",
+        "decode-named-character-reference": "^1.0.0",
+        "devlop": "^1.0.0",
+        "mdast-util-to-string": "^4.0.0",
+        "micromark": "^4.0.0",
+        "micromark-util-decode-numeric-character-reference": "^2.0.0",
+        "micromark-util-decode-string": "^2.0.0",
+        "micromark-util-normalize-identifier": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0",
+        "unist-util-stringify-position": "^4.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-frontmatter": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/mdast-util-frontmatter/-/mdast-util-frontmatter-2.0.1.tgz",
+      "integrity": "sha512-LRqI9+wdgC25P0URIJY9vwocIzCcksduHQ9OF2joxQoyTNVduwLAFUzjoopuRJbJAReaKrNQKAZKL3uCMugWJA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "devlop": "^1.0.0",
+        "escape-string-regexp": "^5.0.0",
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0",
+        "micromark-extension-frontmatter": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-frontmatter/node_modules/escape-string-regexp": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-5.0.0.tgz",
+      "integrity": "sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/mdast-util-gfm": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-gfm/-/mdast-util-gfm-3.1.0.tgz",
+      "integrity": "sha512-0ulfdQOM3ysHhCJ1p06l0b0VKlhU0wuQs3thxZQagjcjPrlFRqY215uZGHHJan9GEAXd9MbfPjFJz+qMkVR6zQ==",
+      "license": "MIT",
+      "dependencies": {
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-gfm-autolink-literal": "^2.0.0",
+        "mdast-util-gfm-footnote": "^2.0.0",
+        "mdast-util-gfm-strikethrough": "^2.0.0",
+        "mdast-util-gfm-table": "^2.0.0",
+        "mdast-util-gfm-task-list-item": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-gfm-autolink-literal": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/mdast-util-gfm-autolink-literal/-/mdast-util-gfm-autolink-literal-2.0.1.tgz",
+      "integrity": "sha512-5HVP2MKaP6L+G6YaxPNjuL0BPrq9orG3TsrZ9YXbA3vDw/ACI4MEsnoDpn6ZNm7GnZgtAcONJyPhOP8tNJQavQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "ccount": "^2.0.0",
+        "devlop": "^1.0.0",
+        "mdast-util-find-and-replace": "^3.0.0",
+        "micromark-util-character": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-gfm-footnote": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-gfm-footnote/-/mdast-util-gfm-footnote-2.1.0.tgz",
+      "integrity": "sha512-sqpDWlsHn7Ac9GNZQMeUzPQSMzR6Wv0WKRNvQRg0KqHh02fpTz69Qc1QSseNX29bhz1ROIyNyxExfawVKTm1GQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "devlop": "^1.1.0",
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0",
+        "micromark-util-normalize-identifier": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-gfm-strikethrough": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-gfm-strikethrough/-/mdast-util-gfm-strikethrough-2.0.0.tgz",
+      "integrity": "sha512-mKKb915TF+OC5ptj5bJ7WFRPdYtuHv0yTRxK2tJvi+BDqbkiG7h7u/9SI89nRAYcmap2xHQL9D+QG/6wSrTtXg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-gfm-table": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-gfm-table/-/mdast-util-gfm-table-2.0.0.tgz",
+      "integrity": "sha512-78UEvebzz/rJIxLvE7ZtDd/vIQ0RHv+3Mh5DR96p7cS7HsBhYIICDBCu8csTNWNO6tBWfqXPWekRuj2FNOGOZg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "devlop": "^1.0.0",
+        "markdown-table": "^3.0.0",
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-gfm-task-list-item": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-gfm-task-list-item/-/mdast-util-gfm-task-list-item-2.0.0.tgz",
+      "integrity": "sha512-IrtvNvjxC1o06taBAVJznEnkiHxLFTzgonUdy8hzFVeDun0uTjxxrRGVaNFqkU1wJR3RBPEfsxmU6jDWPofrTQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "devlop": "^1.0.0",
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-mdx-expression": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/mdast-util-mdx-expression/-/mdast-util-mdx-expression-2.0.1.tgz",
+      "integrity": "sha512-J6f+9hUp+ldTZqKRSg7Vw5V6MqjATc+3E4gf3CFNcuZNWD8XdyI6zQ8GqH7f8169MM6P7hMBRDVGnn7oHB9kXQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree-jsx": "^1.0.0",
+        "@types/hast": "^3.0.0",
+        "@types/mdast": "^4.0.0",
+        "devlop": "^1.0.0",
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-mdx-jsx": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-mdx-jsx/-/mdast-util-mdx-jsx-3.2.0.tgz",
+      "integrity": "sha512-lj/z8v0r6ZtsN/cGNNtemmmfoLAFZnjMbNyLzBafjzikOM+glrjNHPlf6lQDOTccj9n5b0PPihEBbhneMyGs1Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree-jsx": "^1.0.0",
+        "@types/hast": "^3.0.0",
+        "@types/mdast": "^4.0.0",
+        "@types/unist": "^3.0.0",
+        "ccount": "^2.0.0",
+        "devlop": "^1.1.0",
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0",
+        "parse-entities": "^4.0.0",
+        "stringify-entities": "^4.0.0",
+        "unist-util-stringify-position": "^4.0.0",
+        "vfile-message": "^4.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-mdxjs-esm": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/mdast-util-mdxjs-esm/-/mdast-util-mdxjs-esm-2.0.1.tgz",
+      "integrity": "sha512-EcmOpxsZ96CvlP03NghtH1EsLtr0n9Tm4lPUJUBccV9RwUOneqSycg19n5HGzCf+10LozMRSObtVr3ee1WoHtg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree-jsx": "^1.0.0",
+        "@types/hast": "^3.0.0",
+        "@types/mdast": "^4.0.0",
+        "devlop": "^1.0.0",
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-phrasing": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-phrasing/-/mdast-util-phrasing-4.1.0.tgz",
+      "integrity": "sha512-TqICwyvJJpBwvGAMZjj4J2n0X8QWp21b9l0o7eXyVJ25YNWYbJDVIyD1bZXE6WtV6RmKJVYmQAKWa0zWOABz2w==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "unist-util-is": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-to-hast": {
+      "version": "13.2.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-to-hast/-/mdast-util-to-hast-13.2.0.tgz",
+      "integrity": "sha512-QGYKEuUsYT9ykKBCMOEDLsU5JRObWQusAolFMeko/tYPufNkRffBAQjIE+99jbA87xv6FgmjLtwjh9wBWajwAA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "@types/mdast": "^4.0.0",
+        "@ungap/structured-clone": "^1.0.0",
+        "devlop": "^1.0.0",
+        "micromark-util-sanitize-uri": "^2.0.0",
+        "trim-lines": "^3.0.0",
+        "unist-util-position": "^5.0.0",
+        "unist-util-visit": "^5.0.0",
+        "vfile": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-to-markdown": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/mdast-util-to-markdown/-/mdast-util-to-markdown-2.1.2.tgz",
+      "integrity": "sha512-xj68wMTvGXVOKonmog6LwyJKrYXZPvlwabaryTjLh9LuvovB/KAH+kvi8Gjj+7rJjsFi23nkUxRQv1KqSroMqA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "@types/unist": "^3.0.0",
+        "longest-streak": "^3.0.0",
+        "mdast-util-phrasing": "^4.0.0",
+        "mdast-util-to-string": "^4.0.0",
+        "micromark-util-classify-character": "^2.0.0",
+        "micromark-util-decode-string": "^2.0.0",
+        "unist-util-visit": "^5.0.0",
+        "zwitch": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-to-string": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-to-string/-/mdast-util-to-string-4.0.0.tgz",
+      "integrity": "sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/media-typer": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-1.1.0.tgz",
@@ -4117,6 +6236,585 @@
         "node": ">= 8"
       }
     },
+    "node_modules/micromark": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/micromark/-/micromark-4.0.2.tgz",
+      "integrity": "sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "@types/debug": "^4.0.0",
+        "debug": "^4.0.0",
+        "decode-named-character-reference": "^1.0.0",
+        "devlop": "^1.0.0",
+        "micromark-core-commonmark": "^2.0.0",
+        "micromark-factory-space": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-chunked": "^2.0.0",
+        "micromark-util-combine-extensions": "^2.0.0",
+        "micromark-util-decode-numeric-character-reference": "^2.0.0",
+        "micromark-util-encode": "^2.0.0",
+        "micromark-util-normalize-identifier": "^2.0.0",
+        "micromark-util-resolve-all": "^2.0.0",
+        "micromark-util-sanitize-uri": "^2.0.0",
+        "micromark-util-subtokenize": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-core-commonmark": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/micromark-core-commonmark/-/micromark-core-commonmark-2.0.3.tgz",
+      "integrity": "sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "decode-named-character-reference": "^1.0.0",
+        "devlop": "^1.0.0",
+        "micromark-factory-destination": "^2.0.0",
+        "micromark-factory-label": "^2.0.0",
+        "micromark-factory-space": "^2.0.0",
+        "micromark-factory-title": "^2.0.0",
+        "micromark-factory-whitespace": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-chunked": "^2.0.0",
+        "micromark-util-classify-character": "^2.0.0",
+        "micromark-util-html-tag-name": "^2.0.0",
+        "micromark-util-normalize-identifier": "^2.0.0",
+        "micromark-util-resolve-all": "^2.0.0",
+        "micromark-util-subtokenize": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-extension-frontmatter": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-frontmatter/-/micromark-extension-frontmatter-2.0.0.tgz",
+      "integrity": "sha512-C4AkuM3dA58cgZha7zVnuVxBhDsbttIMiytjgsM2XbHAB2faRVaHRle40558FBN+DJcrLNCoqG5mlrpdU4cRtg==",
+      "license": "MIT",
+      "dependencies": {
+        "fault": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm/-/micromark-extension-gfm-3.0.0.tgz",
+      "integrity": "sha512-vsKArQsicm7t0z2GugkCKtZehqUm31oeGBV/KVSorWSy8ZlNAv7ytjFhvaryUiCUJYqs+NoE6AFhpQvBTM6Q4w==",
+      "license": "MIT",
+      "dependencies": {
+        "micromark-extension-gfm-autolink-literal": "^2.0.0",
+        "micromark-extension-gfm-footnote": "^2.0.0",
+        "micromark-extension-gfm-strikethrough": "^2.0.0",
+        "micromark-extension-gfm-table": "^2.0.0",
+        "micromark-extension-gfm-tagfilter": "^2.0.0",
+        "micromark-extension-gfm-task-list-item": "^2.0.0",
+        "micromark-util-combine-extensions": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm-autolink-literal": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-autolink-literal/-/micromark-extension-gfm-autolink-literal-2.1.0.tgz",
+      "integrity": "sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw==",
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-sanitize-uri": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm-footnote": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-footnote/-/micromark-extension-gfm-footnote-2.1.0.tgz",
+      "integrity": "sha512-/yPhxI1ntnDNsiHtzLKYnE3vf9JZ6cAisqVDauhp4CEHxlb4uoOTxOCJ+9s51bIB8U1N1FJ1RXOKTIlD5B/gqw==",
+      "license": "MIT",
+      "dependencies": {
+        "devlop": "^1.0.0",
+        "micromark-core-commonmark": "^2.0.0",
+        "micromark-factory-space": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-normalize-identifier": "^2.0.0",
+        "micromark-util-sanitize-uri": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm-strikethrough": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-strikethrough/-/micromark-extension-gfm-strikethrough-2.1.0.tgz",
+      "integrity": "sha512-ADVjpOOkjz1hhkZLlBiYA9cR2Anf8F4HqZUO6e5eDcPQd0Txw5fxLzzxnEkSkfnD0wziSGiv7sYhk/ktvbf1uw==",
+      "license": "MIT",
+      "dependencies": {
+        "devlop": "^1.0.0",
+        "micromark-util-chunked": "^2.0.0",
+        "micromark-util-classify-character": "^2.0.0",
+        "micromark-util-resolve-all": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm-table": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-table/-/micromark-extension-gfm-table-2.1.1.tgz",
+      "integrity": "sha512-t2OU/dXXioARrC6yWfJ4hqB7rct14e8f7m0cbI5hUmDyyIlwv5vEtooptH8INkbLzOatzKuVbQmAYcbWoyz6Dg==",
+      "license": "MIT",
+      "dependencies": {
+        "devlop": "^1.0.0",
+        "micromark-factory-space": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm-tagfilter": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-tagfilter/-/micromark-extension-gfm-tagfilter-2.0.0.tgz",
+      "integrity": "sha512-xHlTOmuCSotIA8TW1mDIM6X2O1SiX5P9IuDtqGonFhEK0qgRI4yeC6vMxEV2dgyr2TiD+2PQ10o+cOhdVAcwfg==",
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm-task-list-item": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-task-list-item/-/micromark-extension-gfm-task-list-item-2.1.0.tgz",
+      "integrity": "sha512-qIBZhqxqI6fjLDYFTBIa4eivDMnP+OZqsNwmQ3xNLE4Cxwc+zfQEfbs6tzAo2Hjq+bh6q5F+Z8/cksrLFYWQQw==",
+      "license": "MIT",
+      "dependencies": {
+        "devlop": "^1.0.0",
+        "micromark-factory-space": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-factory-destination": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-factory-destination/-/micromark-factory-destination-2.0.1.tgz",
+      "integrity": "sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-factory-label": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-factory-label/-/micromark-factory-label-2.0.1.tgz",
+      "integrity": "sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "devlop": "^1.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-factory-space": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-factory-space/-/micromark-factory-space-2.0.1.tgz",
+      "integrity": "sha512-zRkxjtBxxLd2Sc0d+fbnEunsTj46SWXgXciZmHq0kDYGnck/ZSGj9/wULTV95uoeYiK5hRXP2mJ98Uo4cq/LQg==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-factory-title": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-factory-title/-/micromark-factory-title-2.0.1.tgz",
+      "integrity": "sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-factory-space": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-factory-whitespace": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-factory-whitespace/-/micromark-factory-whitespace-2.0.1.tgz",
+      "integrity": "sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-factory-space": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-util-character": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/micromark-util-character/-/micromark-util-character-2.1.1.tgz",
+      "integrity": "sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-util-chunked": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-util-chunked/-/micromark-util-chunked-2.0.1.tgz",
+      "integrity": "sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-symbol": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-util-classify-character": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-util-classify-character/-/micromark-util-classify-character-2.0.1.tgz",
+      "integrity": "sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-util-combine-extensions": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-util-combine-extensions/-/micromark-util-combine-extensions-2.0.1.tgz",
+      "integrity": "sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-chunked": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-util-decode-numeric-character-reference": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/micromark-util-decode-numeric-character-reference/-/micromark-util-decode-numeric-character-reference-2.0.2.tgz",
+      "integrity": "sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-symbol": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-util-decode-string": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-util-decode-string/-/micromark-util-decode-string-2.0.1.tgz",
+      "integrity": "sha512-nDV/77Fj6eH1ynwscYTOsbK7rR//Uj0bZXBwJZRfaLEJ1iGBR6kIfNmlNqaqJf649EP0F3NWNdeJi03elllNUQ==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "decode-named-character-reference": "^1.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-decode-numeric-character-reference": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-util-encode": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-util-encode/-/micromark-util-encode-2.0.1.tgz",
+      "integrity": "sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT"
+    },
+    "node_modules/micromark-util-html-tag-name": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-util-html-tag-name/-/micromark-util-html-tag-name-2.0.1.tgz",
+      "integrity": "sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT"
+    },
+    "node_modules/micromark-util-normalize-identifier": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-util-normalize-identifier/-/micromark-util-normalize-identifier-2.0.1.tgz",
+      "integrity": "sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-symbol": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-util-resolve-all": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-util-resolve-all/-/micromark-util-resolve-all-2.0.1.tgz",
+      "integrity": "sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-util-sanitize-uri": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-util-sanitize-uri/-/micromark-util-sanitize-uri-2.0.1.tgz",
+      "integrity": "sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-encode": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-util-subtokenize": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/micromark-util-subtokenize/-/micromark-util-subtokenize-2.1.0.tgz",
+      "integrity": "sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "devlop": "^1.0.0",
+        "micromark-util-chunked": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-util-symbol": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-util-symbol/-/micromark-util-symbol-2.0.1.tgz",
+      "integrity": "sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT"
+    },
+    "node_modules/micromark-util-types": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/micromark-util-types/-/micromark-util-types-2.0.2.tgz",
+      "integrity": "sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT"
+    },
     "node_modules/micromatch": {
       "version": "4.0.8",
       "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.8.tgz",
@@ -4181,7 +6879,6 @@
       "version": "2.1.3",
       "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
       "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/nanoid": {
@@ -4289,6 +6986,46 @@
         }
       }
     },
+    "node_modules/next/node_modules/postcss": {
+      "version": "8.4.31",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.4.31.tgz",
+      "integrity": "sha512-PS08Iboia9mts/2ygV3eLpY5ghnUcfLV/EXTOW1E2qYxJKGGBUtNjN76FYHnMs36RmARn41bC0AZmn+rR0OVpQ==",
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/postcss/"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/postcss"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "nanoid": "^3.3.6",
+        "picocolors": "^1.0.0",
+        "source-map-js": "^1.0.2"
+      },
+      "engines": {
+        "node": "^10 || ^12 || >=14"
+      }
+    },
+    "node_modules/nth-check": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/nth-check/-/nth-check-2.1.1.tgz",
+      "integrity": "sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w==",
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "boolbase": "^1.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/nth-check?sponsor=1"
+      }
+    },
     "node_modules/object-assign": {
       "version": "4.1.1",
       "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz",
@@ -4412,6 +7149,27 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/octokit": {
+      "version": "4.1.3",
+      "resolved": "https://registry.npmjs.org/octokit/-/octokit-4.1.3.tgz",
+      "integrity": "sha512-PP+EL8h4xPCE9NBo6jXq6I2/EiTXsn1cg9F0IZehHBv/qhuQpyGMFElEB17miWKciuT6vRHiFFiG9+FoXOmg6A==",
+      "license": "MIT",
+      "dependencies": {
+        "@octokit/app": "^15.1.6",
+        "@octokit/core": "^6.1.5",
+        "@octokit/oauth-app": "^7.1.6",
+        "@octokit/plugin-paginate-graphql": "^5.2.4",
+        "@octokit/plugin-paginate-rest": "^12.0.0",
+        "@octokit/plugin-rest-endpoint-methods": "^14.0.0",
+        "@octokit/plugin-retry": "^7.2.1",
+        "@octokit/plugin-throttling": "^10.0.0",
+        "@octokit/request-error": "^6.1.8",
+        "@octokit/types": "^14.0.0"
+      },
+      "engines": {
+        "node": ">= 18"
+      }
+    },
     "node_modules/on-finished": {
       "version": "2.4.1",
       "resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz",
@@ -4435,6 +7193,23 @@
         "wrappy": "1"
       }
     },
+    "node_modules/oniguruma-parser": {
+      "version": "0.12.1",
+      "resolved": "https://registry.npmjs.org/oniguruma-parser/-/oniguruma-parser-0.12.1.tgz",
+      "integrity": "sha512-8Unqkvk1RYc6yq2WBYRj4hdnsAxVze8i7iPfQr8e4uSP3tRv0rpZcbGUDvxfQQcdwHt/e9PrMvGCsa8OqG9X3w==",
+      "license": "MIT"
+    },
+    "node_modules/oniguruma-to-es": {
+      "version": "4.3.3",
+      "resolved": "https://registry.npmjs.org/oniguruma-to-es/-/oniguruma-to-es-4.3.3.tgz",
+      "integrity": "sha512-rPiZhzC3wXwE59YQMRDodUwwT9FZ9nNBwQQfsd1wfdtlKEyCdRV0avrTcSZ5xlIvGRVPd/cx6ZN45ECmS39xvg==",
+      "license": "MIT",
+      "dependencies": {
+        "oniguruma-parser": "^0.12.1",
+        "regex": "^6.0.1",
+        "regex-recursion": "^6.0.2"
+      }
+    },
     "node_modules/optionator": {
       "version": "0.9.4",
       "resolved": "https://registry.npmjs.org/optionator/-/optionator-0.9.4.tgz",
@@ -4516,6 +7291,43 @@
         "node": ">=6"
       }
     },
+    "node_modules/parse-entities": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/parse-entities/-/parse-entities-4.0.2.tgz",
+      "integrity": "sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^2.0.0",
+        "character-entities-legacy": "^3.0.0",
+        "character-reference-invalid": "^2.0.0",
+        "decode-named-character-reference": "^1.0.0",
+        "is-alphanumerical": "^2.0.0",
+        "is-decimal": "^2.0.0",
+        "is-hexadecimal": "^2.0.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/parse-entities/node_modules/@types/unist": {
+      "version": "2.0.11",
+      "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.11.tgz",
+      "integrity": "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==",
+      "license": "MIT"
+    },
+    "node_modules/parse5": {
+      "version": "7.3.0",
+      "resolved": "https://registry.npmjs.org/parse5/-/parse5-7.3.0.tgz",
+      "integrity": "sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw==",
+      "license": "MIT",
+      "dependencies": {
+        "entities": "^6.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/inikulin/parse5?sponsor=1"
+      }
+    },
     "node_modules/parseurl": {
       "version": "1.3.3",
       "resolved": "https://registry.npmjs.org/parseurl/-/parseurl-1.3.3.tgz",
@@ -4603,9 +7415,10 @@
       }
     },
     "node_modules/postcss": {
-      "version": "8.4.31",
-      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.4.31.tgz",
-      "integrity": "sha512-PS08Iboia9mts/2ygV3eLpY5ghnUcfLV/EXTOW1E2qYxJKGGBUtNjN76FYHnMs36RmARn41bC0AZmn+rR0OVpQ==",
+      "version": "8.5.3",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.3.tgz",
+      "integrity": "sha512-dle9A3yYxlBSrt8Fu+IpjGT8SY8hN0mlaA6GY8t0P5PjIOZemULz/E2Bnm/2dcUOena75OTNkHI76uZBNUUq3A==",
+      "dev": true,
       "funding": [
         {
           "type": "opencollective",
@@ -4622,14 +7435,128 @@
       ],
       "license": "MIT",
       "dependencies": {
-        "nanoid": "^3.3.6",
-        "picocolors": "^1.0.0",
-        "source-map-js": "^1.0.2"
+        "nanoid": "^3.3.8",
+        "picocolors": "^1.1.1",
+        "source-map-js": "^1.2.1"
       },
       "engines": {
         "node": "^10 || ^12 || >=14"
       }
     },
+    "node_modules/postcss-js": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/postcss-js/-/postcss-js-4.0.1.tgz",
+      "integrity": "sha512-dDLF8pEO191hJMtlHFPRa8xsizHaM82MLfNkUHdUtVEV3tgTp5oj+8qbEqYM57SLfc74KSbw//4SeJma2LRVIw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "camelcase-css": "^2.0.1"
+      },
+      "engines": {
+        "node": "^12 || ^14 || >= 16"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/postcss/"
+      },
+      "peerDependencies": {
+        "postcss": "^8.4.21"
+      }
+    },
+    "node_modules/postcss-mixins": {
+      "version": "9.0.4",
+      "resolved": "https://registry.npmjs.org/postcss-mixins/-/postcss-mixins-9.0.4.tgz",
+      "integrity": "sha512-XVq5jwQJDRu5M1XGkdpgASqLk37OqkH4JCFDXl/Dn7janOJjCTEKL+36cnRVy7bMtoBzALfO7bV7nTIsFnUWLA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fast-glob": "^3.2.11",
+        "postcss-js": "^4.0.0",
+        "postcss-simple-vars": "^7.0.0",
+        "sugarss": "^4.0.1"
+      },
+      "engines": {
+        "node": ">=14.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/postcss/"
+      },
+      "peerDependencies": {
+        "postcss": "^8.2.14"
+      }
+    },
+    "node_modules/postcss-nested": {
+      "version": "6.2.0",
+      "resolved": "https://registry.npmjs.org/postcss-nested/-/postcss-nested-6.2.0.tgz",
+      "integrity": "sha512-HQbt28KulC5AJzG+cZtj9kvKB93CFCdLvog1WFLf1D+xmMvPGlBstkpTEZfK5+AN9hfJocyBFCNiqyS48bpgzQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/postcss/"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "postcss-selector-parser": "^6.1.1"
+      },
+      "engines": {
+        "node": ">=12.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.2.14"
+      }
+    },
+    "node_modules/postcss-preset-mantine": {
+      "version": "1.17.0",
+      "resolved": "https://registry.npmjs.org/postcss-preset-mantine/-/postcss-preset-mantine-1.17.0.tgz",
+      "integrity": "sha512-ji1PMDBUf2Vsx/HE5faMSs1+ff6qE6YRulTr4Ja+6HD3gop8rSMTCYdpN7KrdsEg079kfBKkO/PaKhG9uR0zwQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "postcss-mixins": "^9.0.4",
+        "postcss-nested": "^6.0.1"
+      },
+      "peerDependencies": {
+        "postcss": ">=8.0.0"
+      }
+    },
+    "node_modules/postcss-selector-parser": {
+      "version": "6.1.2",
+      "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-6.1.2.tgz",
+      "integrity": "sha512-Q8qQfPiZ+THO/3ZrOrO0cJJKfpYCagtMUkXbnEfmgUjwXg6z/WBeOyS9APBBPCTSiDV+s4SwQGu8yFsiMRIudg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cssesc": "^3.0.0",
+        "util-deprecate": "^1.0.2"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/postcss-simple-vars": {
+      "version": "7.0.1",
+      "resolved": "https://registry.npmjs.org/postcss-simple-vars/-/postcss-simple-vars-7.0.1.tgz",
+      "integrity": "sha512-5GLLXaS8qmzHMOjVxqkk1TZPf1jMqesiI7qLhnlyERalG0sMbHIbJqrcnrpmZdKCLglHnRHoEBB61RtGTsj++A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/postcss/"
+      },
+      "peerDependencies": {
+        "postcss": "^8.2.1"
+      }
+    },
     "node_modules/prelude-ls": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/prelude-ls/-/prelude-ls-1.2.1.tgz",
@@ -4652,6 +7579,16 @@
         "react-is": "^16.13.1"
       }
     },
+    "node_modules/property-information": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/property-information/-/property-information-7.0.0.tgz",
+      "integrity": "sha512-7D/qOz/+Y4X/rzSB6jKxKUsQnphO046ei8qxG59mtM3RG3DHgTK81HrxrmoDVINJb8NKT5ZsRbwHvQ6B68Iyhg==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/proxy-addr": {
       "version": "2.0.7",
       "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz",
@@ -4767,6 +7704,129 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/react-markdown": {
+      "version": "10.1.0",
+      "resolved": "https://registry.npmjs.org/react-markdown/-/react-markdown-10.1.0.tgz",
+      "integrity": "sha512-qKxVopLT/TyA6BX3Ue5NwabOsAzm0Q7kAPwq6L+wWDwisYs7R8vZ0nRXqq6rkueboxpkjvLGU9fWifiX/ZZFxQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "@types/mdast": "^4.0.0",
+        "devlop": "^1.0.0",
+        "hast-util-to-jsx-runtime": "^2.0.0",
+        "html-url-attributes": "^3.0.0",
+        "mdast-util-to-hast": "^13.0.0",
+        "remark-parse": "^11.0.0",
+        "remark-rehype": "^11.0.0",
+        "unified": "^11.0.0",
+        "unist-util-visit": "^5.0.0",
+        "vfile": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      },
+      "peerDependencies": {
+        "@types/react": ">=18",
+        "react": ">=18"
+      }
+    },
+    "node_modules/react-number-format": {
+      "version": "5.4.4",
+      "resolved": "https://registry.npmjs.org/react-number-format/-/react-number-format-5.4.4.tgz",
+      "integrity": "sha512-wOmoNZoOpvMminhifQYiYSTCLUDOiUbBunrMrMjA+dV52sY+vck1S4UhR6PkgnoCquvvMSeJjErXZ4qSaWCliA==",
+      "license": "MIT",
+      "peerDependencies": {
+        "react": "^0.14 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+        "react-dom": "^0.14 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      }
+    },
+    "node_modules/react-remove-scroll": {
+      "version": "2.6.3",
+      "resolved": "https://registry.npmjs.org/react-remove-scroll/-/react-remove-scroll-2.6.3.tgz",
+      "integrity": "sha512-pnAi91oOk8g8ABQKGF5/M9qxmmOPxaAnopyTHYfqYEwJhyFrbbBtHuSgtKEoH0jpcxx5o3hXqH1mNd9/Oi+8iQ==",
+      "license": "MIT",
+      "dependencies": {
+        "react-remove-scroll-bar": "^2.3.7",
+        "react-style-singleton": "^2.2.3",
+        "tslib": "^2.1.0",
+        "use-callback-ref": "^1.3.3",
+        "use-sidecar": "^1.1.3"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/react-remove-scroll-bar": {
+      "version": "2.3.8",
+      "resolved": "https://registry.npmjs.org/react-remove-scroll-bar/-/react-remove-scroll-bar-2.3.8.tgz",
+      "integrity": "sha512-9r+yi9+mgU33AKcj6IbT9oRCO78WriSj6t/cF8DWBZJ9aOGPOTEDvdUDz1FwKim7QXWwmHqtdHnRJfhAxEG46Q==",
+      "license": "MIT",
+      "dependencies": {
+        "react-style-singleton": "^2.2.2",
+        "tslib": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/react-style-singleton": {
+      "version": "2.2.3",
+      "resolved": "https://registry.npmjs.org/react-style-singleton/-/react-style-singleton-2.2.3.tgz",
+      "integrity": "sha512-b6jSvxvVnyptAiLjbkWLE/lOnR4lfTtDAl+eUC7RZy+QQWc6wRzIV2CE6xBuMmDxc2qIihtDCZD5NPOFl7fRBQ==",
+      "license": "MIT",
+      "dependencies": {
+        "get-nonce": "^1.0.0",
+        "tslib": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/react-textarea-autosize": {
+      "version": "8.5.9",
+      "resolved": "https://registry.npmjs.org/react-textarea-autosize/-/react-textarea-autosize-8.5.9.tgz",
+      "integrity": "sha512-U1DGlIQN5AwgjTyOEnI1oCcMuEr1pv1qOtklB2l4nyMGbHzWrI0eFsYK0zos2YWqAolJyG0IWJaqWmWj5ETh0A==",
+      "license": "MIT",
+      "dependencies": {
+        "@babel/runtime": "^7.20.13",
+        "use-composed-ref": "^1.3.0",
+        "use-latest": "^1.2.1"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "peerDependencies": {
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      }
+    },
     "node_modules/reflect.getprototypeof": {
       "version": "1.0.10",
       "resolved": "https://registry.npmjs.org/reflect.getprototypeof/-/reflect.getprototypeof-1.0.10.tgz",
@@ -4790,6 +7850,30 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/regex": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/regex/-/regex-6.0.1.tgz",
+      "integrity": "sha512-uorlqlzAKjKQZ5P+kTJr3eeJGSVroLKoHmquUj4zHWuR+hEyNqlXsSKlYYF5F4NI6nl7tWCs0apKJ0lmfsXAPA==",
+      "license": "MIT",
+      "dependencies": {
+        "regex-utilities": "^2.3.0"
+      }
+    },
+    "node_modules/regex-recursion": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/regex-recursion/-/regex-recursion-6.0.2.tgz",
+      "integrity": "sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg==",
+      "license": "MIT",
+      "dependencies": {
+        "regex-utilities": "^2.3.0"
+      }
+    },
+    "node_modules/regex-utilities": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/regex-utilities/-/regex-utilities-2.3.0.tgz",
+      "integrity": "sha512-8VhliFJAWRaUiVvREIiW2NXXTmHs4vMNnSzuJVhscgmGav3g9VDxLrQndI3dZZVVdp0ZO/5v0xmX516/7M9cng==",
+      "license": "MIT"
+    },
     "node_modules/regexp.prototype.flags": {
       "version": "1.5.4",
       "resolved": "https://registry.npmjs.org/regexp.prototype.flags/-/regexp.prototype.flags-1.5.4.tgz",
@@ -4811,6 +7895,123 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/rehype-autolink-headings": {
+      "version": "7.1.0",
+      "resolved": "https://registry.npmjs.org/rehype-autolink-headings/-/rehype-autolink-headings-7.1.0.tgz",
+      "integrity": "sha512-rItO/pSdvnvsP4QRB1pmPiNHUskikqtPojZKJPPPAVx9Hj8i8TwMBhofrrAYRhYOOBZH9tgmG5lPqDLuIWPWmw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "@ungap/structured-clone": "^1.0.0",
+        "hast-util-heading-rank": "^3.0.0",
+        "hast-util-is-element": "^3.0.0",
+        "unified": "^11.0.0",
+        "unist-util-visit": "^5.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/rehype-slug": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/rehype-slug/-/rehype-slug-6.0.0.tgz",
+      "integrity": "sha512-lWyvf/jwu+oS5+hL5eClVd3hNdmwM1kAC0BUvEGD19pajQMIzcNUd/k9GsfQ+FfECvX+JE+e9/btsKH0EjJT6A==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "github-slugger": "^2.0.0",
+        "hast-util-heading-rank": "^3.0.0",
+        "hast-util-to-string": "^3.0.0",
+        "unist-util-visit": "^5.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/remark-frontmatter": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/remark-frontmatter/-/remark-frontmatter-5.0.0.tgz",
+      "integrity": "sha512-XTFYvNASMe5iPN0719nPrdItC9aU0ssC4v14mH1BCi1u0n1gAocqcujWUrByftZTbLhRtiKRyjYTSIOcr69UVQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "mdast-util-frontmatter": "^2.0.0",
+        "micromark-extension-frontmatter": "^2.0.0",
+        "unified": "^11.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/remark-gfm": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/remark-gfm/-/remark-gfm-4.0.1.tgz",
+      "integrity": "sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "mdast-util-gfm": "^3.0.0",
+        "micromark-extension-gfm": "^3.0.0",
+        "remark-parse": "^11.0.0",
+        "remark-stringify": "^11.0.0",
+        "unified": "^11.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/remark-parse": {
+      "version": "11.0.0",
+      "resolved": "https://registry.npmjs.org/remark-parse/-/remark-parse-11.0.0.tgz",
+      "integrity": "sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "mdast-util-from-markdown": "^2.0.0",
+        "micromark-util-types": "^2.0.0",
+        "unified": "^11.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/remark-rehype": {
+      "version": "11.1.2",
+      "resolved": "https://registry.npmjs.org/remark-rehype/-/remark-rehype-11.1.2.tgz",
+      "integrity": "sha512-Dh7l57ianaEoIpzbp0PC9UKAdCSVklD8E5Rpw7ETfbTl3FqcOOgq5q2LVDhgGCkaBv7p24JXikPdvhhmHvKMsw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "@types/mdast": "^4.0.0",
+        "mdast-util-to-hast": "^13.0.0",
+        "unified": "^11.0.0",
+        "vfile": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/remark-stringify": {
+      "version": "11.0.0",
+      "resolved": "https://registry.npmjs.org/remark-stringify/-/remark-stringify-11.0.0.tgz",
+      "integrity": "sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "mdast-util-to-markdown": "^2.0.0",
+        "unified": "^11.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/resolve": {
       "version": "1.22.10",
       "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.22.10.tgz",
@@ -4993,6 +8194,19 @@
       "integrity": "sha512-NlHwttCI/l5gCPR3D1nNXtWABUmBwvZpEQiD4IXSbIDq8BzLIK/7Ir5gTFSGZDUu37K5cMNp0hFtzO38sC7gWA==",
       "license": "MIT"
     },
+    "node_modules/section-matter": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/section-matter/-/section-matter-1.0.0.tgz",
+      "integrity": "sha512-vfD3pmTzGpufjScBh50YHKzEu2lxBWhVEHsNGoEXmCmn2hKGfeNLYMzCJpe8cD7gqX7TJluOVpBkAequ6dgMmA==",
+      "license": "MIT",
+      "dependencies": {
+        "extend-shallow": "^2.0.1",
+        "kind-of": "^6.0.0"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
     "node_modules/semver": {
       "version": "7.7.1",
       "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.1.tgz",
@@ -5165,6 +8379,22 @@
         "node": ">=8"
       }
     },
+    "node_modules/shiki": {
+      "version": "3.4.0",
+      "resolved": "https://registry.npmjs.org/shiki/-/shiki-3.4.0.tgz",
+      "integrity": "sha512-Ni80XHcqhOEXv5mmDAvf5p6PAJqbUc/RzFeaOqk+zP5DLvTPS3j0ckvA+MI87qoxTQ5RGJDVTbdl/ENLSyyAnQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/core": "3.4.0",
+        "@shikijs/engine-javascript": "3.4.0",
+        "@shikijs/engine-oniguruma": "3.4.0",
+        "@shikijs/langs": "3.4.0",
+        "@shikijs/themes": "3.4.0",
+        "@shikijs/types": "3.4.0",
+        "@shikijs/vscode-textmate": "^10.0.2",
+        "@types/hast": "^3.0.4"
+      }
+    },
     "node_modules/side-channel": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.0.tgz",
@@ -5260,6 +8490,22 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/space-separated-tokens": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/space-separated-tokens/-/space-separated-tokens-2.0.2.tgz",
+      "integrity": "sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/sprintf-js": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz",
+      "integrity": "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==",
+      "license": "BSD-3-Clause"
+    },
     "node_modules/stable-hash": {
       "version": "0.0.5",
       "resolved": "https://registry.npmjs.org/stable-hash/-/stable-hash-0.0.5.tgz",
@@ -5398,6 +8644,20 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/stringify-entities": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/stringify-entities/-/stringify-entities-4.0.4.tgz",
+      "integrity": "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==",
+      "license": "MIT",
+      "dependencies": {
+        "character-entities-html4": "^2.0.0",
+        "character-entities-legacy": "^3.0.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/strip-bom": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/strip-bom/-/strip-bom-3.0.0.tgz",
@@ -5408,6 +8668,15 @@
         "node": ">=4"
       }
     },
+    "node_modules/strip-bom-string": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/strip-bom-string/-/strip-bom-string-1.0.0.tgz",
+      "integrity": "sha512-uCC2VHvQRYu+lMh4My/sFNmF2klFymLX1wHJeXnbEJERpV/ZsVuonzerjfrGpIGF7LBVa1O7i9kjiWvJiFck8g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/strip-json-comments": {
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-3.1.1.tgz",
@@ -5421,6 +8690,24 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/style-to-js": {
+      "version": "1.1.16",
+      "resolved": "https://registry.npmjs.org/style-to-js/-/style-to-js-1.1.16.tgz",
+      "integrity": "sha512-/Q6ld50hKYPH3d/r6nr117TZkHR0w0kGGIVfpG9N6D8NymRPM9RqCUv4pRpJ62E5DqOYx2AFpbZMyCPnjQCnOw==",
+      "license": "MIT",
+      "dependencies": {
+        "style-to-object": "1.0.8"
+      }
+    },
+    "node_modules/style-to-object": {
+      "version": "1.0.8",
+      "resolved": "https://registry.npmjs.org/style-to-object/-/style-to-object-1.0.8.tgz",
+      "integrity": "sha512-xT47I/Eo0rwJmaXC4oilDGDWLohVhR6o/xAQcPQN8q6QBuZVL8qMYL85kLmST5cPjAorwvqIA4qXTRQoYHaL6g==",
+      "license": "MIT",
+      "dependencies": {
+        "inline-style-parser": "0.2.4"
+      }
+    },
     "node_modules/styled-jsx": {
       "version": "5.1.6",
       "resolved": "https://registry.npmjs.org/styled-jsx/-/styled-jsx-5.1.6.tgz",
@@ -5444,6 +8731,23 @@
         }
       }
     },
+    "node_modules/sugarss": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/sugarss/-/sugarss-4.0.1.tgz",
+      "integrity": "sha512-WCjS5NfuVJjkQzK10s8WOBY+hhDxxNt/N6ZaGwxFZ+wN3/lKKFSaaKUNecULcTTvE4urLcKaZFQD8vO0mOZujw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/postcss/"
+      },
+      "peerDependencies": {
+        "postcss": "^8.3.3"
+      }
+    },
     "node_modules/supports-color": {
       "version": "7.2.0",
       "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz",
@@ -5470,6 +8774,12 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/tabbable": {
+      "version": "6.2.0",
+      "resolved": "https://registry.npmjs.org/tabbable/-/tabbable-6.2.0.tgz",
+      "integrity": "sha512-Cat63mxsVJlzYvN51JmVXIgNoUokrIaT2zLclCXjRd8boZ0004U4KCs/sToJ75C6sdlByWxpYnb5Boif1VSFew==",
+      "license": "MIT"
+    },
     "node_modules/tinyglobby": {
       "version": "0.2.13",
       "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.13.tgz",
@@ -5528,6 +8838,15 @@
         "node": ">=8.0"
       }
     },
+    "node_modules/toad-cache": {
+      "version": "3.7.0",
+      "resolved": "https://registry.npmjs.org/toad-cache/-/toad-cache-3.7.0.tgz",
+      "integrity": "sha512-/m8M+2BJUpoJdgAHoG+baCwBT+tf2VraSfkBgl0Y00qIWt41DJ8R5B8nsEw0I58YwF5IZH6z24/2TobDKnqSWw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/toidentifier": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz",
@@ -5538,6 +8857,26 @@
         "node": ">=0.6"
       }
     },
+    "node_modules/trim-lines": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/trim-lines/-/trim-lines-3.0.1.tgz",
+      "integrity": "sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/trough": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/trough/-/trough-2.2.0.tgz",
+      "integrity": "sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/ts-api-utils": {
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/ts-api-utils/-/ts-api-utils-2.1.0.tgz",
@@ -5570,6 +8909,26 @@
       "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
       "license": "0BSD"
     },
+    "node_modules/tsx": {
+      "version": "4.19.4",
+      "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.19.4.tgz",
+      "integrity": "sha512-gK5GVzDkJK1SI1zwHf32Mqxf2tSJkNx+eYcNly5+nHvWqXUJYUkWBQtKauoESz3ymezAI++ZwT855x5p5eop+Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "~0.25.0",
+        "get-tsconfig": "^4.7.5"
+      },
+      "bin": {
+        "tsx": "dist/cli.mjs"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      }
+    },
     "node_modules/type-check": {
       "version": "0.4.0",
       "resolved": "https://registry.npmjs.org/type-check/-/type-check-0.4.0.tgz",
@@ -5583,6 +8942,18 @@
         "node": ">= 0.8.0"
       }
     },
+    "node_modules/type-fest": {
+      "version": "4.41.0",
+      "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-4.41.0.tgz",
+      "integrity": "sha512-TeTSQ6H5YHvpqVwBRcnLDCBnDOHWYu7IvGbHT6N8AOymcr9PJGjc1GTtiWZTYg0NCgYwvnYWEkVChQAr9bjfwA==",
+      "license": "(MIT OR CC0-1.0)",
+      "engines": {
+        "node": ">=16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/type-is": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/type-is/-/type-is-2.0.1.tgz",
@@ -5716,6 +9087,105 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/unified": {
+      "version": "11.0.5",
+      "resolved": "https://registry.npmjs.org/unified/-/unified-11.0.5.tgz",
+      "integrity": "sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0",
+        "bail": "^2.0.0",
+        "devlop": "^1.0.0",
+        "extend": "^3.0.0",
+        "is-plain-obj": "^4.0.0",
+        "trough": "^2.0.0",
+        "vfile": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/unist-util-is": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/unist-util-is/-/unist-util-is-6.0.0.tgz",
+      "integrity": "sha512-2qCTHimwdxLfz+YzdGfkqNlH0tLi9xjTnHddPmJwtIG9MGsdbutfTc4P+haPD7l7Cjxf/WZj+we5qfVPvvxfYw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/unist-util-position": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/unist-util-position/-/unist-util-position-5.0.0.tgz",
+      "integrity": "sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/unist-util-stringify-position": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/unist-util-stringify-position/-/unist-util-stringify-position-4.0.0.tgz",
+      "integrity": "sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/unist-util-visit": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-5.0.0.tgz",
+      "integrity": "sha512-MR04uvD+07cwl/yhVuVWAtw+3GOR/knlL55Nd/wAdblk27GCVt3lqpTivy/tkJcZoNPzTwS1Y+KMojlLDhoTzg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0",
+        "unist-util-is": "^6.0.0",
+        "unist-util-visit-parents": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/unist-util-visit-parents": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/unist-util-visit-parents/-/unist-util-visit-parents-6.0.1.tgz",
+      "integrity": "sha512-L/PqWzfTP9lzzEa6CKs0k2nARxTdZduw3zyh8d2NVBnsyvHjSX4TWse388YrrQKbvI8w20fGjGlhgT96WwKykw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0",
+        "unist-util-is": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/universal-github-app-jwt": {
+      "version": "2.2.2",
+      "resolved": "https://registry.npmjs.org/universal-github-app-jwt/-/universal-github-app-jwt-2.2.2.tgz",
+      "integrity": "sha512-dcmbeSrOdTnsjGjUfAlqNDJrhxXizjAz94ija9Qw8YkZ1uu0d+GoZzyH+Jb9tIIqvGsadUfwg+22k5aDqqwzbw==",
+      "license": "MIT"
+    },
+    "node_modules/universal-user-agent": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/universal-user-agent/-/universal-user-agent-7.0.2.tgz",
+      "integrity": "sha512-0JCqzSKnStlRRQfCdowvqy3cy0Dvtlb8xecj/H8JFZuCze4rwjPZQOgvFvn0Ws/usCHQFGpyr+pB9adaGwXn4Q==",
+      "license": "ISC"
+    },
     "node_modules/unpipe": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz",
@@ -5769,6 +9239,101 @@
         "punycode": "^2.1.0"
       }
     },
+    "node_modules/use-callback-ref": {
+      "version": "1.3.3",
+      "resolved": "https://registry.npmjs.org/use-callback-ref/-/use-callback-ref-1.3.3.tgz",
+      "integrity": "sha512-jQL3lRnocaFtu3V00JToYz/4QkNWswxijDaCVNZRiRTO3HQDLsdu1ZtmIUvV4yPp+rvWm5j0y0TG/S61cuijTg==",
+      "license": "MIT",
+      "dependencies": {
+        "tslib": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/use-composed-ref": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/use-composed-ref/-/use-composed-ref-1.4.0.tgz",
+      "integrity": "sha512-djviaxuOOh7wkj0paeO1Q/4wMZ8Zrnag5H6yBvzN7AKKe8beOaED9SF5/ByLqsku8NP4zQqsvM2u3ew/tJK8/w==",
+      "license": "MIT",
+      "peerDependencies": {
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/use-isomorphic-layout-effect": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/use-isomorphic-layout-effect/-/use-isomorphic-layout-effect-1.2.0.tgz",
+      "integrity": "sha512-q6ayo8DWoPZT0VdG4u3D3uxcgONP3Mevx2i2b0434cwWBoL+aelL1DzkXI6w3PhTZzUeR2kaVlZn70iCiseP6w==",
+      "license": "MIT",
+      "peerDependencies": {
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/use-latest": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/use-latest/-/use-latest-1.3.0.tgz",
+      "integrity": "sha512-mhg3xdm9NaM8q+gLT8KryJPnRFOz1/5XPBhmDEVZK1webPzDjrPk7f/mbpeLqTgB9msytYWANxgALOCJKnLvcQ==",
+      "license": "MIT",
+      "dependencies": {
+        "use-isomorphic-layout-effect": "^1.1.1"
+      },
+      "peerDependencies": {
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/use-sidecar": {
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/use-sidecar/-/use-sidecar-1.1.3.tgz",
+      "integrity": "sha512-Fedw0aZvkhynoPYlA5WXrMCAMm+nSWdZt6lzJQ7Ok8S6Q+VsHmHpRWndVRJ8Be0ZbkfPc5LRYH+5XrzXcEeLRQ==",
+      "license": "MIT",
+      "dependencies": {
+        "detect-node-es": "^1.1.0",
+        "tslib": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/util-deprecate": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
+      "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/vary": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz",
@@ -5779,6 +9344,58 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/vfile": {
+      "version": "6.0.3",
+      "resolved": "https://registry.npmjs.org/vfile/-/vfile-6.0.3.tgz",
+      "integrity": "sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0",
+        "vfile-message": "^4.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/vfile-location": {
+      "version": "5.0.3",
+      "resolved": "https://registry.npmjs.org/vfile-location/-/vfile-location-5.0.3.tgz",
+      "integrity": "sha512-5yXvWDEgqeiYiBe1lbxYF7UMAIm/IcopxMHrMQDq3nvKcjPKIhZklUKL+AE7J7uApI4kwe2snsK+eI6UTj9EHg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0",
+        "vfile": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/vfile-message": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/vfile-message/-/vfile-message-4.0.2.tgz",
+      "integrity": "sha512-jRDZ1IMLttGj41KcZvlrYAaI3CfqpLpfpf+Mfig13viT6NKvRzWZ+lXz0Y5D60w6uJIBAOGq9mSHf0gktF0duw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0",
+        "unist-util-stringify-position": "^4.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/web-namespaces": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/web-namespaces/-/web-namespaces-2.0.1.tgz",
+      "integrity": "sha512-bKr1DkiNa2krS7qxNtdrtHAmzuYGFQLiQ13TsorsdT6ULTkPLKuu5+GsFpDlg6JFjUTwX2DyhMPG2be8uPrqsQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/which": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
@@ -5933,6 +9550,16 @@
       "peerDependencies": {
         "zod": "^3.24.1"
       }
+    },
+    "node_modules/zwitch": {
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/zwitch/-/zwitch-2.0.4.tgz",
+      "integrity": "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
     }
   }
 }
diff --git a/package.json b/package.json
index 55abf671..8d90c918 100644
--- a/package.json
+++ b/package.json
@@ -2,24 +2,48 @@
   "name": "prometheus-next",
   "version": "0.1.0",
   "private": true,
+  "type": "module",
   "scripts": {
     "dev": "next dev --turbopack",
+    "fetch-repo-docs": "tsx scripts/fetch-repo-docs.ts",
+    "clean": "rm -rf generated out .next",
     "build": "next build",
     "start": "next start",
     "lint": "next lint"
   },
   "dependencies": {
+    "@mantine/code-highlight": "^8.0.0",
+    "@mantine/core": "^8.0.0",
+    "@mantine/hooks": "^8.0.0",
+    "@tabler/icons-react": "^3.31.0",
+    "gray-matter": "^4.0.3",
+    "hast-util-from-html": "^2.0.3",
+    "hast-util-select": "^6.0.4",
+    "hastscript": "^9.0.1",
+    "next": "15.3.1",
+    "octokit": "^4.1.3",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "next": "15.3.1"
+    "react-markdown": "^10.1.0",
+    "rehype-autolink-headings": "^7.1.0",
+    "rehype-slug": "^6.0.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.1",
+    "shiki": "^3.4.0"
   },
   "devDependencies": {
-    "typescript": "^5",
+    "@eslint/eslintrc": "^3",
+    "@shikijs/rehype": "^3.4.0",
     "@types/node": "^20",
     "@types/react": "^19",
     "@types/react-dom": "^19",
+    "dotenv": "^16.5.0",
     "eslint": "^9",
     "eslint-config-next": "15.3.1",
-    "@eslint/eslintrc": "^3"
+    "postcss": "^8.5.3",
+    "postcss-preset-mantine": "^1.17.0",
+    "postcss-simple-vars": "^7.0.1",
+    "tsx": "^4.19.4",
+    "typescript": "^5"
   }
 }
diff --git a/postcss.config.cjs b/postcss.config.cjs
new file mode 100644
index 00000000..e817f567
--- /dev/null
+++ b/postcss.config.cjs
@@ -0,0 +1,14 @@
+module.exports = {
+  plugins: {
+    "postcss-preset-mantine": {},
+    "postcss-simple-vars": {
+      variables: {
+        "mantine-breakpoint-xs": "36em",
+        "mantine-breakpoint-sm": "48em",
+        "mantine-breakpoint-md": "62em",
+        "mantine-breakpoint-lg": "75em",
+        "mantine-breakpoint-xl": "88em",
+      },
+    },
+  },
+};
diff --git a/public/assets/company-logos/Amadeus.png b/public/assets/company-logos/Amadeus.png
new file mode 100644
index 00000000..b7d80898
Binary files /dev/null and b/public/assets/company-logos/Amadeus.png differ
diff --git a/public/assets/company-logos/Argus.png b/public/assets/company-logos/Argus.png
new file mode 100644
index 00000000..ca046cb3
Binary files /dev/null and b/public/assets/company-logos/Argus.png differ
diff --git a/public/assets/company-logos/Boxever.png b/public/assets/company-logos/Boxever.png
new file mode 100644
index 00000000..b5ccb9d7
Binary files /dev/null and b/public/assets/company-logos/Boxever.png differ
diff --git a/public/assets/company-logos/CoreOS.png b/public/assets/company-logos/CoreOS.png
new file mode 100644
index 00000000..c6db7c41
Binary files /dev/null and b/public/assets/company-logos/CoreOS.png differ
diff --git a/public/assets/company-logos/Docker.png b/public/assets/company-logos/Docker.png
new file mode 100644
index 00000000..ac639620
Binary files /dev/null and b/public/assets/company-logos/Docker.png differ
diff --git a/public/assets/company-logos/Ericsson.png b/public/assets/company-logos/Ericsson.png
new file mode 100644
index 00000000..a748d95e
Binary files /dev/null and b/public/assets/company-logos/Ericsson.png differ
diff --git a/public/assets/company-logos/Eurotech.png b/public/assets/company-logos/Eurotech.png
new file mode 100644
index 00000000..2b97de4e
Binary files /dev/null and b/public/assets/company-logos/Eurotech.png differ
diff --git a/public/assets/company-logos/Fosdem.png b/public/assets/company-logos/Fosdem.png
new file mode 100644
index 00000000..5c89ff35
Binary files /dev/null and b/public/assets/company-logos/Fosdem.png differ
diff --git a/public/assets/company-logos/FreshTracks.png b/public/assets/company-logos/FreshTracks.png
new file mode 100644
index 00000000..8d3d76f3
Binary files /dev/null and b/public/assets/company-logos/FreshTracks.png differ
diff --git a/public/assets/company-logos/Improbable.png b/public/assets/company-logos/Improbable.png
new file mode 100644
index 00000000..dba9dce6
Binary files /dev/null and b/public/assets/company-logos/Improbable.png differ
diff --git a/public/assets/company-logos/Jodel.png b/public/assets/company-logos/Jodel.png
new file mode 100644
index 00000000..c74ec1a9
Binary files /dev/null and b/public/assets/company-logos/Jodel.png differ
diff --git a/public/assets/company-logos/JustWatch.png b/public/assets/company-logos/JustWatch.png
new file mode 100644
index 00000000..9e0061e1
Binary files /dev/null and b/public/assets/company-logos/JustWatch.png differ
diff --git a/public/assets/company-logos/Kubermatic.png b/public/assets/company-logos/Kubermatic.png
new file mode 100644
index 00000000..fb3fe2e1
Binary files /dev/null and b/public/assets/company-logos/Kubermatic.png differ
diff --git a/public/assets/company-logos/Kumina.png b/public/assets/company-logos/Kumina.png
new file mode 100644
index 00000000..69599ead
Binary files /dev/null and b/public/assets/company-logos/Kumina.png differ
diff --git a/public/assets/company-logos/MOIA.png b/public/assets/company-logos/MOIA.png
new file mode 100644
index 00000000..7699d2e1
Binary files /dev/null and b/public/assets/company-logos/MOIA.png differ
diff --git a/public/assets/company-logos/MavenSecurities.png b/public/assets/company-logos/MavenSecurities.png
new file mode 100644
index 00000000..e437378e
Binary files /dev/null and b/public/assets/company-logos/MavenSecurities.png differ
diff --git a/public/assets/company-logos/Outbrain.png b/public/assets/company-logos/Outbrain.png
new file mode 100644
index 00000000..0d7b03da
Binary files /dev/null and b/public/assets/company-logos/Outbrain.png differ
diff --git a/public/assets/company-logos/Qaware.png b/public/assets/company-logos/Qaware.png
new file mode 100644
index 00000000..3c3cdbe3
Binary files /dev/null and b/public/assets/company-logos/Qaware.png differ
diff --git a/public/assets/company-logos/RobustPerception.png b/public/assets/company-logos/RobustPerception.png
new file mode 100644
index 00000000..66106e41
Binary files /dev/null and b/public/assets/company-logos/RobustPerception.png differ
diff --git a/public/assets/company-logos/Showmax.png b/public/assets/company-logos/Showmax.png
new file mode 100644
index 00000000..9833d2a8
Binary files /dev/null and b/public/assets/company-logos/Showmax.png differ
diff --git a/public/assets/company-logos/Spacenet.png b/public/assets/company-logos/Spacenet.png
new file mode 100644
index 00000000..2ff20383
Binary files /dev/null and b/public/assets/company-logos/Spacenet.png differ
diff --git a/public/assets/company-logos/Sysdig.png b/public/assets/company-logos/Sysdig.png
new file mode 100644
index 00000000..10b4704f
Binary files /dev/null and b/public/assets/company-logos/Sysdig.png differ
diff --git a/public/assets/company-logos/ayedo.png b/public/assets/company-logos/ayedo.png
new file mode 100644
index 00000000..7401695a
Binary files /dev/null and b/public/assets/company-logos/ayedo.png differ
diff --git a/public/assets/company-logos/cesanta.png b/public/assets/company-logos/cesanta.png
new file mode 100644
index 00000000..7630313d
Binary files /dev/null and b/public/assets/company-logos/cesanta.png differ
diff --git a/public/assets/company-logos/crononauta.png b/public/assets/company-logos/crononauta.png
new file mode 100644
index 00000000..897d3f2a
Binary files /dev/null and b/public/assets/company-logos/crononauta.png differ
diff --git a/public/assets/company-logos/digitalocean.png b/public/assets/company-logos/digitalocean.png
new file mode 100644
index 00000000..06a747dc
Binary files /dev/null and b/public/assets/company-logos/digitalocean.png differ
diff --git a/public/assets/company-logos/ecobee.png b/public/assets/company-logos/ecobee.png
new file mode 100644
index 00000000..6904bdec
Binary files /dev/null and b/public/assets/company-logos/ecobee.png differ
diff --git a/public/assets/company-logos/giantswarm.png b/public/assets/company-logos/giantswarm.png
new file mode 100644
index 00000000..df0020da
Binary files /dev/null and b/public/assets/company-logos/giantswarm.png differ
diff --git a/public/assets/company-logos/grafana.png b/public/assets/company-logos/grafana.png
new file mode 100644
index 00000000..238760dd
Binary files /dev/null and b/public/assets/company-logos/grafana.png differ
diff --git a/public/assets/company-logos/mixpanel.png b/public/assets/company-logos/mixpanel.png
new file mode 100644
index 00000000..949331ae
Binary files /dev/null and b/public/assets/company-logos/mixpanel.png differ
diff --git a/public/assets/company-logos/pingcap.png b/public/assets/company-logos/pingcap.png
new file mode 100644
index 00000000..26c34469
Binary files /dev/null and b/public/assets/company-logos/pingcap.png differ
diff --git a/public/assets/company-logos/quobyte.png b/public/assets/company-logos/quobyte.png
new file mode 100644
index 00000000..200cf64a
Binary files /dev/null and b/public/assets/company-logos/quobyte.png differ
diff --git a/public/assets/company-logos/shuttlecloud.png b/public/assets/company-logos/shuttlecloud.png
new file mode 100644
index 00000000..28b7699e
Binary files /dev/null and b/public/assets/company-logos/shuttlecloud.png differ
diff --git a/public/assets/company-logos/soundcloud.png b/public/assets/company-logos/soundcloud.png
new file mode 100644
index 00000000..85f0e0a4
Binary files /dev/null and b/public/assets/company-logos/soundcloud.png differ
diff --git a/public/assets/company-logos/transloadit.png b/public/assets/company-logos/transloadit.png
new file mode 100644
index 00000000..fb97e102
Binary files /dev/null and b/public/assets/company-logos/transloadit.png differ
diff --git a/public/assets/company-logos/unosoft.png b/public/assets/company-logos/unosoft.png
new file mode 100644
index 00000000..6df902c5
Binary files /dev/null and b/public/assets/company-logos/unosoft.png differ
diff --git a/public/assets/company-logos/weave.png b/public/assets/company-logos/weave.png
new file mode 100644
index 00000000..e556a3a0
Binary files /dev/null and b/public/assets/company-logos/weave.png differ
diff --git a/public/repo-docs-assets b/public/repo-docs-assets
new file mode 120000
index 00000000..4b5cbd8f
--- /dev/null
+++ b/public/repo-docs-assets
@@ -0,0 +1 @@
+../generated/repo-docs-assets
\ No newline at end of file
diff --git a/scripts/fetch-repo-docs.ts b/scripts/fetch-repo-docs.ts
new file mode 100644
index 00000000..21385f2c
--- /dev/null
+++ b/scripts/fetch-repo-docs.ts
@@ -0,0 +1,334 @@
+import { Octokit } from "octokit";
+import { execSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import docsConfig from "../docs-config";
+import { GithubMarkdownSource } from "../src/docs-config-types";
+import {
+  DocsCollection,
+  AllRepoVersions,
+  RepoDocMetadata,
+} from "@/docs-collection-types";
+import matter from "gray-matter";
+import dotenv from "dotenv";
+
+dotenv.config();
+
+const OUTDIR = "./generated";
+
+const octokit = new Octokit({
+  auth: `${process.env.GITHUB_TOKEN}`,
+});
+
+const docsCollection: DocsCollection = {};
+const allRepoVersions: AllRepoVersions = {};
+
+// Find all files (.md and others) recursively in a directory.
+const findFiles = (dir: string): string[] => {
+  let results: string[] = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results = results.concat(findFiles(fullPath));
+    } else if (entry.isFile()) {
+      results.push(fullPath);
+    }
+  }
+
+  return results;
+};
+
+const syncRepo = (owner: string, repo: string, repoDir: string) => {
+  console.log(`Syncing ${repo} repo to ${repoDir}...`);
+  if (!fs.existsSync(repoDir)) {
+    execSync(
+      `git clone --bare --filter=blob:none https://github.com/${owner}/${repo}.git ${repoDir}`
+    );
+    execSync(`git -C ${repoDir} config core.sparseCheckout true`);
+  } else {
+    execSync(`git -C ${repoDir} fetch --prune --quiet`);
+  }
+};
+
+const checkoutVersionDocs = (
+  owner: string,
+  repo: string,
+  repoDir: string,
+  version: string,
+  workingTreeBase: string,
+  repoDocsDir: string
+) => {
+  const workingTree = path.resolve(
+    `${workingTreeBase}/${owner}/${repo}/${version}`
+  );
+  const checkoutConfig = `${repoDir}/worktrees/${version}/info/sparse-checkout`;
+  const branch = `release-${version}`;
+
+  console.log(
+    `Checking out ${branch} of ${owner}/${repo} from ${repoDir} into ${workingTree}...`
+  );
+
+  if (!fs.existsSync(checkoutConfig) || !fs.existsSync(workingTree)) {
+    console.log("Creating new worktree...");
+    // Just a safety check before running rm -rf.
+    // TODO: Maybe remove this.
+    if (workingTree.length > 1) {
+      execSync(`rm -rf ${workingTree}`);
+    }
+    execSync(
+      `cd ${repoDir} && git worktree prune && git worktree add --no-checkout ${workingTree} ${branch}`
+    );
+    if (!fs.existsSync(path.dirname(checkoutConfig))) {
+      fs.mkdirSync(path.dirname(checkoutConfig), { recursive: true });
+    }
+    fs.writeFileSync(checkoutConfig, `/${repoDocsDir}\n`);
+  } else {
+    console.log("Worktree already exists...");
+  }
+
+  execSync(`git -C ${workingTree} reset --hard --quiet`);
+  execSync(`git -C ${workingTree} clean --force`);
+};
+
+const fetchRepoDocs = async ({
+  owner,
+  repo,
+  repoDocsDir,
+  minNumVersions,
+  slugPrefix,
+}: GithubMarkdownSource) => {
+  console.log(`Fetching releases and repo docs for ${owner}/${repo}...`);
+
+  // Clone a bare repo with sparse checkout so we can get the docs at specific
+  // versions from it later on.
+  const repoCheckoutDir = `${OUTDIR}/repos/${owner}/${repo}.git`;
+  syncRepo(owner, repo, repoCheckoutDir);
+
+  // List all GitHub releases for the repo.
+  const iterator = octokit.paginate.iterator(octokit.rest.repos.listReleases, {
+    owner,
+    repo,
+    per_page: 100,
+  });
+
+  const allReleaseTags: string[] = [];
+
+  for await (const { data: releases } of iterator) {
+    allReleaseTags.push(...releases.map((r) => r.tag_name));
+    // For the Prometheus repo for efficieny-reasons, stop once we have found at least
+    // one release starting with "v1.".
+    // Note: releases are sorted by date, so this works ok.
+    // TODO: Do we even still want to show the latest v1 release?
+    if (
+      owner === "prometheus" &&
+      repo === "prometheus" &&
+      releases.find((release) => release.tag_name.startsWith("v1."))
+    ) {
+      break;
+    }
+  }
+  // We still need to sort the releases by version number, as e.g. "2.53.4"
+  // was released after "3.2.1".
+  //
+  // Sorting by major + minor should be sufficient, as patch versions and
+  // other suffixes should be in the expected order already when sorting by
+  // release date.
+  allReleaseTags
+    .sort((a, b) => {
+      const [majorA, minorA] = a.replace(/^v/, "").split(".").map(Number);
+      const [majorB, minorB] = b.replace(/^v/, "").split(".").map(Number);
+      return majorA === majorB ? minorA - minorB : majorA - majorB;
+    })
+    .reverse();
+
+  function onlyUnique(value: string, index: number, array: string[]) {
+    return array.indexOf(value) === index;
+  }
+
+  // "v3.4.1" -> "3.4"
+  function shortVersion(version: string) {
+    return version.replace(/^v/, "").split(".").slice(0, 2).join(".");
+  }
+
+  // Get all <major>.<minor> versions, regardless of the patch version.
+  const allVersions = allReleaseTags
+    .filter((tag) => tag.startsWith("v")) // Ignore prehistoric release tags like "0.1.0"
+    .map((tag) => shortVersion(tag))
+    .filter(onlyUnique); // Remove dupes (e.g. "3.4.0" and "3.4.1" both become "3.4")
+
+  // First, get the last 10 versions, regardless of the major version.
+  const recentVersions = allVersions.slice(0, minNumVersions);
+
+  // Then, ensure we include at least one release for each major version.
+  const groupedByMajor = Object.groupBy(
+    allVersions,
+    (version) => version.split(".")[0]
+  );
+  for (const major in groupedByMajor) {
+    const latestInMajor = groupedByMajor[major]![0];
+    if (!recentVersions.includes(latestInMajor)) {
+      recentVersions.push(latestInMajor);
+    }
+  }
+
+  const latestTag = allReleaseTags.find((tag) => !tag.includes("-"));
+  if (!latestTag) {
+    throw new Error(`No latest version found for ${owner}/${repo}.`);
+  }
+  const latestVersion = shortVersion(latestTag);
+
+  // Store metadata about the repo and its versions.
+  if (!allRepoVersions[owner]) {
+    allRepoVersions[owner] = {};
+  }
+  allRepoVersions[owner][repo] = {
+    versions: recentVersions,
+    latestVersion,
+    ltsVersions: (owner === "prometheus" && docsConfig.ltsVersions[repo]) || [],
+  };
+
+  console.log(
+    `Found ${allReleaseTags.length} releases, ${allVersions.length} major/minor versions, ${recentVersions.length} recent versions, and the latest version ${latestVersion} for ${owner}/${repo}.`
+  );
+
+  // For each recent version, check out the corresponding commit and
+  // produce a directory containing its docs, then add it to the metadata.
+  for (const version of recentVersions) {
+    checkoutVersionDocs(
+      owner,
+      repo,
+      repoCheckoutDir,
+      version,
+      `${OUTDIR}/repo-docs`,
+      repoDocsDir
+    );
+    const docsDir = `${OUTDIR}/repo-docs/${owner}/${repo}/${version}/${repoDocsDir}`;
+
+    // Store metadata about Markdown page files, copy non-Markdown
+    // assets to the docs assets directory.
+    const assetsRoot = `/repo-docs-assets/${owner}/${repo}/${version}`;
+    for (const file of findFiles(docsDir)) {
+      const filePath = path.relative(docsDir, file);
+
+      if (
+        owner === "prometheus" &&
+        ["prometheus", "alertmanager"].includes(repo) &&
+        filePath === "index.md"
+      ) {
+        // Skip the index.md file in the external repo, as it is not a real or conformant page.
+        console.log("Skipping Prometheus index.md file:", filePath);
+        continue;
+      }
+
+      if (file.endsWith(".md")) {
+        console.log("Found Markdown file:", filePath);
+
+        const {
+          data: { title, nav_title: navTitle, sort_rank: sortRank },
+          content,
+        } = matter(fs.readFileSync(file, "utf-8"));
+
+        if (!title) {
+          throw new Error(`Missing title in ${file}`);
+        }
+        if (!sortRank) {
+          // Docs in https://github.com/prometheus/prometheus/tree/main/docs/command-line
+          // are currently missing sort_rank 😤
+          if (!filePath.includes("command-line")) {
+            throw new Error(`Missing sort_rank in ${file}`);
+          }
+        }
+
+        const newDoc: RepoDocMetadata = {
+          type: "repo-doc",
+          filePath: file,
+          content: "",
+          owner,
+          repo,
+          version,
+          slugPrefix,
+          latestVersion,
+          versionRoot: path.join(slugPrefix, version),
+          assetsRoot,
+          title,
+          navTitle,
+          sortRank: sortRank ?? 0,
+        };
+
+        docsCollection[
+          path.join(slugPrefix, version, filePath.replace(/\.md$/, ""))
+        ] = newDoc;
+
+        if (version === latestVersion) {
+          // Also add the latest version to the collection with
+          // "latest" as the version in the slug.
+          docsCollection[
+            path.join(slugPrefix, "latest", filePath.replace(/\.md$/, ""))
+          ] = newDoc;
+        }
+      } else {
+        console.log("Found non-Markdown asset file:", filePath);
+        const destDir = `${OUTDIR}/${assetsRoot}/${path.dirname(filePath)}`;
+        if (!fs.existsSync(destDir)) {
+          fs.mkdirSync(destDir, { recursive: true });
+        }
+        fs.copyFileSync(file, `${destDir}/${path.basename(filePath)}`);
+      }
+    }
+  }
+};
+
+for (const sourceConfig of docsConfig.githubMarkdownSources) {
+  await fetchRepoDocs(sourceConfig);
+}
+
+for (const sourceConfig of docsConfig.localMarkdownSources) {
+  const { docsDir, slugPrefix } = sourceConfig;
+  console.log(`Integrating local docs from ${docsDir}...`);
+  for (const file of findFiles(docsDir)) {
+    if (!file.endsWith(".md")) {
+      throw new Error(
+        `Found non-Markdown file ${file} in local docs dir, please put assets into public/.`
+      );
+    }
+
+    const filePath = path.relative(docsDir, file);
+    const {
+      data: { title, sort_rank: sortRank, nav_icon: navIcon },
+      content,
+    } = matter(fs.readFileSync(file, "utf-8"));
+    if (!title) {
+      throw new Error(`Missing title in ${file}`);
+    }
+    if (!sortRank) {
+      // A number of guides in https://github.com/prometheus/docs/tree/main/content/docs/guides
+      // are currently missing sort_rank 😤
+      if (!filePath.includes("guides")) {
+        throw new Error(`Missing sort_rank in ${file}`);
+      }
+    }
+
+    if (file.endsWith(".md")) {
+      console.log("Found Markdown file:", filePath);
+      docsCollection[path.join(slugPrefix, filePath.replace(/\.md$/, ""))] = {
+        type: "local-doc",
+        filePath: file,
+        content: "",
+        title,
+        sortRank: sortRank ?? 0,
+        navIcon,
+      };
+    }
+
+    // Don't need to care about assets for local docs here, local doc authors
+    // should store them in public/ and link to them there.
+  }
+}
+
+// Write out the docs collection metadata object to a JSON file.
+const docsCollectionFile = `${OUTDIR}/docs-collection.json`;
+const allRepoVersionsFile = `${OUTDIR}/repo-versions.json`;
+fs.writeFileSync(docsCollectionFile, JSON.stringify(docsCollection, null, 2));
+fs.writeFileSync(allRepoVersionsFile, JSON.stringify(allRepoVersions, null, 2));
diff --git a/src/app/docs/[...slug]/page.tsx b/src/app/docs/[...slug]/page.tsx
new file mode 100644
index 00000000..6e78f672
--- /dev/null
+++ b/src/app/docs/[...slug]/page.tsx
@@ -0,0 +1,207 @@
+import { MarkdownAsync } from "react-markdown";
+import remarkGfm from "remark-gfm";
+import remarkFrontmatter from "remark-frontmatter";
+import fs from "fs/promises";
+// import { CodeHighlight } from "@mantine/code-highlight";
+import rehypeSlug from "rehype-slug";
+import rehypeAutolinkHeadings from "rehype-autolink-headings";
+import rehypeConfigLinker from "@/rehypeConfigLinker";
+import rehypeShiki from "@shikijs/rehype";
+import { IconLink } from "@tabler/icons-react";
+import { docsCollection } from "@/docs-collection";
+import {
+  Table,
+  TableTbody,
+  TableTd,
+  TableTh,
+  TableThead,
+  TableTr,
+  Title,
+  TitleProps,
+} from "@mantine/core";
+
+const SITE_URL = "https://prometheus.io";
+
+function isAbsoluteUrl(url: string) {
+  try {
+    new URL(url); // will succeed for absolute URLs
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Next.js uses this function at build time to figure out which
+// docs pages it should statically generate.
+export async function generateStaticParams() {
+  const params = Object.keys(docsCollection).map((slug: string) => ({
+    slug: slug.split("/"),
+  }));
+  return params;
+}
+
+const h = (order: 1 | 2 | 3 | 4 | 5 | 6) => (props: TitleProps) =>
+  <Title order={order} {...props} />;
+
+export default async function DocsPage({
+  params,
+}: {
+  params: Promise<{ slug: string[] }>;
+}) {
+  const slug = (await params).slug;
+  console.log("Building docs page", slug.join("/"));
+
+  const docMeta = docsCollection[slug.join("/")];
+  // TODO: Use the content from the meta json.
+  const markdown = await fs.readFile(docMeta.filePath, "utf-8");
+
+  return (
+    <div className="markdown-content">
+      <MarkdownAsync
+        remarkPlugins={[remarkFrontmatter, remarkGfm]}
+        rehypePlugins={[
+          rehypeSlug,
+          [
+            rehypeAutolinkHeadings,
+            {
+              content: { type: "text", value: "<replaceme>" },
+              // Don't link top-level page headings (h1).
+              test: (el) => el.tagName !== "h1",
+            },
+          ],
+          [
+            rehypeShiki,
+            {
+              // or `theme` for a single theme
+              themes: {
+                light: "github-light",
+                dark: "vitesse-dark",
+              },
+            },
+          ],
+
+          // Important: this has to run after rehypeSlug, since it
+          // relies on the headers to already have IDs.
+          rehypeConfigLinker,
+        ]}
+        components={{
+          a: (props) => {
+            if (
+              props.node?.children &&
+              props.node.children[0].type === "text" &&
+              props.node.children[0].value === "<replaceme>"
+            ) {
+              return (
+                <a {...props} className="header-auto-link">
+                  <IconLink size={16} />
+                </a>
+              );
+            }
+
+            const href = props.href;
+            if (!href || docMeta.type === "local-doc") {
+              return <a {...props} />;
+            }
+
+            let normalizedHref = href;
+            if (href.startsWith(SITE_URL)) {
+              // Remove the "https://prometheus.io" from links that start with it.
+              normalizedHref = href.slice(SITE_URL.length);
+            } else if (href.startsWith("/")) {
+              // Turn "/<path>" into "https://github.com/prometheus/prometheus/blob/release-3.3.0/<path>"
+              normalizedHref = `https://github.com/prometheus/prometheus/blob/release-${docMeta.version}${href}`;
+            } else if (href.includes(".md") && !isAbsoluteUrl(href)) {
+              // Turn "foo/bar/baz.md" into "../foo/bar/baz" for relative links between Markdown pages.
+              normalizedHref = `${href.replace(/\.md($|#)/, "$1")}`;
+            }
+
+            return <a href={normalizedHref}>{props.children}</a>;
+          },
+          img: (props) => {
+            const src = props.src;
+            if (
+              !src ||
+              typeof src !== "string" ||
+              isAbsoluteUrl(src) ||
+              docMeta.type === "local-doc"
+            ) {
+              return <img {...props} />;
+            }
+
+            return <img {...props} src={`${docMeta.assetsRoot}/${src}`} />;
+          },
+          pre: (props) => {
+            const firstChild = props.node?.children[0];
+            if (
+              !firstChild ||
+              firstChild?.type !== "element" ||
+              firstChild?.tagName !== "code"
+            ) {
+              return <pre>{props.children}</pre>;
+            }
+
+            return (
+              <pre
+                style={{
+                  fontSize: 14,
+                  backgroundColor: "var(--mantine-color-gray-0)",
+                  lineHeight: 1.7,
+                  display: "block",
+                  padding: "1em",
+                  borderRadius: "0.5em",
+                  overflow: "auto",
+                }}
+              >
+                {props.children}
+              </pre>
+            );
+          },
+          h1: h(1),
+          h2: h(2),
+          h3: h(3),
+          h4: h(4),
+          h5: h(5),
+          h6: h(6),
+          table: (props) => (
+            <Table withColumnBorders withTableBorder highlightOnHover>
+              {props.children}
+            </Table>
+          ),
+          th: TableTh,
+          td: TableTd,
+          tr: TableTr,
+          thead: TableThead,
+          tbody: TableTbody,
+          // For <pre> tags that contain <code> tags, we need to extract the content
+          // of the <code> tag and pass it to a <CodeHighlight> Mantine component. If it's
+          // a <pre> tag that doesn't contain a <code> tag, we just render it as is.
+          // pre: (props) => {
+          //   const firstChild = props.node?.children[0];
+          //   if (
+          //     firstChild?.type === "element" &&
+          //     firstChild?.tagName === "code"
+          //   ) {
+          //     const contentElement = firstChild.children[0];
+          //     if (contentElement.type !== "text") {
+          //       throw new Error("Code content is not text");
+          //     }
+          //     const content = contentElement.value;
+          //     const language = firstChild.properties?.className?.[0]?.replace(
+          //       "language-",
+          //       ""
+          //     );
+
+          //     return (
+          //       <CodeHighlight code={content} language={language || "yaml"} />
+          //     );
+          //   } else {
+          //     return <pre {...props} />;
+          //   }
+          // },
+        }}
+      >
+        {markdown}
+      </MarkdownAsync>
+    </div>
+  );
+}
diff --git a/src/app/docs/layout.tsx b/src/app/docs/layout.tsx
new file mode 100644
index 00000000..44589f4c
--- /dev/null
+++ b/src/app/docs/layout.tsx
@@ -0,0 +1,363 @@
+"use client";
+
+import { docsCollection, allRepoVersions } from "@/docs-collection";
+import {
+  DocsCollection,
+  LocalDocMetadata,
+  RepoDocMetadata,
+} from "@/docs-collection-types";
+import {
+  Container,
+  Group,
+  Box,
+  List,
+  ListItem,
+  Text,
+  Select,
+  NavLink,
+  Alert,
+} from "@mantine/core";
+import Link from "next/link";
+import { usePathname, useRouter } from "next/navigation";
+import {
+  IconFlask,
+  IconServer,
+  IconCode,
+  IconThumbUp,
+  IconBell,
+  IconBook,
+  IconSettings,
+  IconHandFingerRight,
+  IconChartLine,
+  IconMap,
+  IconFileDescription,
+  IconProps,
+  IconInfoCircle,
+  IconVersions,
+  IconTag,
+} from "@tabler/icons-react";
+import { ReactElement } from "react";
+
+const iconMap: Record<string, React.ComponentType<any>> = {
+  flask: IconFlask,
+  server: IconServer,
+  code: IconCode,
+  "thumb-up": IconThumbUp,
+  bell: IconBell,
+  book: IconBook,
+  settings: IconSettings,
+  "hand-finger-right": IconHandFingerRight,
+  "chart-line": IconChartLine,
+  map: IconMap,
+  "file-description": IconFileDescription,
+};
+
+export function NavIcon({
+  iconName,
+  ...props
+}: { iconName: string } & IconProps) {
+  const Icon = iconMap[iconName];
+  return Icon ? (
+    <Icon {...props} color="var(--mantine-primary-color-4)" />
+  ) : (
+    <span>?</span>
+  );
+}
+
+type DocsTree =
+  | {
+      type: "directory";
+      path: string;
+      document: LocalDocMetadata | RepoDocMetadata;
+      children: DocsTree[];
+    }
+  | {
+      type: "document";
+      path: string;
+      document: LocalDocMetadata | RepoDocMetadata;
+    };
+
+function buildDocsTree(docs: DocsCollection): DocsTree[] {
+  // Remove any final /index segments from paths.
+  const paths = Object.keys(docs).map((path) => {
+    return path.replace(/\/index$/, "");
+  });
+
+  // Normalize and sort paths by depth
+  const sortedPaths = paths.sort(
+    (a, b) => a.split("/").length - b.split("/").length
+  );
+
+  const pathTrees = new Map<string, DocsTree>();
+
+  for (const path of sortedPaths) {
+    const isDoc = !sortedPaths.some((p) => p.startsWith(`${path}/`));
+    const node: DocsTree = isDoc
+      ? { type: "document", path, document: docs[path] }
+      : {
+          type: "directory",
+          path,
+          document: docs[`${path}/index`],
+          children: [],
+        };
+
+    pathTrees.set(path, node);
+
+    const segments = path.split("/").filter(Boolean);
+    if (segments.length === 1) {
+      continue; // Top-level, no parent
+    }
+
+    // Try to find a parent by removing trailing segments until a match is found
+    let parentPath = segments.slice(0, -1).join("/");
+    let parentNode: DocsTree | undefined = undefined;
+
+    while (parentPath && !parentNode) {
+      parentNode = pathTrees.get(parentPath);
+      if (parentNode && parentNode.type === "directory") {
+        parentNode.children.push(node);
+        break;
+      } else if (parentPath.includes("/")) {
+        // Keep removing segments until we find a parent or run out of segments
+        parentPath = parentPath.split("/").slice(0, -1).join("/");
+      } else {
+        // No more segments to remove
+        break;
+      }
+    }
+  }
+  // console.log("Path map", pathMap);
+
+  // Return only top-level nodes
+  return Array.from(pathTrees.values()).filter((node) => {
+    const segments = node.path.split("/").filter(Boolean);
+    return segments.length === 1;
+  });
+}
+
+// Return a navigation tree UI for the DocsTree.
+function buildRecursiveNav(
+  docsTree: DocsTree[],
+  currentPageSlug: string,
+  router: ReturnType<typeof useRouter>,
+  level = 0
+) {
+  return docsTree
+    .sort((a, b) => a.document.sortRank - b.document.sortRank)
+    .map((node) => {
+      if (node.type === "directory") {
+        const fc = node.children[0];
+        const repoVersions =
+          fc && fc.document.type === "repo-doc"
+            ? allRepoVersions[fc.document.owner][fc.document.repo]
+            : null;
+
+        const currentPage = docsCollection[currentPageSlug];
+        const currentPageVersion =
+          currentPage.type === "repo-doc" &&
+          fc.document.type === "repo-doc" &&
+          currentPage.owner === fc.document.owner &&
+          currentPage.repo === fc.document.repo
+            ? currentPage.version
+            : null;
+
+        const shownChildren = node.children.filter((child) => {
+          // Always show unversioned local docs in the nav.
+          if (child.document.type === "local-doc") {
+            return true;
+          }
+
+          // Always show latest version docs if we're not looking at a different version of the same repo.
+          if (
+            !currentPageVersion &&
+            child.document.version === repoVersions?.latestVersion
+          ) {
+            if (child.path.startsWith(child.document.versionRoot)) {
+              // Don't show "3.4", even if it is the latest.
+              return false;
+            } else {
+              // Show "latest".
+              return true;
+            }
+          }
+
+          // If we're looking at a specific version and it's not the latest version,
+          // show all children with that same version.
+          if (child.document.version === currentPageVersion) {
+            if (currentPageVersion !== repoVersions?.latestVersion) {
+              return true;
+            } else {
+              if (child.path.startsWith(child.document.versionRoot)) {
+                return false;
+              } else {
+                return true;
+              }
+            }
+          }
+        });
+
+        // If the latest version (3.3) is selected, only show nav items for "latest". Otherwise,
+        // show nav items for the selected version (3.3).
+        //
+        // currentPageVersion === repoVersions?.latestVersion && child.path.startsWith(currentPage.versionRoot.replace)
+
+        const navIcon =
+          node.document.type === "local-doc" && node.document.navIcon;
+
+        return (
+          <NavLink
+            key={node.path}
+            href="#required-for-focus"
+            label={node.document.title}
+            childrenOffset={level === 0 ? 28 : 14}
+            leftSection={
+              navIcon ? (
+                <NavIcon iconName={navIcon} size={16} stroke={1.8} />
+              ) : undefined
+            }
+            ff={level === 0 ? "var(--font-inter)" : undefined}
+            fw={level === 0 ? 500 : undefined}
+            c={level === 0 ? "black" : "gray.7"}
+            style={{ borderRadius: 2.5 }}
+            // style={
+            //   level === 1
+            //     ? { borderLeft: "1px solid var(--mantine-color-gray-3)" }
+            //     : {}
+            // }
+          >
+            {level === 0 && repoVersions && (
+              <Select
+                w="100%"
+                size="sm"
+                my="xs"
+                leftSection={<IconTag size={16} />}
+                // placeholder="Pick version"
+                value={currentPageVersion || repoVersions.latestVersion}
+                data={repoVersions.versions.map((version) => ({
+                  value: version,
+                  label:
+                    version === repoVersions.latestVersion
+                      ? `${version} (latest)`
+                      : repoVersions.ltsVersions.includes(version)
+                      ? `${version} (LTS)`
+                      : version,
+                }))}
+                onChange={(version) => {
+                  const newPageNode = node.children
+                    .filter(
+                      (child) =>
+                        child.document.type === "repo-doc" &&
+                        child.document.version === version
+                    )
+                    .sort(
+                      (a, b) => a.document.sortRank - b.document.sortRank
+                    )[0];
+                  if (newPageNode) {
+                    router.push(`/docs/${newPageNode.path}`);
+                  }
+                }}
+              />
+            )}
+            {buildRecursiveNav(
+              shownChildren,
+              currentPageSlug,
+              router,
+              level + 1
+            )}
+          </NavLink>
+        );
+      }
+
+      const active = currentPageSlug === node.path;
+
+      return (
+        <NavLink
+          active={active}
+          variant="light"
+          component={Link}
+          key={node.path}
+          label={node.document.title}
+          href={`/docs/${node.path}`}
+          style={{ borderRadius: 2.5 }}
+          c={active ? undefined : "gray.7"}
+          // style={
+          //   level === 1
+          //     ? { borderLeft: "1px solid var(--mantine-color-gray-3)" }
+          //     : {}
+          // }
+        />
+      );
+    });
+}
+
+function compareVersions(a: string, b: string): number {
+  const [majorA, minorA] = a.split(".").map(Number);
+  const [majorB, minorB] = b.split(".").map(Number);
+
+  if (majorA !== majorB) {
+    return Math.sign(majorA - majorB);
+  }
+  return Math.sign(minorA - minorB);
+}
+
+export default function DocsLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  const router = useRouter();
+  const docsTree = buildDocsTree(docsCollection);
+  const pageSlug = usePathname().replace(/^\/docs\//, "");
+  const currentPage = docsCollection[pageSlug];
+
+  let alert: ReactElement | null = null;
+  if (currentPage.type === "repo-doc") {
+    const latestSlug = pageSlug.replace(currentPage.version, "latest");
+
+    switch (compareVersions(currentPage.version, currentPage.latestVersion)) {
+      case -1:
+        alert = (
+          <Alert
+            icon={<IconInfoCircle size={16} />}
+            title="Outdated version"
+            color="yellow"
+            mb="xl"
+          >
+            This page documents version {currentPage.version}, which is
+            outdated. Check out the{" "}
+            <Link href={`/docs/${latestSlug}`}>latest stable version.</Link>
+          </Alert>
+        );
+        break;
+      case 1:
+        alert = (
+          <Alert
+            icon={<IconInfoCircle size={16} />}
+            title="Pre-release version"
+            color="yellow"
+            mb="xl"
+          >
+            This page documents a pre-release version ({currentPage.version}).
+            Check out the{" "}
+            <Link href={`/docs/${latestSlug}`}>latest stable version</Link> (
+            {currentPage.latestVersion}).
+          </Alert>
+        );
+        break;
+    }
+  }
+
+  return (
+    <Container size="lg">
+      <Group wrap="nowrap" align="flex-start" gap={80}>
+        <Box w={250} flex="0 0 auto" mih={300}>
+          {buildRecursiveNav(docsTree, pageSlug, router)}
+        </Box>
+        <Box miw={0}>
+          {alert}
+          {children}
+        </Box>
+      </Group>
+    </Container>
+  );
+}
diff --git a/src/app/globals.css b/src/app/globals.css
index e3734be1..3551960e 100644
--- a/src/app/globals.css
+++ b/src/app/globals.css
@@ -1,42 +1,51 @@
-:root {
-  --background: #ffffff;
-  --foreground: #171717;
-}
-
-@media (prefers-color-scheme: dark) {
-  :root {
-    --background: #0a0a0a;
-    --foreground: #ededed;
-  }
-}
-
-html,
-body {
-  max-width: 100vw;
-  overflow-x: hidden;
-}
-
-body {
-  color: var(--foreground);
-  background: var(--background);
-  font-family: Arial, Helvetica, sans-serif;
-  -webkit-font-smoothing: antialiased;
-  -moz-osx-font-smoothing: grayscale;
-}
-
-* {
-  box-sizing: border-box;
-  padding: 0;
-  margin: 0;
-}
-
-a {
-  color: inherit;
+:is(h1, h2, h3, h4, h5, h6) > a {
+  position: absolute;
+  transform: translateX(-130%);
   text-decoration: none;
-}
+  opacity: 0;
+  color: var(--mantine-color-gray-6);
 
-@media (prefers-color-scheme: dark) {
-  html {
-    color-scheme: dark;
+  &:hover {
+    opacity: 1;
   }
 }
+
+:is(h1, h2, h3, h4, h5, h6):hover > a {
+  opacity: 1;
+}
+
+:is(h1, h2, h3, h4, h5, h6) a:hover {
+  color: var(--mantine-color-gray-8);
+}
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  margin-top: calc(var(--mantine-spacing-xl) * 1.2);
+  margin-bottom: calc(var(--mantine-spacing-md) * 1.2);
+
+  &:is(h1) {
+    margin-top: 0;
+  }
+}
+
+pre > code a {
+  color: #337ab7;
+  font-style: italic;
+  text-decoration: none;
+
+  &:hover {
+    color: #23527c;
+    text-decoration: underline;
+  }
+}
+
+:not(pre) > code {
+  background-color: var(--mantine-color-gray-1);
+  font-size: 0.9em;
+  padding: 0.1em 0.2em;
+  border-radius: 0.3em;
+}
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index 42fc323e..66177ab9 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -1,21 +1,35 @@
-import type { Metadata } from "next";
-import { Geist, Geist_Mono } from "next/font/google";
+"use client";
+
+// import type { Metadata } from "next";
+import { Inter } from "next/font/google";
+import {
+  Anchor,
+  ColorSchemeScript,
+  Container,
+  Group,
+  mantineHtmlProps,
+  MantineProvider,
+  Space,
+  Text,
+} from "@mantine/core";
+
+// Using layered imports here to be able to override Mantine's CSS, see
+// https://mantine.dev/styles/mantine-styles/#css-layers.
+import "@mantine/core/styles.layer.css";
+import "@mantine/code-highlight/styles.layer.css";
 import "./globals.css";
+import { Header } from "@/components/Header";
+import { theme } from "@/theme";
 
-const geistSans = Geist({
-  variable: "--font-geist-sans",
+const interFont = Inter({
+  variable: "--font-inter",
   subsets: ["latin"],
 });
 
-const geistMono = Geist_Mono({
-  variable: "--font-geist-mono",
-  subsets: ["latin"],
-});
-
-export const metadata: Metadata = {
-  title: "Create Next App",
-  description: "Generated by create next app",
-};
+// export const metadata: Metadata = {
+//   title: "Create Next App",
+//   description: "Generated by create next app",
+// };
 
 export default function RootLayout({
   children,
@@ -23,9 +37,40 @@ export default function RootLayout({
   children: React.ReactNode;
 }>) {
   return (
-    <html lang="en">
-      <body className={`${geistSans.variable} ${geistMono.variable}`}>
-        {children}
+    <html lang="en" {...mantineHtmlProps} className={interFont.variable}>
+      <head>
+        <ColorSchemeScript />
+      </head>
+      <body>
+        <MantineProvider theme={theme}>
+          <Header />
+          {children}
+          <Space h={50} />
+          <footer style={{ backgroundColor: "var(--mantine-color-gray-0)" }}>
+            <Container size="lg" p="xl">
+              <Group h={100}>
+                <Text c="dimmed" fz="sm">
+                  &copy; Prometheus Authors 2014-2024 | Documentation
+                  Distributed under CC-BY-4.0
+                </Text>
+                <Text c="dimmed" fz="sm">
+                  &copy; 2024 The Linux Foundation. All rights reserved. The
+                  Linux Foundation has registered trademarks and uses
+                  trademarks. For a list of trademarks of The Linux Foundation,
+                  please see our{" "}
+                  <Anchor
+                    inherit
+                    href="https://www.linuxfoundation.org/trademark-usage"
+                    target="_blank"
+                  >
+                    Trademark Usage
+                  </Anchor>{" "}
+                  page.
+                </Text>
+              </Group>
+            </Container>
+          </footer>
+        </MantineProvider>
       </body>
     </html>
   );
diff --git a/src/app/page.module.css b/src/app/page.module.css
deleted file mode 100644
index a11c8f31..00000000
--- a/src/app/page.module.css
+++ /dev/null
@@ -1,168 +0,0 @@
-.page {
-  --gray-rgb: 0, 0, 0;
-  --gray-alpha-200: rgba(var(--gray-rgb), 0.08);
-  --gray-alpha-100: rgba(var(--gray-rgb), 0.05);
-
-  --button-primary-hover: #383838;
-  --button-secondary-hover: #f2f2f2;
-
-  display: grid;
-  grid-template-rows: 20px 1fr 20px;
-  align-items: center;
-  justify-items: center;
-  min-height: 100svh;
-  padding: 80px;
-  gap: 64px;
-  font-family: var(--font-geist-sans);
-}
-
-@media (prefers-color-scheme: dark) {
-  .page {
-    --gray-rgb: 255, 255, 255;
-    --gray-alpha-200: rgba(var(--gray-rgb), 0.145);
-    --gray-alpha-100: rgba(var(--gray-rgb), 0.06);
-
-    --button-primary-hover: #ccc;
-    --button-secondary-hover: #1a1a1a;
-  }
-}
-
-.main {
-  display: flex;
-  flex-direction: column;
-  gap: 32px;
-  grid-row-start: 2;
-}
-
-.main ol {
-  font-family: var(--font-geist-mono);
-  padding-left: 0;
-  margin: 0;
-  font-size: 14px;
-  line-height: 24px;
-  letter-spacing: -0.01em;
-  list-style-position: inside;
-}
-
-.main li:not(:last-of-type) {
-  margin-bottom: 8px;
-}
-
-.main code {
-  font-family: inherit;
-  background: var(--gray-alpha-100);
-  padding: 2px 4px;
-  border-radius: 4px;
-  font-weight: 600;
-}
-
-.ctas {
-  display: flex;
-  gap: 16px;
-}
-
-.ctas a {
-  appearance: none;
-  border-radius: 128px;
-  height: 48px;
-  padding: 0 20px;
-  border: none;
-  border: 1px solid transparent;
-  transition:
-    background 0.2s,
-    color 0.2s,
-    border-color 0.2s;
-  cursor: pointer;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  font-size: 16px;
-  line-height: 20px;
-  font-weight: 500;
-}
-
-a.primary {
-  background: var(--foreground);
-  color: var(--background);
-  gap: 8px;
-}
-
-a.secondary {
-  border-color: var(--gray-alpha-200);
-  min-width: 158px;
-}
-
-.footer {
-  grid-row-start: 3;
-  display: flex;
-  gap: 24px;
-}
-
-.footer a {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-}
-
-.footer img {
-  flex-shrink: 0;
-}
-
-/* Enable hover only on non-touch devices */
-@media (hover: hover) and (pointer: fine) {
-  a.primary:hover {
-    background: var(--button-primary-hover);
-    border-color: transparent;
-  }
-
-  a.secondary:hover {
-    background: var(--button-secondary-hover);
-    border-color: transparent;
-  }
-
-  .footer a:hover {
-    text-decoration: underline;
-    text-underline-offset: 4px;
-  }
-}
-
-@media (max-width: 600px) {
-  .page {
-    padding: 32px;
-    padding-bottom: 80px;
-  }
-
-  .main {
-    align-items: center;
-  }
-
-  .main ol {
-    text-align: center;
-  }
-
-  .ctas {
-    flex-direction: column;
-  }
-
-  .ctas a {
-    font-size: 14px;
-    height: 40px;
-    padding: 0 16px;
-  }
-
-  a.secondary {
-    min-width: auto;
-  }
-
-  .footer {
-    flex-wrap: wrap;
-    align-items: center;
-    justify-content: center;
-  }
-}
-
-@media (prefers-color-scheme: dark) {
-  .logo {
-    filter: invert();
-  }
-}
diff --git a/src/app/page.tsx b/src/app/page.tsx
index 84af2cb0..4b0807ae 100644
--- a/src/app/page.tsx
+++ b/src/app/page.tsx
@@ -1,95 +1,76 @@
-import Image from "next/image";
-import styles from "./page.module.css";
+import NextImage from "next/image";
+import { Image } from "@mantine/core";
+import classes from "@/components/FeaturesCards.module.css";
+import { FeaturesCards } from "@/components/FeaturesCards";
+import { Hero } from "@/components/Hero";
+import { UserLogos } from "@/components/UserLogos";
+import { Space, Title, Group, Anchor, Text } from "@mantine/core";
+import cncfLogo from "../assets/cncf-logo.svg";
+import githubLogo from "../assets/github-logo.svg";
 
 export default function Home() {
   return (
-    <div className={styles.page}>
-      <main className={styles.main}>
-        <Image
-          className={styles.logo}
-          src="/next.svg"
-          alt="Next.js logo"
-          width={180}
-          height={38}
-          priority
-        />
-        <ol>
-          <li>
-            Get started by editing <code>src/app/page.tsx</code>.
-          </li>
-          <li>Save and see your changes instantly.</li>
-        </ol>
+    <>
+      <Hero />
+      <FeaturesCards />
+      <UserLogos />
+      <Space h="xl" mb={50} />
+      <Title order={2} className={classes.title} mt="sm">
+        <Group justify="center">
+          <Image
+            component={NextImage}
+            src={githubLogo}
+            style={{ height: 40, width: 40 }}
+            alt="GitHub logo"
+          />{" "}
+          Open Source
+        </Group>
+      </Title>
 
-        <div className={styles.ctas}>
-          <a
-            className={styles.primary}
-            href="https://vercel.com/new?utm_source=create-next-app&utm_medium=appdir-template&utm_campaign=create-next-app"
-            target="_blank"
-            rel="noopener noreferrer"
-          >
-            <Image
-              className={styles.logo}
-              src="/vercel.svg"
-              alt="Vercel logomark"
-              width={20}
-              height={20}
-            />
-            Deploy now
-          </a>
-          <a
-            href="https://nextjs.org/docs?utm_source=create-next-app&utm_medium=appdir-template&utm_campaign=create-next-app"
-            target="_blank"
-            rel="noopener noreferrer"
-            className={styles.secondary}
-          >
-            Read our docs
-          </a>
-        </div>
-      </main>
-      <footer className={styles.footer}>
-        <a
-          href="https://nextjs.org/learn?utm_source=create-next-app&utm_medium=appdir-template&utm_campaign=create-next-app"
-          target="_blank"
-          rel="noopener noreferrer"
-        >
-          <Image
-            aria-hidden
-            src="/file.svg"
-            alt="File icon"
-            width={16}
-            height={16}
-          />
-          Learn
-        </a>
-        <a
-          href="https://vercel.com/templates?framework=next.js&utm_source=create-next-app&utm_medium=appdir-template&utm_campaign=create-next-app"
-          target="_blank"
-          rel="noopener noreferrer"
-        >
-          <Image
-            aria-hidden
-            src="/window.svg"
-            alt="Window icon"
-            width={16}
-            height={16}
-          />
-          Examples
-        </a>
-        <a
-          href="https://nextjs.org?utm_source=create-next-app&utm_medium=appdir-template&utm_campaign=create-next-app"
-          target="_blank"
-          rel="noopener noreferrer"
-        >
-          <Image
-            aria-hidden
-            src="/globe.svg"
-            alt="Globe icon"
-            width={16}
-            height={16}
-          />
-          Go to nextjs.org →
-        </a>
-      </footer>
-    </div>
+      <Text c="dimmed" className={classes.description} ta="center" mt="md">
+        Prometheus is 100% open source and community-driven. All components are
+        available under the{" "}
+        <Anchor href="http://www.apache.org/licenses/LICENSE-2.0">
+          Apache 2 License
+        </Anchor>{" "}
+        on <Anchor href="https://github.com/prometheus">GitHub</Anchor>.
+        <iframe
+          src="https://ghbtns.com/github-btn.html?user=prometheus&repo=prometheus&type=star&count=true&size=large"
+          scrolling="0"
+          style={{
+            width: 200,
+            height: 30,
+            margin: "auto",
+            display: "block",
+            marginTop: 20,
+            marginBottom: 20,
+            border: 0,
+          }}
+        ></iframe>
+      </Text>
+
+      <Title order={2} className={classes.title} mt={80}>
+        <Group justify="center">Open Governance</Group>
+      </Title>
+      <Text c="dimmed" className={classes.description} ta="center" mt="md">
+        Prometheus is a{" "}
+        <Anchor href="https://cncf.io/">
+          Cloud Native Computing Foundation
+        </Anchor>{" "}
+        graduated project.
+        <Image
+          component={NextImage}
+          mt="md"
+          m="auto"
+          w="auto"
+          src={cncfLogo}
+          alt="CNCF logo"
+          className={classes.cncfLogo}
+          style={{
+            objectFit: "fill",
+          }}
+        />
+      </Text>
+    </>
   );
 }
diff --git a/src/assets/cncf-logo.svg b/src/assets/cncf-logo.svg
new file mode 100644
index 00000000..6ed42883
--- /dev/null
+++ b/src/assets/cncf-logo.svg
@@ -0,0 +1,88 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 26.1.0, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
+<svg version="1.1" id="a" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 viewBox="0 0 399.1 76.1" style="enable-background:new 0 0 399.1 76.1;" xml:space="preserve">
+<style type="text/css">
+	.st0{fill:#0086FF;}
+	.st1{fill:#93EAFF;}
+</style>
+<g>
+	<g>
+		<g>
+			<path d="M98.9,33.4c1.5,0,2.9-0.3,4.3-0.9c1.3-0.6,2.5-1.6,3.4-2.8l4.1,4.2c-3.2,3.6-6.9,5.4-11.3,5.4c-2,0.1-3.9-0.2-5.8-1
+				c-1.8-0.7-3.5-1.8-5-3.1c-1.4-1.3-2.5-3-3.2-4.7c-0.7-1.8-1.1-3.7-1-5.6c-0.1-1.9,0.3-3.9,1-5.7c0.7-1.8,1.8-3.4,3.2-4.8
+				c1.5-1.4,3.3-2.5,5.2-3.2c1.9-0.7,4-1,6.1-0.9c2.1,0.1,4.1,0.6,6,1.5c1.9,0.9,3.5,2.2,4.9,3.8l-3.9,4.5c-0.9-1.2-2-2.1-3.3-2.7
+				c-1.3-0.6-2.7-1-4.2-1c-2.2,0-4.4,0.8-6.1,2.3c-0.9,0.8-1.5,1.8-2,2.9c-0.4,1.1-0.6,2.3-0.6,3.4c-0.1,1.2,0.1,2.3,0.5,3.4
+				c0.4,1.1,1,2.1,1.9,2.9C94.7,32.6,96.8,33.4,98.9,33.4L98.9,33.4z M115.5,38.9V10.7h6.3v22.6h12.1v5.6H115.5z M161.5,35
+				c-2.9,2.7-6.6,4.2-10.6,4.2s-7.7-1.5-10.6-4.2c-1.4-1.3-2.5-2.9-3.2-4.7c-0.7-1.8-1.1-3.7-1.1-5.6c-0.1-1.9,0.3-3.9,1-5.6
+				c0.7-1.8,1.8-3.4,3.2-4.7c2.9-2.7,6.6-4.2,10.6-4.2s7.7,1.5,10.6,4.2c1.4,1.3,2.5,2.9,3.2,4.7c0.7,1.8,1.1,3.7,1,5.6
+				c0.1,1.9-0.3,3.9-1,5.6C164,32.1,162.9,33.7,161.5,35z M159.3,24.7c0-2.4-0.9-4.7-2.5-6.5c-0.8-0.8-1.7-1.5-2.7-2
+				c-1-0.5-2.2-0.7-3.3-0.7c-1.1,0-2.2,0.2-3.3,0.7c-1,0.5-2,1.1-2.7,2c-1.6,1.8-2.5,4.1-2.5,6.5c0,2.4,0.9,4.7,2.5,6.5
+				c0.8,0.8,1.7,1.5,2.7,2c1,0.5,2.2,0.7,3.3,0.7c1.1,0,2.2-0.2,3.3-0.7c1-0.5,2-1.1,2.7-2c0.8-0.9,1.5-1.9,1.9-3
+				C159.2,27,159.4,25.9,159.3,24.7z M178.6,31.7c0.5,0.7,1.2,1.2,1.9,1.5c0.7,0.3,1.6,0.5,2.4,0.5c0.8,0,1.6-0.1,2.3-0.5
+				c0.7-0.3,1.4-0.9,1.8-1.5c1.1-1.6,1.6-3.4,1.5-5.3V10.8h6.3v15.8c0,4.1-1.1,7.2-3.4,9.4c-1.2,1.1-2.5,2-4,2.5
+				c-1.5,0.6-3.1,0.8-4.7,0.8c-1.6,0-3.2-0.2-4.7-0.8c-1.5-0.6-2.9-1.4-4-2.5c-2.3-2.2-3.4-5.3-3.4-9.4V10.8h6.3v15.6
+				C176.9,28.3,177.5,30.2,178.6,31.7z M223.1,14.4c2.7,2.5,4.1,5.9,4.1,10.3s-1.3,7.9-3.9,10.5c-2.6,2.6-6.7,3.8-12,3.8h-9.8V10.7
+				h10C216.5,10.7,220.4,11.9,223.1,14.4z M218.5,31.2c1.5-1.4,2.3-3.6,2.3-6.4s-0.8-4.9-2.3-6.4s-3.9-2.3-7.1-2.3h-3.5v17.2h4
+				C214.3,33.5,216.7,32.8,218.5,31.2z M263.1,10.7h6.3v28.3h-6.3l-13.5-17.7v17.7h-6.3V10.7h5.9l13.9,18.2V10.7z M296.5,38.9
+				l-2.7-6.1h-11.9l-2.7,6.1h-6.8l12.2-28.3h6.1L303,38.9H296.5z M288,19.1l-3.5,8.2h7L288,19.1z M316.5,16.2V39h-6.3V16.2h-8v-5.4
+				h22.4v5.4C324.6,16.2,316.5,16.2,316.5,16.2z M329,10.7h6.3v28.3H329C329,38.9,329,10.7,329,10.7z M352.8,28.7l7.2-18h6.9
+				l-11.3,28.3h-5.3l-11.3-28.3h6.9L352.8,28.7z M390.5,10.7v5.6h-14.1v5.8h12.7v5.4h-12.7v5.9H391V39h-20.8V10.8L390.5,10.7
+				C390.5,10.8,390.5,10.7,390.5,10.7z M91.6,63c0.8,0,1.6-0.2,2.4-0.5c0.7-0.4,1.4-0.9,1.9-1.6l2.3,2.4c-0.8,0.9-1.7,1.7-2.9,2.2
+				c-1.1,0.5-2.3,0.8-3.5,0.8c-1.1,0-2.2-0.1-3.2-0.5c-1-0.4-2-1-2.8-1.8c-0.8-0.7-1.4-1.6-1.8-2.6c-0.4-1-0.6-2.1-0.6-3.2
+				c0-1.1,0.2-2.2,0.6-3.2c0.4-1,1-1.9,1.8-2.7c0.8-0.8,1.7-1.4,2.7-1.8c1-0.4,2.1-0.6,3.2-0.6c1.2,0,2.5,0.2,3.6,0.7
+				c1.1,0.5,2.1,1.3,3,2.2l-2.2,2.5c-0.5-0.7-1.1-1.2-1.8-1.6c-0.7-0.4-1.5-0.5-2.4-0.5c-1.3,0-2.5,0.5-3.4,1.3
+				c-0.5,0.4-0.9,1-1.1,1.6c-0.2,0.6-0.4,1.3-0.3,1.9c0,0.6,0.1,1.3,0.3,1.9c0.2,0.6,0.6,1.2,1,1.6c0.4,0.4,0.9,0.8,1.5,1
+				S91,63,91.6,63L91.6,63z M113.9,63.9c-1.6,1.5-3.7,2.4-5.9,2.4c-1.1,0-2.2-0.2-3.2-0.6c-1-0.4-1.9-1-2.7-1.8
+				c-1.5-1.5-2.4-3.6-2.4-5.8s0.9-4.3,2.4-5.8c1.6-1.5,3.7-2.4,5.9-2.4c1.1,0,2.2,0.2,3.2,0.6s1.9,1,2.7,1.8
+				c1.5,1.5,2.4,3.6,2.4,5.8S115.4,62.4,113.9,63.9z M112.8,58.1c0-1.3-0.4-2.6-1.3-3.6c-0.4-0.5-0.9-0.8-1.5-1.1
+				c-0.6-0.3-1.2-0.4-1.8-0.4c-0.6,0-1.3,0.1-1.8,0.4c-0.6,0.3-1.1,0.7-1.5,1.2c-0.5,0.5-0.8,1-1,1.7c-0.2,0.6-0.3,1.3-0.3,1.9
+				c0,1.3,0.5,2.6,1.3,3.6c0.4,0.5,0.9,0.8,1.5,1.1c0.6,0.3,1.2,0.4,1.8,0.4c0.6,0,1.3-0.1,1.8-0.4c0.6-0.3,1.1-0.7,1.5-1.2
+				C112.3,60.8,112.8,59.5,112.8,58.1L112.8,58.1z M133.5,56.1l-4.3,8.7h-2.1l-4.3-8.7v10h-3.5V50.3h4.8l4.1,8.7l4.1-8.7h4.8v15.9
+				h-3.5L133.5,56.1L133.5,56.1z M151.9,51.8c0.6,0.5,1.1,1.2,1.4,2c0.3,0.8,0.4,1.6,0.3,2.4c0,2-0.6,3.4-1.7,4.3
+				c-1.1,1-2.9,1.3-5.2,1.3h-2.1v4.4H141V50.3h5.6C149,50.3,150.7,50.8,151.9,51.8z M149.3,58c0.5-0.6,0.7-1.3,0.7-2.1
+				c0-0.4,0-0.7-0.2-1.1c-0.2-0.3-0.4-0.6-0.7-0.8c-0.8-0.4-1.7-0.6-2.6-0.6h-2v5.3h2.4c0.4,0,0.9,0,1.3-0.1
+				C148.6,58.4,149,58.2,149.3,58z M160.6,62c0.3,0.4,0.6,0.6,1.1,0.8c0.4,0.2,0.9,0.3,1.3,0.3c0.5,0,0.9-0.1,1.3-0.3
+				c0.4-0.2,0.8-0.5,1.1-0.8c0.6-0.9,0.9-2,0.9-3v-8.8h3.5v8.8c0.1,1-0.1,1.9-0.4,2.9c-0.3,0.9-0.8,1.8-1.5,2.5
+				c-1.3,1.2-3.1,1.8-4.9,1.8c-1.8,0-3.5-0.7-4.8-1.9c-0.7-0.7-1.2-1.6-1.5-2.5c-0.3-0.9-0.5-1.9-0.4-2.9v-8.8h3.5v8.8
+				C159.6,60,159.9,61.1,160.6,62z M180.1,53.4v12.7h-3.5V53.4h-4.5v-3h12.6v3C184.6,53.4,180.1,53.4,180.1,53.4z M187.2,50.3h3.5
+				v15.9h-3.5C187.2,66.2,187.2,50.3,187.2,50.3z M205.7,50.3h3.5v15.9h-3.5l-7.5-9.9v9.9h-3.5V50.3h3.3l7.8,10.2L205.7,50.3
+				C205.8,50.3,205.7,50.3,205.7,50.3z M223.5,58.1h3.5v5.6c-0.8,0.9-1.9,1.6-3,2c-1.1,0.5-2.4,0.7-3.6,0.6c-2.2,0-4.3-0.8-5.9-2.3
+				c-0.8-0.7-1.4-1.6-1.8-2.6c-0.4-1-0.6-2.1-0.6-3.2c0-1.1,0.2-2.2,0.6-3.2c0.4-1,1-1.9,1.8-2.7s1.7-1.4,2.7-1.8
+				c1-0.4,2.1-0.6,3.2-0.6c2.2,0,4.3,0.8,5.9,2.3l-1.8,2.7c-0.5-0.6-1.2-1-2-1.2c-0.6-0.2-1.3-0.4-1.9-0.4c-1.3,0-2.5,0.5-3.4,1.3
+				c-0.5,0.5-0.9,1-1.1,1.7s-0.4,1.3-0.3,2c0,1.3,0.4,2.6,1.3,3.6c0.4,0.4,0.9,0.8,1.4,1c0.5,0.2,1.1,0.3,1.7,0.3
+				c1.1,0.1,2.1-0.2,3-0.7v-4.5H223.5z M247,50.3v3.1h-7.3v3.4h6.9V60h-6.9v6.2h-3.5V50.3C236.1,50.3,247,50.3,247,50.3z
+				 M263.4,63.9c-1.6,1.5-3.7,2.4-5.9,2.4c-1.1,0-2.2-0.2-3.2-0.6c-1-0.4-1.9-1-2.7-1.8c-1.5-1.5-2.4-3.6-2.4-5.8s0.9-4.3,2.4-5.8
+				c1.6-1.5,3.7-2.4,5.9-2.4c1.1,0,2.2,0.2,3.2,0.6s1.9,1,2.7,1.8c1.5,1.5,2.4,3.6,2.4,5.8S264.9,62.4,263.4,63.9z M262.1,58.1
+				c0-1.3-0.4-2.6-1.3-3.6c-0.4-0.5-0.9-0.8-1.5-1.1c-0.6-0.3-1.2-0.4-1.8-0.4c-0.6,0-1.3,0.1-1.8,0.4c-0.6,0.3-1.1,0.7-1.5,1.2
+				c-0.5,0.5-0.8,1-1,1.7s-0.3,1.3-0.3,1.9c0,1.3,0.5,2.6,1.3,3.6c0.4,0.5,0.9,0.8,1.5,1.1c0.6,0.3,1.2,0.4,1.8,0.4
+				c0.6,0,1.3-0.1,1.8-0.4c0.6-0.3,1.1-0.7,1.5-1.2c0.5-0.5,0.8-1,1-1.7S262.2,58.8,262.1,58.1L262.1,58.1z M273,62
+				c0.3,0.4,0.6,0.6,1.1,0.8c0.4,0.2,0.9,0.3,1.3,0.3s0.9-0.1,1.3-0.3c0.4-0.2,0.8-0.5,1.1-0.8c0.6-0.9,0.9-2,0.9-3v-8.8h3.5v8.8
+				c0.1,1-0.1,1.9-0.4,2.9c-0.3,0.9-0.8,1.8-1.5,2.5c-1.3,1.2-3.1,1.8-4.9,1.8c-1.8,0-3.5-0.7-4.8-1.9c-0.7-0.7-1.2-1.6-1.5-2.5
+				c-0.3-0.9-0.5-1.9-0.4-2.9v-8.8h3.5v8.8C272,60,272.3,61.2,273,62z M296.9,50.3h3.5v15.9h-3.5l-7.5-9.9v9.9h-3.5V50.3h3.3
+				l7.8,10.2L296.9,50.3C297,50.3,296.9,50.3,296.9,50.3z M316.4,52.4c0.8,0.7,1.4,1.7,1.8,2.7s0.6,2.1,0.5,3.1
+				c0.1,1.1-0.1,2.1-0.5,3.1c-0.4,1-1,1.9-1.7,2.7c-1.4,1.4-3.7,2.2-6.8,2.2h-5.4V50.3h5.6C312.8,50.3,315,51,316.4,52.4z
+				 M313.8,61.9c0.4-0.5,0.8-1,1-1.6c0.2-0.6,0.3-1.3,0.3-1.9c0-0.7-0.1-1.3-0.3-1.9s-0.6-1.2-1-1.7c-0.6-0.5-1.2-0.8-1.9-1
+				s-1.4-0.3-2.1-0.2h-2v9.6h2.3C311.4,63.1,312.8,62.7,313.8,61.9z M332.6,66.1l-1.4-3.4h-6.7l-1.4,3.4h-3.8l6.9-15.9h3.4l6.9,15.9
+				H332.6z M327.8,55l-2,4.6h4L327.8,55z M343.8,53.4v12.7h-3.5V53.4h-4.6v-3h12.6v3C348.3,53.4,343.8,53.4,343.8,53.4z M350.8,50.3
+				h3.5v15.9h-3.5C350.8,66.2,350.8,50.3,350.8,50.3z M371.6,63.9c-1.6,1.5-3.7,2.4-5.9,2.4c-1.1,0-2.2-0.2-3.2-0.6s-1.9-1-2.7-1.8
+				c-1.5-1.5-2.4-3.6-2.4-5.8s0.9-4.3,2.4-5.8c1.6-1.5,3.7-2.4,5.9-2.4c1.1,0,2.2,0.2,3.2,0.6c1,0.4,1.9,1,2.7,1.8
+				c1.5,1.5,2.4,3.6,2.4,5.8S373.1,62.4,371.6,63.9z M370.5,58.1c0-1.3-0.5-2.6-1.3-3.6c-0.4-0.5-0.9-0.8-1.5-1.1
+				c-0.6-0.3-1.2-0.4-1.8-0.4c-0.6,0-1.3,0.1-1.8,0.4c-0.6,0.3-1.1,0.7-1.5,1.2c-0.5,0.5-0.8,1-1,1.7s-0.3,1.3-0.3,1.9
+				c0,1.3,0.5,2.6,1.3,3.6c0.4,0.5,0.9,0.8,1.5,1.1c0.6,0.3,1.2,0.4,1.8,0.4c0.6,0,1.3-0.1,1.8-0.4c0.6-0.3,1.1-0.7,1.5-1.2
+				C370,60.8,370.5,59.5,370.5,58.1z M388.1,50.3h3.5v15.9h-3.5l-7.5-9.9v9.9H377V50.3h3.3l7.8,10.2
+				C388.2,60.5,388.1,50.3,388.1,50.3z"/>
+		</g>
+	</g>
+</g>
+<g>
+	<path class="st0" d="M16.2,47.3H7.5v20.3h20.3v-8.7H16.2V47.3z"/>
+	<path class="st0" d="M59.8,47.4v11.5H48.2v8.7h20.3V47.3L59.8,47.4L59.8,47.4z"/>
+	<path class="st0" d="M7.5,27.1h8.8L16.2,27V15.5h11.6V6.8H7.5V27.1z"/>
+	<path class="st0" d="M48.2,6.8v8.7h11.6v11.6h8.7V6.8C68.4,6.8,48.2,6.8,48.2,6.8z"/>
+	<path class="st1" d="M47,27.1L35.4,15.5h12.7V6.8H27.8v8.7l11.6,11.6H47z"/>
+	<path class="st1" d="M36.6,47.3H29l9.6,9.6l1.9,2H27.8v8.7h20.4v-8.8l-5.8-5.7L36.6,47.3z"/>
+	<path class="st1" d="M59.8,27.1v12.6l-2-2l-9.6-9.6v7.7l5.7,5.7l5.8,5.8h8.8V27.1H59.8L59.8,27.1z"/>
+	<path class="st1" d="M27.8,38.6L16.3,27.1H7.5v20.2h8.7V34.7l11.6,11.6V38.6z"/>
+</g>
+</svg>
diff --git a/src/assets/github-logo.svg b/src/assets/github-logo.svg
new file mode 100644
index 00000000..37fa923d
--- /dev/null
+++ b/src/assets/github-logo.svg
@@ -0,0 +1 @@
+<svg width="98" height="96" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6-10.839-1.141-22.243-5.378-22.243-24.283 0-5.378 1.94-9.778 5.014-13.2-.485-1.222-2.184-6.275.486-13.038 0 0 4.125-1.304 13.426 5.052a46.97 46.97 0 0 1 12.214-1.63c4.125 0 8.33.571 12.213 1.63 9.302-6.356 13.427-5.052 13.427-5.052 2.67 6.763.97 11.816.485 13.038 3.155 3.422 5.015 7.822 5.015 13.2 0 18.905-11.404 23.06-22.324 24.283 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z" fill="#24292f"/></svg>
\ No newline at end of file
diff --git a/src/assets/prometheus-logo.svg b/src/assets/prometheus-logo.svg
new file mode 100644
index 00000000..b914095e
--- /dev/null
+++ b/src/assets/prometheus-logo.svg
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 16.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 width="115.333px" height="114px" viewBox="0 0 115.333 114" enable-background="new 0 0 115.333 114" xml:space="preserve">
+<g id="Layer_2">
+</g>
+<g>
+	<path fill="#EEEEEE" d="M56.667,0.667C25.372,0.667,0,26.036,0,57.332c0,31.295,25.372,56.666,56.667,56.666
+		s56.666-25.371,56.666-56.666C113.333,26.036,87.961,0.667,56.667,0.667z M56.667,106.722c-8.904,0-16.123-5.948-16.123-13.283
+		H72.79C72.79,100.773,65.571,106.722,56.667,106.722z M83.297,89.04H30.034v-9.658h53.264V89.04z M83.106,74.411h-52.92
+		c-0.176-0.203-0.356-0.403-0.526-0.609c-5.452-6.62-6.736-10.076-7.983-13.598c-0.021-0.116,6.611,1.355,11.314,2.413
+		c0,0,2.42,0.56,5.958,1.205c-3.397-3.982-5.414-9.044-5.414-14.218c0-11.359,8.712-21.285,5.569-29.308
+		c3.059,0.249,6.331,6.456,6.552,16.161c3.252-4.494,4.613-12.701,4.613-17.733c0-5.21,3.433-11.262,6.867-11.469
+		c-3.061,5.045,0.793,9.37,4.219,20.099c1.285,4.03,1.121,10.812,2.113,15.113C63.797,33.534,65.333,20.5,71,16
+		c-2.5,5.667,0.37,12.758,2.333,16.167c3.167,5.5,5.087,9.667,5.087,17.548c0,5.284-1.951,10.259-5.242,14.148
+		c3.742-0.702,6.326-1.335,6.326-1.335l12.152-2.371C91.657,60.156,89.891,67.418,83.106,74.411z"/>
+</g>
+</svg>
diff --git a/src/components/Dots.tsx b/src/components/Dots.tsx
new file mode 100644
index 00000000..51d572f3
--- /dev/null
+++ b/src/components/Dots.tsx
@@ -0,0 +1,119 @@
+export interface DotsProps extends React.ComponentPropsWithoutRef<"svg"> {
+  size?: number;
+  radius?: number;
+}
+
+export function Dots({ size = 185, radius = 2.5, ...others }: DotsProps) {
+  return (
+    <svg
+      aria-hidden
+      xmlns="http://www.w3.org/2000/svg"
+      fill="currentColor"
+      viewBox="0 0 185 185"
+      width={size}
+      height={size}
+      {...others}
+    >
+      <rect width="5" height="5" rx={radius} />
+      <rect width="5" height="5" x="60" rx={radius} />
+      <rect width="5" height="5" x="120" rx={radius} />
+      <rect width="5" height="5" x="20" rx={radius} />
+      <rect width="5" height="5" x="80" rx={radius} />
+      <rect width="5" height="5" x="140" rx={radius} />
+      <rect width="5" height="5" x="40" rx={radius} />
+      <rect width="5" height="5" x="100" rx={radius} />
+      <rect width="5" height="5" x="160" rx={radius} />
+      <rect width="5" height="5" x="180" rx={radius} />
+      <rect width="5" height="5" y="20" rx={radius} />
+      <rect width="5" height="5" x="60" y="20" rx={radius} />
+      <rect width="5" height="5" x="120" y="20" rx={radius} />
+      <rect width="5" height="5" x="20" y="20" rx={radius} />
+      <rect width="5" height="5" x="80" y="20" rx={radius} />
+      <rect width="5" height="5" x="140" y="20" rx={radius} />
+      <rect width="5" height="5" x="40" y="20" rx={radius} />
+      <rect width="5" height="5" x="100" y="20" rx={radius} />
+      <rect width="5" height="5" x="160" y="20" rx={radius} />
+      <rect width="5" height="5" x="180" y="20" rx={radius} />
+      <rect width="5" height="5" y="40" rx={radius} />
+      <rect width="5" height="5" x="60" y="40" rx={radius} />
+      <rect width="5" height="5" x="120" y="40" rx={radius} />
+      <rect width="5" height="5" x="20" y="40" rx={radius} />
+      <rect width="5" height="5" x="80" y="40" rx={radius} />
+      <rect width="5" height="5" x="140" y="40" rx={radius} />
+      <rect width="5" height="5" x="40" y="40" rx={radius} />
+      <rect width="5" height="5" x="100" y="40" rx={radius} />
+      <rect width="5" height="5" x="160" y="40" rx={radius} />
+      <rect width="5" height="5" x="180" y="40" rx={radius} />
+      <rect width="5" height="5" y="60" rx={radius} />
+      <rect width="5" height="5" x="60" y="60" rx={radius} />
+      <rect width="5" height="5" x="120" y="60" rx={radius} />
+      <rect width="5" height="5" x="20" y="60" rx={radius} />
+      <rect width="5" height="5" x="80" y="60" rx={radius} />
+      <rect width="5" height="5" x="140" y="60" rx={radius} />
+      <rect width="5" height="5" x="40" y="60" rx={radius} />
+      <rect width="5" height="5" x="100" y="60" rx={radius} />
+      <rect width="5" height="5" x="160" y="60" rx={radius} />
+      <rect width="5" height="5" x="180" y="60" rx={radius} />
+      <rect width="5" height="5" y="80" rx={radius} />
+      <rect width="5" height="5" x="60" y="80" rx={radius} />
+      <rect width="5" height="5" x="120" y="80" rx={radius} />
+      <rect width="5" height="5" x="20" y="80" rx={radius} />
+      <rect width="5" height="5" x="80" y="80" rx={radius} />
+      <rect width="5" height="5" x="140" y="80" rx={radius} />
+      <rect width="5" height="5" x="40" y="80" rx={radius} />
+      <rect width="5" height="5" x="100" y="80" rx={radius} />
+      <rect width="5" height="5" x="160" y="80" rx={radius} />
+      <rect width="5" height="5" x="180" y="80" rx={radius} />
+      <rect width="5" height="5" y="100" rx={radius} />
+      <rect width="5" height="5" x="60" y="100" rx={radius} />
+      <rect width="5" height="5" x="120" y="100" rx={radius} />
+      <rect width="5" height="5" x="20" y="100" rx={radius} />
+      <rect width="5" height="5" x="80" y="100" rx={radius} />
+      <rect width="5" height="5" x="140" y="100" rx={radius} />
+      <rect width="5" height="5" x="40" y="100" rx={radius} />
+      <rect width="5" height="5" x="100" y="100" rx={radius} />
+      <rect width="5" height="5" x="160" y="100" rx={radius} />
+      <rect width="5" height="5" x="180" y="100" rx={radius} />
+      <rect width="5" height="5" y="120" rx={radius} />
+      <rect width="5" height="5" x="60" y="120" rx={radius} />
+      <rect width="5" height="5" x="120" y="120" rx={radius} />
+      <rect width="5" height="5" x="20" y="120" rx={radius} />
+      <rect width="5" height="5" x="80" y="120" rx={radius} />
+      <rect width="5" height="5" x="140" y="120" rx={radius} />
+      <rect width="5" height="5" x="40" y="120" rx={radius} />
+      <rect width="5" height="5" x="100" y="120" rx={radius} />
+      <rect width="5" height="5" x="160" y="120" rx={radius} />
+      <rect width="5" height="5" x="180" y="120" rx={radius} />
+      <rect width="5" height="5" y="140" rx={radius} />
+      <rect width="5" height="5" x="60" y="140" rx={radius} />
+      <rect width="5" height="5" x="120" y="140" rx={radius} />
+      <rect width="5" height="5" x="20" y="140" rx={radius} />
+      <rect width="5" height="5" x="80" y="140" rx={radius} />
+      <rect width="5" height="5" x="140" y="140" rx={radius} />
+      <rect width="5" height="5" x="40" y="140" rx={radius} />
+      <rect width="5" height="5" x="100" y="140" rx={radius} />
+      <rect width="5" height="5" x="160" y="140" rx={radius} />
+      <rect width="5" height="5" x="180" y="140" rx={radius} />
+      <rect width="5" height="5" y="160" rx={radius} />
+      <rect width="5" height="5" x="60" y="160" rx={radius} />
+      <rect width="5" height="5" x="120" y="160" rx={radius} />
+      <rect width="5" height="5" x="20" y="160" rx={radius} />
+      <rect width="5" height="5" x="80" y="160" rx={radius} />
+      <rect width="5" height="5" x="140" y="160" rx={radius} />
+      <rect width="5" height="5" x="40" y="160" rx={radius} />
+      <rect width="5" height="5" x="100" y="160" rx={radius} />
+      <rect width="5" height="5" x="160" y="160" rx={radius} />
+      <rect width="5" height="5" x="180" y="160" rx={radius} />
+      <rect width="5" height="5" y="180" rx={radius} />
+      <rect width="5" height="5" x="60" y="180" rx={radius} />
+      <rect width="5" height="5" x="120" y="180" rx={radius} />
+      <rect width="5" height="5" x="20" y="180" rx={radius} />
+      <rect width="5" height="5" x="80" y="180" rx={radius} />
+      <rect width="5" height="5" x="140" y="180" rx={radius} />
+      <rect width="5" height="5" x="40" y="180" rx={radius} />
+      <rect width="5" height="5" x="100" y="180" rx={radius} />
+      <rect width="5" height="5" x="160" y="180" rx={radius} />
+      <rect width="5" height="5" x="180" y="180" rx={radius} />
+    </svg>
+  );
+}
diff --git a/src/components/FeaturesCards.module.css b/src/components/FeaturesCards.module.css
new file mode 100644
index 00000000..695fd754
--- /dev/null
+++ b/src/components/FeaturesCards.module.css
@@ -0,0 +1,47 @@
+.title {
+  font-size: rem(34px);
+  font-weight: 900;
+
+  @media (max-width: $mantine-breakpoint-sm) {
+    font-size: rem(24px);
+  }
+}
+
+.description {
+  max-width: rem(600px);
+  margin: auto;
+
+  &::after {
+    content: "";
+    display: block;
+    background-color: var(--mantine-primary-color-filled);
+    width: rem(45px);
+    height: rem(2px);
+    margin-top: var(--mantine-spacing-sm);
+    margin-left: auto;
+    margin-right: auto;
+  }
+}
+
+.card {
+  border: rem(1px) solid
+    light-dark(var(--mantine-color-gray-1), var(--mantine-color-dark-5));
+  cursor: pointer;
+  transition: border-color 100ms ease, background-color 500ms ease;
+}
+
+.card:hover {
+  border-color: var(--mantine-primary-color-filled);
+  background-color: var(--mantine-primary-color-0);
+}
+
+.cardTitle {
+  &::after {
+    content: "";
+    display: block;
+    background-color: var(--mantine-primary-color-filled);
+    width: rem(45px);
+    height: rem(2px);
+    margin-top: var(--mantine-spacing-sm);
+  }
+}
diff --git a/src/components/FeaturesCards.tsx b/src/components/FeaturesCards.tsx
new file mode 100644
index 00000000..ad17dd21
--- /dev/null
+++ b/src/components/FeaturesCards.tsx
@@ -0,0 +1,126 @@
+import {
+  Badge,
+  Group,
+  Title,
+  Text,
+  Card,
+  SimpleGrid,
+  Container,
+  rem,
+} from "@mantine/core";
+import {
+  IconGauge,
+  IconChartGridDots,
+  IconDatabaseSearch,
+  IconBell,
+  IconRun,
+  IconAffiliate,
+} from "@tabler/icons-react";
+import classes from "./FeaturesCards.module.css";
+import { theme } from "@/theme";
+
+const mockdata = [
+  {
+    title: "Dimensional data model",
+    description:
+      "Prometheus models time series in a flexible dimensional data model. Time series are identified by a metric name and a set of key-value pairs.",
+    icon: IconChartGridDots,
+  },
+  {
+    title: "Powerful queries",
+    description:
+      "The PromQL query language allows you to query, correlate, and transform your time series data in powerful ways for visualizations, alerts, and more.",
+    icon: IconDatabaseSearch,
+  },
+  {
+    title: "Precise alerting",
+    description:
+      "Alerting rules are based on PromQL and make full use of the dimensional data model. A separate Alertmanager component handles notifications and silencing.",
+    icon: IconBell,
+  },
+  {
+    title: "Simple operation",
+    description:
+      "Prometheus servers operate independently and only rely on local storage. Developed in Go, the statically linked binaries are easy to deploy across various environments.",
+    icon: IconRun,
+  },
+  {
+    title: "Instrumentation libraries",
+    description:
+      "Prometheus provides a large number of official and community-contributed metrics instrumentation libraries that cover most major languages.",
+    icon: IconGauge,
+  },
+  {
+    title: "Ubiquitous integrations",
+    description:
+      "Prometheus comes with hundreds of official and community-contributed integrations that allow you to easily extract metrics from existing systems.",
+    icon: IconAffiliate,
+  },
+  // {
+  //   title: "Efficient storage",
+  //   description:
+  //     "Prometheus stores data in an efficient custom-designed format. You can scale Prometheus by sharding, federating, or other using external integrations.",
+  //   icon: IconServerBolt,
+  // },
+  // {
+  //   title: "Alerting",
+  //   description:
+  //     "Alerts are defined based on Prometheus's flexible PromQL and maintain dimensional information. An alertmanager handles notifications and silencing.",
+  //   icon: IconBell,
+  // },
+];
+
+export function FeaturesCards() {
+  // const theme = useMantineTheme();
+  const features = mockdata.map((feature) => (
+    <Card
+      key={feature.title}
+      shadow="md"
+      radius="md"
+      className={classes.card}
+      padding="xl"
+    >
+      <feature.icon
+        style={{ width: rem(50), height: rem(50) }}
+        stroke={2}
+        color={theme.colors!.prometheusColor![6]}
+      />
+      <Text fz="lg" fw={500} className={classes.cardTitle} mt="md">
+        {feature.title}
+      </Text>
+      <Text fz="sm" c="dimmed" mt="sm">
+        {feature.description}
+      </Text>
+    </Card>
+  ));
+
+  return (
+    <Container size="lg" pb={90}>
+      <SimpleGrid cols={{ base: 1, md: 3 }} spacing="xl" my={50}>
+        {features}
+      </SimpleGrid>
+      <Group justify="center" mt={120}>
+        <Badge variant="filled" size="lg">
+          Modern monitoring
+        </Badge>
+      </Group>
+
+      <Title order={2} className={classes.title} ta="center" mt="sm">
+        Monitoring for the cloud native world
+      </Title>
+
+      <Text c="dimmed" className={classes.description} ta="center" mt="md">
+        Designed for the cloud native world, Prometheus integrates with
+        Kubernetes and other cloud and container managers to continuously
+        discover and monitor your services. It is the second project to graduate
+        from the CNCF after Kubernetes.
+      </Text>
+
+      {/* <Group justify="center" mt={120}>
+        <Badge variant="filled" size="lg">
+          100% Open Source
+        </Badge>
+      </Group> */}
+    </Container>
+  );
+}
diff --git a/src/components/Header.module.css b/src/components/Header.module.css
new file mode 100644
index 00000000..72df9dd8
--- /dev/null
+++ b/src/components/Header.module.css
@@ -0,0 +1,35 @@
+.header {
+  height: rem(72px);
+  margin-bottom: rem(60px);
+  /* background-color: var(--mantine-color-body); */
+  /* background-color: var(--mantine-color-gray-7); */
+  /* background-color: #3e4a56; */
+  /* background-color: #2d3b48; */
+  background-color: #28313a;
+  /* border-bottom: rem(1px) solid
+      light-dark(var(--mantine-color-gray-3), var(--mantine-color-dark-4)); */
+  padding-left: var(--mantine-spacing-md);
+  padding-right: var(--mantine-spacing-md);
+}
+
+.inner {
+  height: rem(72px);
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.link {
+  display: block;
+  line-height: 1;
+  padding: rem(8px) rem(12px);
+  border-radius: var(--mantine-radius-sm);
+  text-decoration: none;
+  color: var(--mantine-color-gray-2);
+  font-size: var(--mantine-font-size-sm);
+  font-weight: 500;
+
+  @mixin hover {
+    background-color: var(--mantine-color-dark-6);
+  }
+}
diff --git a/src/components/Header.tsx b/src/components/Header.tsx
new file mode 100644
index 00000000..e90731d5
--- /dev/null
+++ b/src/components/Header.tsx
@@ -0,0 +1,107 @@
+import { Group, Burger, rem, Text, Container, TextInput } from "@mantine/core";
+import Image from "next/image";
+import { useDisclosure } from "@mantine/hooks";
+import { IconSearch } from "@tabler/icons-react";
+import prometheusLogo from "../assets/prometheus-logo.svg";
+import classes from "./Header.module.css";
+import { FC } from "react";
+import githubLogo from "../assets/github-logo.svg";
+import Link from "next/link";
+
+const links = [
+  { link: "/docs/introduction/overview", label: "Docs" },
+  { link: "/download", label: "Download" },
+  { link: "/community", label: "Community" },
+  { link: "/support-training", label: "Support & Training" },
+  { link: "/blog", label: "Blog" },
+];
+
+export const Header: FC = () => {
+  const [opened, { toggle }] = useDisclosure(false);
+
+  const items = links.map((link) => (
+    <Link key={link.label} href={link.link} className={classes.link}>
+      {link.label}
+    </Link>
+  ));
+
+  return (
+    <header className={classes.header}>
+      <Container size="lg">
+        <div className={classes.inner}>
+          <Link href="/" style={{ textDecoration: "none" }}>
+            <Group>
+              <Image src={prometheusLogo} height={32} alt="Prometheus logo" />
+              <Text fz={25} ff="Lato Light" c="white">
+                Prometheus
+              </Text>
+            </Group>
+          </Link>
+
+          <Group align="center">
+            <Group ml={50} gap={5} className={classes.links} visibleFrom="sm">
+              {items}
+            </Group>
+
+            <TextInput
+              className={classes.search}
+              placeholder="Search"
+              w={250}
+              mx="lg"
+              leftSection={
+                <IconSearch
+                  style={{ width: rem(16), height: rem(16) }}
+                  stroke={1.5}
+                />
+              }
+              rightSection={
+                <Text
+                  size="xs"
+                  mx={5}
+                  p={6}
+                  fw={700}
+                  c="dark.1"
+                  //   bg="#394855"
+                  bg="#56697a"
+                  lh={1}
+                  style={{ borderRadius: "0.25em" }}
+                >
+                  Ctrl + K
+                </Text>
+              }
+              rightSectionWidth="fit-content"
+              visibleFrom="xs"
+              styles={{
+                input: {
+                  background: "#394855",
+                  borderColor: "transparent",
+                  color: "white",
+                },
+              }}
+            />
+
+            <a href="https://github.com/prometheus" target="_blank">
+              <Image
+                src={githubLogo}
+                style={{
+                  height: 20,
+                  width: 20,
+                  filter: "invert(1)",
+                  verticalAlign: "middle",
+                }}
+                alt="GitHub Logo"
+              />
+            </a>
+            <Burger
+              opened={opened}
+              onClick={toggle}
+              color="gray.3"
+              size="sm"
+              hiddenFrom="sm"
+            />
+          </Group>
+        </div>
+      </Container>
+    </header>
+  );
+};
diff --git a/src/components/Hero.module.css b/src/components/Hero.module.css
new file mode 100644
index 00000000..2f086c67
--- /dev/null
+++ b/src/components/Hero.module.css
@@ -0,0 +1,82 @@
+.wrapper {
+  position: relative;
+  padding-top: rem(80px);
+  padding-bottom: rem(60px);
+
+  @media (max-width: $mantine-breakpoint-sm) {
+    padding-top: rem(80px);
+    padding-bottom: rem(60px);
+  }
+}
+
+.inner {
+  position: relative;
+  z-index: 1;
+}
+
+.dots {
+  position: absolute;
+  color: light-dark(var(--mantine-color-gray-1), var(--mantine-color-dark-5));
+  @media (max-width: $mantine-breakpoint-sm) {
+    display: none;
+  }
+}
+
+.dotsLeft {
+  left: 0;
+  top: 0;
+}
+
+.title {
+  text-align: center;
+  font-weight: 800;
+  font-size: rem(40px);
+  letter-spacing: -1px;
+  color: light-dark(var(--mantine-color-black), var(--mantine-color-white));
+  margin-bottom: var(--mantine-spacing-xs);
+  font-family: Greycliff CF, var(--mantine-font-family);
+
+  @media (max-width: $mantine-breakpoint-xs) {
+    font-size: rem(28px);
+    text-align: left;
+  }
+}
+
+.highlight {
+  color: var(--mantine-primary-color-6);
+}
+
+.description {
+  text-align: center;
+
+  @media (max-width: $mantine-breakpoint-xs) {
+    text-align: left;
+    font-size: var(--mantine-font-size-md);
+  }
+}
+
+.controls {
+  margin-top: var(--mantine-spacing-lg);
+  display: flex;
+  justify-content: center;
+
+  @media (max-width: $mantine-breakpoint-xs) {
+    flex-direction: column;
+  }
+}
+
+.control {
+  &:not(:first-of-type) {
+    margin-left: var(--mantine-spacing-md);
+  }
+
+  @media (max-width: $mantine-breakpoint-xs) {
+    height: rem(42px);
+    font-size: var(--mantine-font-size-md);
+
+    &:not(:first-of-type) {
+      margin-top: var(--mantine-spacing-md);
+      margin-left: 0;
+    }
+  }
+}
diff --git a/src/components/Hero.tsx b/src/components/Hero.tsx
new file mode 100644
index 00000000..6267cafb
--- /dev/null
+++ b/src/components/Hero.tsx
@@ -0,0 +1,68 @@
+import { Title, Text, Button, Container } from "@mantine/core";
+import { Dots } from "./Dots";
+import classes from "./Hero.module.css";
+import { IconDownload } from "@tabler/icons-react";
+
+export function Hero() {
+  return (
+    <Container className={classes.wrapper} size={1400}>
+      <Dots className={classes.dots} style={{ left: 0, top: 0 }} />
+      <Dots className={classes.dots} style={{ left: 60, top: 0 }} />
+      <Dots className={classes.dots} style={{ left: 0, top: 140 }} />
+      <Dots className={classes.dots} style={{ right: 0, top: 60 }} />
+
+      <div className={classes.inner}>
+        {/* <Container p={0} size={800}>
+          <Title className={classes.title}>
+            The leading{" "}
+            <Text component="span" className={classes.highlight} inherit>
+              metrics and monitoring
+            </Text>{" "}
+            solution
+          </Title>
+        </Container> */}
+        {/* <Container p={0} size={800}>
+          <Title className={classes.title}>
+            Open source{" "}
+            <Text component="span" className={classes.highlight} inherit>
+              metrics and monitoring
+            </Text>{" "}
+            for your systems and services
+          </Title>
+        </Container> */}
+        <Container p={0} size={800}>
+          <Title className={classes.title}>
+            Open source{" "}
+            <Text component="span" className={classes.highlight} inherit>
+              metrics and monitoring
+            </Text>{" "}
+            for your systems and services
+          </Title>
+        </Container>
+
+        <Container p={0} size={600} my="xl">
+          <Text size="lg" c="dimmed" className={classes.description}>
+            Monitor your applications, systems, and services with the leading
+            open source monitoring solution. Instrument, collect, store, and
+            query your metrics for alerting, dashboarding, and other use cases.
+          </Text>
+        </Container>
+
+        <div className={classes.controls}>
+          <Button className={classes.control} size="lg">
+            Get started
+          </Button>
+          <Button
+            className={classes.control}
+            size="lg"
+            variant="default"
+            color="gray"
+            leftSection={<IconDownload />}
+          >
+            Download
+          </Button>
+        </div>
+      </div>
+    </Container>
+  );
+}
diff --git a/src/components/UserLogos.module.css b/src/components/UserLogos.module.css
new file mode 100644
index 00000000..00124101
--- /dev/null
+++ b/src/components/UserLogos.module.css
@@ -0,0 +1,25 @@
+.carouselContainer {
+  width: 100%;
+  overflow: hidden;
+  filter: grayscale(1);
+}
+
+.carousel {
+  display: flex;
+  gap: 60px; /* Space between logos */
+  animation: scroll 20s linear infinite;
+}
+
+.carousel img {
+  height: 40px; /* Adjust size as needed */
+  object-fit: contain;
+}
+
+@keyframes scroll {
+  0% {
+    transform: translateX(0);
+  }
+  100% {
+    transform: translateX(-100%);
+  }
+}
diff --git a/src/components/UserLogos.tsx b/src/components/UserLogos.tsx
new file mode 100644
index 00000000..58053608
--- /dev/null
+++ b/src/components/UserLogos.tsx
@@ -0,0 +1,146 @@
+import { Box } from "@mantine/core";
+import classes from "./UserLogos.module.css";
+
+export function UserLogos() {
+  return (
+    <Box className={classes.carouselContainer} my="xl">
+      <div className={classes.carousel}>
+        <a href="https://amadeus.com/">
+          <img src="/assets/company-logos/Amadeus.png" alt="Amadeus logo" />
+        </a>
+        <a href="https://argus-sec.com/">
+          <img src="/assets/company-logos/Argus.png" alt="Argus logo" />
+        </a>
+        <a href="https://www.ayedo.de/">
+          <img src="/assets/company-logos/ayedo.png" alt="ayedo logo" />
+        </a>
+        <a href="https://www.boxever.com/">
+          <img src="/assets/company-logos/Boxever.png" alt="Boxever logo" />
+        </a>
+        <a href="https://www.cesanta.com/">
+          <img src="/assets/company-logos/cesanta.png" alt="cesanta logo" />
+        </a>
+        <a href="https://www.coreos.com/">
+          <img src="/assets/company-logos/CoreOS.png" alt="CoreOS logo" />
+        </a>
+        <a href="https://www.crononauta.com/">
+          <img
+            src="/assets/company-logos/crononauta.png"
+            alt="crononauta logo"
+          />
+        </a>
+        <a href="https://www.digitalocean.com/">
+          <img
+            src="/assets/company-logos/digitalocean.png"
+            alt="digitalocean logo"
+          />
+        </a>
+        <a href="https://www.docker.com/">
+          <img src="/assets/company-logos/Docker.png" alt="Docker logo" />
+        </a>
+        <a href="https://www.ericsson.com/">
+          <img src="/assets/company-logos/Ericsson.png" alt="Ericsson logo" />
+        </a>
+        <a href="https://www.eurotech.com/">
+          <img src="/assets/company-logos/Eurotech.png" alt="Eurotech logo" />
+        </a>
+        <a href="https://www.fosdem.org/">
+          <img src="/assets/company-logos/Fosdem.png" alt="Fosdem logo" />
+        </a>
+        <a href="https://giantswarm.io/">
+          <img
+            src="/assets/company-logos/giantswarm.png"
+            alt="giantswarm logo"
+          />
+        </a>
+        <a href="https://grafana.com/">
+          <img src="/assets/company-logos/grafana.png" alt="grafana logo" />
+        </a>
+        <a href="https://improbable.io/">
+          <img
+            src="/assets/company-logos/Improbable.png"
+            alt="Improbable logo"
+          />
+        </a>
+        <a href="https://www.jodel.com/">
+          <img src="/assets/company-logos/Jodel.png" alt="Jodel logo" />
+        </a>
+        <a href="https://www.justwatch.com/">
+          <img src="/assets/company-logos/JustWatch.png" alt="JustWatch logo" />
+        </a>
+        <a href="https://www.kubermatic.com/">
+          <img
+            src="/assets/company-logos/Kubermatic.png"
+            alt="Kubermatic logo"
+          />
+        </a>
+        <a href="https://www.kumina.nl/">
+          <img src="/assets/company-logos/Kumina.png" alt="Kumina logo" />
+        </a>
+        <a href="https://www.mavensecurities.com/">
+          <img
+            src="/assets/company-logos/MavenSecurities.png"
+            alt="MavenSecurities logo"
+          />
+        </a>
+        <a href="https://mixpanel.com/">
+          <img src="/assets/company-logos/mixpanel.png" alt="mixpanel logo" />
+        </a>
+        <a href="https://www.moia.io/">
+          <img src="/assets/company-logos/MOIA.png" alt="MOIA logo" />
+        </a>
+        <a href="https://www.outbrain.com/">
+          <img src="/assets/company-logos/Outbrain.png" alt="Outbrain logo" />
+        </a>
+        <a href="https://www.pingcap.com/">
+          <img src="/assets/company-logos/pingcap.png" alt="pingcap logo" />
+        </a>
+        <a href="https://www.qaware.de/">
+          <img src="/assets/company-logos/Qaware.png" alt="Qaware logo" />
+        </a>
+        <a href="https://www.quobyte.com/">
+          <img src="/assets/company-logos/quobyte.png" alt="quobyte logo" />
+        </a>
+        <a href="https://www.robustperception.io/">
+          <img
+            src="/assets/company-logos/RobustPerception.png"
+            alt="RobustPerception logo"
+          />
+        </a>
+        <a href="https://www.showmax.com/">
+          <img src="/assets/company-logos/Showmax.png" alt="Showmax logo" />
+        </a>
+        <a href="https://www.shuttlecloud.com/">
+          <img
+            src="/assets/company-logos/shuttlecloud.png"
+            alt="shuttlecloud logo"
+          />
+        </a>
+        <a href="https://www.soundcloud.com/">
+          <img
+            src="/assets/company-logos/soundcloud.png"
+            alt="soundcloud logo"
+          />
+        </a>
+        <a href="https://www.space.net/">
+          <img src="/assets/company-logos/Spacenet.png" alt="Spacenet logo" />
+        </a>
+        <a href="https://www.sysdig.com/">
+          <img src="/assets/company-logos/Sysdig.png" alt="Sysdig logo" />
+        </a>
+        <a href="https://transloadit.com/">
+          <img
+            src="/assets/company-logos/transloadit.png"
+            alt="transloadit logo"
+          />
+        </a>
+        <a href="https://www.unosoft.hu/">
+          <img src="/assets/company-logos/unosoft.png" alt="unosoft logo" />
+        </a>
+        <a href="https://www.weave.works/">
+          <img src="/assets/company-logos/weave.png" alt="weave logo" />
+        </a>
+      </div>
+    </Box>
+  );
+}
diff --git a/src/docs-collection-types.ts b/src/docs-collection-types.ts
new file mode 100644
index 00000000..a3b8e1a5
--- /dev/null
+++ b/src/docs-collection-types.ts
@@ -0,0 +1,47 @@
+export type LocalDocMetadata = {
+  type: "local-doc";
+  filePath: string;
+  content: string;
+
+  // Frontmatter fields - maybe put them in a separate type?
+  title: string;
+  navIcon?: string;
+  sortRank: number;
+  hideInNav?: boolean;
+};
+
+// TODO: Rename "repo-doc" (and variants) to "external-doc" everywhere.
+export type RepoDocMetadata = {
+  type: "repo-doc";
+  filePath: string;
+  content: string;
+
+  owner: string;
+  repo: string;
+  version: string;
+  slugPrefix: string; // Shared for the whole repo, could be factored out.
+  latestVersion: string; // Shared for the whole repo, could be factored out.
+  versionRoot: string; // Shared for the whole repo, could be factored out.
+  assetsRoot: string; // Shared for the whole repo, could be factored out.
+
+  // Frontmatter fields - maybe put them in a separate type?
+  title: string;
+  navTitle?: string;
+  sortRank: number;
+};
+
+export type DocsCollection = {
+  [slug: string]: LocalDocMetadata | RepoDocMetadata;
+};
+
+export type RepoVersions = {
+  versions: string[];
+  latestVersion: string;
+  ltsVersions: string[];
+};
+
+export type AllRepoVersions = {
+  [owner: string]: {
+    [repo: string]: RepoVersions;
+  };
+};
diff --git a/src/docs-collection.ts b/src/docs-collection.ts
new file mode 100644
index 00000000..29d91321
--- /dev/null
+++ b/src/docs-collection.ts
@@ -0,0 +1,6 @@
+import docsCollectionJson from "../generated/docs-collection.json";
+import allRepoVersionsJson from "../generated/repo-versions.json";
+import { DocsCollection, AllRepoVersions } from "./docs-collection-types";
+
+export const docsCollection = docsCollectionJson as DocsCollection;
+export const allRepoVersions = allRepoVersionsJson as AllRepoVersions;
diff --git a/src/docs-config-types.ts b/src/docs-config-types.ts
new file mode 100644
index 00000000..b8c0521b
--- /dev/null
+++ b/src/docs-config-types.ts
@@ -0,0 +1,22 @@
+export type DocsConfig = {
+  localMarkdownSources: LocalMarkdownSource[];
+  githubMarkdownSources: GithubMarkdownSource[];
+  ltsVersions: LTSConfig;
+};
+
+export type GithubMarkdownSource = {
+  owner: string;
+  repo: string;
+  repoDocsDir: string;
+  slugPrefix: string;
+  minNumVersions: number;
+};
+
+export type LocalMarkdownSource = {
+  docsDir: string;
+  slugPrefix: string;
+};
+
+export type LTSConfig = {
+  [repo: string]: string[];
+};
diff --git a/src/rehypeConfigLinker.ts b/src/rehypeConfigLinker.ts
new file mode 100644
index 00000000..86a465ea
--- /dev/null
+++ b/src/rehypeConfigLinker.ts
@@ -0,0 +1,92 @@
+import type { Root, Element, ElementContent } from "hast";
+import { selectAll } from "hast-util-select";
+import { toString } from "hast-util-to-string";
+import { toHtml } from "hast-util-to-html";
+import { fromHtml } from "hast-util-from-html"; // To parse innerHTML strings
+
+// Replace sequences of non-word characters with single dashes. Remove
+// extra dashes at the beginning or end.
+//
+// Example: <http_config> => "http_config"
+function generateAnchor(text: string) {
+  return text.replace(/\W+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+const placeholderRegex = /^<[^>]+>$/;
+
+// TODO: Only run this on the "Configuration" page, like in the old site?
+const getPlaceholderTypes = (tree: Root): Record<string, string> => {
+  const types: Record<string, string> = {};
+
+  // First, find any headers that contain <code> placeholders and store their types if
+  // their id matches the anchor we generate for the <code> element content.
+  selectAll("h1, h2, h3, h4, h5, h6", tree).forEach((header) => {
+    const codeNodes = selectAll("code", header);
+    const codeNode = codeNodes[0];
+    if (
+      codeNodes.length !== 1 ||
+      !placeholderRegex.test(toString(codeNodes[0]))
+    ) {
+      return;
+    }
+
+    const anchor = generateAnchor(toString(codeNode));
+    if (header.properties?.id === anchor) {
+      types[anchor] = toHtml(codeNode.children);
+    }
+  });
+
+  // Create anchors for the remaining placeholder <code> elements.
+  selectAll("code", tree).forEach((codeNode) => {
+    if (!placeholderRegex.test(toString(codeNode))) {
+      return;
+    }
+
+    const anchor = generateAnchor(toString(codeNode));
+    if (anchor in types) {
+      return;
+    }
+
+    codeNode.properties.id = anchor;
+    types[anchor] = toHtml(codeNode.children);
+  });
+
+  return types;
+};
+
+export default function rehypeConfigLinker() {
+  return (tree: Root) => {
+    const types = getPlaceholderTypes(tree);
+
+    // Second pass: Find <pre><code> blocks and link them
+    const configBlocks: Element[] = selectAll("pre > code", tree);
+
+    configBlocks.forEach((configCodeNode) => {
+      let currentHtml = toHtml(configCodeNode.children);
+      let changed = false;
+
+      Object.entries(types).forEach(([anchor, html]) => {
+        if (currentHtml.includes(html)) {
+          currentHtml = currentHtml.replaceAll(
+            html,
+            `<a href="#${anchor}">${html}</a>`
+          );
+          changed = true;
+        }
+        console.log(`Matched for ${anchor} with ${html}, changed ${changed}`);
+      });
+
+      if (changed) {
+        // Replace children of configCodeNode with the new parsed HTML
+        const newChildren = fromHtml(currentHtml, { fragment: true });
+
+        const elementChildren = newChildren.children.filter(
+          (child): child is ElementContent =>
+            child.type === "element" || child.type === "text"
+        );
+
+        configCodeNode.children = elementChildren;
+      }
+    });
+  };
+}
diff --git a/src/theme.ts b/src/theme.ts
new file mode 100644
index 00000000..da60d57f
--- /dev/null
+++ b/src/theme.ts
@@ -0,0 +1,29 @@
+import { createTheme, MantineColorsTuple } from "@mantine/core";
+
+const prometheusColor: MantineColorsTuple = [
+  "#ffede6",
+  "#ffdad2",
+  "#f6b5a4",
+  "#f08e74",
+  "#ea6b4b",
+  "#e75630",
+  "#e64a22",
+  "#cc3b16",
+  "#b73311",
+  "#a02709",
+];
+
+export const theme = createTheme({
+  colors: {
+    prometheusColor,
+  },
+  primaryColor: "prometheusColor",
+  headings: {
+    fontFamily: "var(--font-inter)",
+    sizes: {
+      h1: {
+        fontWeight: "800",
+      },
+    },
+  },
+});
diff --git a/tsconfig.json b/tsconfig.json
index c1334095..fb670c16 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -20,7 +20,8 @@
     ],
     "paths": {
       "@/*": ["./src/*"]
-    }
+    },
+    "noImplicitAny": false
   },
   "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
   "exclude": ["node_modules"]