Restructure documentation navigation

Assisted-by: opencode (gpt-5.6-sol) Signed-off-by: Jan Fajerski <jan--f@users.noreply.github.com>
jan--f · Sep 16, 2026 · Sep 30, 2026 · 15d05a64226c0726a9aecd6b667ddf2f95081739 · lasomethingsomething · Oct 17, 2026
commit 15d05a64226c0726a9aecd6b667ddf2f95081739
diff --git a/docs-routes.ts b/docs-routes.ts
@@ -0,0 +1,178 @@
+export type DocRoute = {
+  slug?: string;
+  navTitle?: string;
+  sortRank?: number;
+  hideInNav?: boolean;
+  redirectTo?: string;
+};
+
+// Routes are keyed by their path relative to the configured documentation root.
+// External routes use :version so the same information architecture applies to
+// both numbered releases and the "latest" alias.
+export const localDocRoutes: Record<string, DocRoute> = {
+  "introduction/index.md": { slug: "get-started", navTitle: "Get Started", sortRank: 1 },
+  "introduction/overview.md": { slug: "get-started/what-is-prometheus", navTitle: "What is Prometheus?", sortRank: 1 },
+  "introduction/first_steps.md": { slug: "get-started/quickstart", navTitle: "Prometheus quickstart", sortRank: 2 },
+  "introduction/comparison.md": { slug: "get-started/comparison", navTitle: "Comparison to alternatives", sortRank: 3 },
+  "introduction/faq.md": { slug: "get-started/faq", navTitle: "Frequently asked questions", sortRank: 4 },
+  "introduction/glossary.md": { slug: "get-started/glossary", sortRank: 5 },
+
+  "concepts/index.md": { slug: "concepts", sortRank: 2 },
+  "concepts/data_model.md": { slug: "concepts/data-model", sortRank: 1 },
+  "concepts/metric_types.md": { slug: "concepts/metric-types", sortRank: 2 },
+  "concepts/jobs_instances.md": { slug: "concepts/jobs-and-instances", sortRank: 3 },
+
+  "prometheus/index.md": { slug: "running-prometheus", navTitle: "Running Prometheus", sortRank: 3 },
+  "querying/index.md": { slug: "querying", sortRank: 4 },
+
+  "instrumenting/index.md": { slug: "instrument-your-code", navTitle: "Instrument Your Code", sortRank: 5 },
+  "instrumenting/clientlibs.md": { slug: "instrument-your-code/client-libraries", sortRank: 1 },
+  "instrumenting/writing_clientlibs.md": { slug: "instrument-your-code/writing-client-libraries", sortRank: 2 },
+  "instrumenting/pushing.md": { slug: "instrument-your-code/pushing-metrics", sortRank: 3 },
+  "instrumenting/exporters.md": { slug: "instrument-your-code/exporters-and-integrations", sortRank: 4 },
+  "instrumenting/writing_exporters.md": { slug: "instrument-your-code/writing-exporters", sortRank: 5 },
+  "instrumenting/exposition_formats.md": { slug: "instrument-your-code/exposition-formats", sortRank: 6 },
+  "guides/utf8.md": { slug: "instrument-your-code/adopt-utf-8", navTitle: "Adopt UTF-8 metric and label names", sortRank: 7 },
+  "instrumenting/escaping_schemes.md": { slug: "instrument-your-code/utf-8-escaping-schemes", sortRank: 8 },
+  "instrumenting/content_negotiation.md": { slug: "instrument-your-code/content-negotiation", sortRank: 9 },
+  "guides/open_metrics_2_0_migration.md": { slug: "instrument-your-code/openmetrics-2-migration", navTitle: "Migrate client libraries to OpenMetrics 2.0", sortRank: 10 },
+
+  "visualization/index.md": { slug: "visualization", sortRank: 6 },
+  "visualization/browser.md": { slug: "visualization/expression-browser", sortRank: 1 },
+  "visualization/grafana.md": { slug: "visualization/grafana", sortRank: 2 },
+  "visualization/perses.md": { slug: "visualization/perses", sortRank: 3 },
+  "visualization/consoles.md": { slug: "visualization/console-templates", sortRank: 4 },
+
+  "operating/index.md": { slug: "operate-in-production", navTitle: "Operate in Production", sortRank: 7 },
+  "operating/security.md": { slug: "operate-in-production/security", sortRank: 1 },
+  "operating/integrations.md": { slug: "operate-in-production/integrations", sortRank: 2 },
+  "guides/basic-auth.md": { slug: "operate-in-production/basic-authentication", sortRank: 3 },
+  "guides/tls-encryption.md": { slug: "operate-in-production/tls-encryption", sortRank: 4 },
+  "practices/remote_write.md": { slug: "operate-in-production/remote-write-tuning", sortRank: 5 },
+  "guides/query-log.md": { slug: "operate-in-production/query-logging", sortRank: 6 },
+  "guides/dockerswarm.md": { slug: "operate-in-production/docker-swarm-service-discovery", sortRank: 7 },
+  "guides/file-sd.md": { slug: "operate-in-production/file-based-service-discovery", sortRank: 8 },
+
+  "alerting/index.md": { slug: "alertmanager", navTitle: "Alertmanager", sortRank: 8 },
+
+  "practices/index.md": { slug: "best-practices", navTitle: "Best Practices", sortRank: 9 },
+  "practices/naming.md": { slug: "best-practices/metric-and-label-naming", sortRank: 1 },
+  "practices/consoles.md": { slug: "best-practices/consoles-and-dashboards", sortRank: 2 },
+  "practices/instrumentation.md": { slug: "best-practices/instrumentation", sortRank: 3 },
+  "practices/histograms.md": { slug: "best-practices/histograms-and-summaries", sortRank: 4 },
+  "practices/alerting.md": { slug: "best-practices/alerting", sortRank: 5 },
+  "practices/rules.md": { slug: "best-practices/recording-rules", sortRank: 6 },
+  "practices/pushing.md": { slug: "best-practices/when-to-use-the-pushgateway", sortRank: 7 },
+  "practices/the_zen.md": { slug: "best-practices/zen", sortRank: 8 },
+
+  "guides/index.md": { slug: "guides", sortRank: 10 },
+  "guides/opentelemetry.md": { slug: "guides/opentelemetry-backend", navTitle: "Use Prometheus as an OpenTelemetry backend", sortRank: 1 },
+  "guides/cadvisor.md": { slug: "guides/cadvisor", navTitle: "Monitor containers with cAdvisor", sortRank: 2 },
+  "guides/node-exporter.md": { slug: "guides/node-exporter", navTitle: "Monitor Linux hosts with Node Exporter", sortRank: 3 },
+  "guides/multi-target-exporter.md": { slug: "guides/multi-target-exporter", navTitle: "Use the multi-target exporter pattern", sortRank: 4 },
+  "tutorials/understanding_metric_types.md": { slug: "guides/understand-metric-types", navTitle: "Understand metric types", sortRank: 5 },
+  "guides/go-application.md": { slug: "guides/go-application", navTitle: "Instrument a Go application", sortRank: 6 },
+  "tutorials/visualizing_metrics_using_grafana.md": { slug: "guides/visualize-metrics-with-grafana", navTitle: "Visualize metrics with Grafana", sortRank: 7 },
+  "tutorials/alerting_based_on_metrics.md": { slug: "guides/alert-based-on-metrics", navTitle: "Alert based on metrics", sortRank: 8 },
+  "tutorials/index.md": { redirectTo: "guides" },
+  "tutorials/getting_started.md": { redirectTo: "get-started/quickstart" },
+  "tutorials/instrumenting_http_server_in_go.md": { redirectTo: "guides/go-application" },
+
+  "specs/index.md": { slug: "specifications", navTitle: "Specifications", sortRank: 11 },
+  "specs/native_histograms.md": { slug: "specifications/native-histograms", sortRank: 1 },
+  "specs/om/index.md": { slug: "specifications/openmetrics", navTitle: "OpenMetrics", sortRank: 2 },
+  "specs/om/open_metrics_spec.md": { slug: "specifications/openmetrics/1.0", navTitle: "1.0", sortRank: 1 },
+  "specs/om/open_metrics_spec_2_0.md": { slug: "specifications/openmetrics/2.0", navTitle: "2.0", sortRank: 2 },
+  "specs/prw/index.md": { slug: "specifications/remote-write", navTitle: "Remote Write", sortRank: 3 },
+  "specs/prw/remote_write_spec.md": { slug: "specifications/remote-write/1.0", navTitle: "1.0", sortRank: 1 },
+  "specs/prw/remote_write_spec_2_0.md": { slug: "specifications/remote-write/2.0", navTitle: "2.0", sortRank: 2 },
+
+  "introduction/roadmap.md": { slug: "about-the-project/roadmap", sortRank: 1 },
+  "introduction/design-doc.md": { slug: "about-the-project/design-documents", sortRank: 2 },
+  "guides/contributing.md": { slug: "about-the-project/contributing", navTitle: "Contributing guide", sortRank: 3 },
+  "introduction/release-cycle.md": { slug: "about-the-project/long-term-support", navTitle: "Long-term support", sortRank: 4 },
+  "introduction/media.md": { slug: "about-the-project/media", sortRank: 5 },
+  "about-the-project/index.md": { slug: "about-the-project", navTitle: "About the Project", sortRank: 12 },
+};
+
+export const githubDocRoutes: Record<string, Record<string, DocRoute>> = {
+  prometheus: {
+    // Preserve release-specific walkthroughs for existing links, but avoid a
+    // second introductory entry in the menu alongside the local quickstart.
+    "getting_started.md": { slug: "running-prometheus/:version/getting-started", sortRank: 10, hideInNav: true },
+    "installation.md": { slug: "running-prometheus/:version/installation", sortRank: 1 },
+    "configuration/index.md": { slug: "running-prometheus/:version/configuration", navTitle: "Configuration reference", sortRank: 2 },
+    "configuration/configuration.md": { slug: "running-prometheus/:version/configuration/reference", navTitle: "Configuration", sortRank: 1 },
+    "configuration/recording_rules.md": { slug: "running-prometheus/:version/configuration/recording-rules", sortRank: 2 },
+    "configuration/alerting_rules.md": { slug: "running-prometheus/:version/configuration/alerting-rules", sortRank: 3 },
+    "configuration/template_examples.md": { slug: "running-prometheus/:version/configuration/template-examples", sortRank: 4 },
+    "configuration/template_reference.md": { slug: "running-prometheus/:version/configuration/template-reference", sortRank: 5 },
+    "configuration/unit_testing_rules.md": { slug: "running-prometheus/:version/configuration/unit-testing-rules", sortRank: 6 },
+    "configuration/promtool.md": { slug: "running-prometheus/:version/configuration/promtool-http", navTitle: "HTTP configuration for promtool", sortRank: 7 },
+    "http_sd.md": { slug: "running-prometheus/:version/configuration/http-service-discovery", navTitle: "HTTP service discovery endpoint", sortRank: 8 },
+    "configuration/https.md": { slug: "running-prometheus/:version/configuration/https-authentication", navTitle: "HTTPS and authentication", sortRank: 9 },
+    "prometheus_agent.md": { slug: "running-prometheus/:version/agent-mode", navTitle: "Agent mode", sortRank: 3 },
+    "storage.md": { slug: "running-prometheus/:version/storage", sortRank: 4 },
+    "federation.md": { slug: "running-prometheus/:version/federation", sortRank: 5 },
+    "migration.md": { slug: "running-prometheus/:version/migration", sortRank: 6 },
+    "feature_flags.md": { slug: "running-prometheus/:version/feature-flags", sortRank: 7 },
+    "command-line/index.md": { slug: "running-prometheus/:version/command-line", sortRank: 8 },
+    "command-line/prometheus.md": { slug: "running-prometheus/:version/command-line/prometheus", navTitle: "Prometheus", sortRank: 1 },
+    "command-line/promtool.md": { slug: "running-prometheus/:version/command-line/promtool", sortRank: 2 },
+    "stability.md": { slug: "running-prometheus/:version/api-stability", navTitle: "API stability", sortRank: 9 },
+
+    "querying/index.md": { redirectTo: "querying" },
+    "querying/basics.md": { slug: "querying/:version/basics", sortRank: 1 },
+    "querying/operators.md": { slug: "querying/:version/operators", sortRank: 2 },
+    "querying/functions.md": { slug: "querying/:version/functions", sortRank: 3 },
+    "querying/examples.md": { slug: "querying/:version/examples", sortRank: 4 },
+    "querying/api.md": { slug: "querying/:version/http-api", navTitle: "HTTP API", sortRank: 5 },
+    "querying/remote_read_api.md": { slug: "querying/:version/remote-read-api", sortRank: 6 },
+
+    "management_api.md": { slug: "operate-in-production/:version/management-api", sortRank: 10 },
+  },
+  alertmanager: {
+    "overview.md": { slug: "alertmanager/:version/overview", navTitle: "Alerting overview", sortRank: 1 },
+    "alertmanager.md": { slug: "alertmanager/:version/alertmanager", sortRank: 2 },
+    "configuration.md": { slug: "alertmanager/:version/configuration", sortRank: 3 },
+    "integrations.md": { slug: "alertmanager/:version/notification-integrations", sortRank: 4 },
+    "clients.md": { slug: "alertmanager/:version/notification-integrations", sortRank: 4 },
+    "notifications.md": { slug: "alertmanager/:version/notification-template-reference", sortRank: 5 },
+    "notification_examples.md": { slug: "alertmanager/:version/notification-template-examples", sortRank: 6 },
+    "alerts_api.md": { slug: "alertmanager/:version/alerts-api", sortRank: 7 },
+    "management_api.md": { slug: "alertmanager/:version/management-api", sortRank: 8 },
+    "high_availability.md": { slug: "alertmanager/:version/high-availability", sortRank: 9 },
+    "https.md": { slug: "alertmanager/:version/https-authentication", navTitle: "HTTPS and authentication", sortRank: 10 },
+  },
+};
+
+export function materializeRoute(route: DocRoute, version?: string): string | undefined {
+  return route.slug?.replace(":version", version ?? "");
+}
+
+export function canonicalizeDocPath(url: string): string {
+  const match = url.match(/^([^?#]*)(.*)$/);
+  const pathname = match?.[1] ?? url;
+  const suffix = match?.[2] ?? "";
+  const oldSlug = pathname.replace(/^\/docs\//, "").replace(/\/$/, "");
+  const external = oldSlug.match(/^(prometheus|alerting)\/([^/]+)\/(.+)$/);
+
+  let route: DocRoute | undefined;
+  let version: string | undefined;
+  if (external) {
+    const [, oldPrefix, routeVersion, sourceSlug] = external;
+    const repo = oldPrefix === "alerting" ? "alertmanager" : "prometheus";
+    route =
+      githubDocRoutes[repo]?.[`${sourceSlug}.md`] ??
+      githubDocRoutes[repo]?.[`${sourceSlug}/index.md`];
+    version = routeVersion;
+  } else {
+    route =
+      localDocRoutes[`${oldSlug}.md`] ??
+      localDocRoutes[`${oldSlug}/index.md`];
+  }
+
+  const canonicalSlug =
+    route?.redirectTo ?? (route && materializeRoute(route, version));
+  return canonicalSlug ? `/docs/${canonicalSlug}/${suffix}` : url;
+}
diff --git a/docs/about-the-project/index.md b/docs/about-the-project/index.md
@@ -0,0 +1,7 @@
+---
+title: About the Project
+sort_rank: 12
+nav_icon: file-description
+---
+
+Learn about the Prometheus project's direction, governance, and community.
diff --git a/docs/introduction/first_steps.md b/docs/introduction/first_steps.md
@@ -4,7 +4,7 @@ nav_title: First steps
 sort_rank: 3
 ---
 
-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.
+Welcome to Prometheus! Prometheus is a monitoring platform that collects metrics from monitored targets by scraping metrics HTTP endpoints on these targets. This quickstart shows how to install and run Prometheus, have it scrape its own metrics, and query the results. For a longer walkthrough of server features, see the [version-specific Getting started guide](/docs/running-prometheus/latest/getting-started/).
 
 ## Downloading Prometheus
 

diff --git a/docs/querying/index.md b/docs/querying/index.md
@@ -0,0 +1,8 @@
+---
+title: Querying
+sort_rank: 4
+nav_icon: chart-line
+---
+
+Prometheus provides a functional query language called PromQL for selecting and
+aggregating time series data in real time.
diff --git a/docs/tutorials/alerting_based_on_metrics.md b/docs/tutorials/alerting_based_on_metrics.md
@@ -3,10 +3,10 @@ title: Alerting based on metrics
 sort_rank: 5
 ---
 
-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.md) tutorial.
+In this tutorial we will create alerts on the `myapp_processed_ops_total` metric from the
+[Instrument a Go application](../guides/go-application.md) tutorial. Run that application on `localhost:2112` before continuing.
 
-For the sake of this tutorial we will alert when the `ping_request_count` metric is greater than 5. Check out real world [best practices](../practices/alerting.md) to learn more about alerting principles.
+For the sake of this tutorial we will alert when the `myapp_processed_ops_total` metric is greater than 5. Check out real world [best practices](../practices/alerting.md) to learn more about alerting principles.
 
 Download the latest release of Alertmanager for your operating system from [here](https://github.com/prometheus/alertmanager/releases).
 
@@ -41,44 +41,41 @@ Now that we have configured the Alertmanager with webhook receiver let's add the
 
 ```yaml
 global:
- scrape_interval: 15s
- evaluation_interval: 10s
+  scrape_interval: 15s
+  evaluation_interval: 10s
 rule_files:
   - rules.yml
 alerting:
   alertmanagers:
-  - static_configs:
-    - targets:
-       - localhost:9093
+    - static_configs:
+        - targets: ["localhost:9093"]
 scrape_configs:
- - job_name: prometheus
-   static_configs:
-       - targets: ["localhost:9090"]
- - job_name: simple_server
-   static_configs:
-       - targets: ["localhost:8090"]
+  - job_name: prometheus
+    static_configs:
+      - targets: ["localhost:9090"]
+  - job_name: myapp
+    static_configs:
+      - targets: ["localhost:2112"]
 ```
 
 Note that the `evaluation_interval`,`rule_files` and `alerting` sections were added to the Prometheus config. `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.
+raise an alert when the `myapp_processed_ops_total` value is greater than 5.
 
 > rules.yml
 
 ```yaml
 groups:
- - name: Count greater than 5
-   rules:
-   - alert: CountGreaterThan5
-     expr: ping_request_count > 5
-     for: 10s
+  - name: Count greater than 5
+    rules:
+      - alert: CountGreaterThan5
+        expr: myapp_processed_ops_total > 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 at least 6 times. You can check the ping count by navigating to the [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.
+Open [http://localhost:9090/rules](http://localhost:9090/rules) in your browser to see the rules. The Go application's counter increases automatically every two seconds; you can check its value at [http://localhost:2112/metrics](http://localhost:2112/metrics). To see the status of the alert visit [http://localhost:9090/alerts](http://localhost:9090/alerts). Once Prometheus has scraped a value of `myapp_processed_ops_total` greater than 5 for more than 10 seconds, 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.
+Similarly Alertmanager can be configured with other receivers to notify when an alert is firing.