Standardize doc page title handling

See https://groups.google.com/g/prometheus-developers/c/cwL3cM66Em8

Signed-off-by: Julius Volz <julius.volz@gmail.com>

docs/command-line/prometheus.md

@@ -2,12 +2,9 @@
 title: prometheus
 ---
 
-# prometheus
-
 The Prometheus monitoring server
 
 
-
 ## Flags
 
 | Flag | Description | Default |

docs/command-line/promtool.md

@@ -2,12 +2,9 @@
 title: promtool
 ---
 
-# promtool
-
 Tooling for the Prometheus monitoring system.
 
 
-
 ## Flags
 
 | Flag | Description |

docs/configuration/alerting_rules.md

@@ -3,8 +3,6 @@ title: Alerting rules
 sort_rank: 3
 ---
 
-# Alerting rules
-
 Alerting rules allow you to define alert conditions based on Prometheus
 expression language expressions and to send notifications about firing alerts
 to an external service. Whenever the alert expression results in one or more

docs/configuration/configuration.md

@@ -3,8 +3,6 @@ title: Configuration
 sort_rank: 1
 ---
 
-# Configuration
-
 Prometheus is configured via command-line flags and a configuration file. While
 the command-line flags configure immutable system parameters (such as storage
 locations, amount of data to keep on disk and in memory, etc.), the

docs/configuration/https.md

@@ -3,8 +3,6 @@ title: HTTPS and authentication
 sort_rank: 7
 ---
 
-# HTTPS and authentication
-
 Prometheus supports basic authentication and TLS.
 This is **experimental** and might change in the future.
 

docs/configuration/recording_rules.md

@@ -1,10 +1,9 @@
 ---
-title: Recording rules
+title: Defining recording rules
+nav_title: Recording rules
 sort_rank: 2
 ---
 
-# Defining recording rules
-
 ## Configuring rules
 
 Prometheus supports two types of rules which may be configured and then

docs/configuration/template_examples.md

@@ -3,8 +3,6 @@ title: Template examples
 sort_rank: 4
 ---
 
-# Template examples
-
 Prometheus supports templating in the annotations and labels of alerts,
 as well as in served console pages. Templates have the ability to run
 queries against the local database, iterate over data, use conditionals,

docs/configuration/template_reference.md

@@ -3,8 +3,6 @@ title: Template reference
 sort_rank: 5
 ---
 
-# Template reference
-
 Prometheus supports templating in the annotations and labels of alerts,
 as well as in served console pages. Templates have the ability to run
 queries against the local database, iterate over data, use conditionals,

docs/configuration/unit_testing_rules.md

@@ -1,10 +1,8 @@
 ---
-title: Unit Testing for Rules
+title: Unit testing for rules
 sort_rank: 6
 ---
 
-# Unit Testing for Rules
-
 You can use `promtool` to test your rules.
 
 ```shell

docs/feature_flags.md

@@ -3,8 +3,6 @@ title: Feature flags
 sort_rank: 12
 ---
 
-# Feature flags
-
 Here is a list of features that are disabled by default since they are breaking changes or are considered experimental.
 Their behaviour can change in future releases which will be communicated via the [release changelog](https://github.com/prometheus/prometheus/blob/main/CHANGELOG.md).
 

docs/federation.md

@@ -3,8 +3,6 @@ title: Federation
 sort_rank: 6
 ---
 
-# Federation
-
 Federation allows a Prometheus server to scrape selected time series from
 another Prometheus server.
 

docs/getting_started.md

@@ -3,8 +3,6 @@ title: Getting started
 sort_rank: 1
 ---
 
-# Getting started
-
 This guide is a "Hello World"-style tutorial which shows how to install,
 configure, and use a simple Prometheus instance. You will download and run
 Prometheus locally, configure it to scrape itself and an example application,

docs/http_sd.md

@@ -1,10 +1,9 @@
 ---
-title: HTTP SD
+title: Writing HTTP service discovery
+nav_title: HTTP SD
 sort_rank: 7
 ---
 
-# Writing HTTP Service Discovery
-
 Prometheus provides a generic [HTTP Service Discovery](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#http_sd_config),
 that enables it to discover targets over an HTTP endpoint.
 
@@ -40,7 +39,7 @@ an empty list `[]`. Target lists are unordered.
 
 Prometheus caches target lists. If an error occurs while fetching an updated
 targets list, Prometheus keeps using the current targets list. The targets list
-is not saved across restart. The `prometheus_sd_http_failures_total` counter 
+is not saved across restart. The `prometheus_sd_http_failures_total` counter
 metric tracks the number of refresh failures.
 
 The whole list of targets must be returned on every scrape. There is no support

docs/installation.md

@@ -3,8 +3,6 @@ title: Installation
 sort_rank: 2
 ---
 
-# Installation
-
 ## Using pre-compiled binaries
 
 We provide precompiled binaries for most official Prometheus components. Check

docs/management_api.md

@@ -3,12 +3,10 @@ title: Management API
 sort_rank: 8
 ---
 
-# Management API
-
 Prometheus provides a set of management APIs to facilitate automation and integration.
 
 
-### Health check
+## Health check
 
 ```
 GET /-/healthy
@@ -18,7 +16,7 @@ HEAD /-/healthy
 This endpoint always returns 200 and should be used to check Prometheus health.
 
 
-### Readiness check
+## Readiness check
 
 ```
 GET /-/ready
@@ -28,7 +26,7 @@ HEAD /-/ready
 This endpoint returns 200 when Prometheus is ready to serve traffic (i.e. respond to queries).
 
 
-### Reload
+## Reload
 
 ```
 PUT  /-/reload
@@ -40,7 +38,7 @@ This endpoint triggers a reload of the Prometheus configuration and rule files.
 Alternatively, a configuration reload can be triggered by sending a `SIGHUP` to the Prometheus process.
 
 
-### Quit
+## Quit
 
 ```
 PUT  /-/quit

docs/migration.md

@@ -1,10 +1,9 @@
 ---
-title: Migration
+title: Prometheus 3.0 migration guide
+nav_title: Migration
 sort_rank: 10
 ---
 
-# Prometheus 3.0 migration guide
-
 In line with our [stability promise](https://prometheus.io/docs/prometheus/latest/stability/),
 the Prometheus 3.0 release contains a number of backwards incompatible changes.
 This document offers guidance on migrating from Prometheus 2.x to Prometheus 3.0 and newer versions.

docs/querying/api.md

@@ -3,8 +3,6 @@ title: HTTP API
 sort_rank: 7
 ---
 
-# HTTP API
-
 The current stable HTTP API is reachable under `/api/v1` on a Prometheus
 server. Any non-breaking additions will be added under that endpoint.
 

docs/querying/basics.md

@@ -4,11 +4,9 @@ nav_title: Basics
 sort_rank: 1
 ---
 
-# Querying Prometheus
-
 Prometheus provides a functional query language called PromQL (Prometheus Query
 Language) that lets the user select and aggregate time series data in real
-time. 
+time.
 
 When you send a query request to Prometheus, it can be an _instant query_, evaluated at one point in time,
 or a _range query_ at equally-spaced steps between a start and an end time. PromQL works exactly the same
@@ -35,7 +33,7 @@ evaluate to one of four types:
 
 Depending on the use-case (e.g. when graphing vs. displaying the output of an
 expression), only some of these types are legal as the result of a
-user-specified expression. 
+user-specified expression.
 For [instant queries](api.md#instant-queries), any of the above data types are allowed as the root of the expression.
 [Range queries](api.md#range-queries) only support scalar-typed and instant-vector-typed expressions.
 
@@ -217,7 +215,7 @@ and would exclude:
 
     http_requests_total{environment="development"}
 
-Multiple matchers can be used for the same label name; they all must pass for a result to be returned. 
+Multiple matchers can be used for the same label name; they all must pass for a result to be returned.
 
 The query:
 
@@ -307,7 +305,7 @@ Note that this allows a query to look ahead of its evaluation time.
 
 The `@` modifier allows changing the evaluation time for individual instant
 and range vectors in a query. The time supplied to the `@` modifier
-is a unix timestamp and described with a float literal. 
+is a unix timestamp and described with a float literal.
 
 For example, the following expression returns the value of
 `http_requests_total` at `2021-01-04T07:40:00+00:00`:
@@ -403,11 +401,11 @@ as stale, then no value is returned for that time series. If new samples are
 subsequently ingested for that time series, they will be returned as expected.
 
 A time series will go stale when it is no longer exported, or the target no
-longer exists. Such time series will disappear from graphs 
+longer exists. Such time series will disappear from graphs
 at the times of their latest collected sample, and they will not be returned
 in queries after they are marked stale.
 
-Some exporters, which put their own timestamps on samples, get a different behaviour: 
+Some exporters, which put their own timestamps on samples, get a different behaviour:
 series that stop being exported take the last value for (by default) 5 minutes before
 disappearing. The `track_timestamps_staleness` setting can change this.
 

docs/querying/examples.md

@@ -1,11 +1,9 @@
 ---
-title: Querying examples
+title: Query examples
 nav_title: Examples
 sort_rank: 4
 ---
 
-# Query examples
-
 ## Simple time series selection
 
 Return all time series with the metric `http_requests_total`:

docs/querying/functions.md

@@ -4,8 +4,6 @@ nav_title: Functions
 sort_rank: 3
 ---
 
-# Functions
-
 Some functions have default arguments, e.g. `year(v=vector(time())
 instant-vector)`. This means that there is one argument `v` which is an instant
 vector, which if not provided it will default to the value of the expression
@@ -121,7 +119,7 @@ of the week (in UTC) for each of those timestamps. Returned values are from 0
 to 6, where 0 means Sunday etc. Histogram samples in the input vector are
 ignored silently.
 
-## `day_of_year()` 
+## `day_of_year()`
 
 `day_of_year(v=vector(time()) instant-vector)` interpretes float samples in `v`
 as timestamps (number of seconds since January 1, 1970 UTC) and returns the day
@@ -255,9 +253,9 @@ histogram samples:
 
 `histogram_fraction(lower scalar, upper scalar, b instant-vector)` returns the
 estimated fraction of observations between the provided lower and upper values
-for each classic or native histogram contained in `b`. Float samples in `b` are 
+for each classic or native histogram contained in `b`. Float samples in `b` are
 considered the counts of observations in each bucket of one or more classic
-histograms, while native histogram samples in `b` are treated each individually 
+histograms, while native histogram samples in `b` are treated each individually
 as a separate histogram. This works in the same way as for `histogram_quantile()`.
 (See there for more details.)
 
@@ -273,7 +271,7 @@ as a typical example.
 
 For example, the following expression calculates the fraction of HTTP requests
 over the last hour that took 200ms or less:
-    
+
     histogram_fraction(0, 0.2, rate(http_request_duration_seconds[1h]))
 
 The error of the estimation depends on the resolution of the underlying native
@@ -345,7 +343,7 @@ included in the `by` clause. The following expression aggregates the 90th
 percentile by `job` for classic histograms:
 
     histogram_quantile(0.9, sum by (job, le) (rate(http_request_duration_seconds_bucket[10m])))
-	
+
 When aggregating native histograms, the expression simplifies to:
 
     histogram_quantile(0.9, sum by (job) (rate(http_request_duration_seconds[10m])))
@@ -429,7 +427,7 @@ annotation, you should find and remove the source of the invalid data.
 
 `histogram_stddev(v instant-vector)` returns the estimated standard deviation
 of observations for each histogram sample in `v`. For this estimation, all observations
-in a bucket are assumed to have the value of the mean of the bucket boundaries. For 
+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 the usual exponential buckets, the geometric mean is used. Float samples are ignored
 and do not show up in the returned vector.
@@ -489,10 +487,10 @@ consistently on a per-second basis.
 _The `info` function is an experiment to improve UX
 around including labels from [info metrics](https://grafana.com/blog/2021/08/04/how-to-use-promql-joins-for-more-effective-queries-of-prometheus-metrics-at-scale/#info-metrics).
 The behavior of this function may change in future versions of Prometheus,
-including its removal from PromQL. `info` has to be enabled via the 
+including its removal from PromQL. `info` has to be enabled via the
 [feature flag](../feature_flags.md#experimental-promql-functions) `--enable-feature=promql-experimental-functions`._
 
-`info(v instant-vector, [data-label-selector instant-vector])` finds, for each time 
+`info(v instant-vector, [data-label-selector instant-vector])` finds, for each time
 series in `v`, all info series with matching _identifying_ labels (more on
 this later), and adds the union of their _data_ (i.e., non-identifying) labels
 to the time series. The second argument `data-label-selector` is optional.
@@ -509,8 +507,8 @@ function, we “logically” define info series identity in a different way than
 in the conventional Prometheus view.) The identifying labels of an info series
 are used to join it to regular (non-info) series, i.e. those series that have
 the same labels as the identifying labels of the info series. The data labels, which are
-the ones added to the regular series by the `info` function, effectively encode 
+the ones added to the regular series by the `info` function, effectively encode
-metadata key value pairs. (This implies that a change in the data labels 
+metadata key value pairs. (This implies that a change in the data labels
 in the conventional Prometheus view constitutes the end of one info series and
 the beginning of a new info series, while the “logical” view of the `info` function is
 that the same info series continues to exist, just with different “data”.)
@@ -534,7 +532,7 @@ This query is not only verbose and hard to write, it might also run into an “i
 If any of the data labels of `target_info` changes, Prometheus sees that as a change of series
 (as alluded to above, Prometheus just has no native concept of non-identifying labels).
 If the old `target_info` series is not properly marked as stale (which can happen with certain ingestion paths),
-the query above will fail for up to 5m (the lookback delta) because it will find a conflicting 
+the query above will fail for up to 5m (the lookback delta) because it will find a conflicting
 match with both the old and the new version of `target_info`.
 
 The `info` function not only resolves this conflict in favor of the newer series, it also simplifies the syntax
@@ -565,7 +563,7 @@ restrict them by providing a `__name__` label matcher, e.g.
 In its current iteration, `info` defaults to considering only info series with
 the name `target_info`. It also assumes that the identifying info series labels are
 `instance` and `job`. `info` does support other info series names however, through
-`__name__` label matchers. E.g., one can explicitly say to consider both 
+`__name__` label matchers. E.g., one can explicitly say to consider both
 `target_info` and `build_info` as follows:
 `{__name__=~"(target|build)_info"}`. However, the identifying labels always
 have to be `instance` and `job`.

docs/querying/operators.md

@@ -3,8 +3,6 @@ title: Operators
 sort_rank: 2
 ---
 
-# Operators
-
 ## Binary operators
 
 Prometheus's query language supports basic logical and arithmetic operators.
@@ -319,7 +317,7 @@ the input samples, including the original labels, are returned in the result
 vector. `by` and `without` are only used to bucket the input vector. Similar to
 `min` and `max`, they only operate on float samples, considering `NaN` values
 to be farthest from the top or bottom, respectively. Histogram samples in the
-input vector are ignored, flagged by an info-level annotation. 
+input vector are ignored, flagged by an info-level annotation.
 
 If used in an instant query, `topk` and `bottomk` return series ordered by
 value in descending or ascending order, respectively. If used with `by` or

docs/querying/remote_read_api.md

@@ -3,9 +3,7 @@ title: Remote Read API
 sort_rank: 7
 ---
 
-# Remote Read API
+NOTE: This is not currently considered part of the stable API and is subject to change even between non-major version releases of Prometheus.
-
-> This is not currently considered part of the stable API and is subject to change even between non-major version releases of Prometheus.
 
 This API provides data read functionality from Prometheus. This interface expects [snappy](https://github.com/google/snappy) compression.
 The API definition is located [here](https://github.com/prometheus/prometheus/blob/master/prompb/remote.proto).
@@ -15,12 +13,12 @@ Request are made to the following endpoint.
 /api/v1/read
 ```
 
-### Samples
+## Samples
 
-This returns a message that includes a list of raw samples matching the 
+This returns a message that includes a list of raw samples matching the
 requested query.
 
-### Streamed Chunks
+## Streamed Chunks
 
 These streamed chunks utilize an XOR algorithm inspired by the [Gorilla](http://www.vldb.org/pvldb/vol8/p1816-teller.pdf)
 compression to encode the chunks. However, it provides resolution to the millisecond instead of to the second.

docs/stability.md

@@ -1,10 +1,9 @@
 ---
-title: API Stability
+title: API stability guarantees
+nav_title: API stability
 sort_rank: 11
 ---
 
-# API Stability Guarantees
-
 Prometheus promises API stability within a major version, and strives to avoid
 breaking changes for key features. Some features, which are cosmetic, still
 under development, or depend on 3rd party services, are not covered by this.

docs/storage.md

@@ -3,8 +3,6 @@ title: Storage
 sort_rank: 5
 ---
 
-# Storage
-
 Prometheus includes a local on-disk time series database, but also optionally integrates with remote storage systems.
 
 ## Local storage

util/documentcli/documentcli.go

@@ -58,11 +58,8 @@ func header(title, help string) []byte {
 title: %s
 ---
 
-# %s
-
 %s
-
+`, title, help))
-`, title, title, help))
 }
 
 func createFlagRow(flag *kingpin.FlagModel) []string {