docs: update docs ordering and formatting (#1192)

The major change is adding `sort` directive to docs. For those docs which are copied from internal packages `sort` is added via makefile command. For the rest it is added manually since they're updated manually as well. The rest of changes is connected with markdown formatting. For example, changing headers in some files (`##` => `#`) makes navigation on .github.io to look better. This especially useful for `changelog` docs. Table of contents for `vmctl` is dropped, since we already have it autogenerated on .github.io. No link changes expected. The corresponding PR to `cluster` branch will be made in follow-up PR.
2024-11-21 14:44:00 +00:00 · 2021-04-07 11:39:16 +01:00 · 2021-04-07 11:39:16 +01:00 · c6a8ebb11f
commit c6a8ebb11f
parent df32d2836c
28 changed files with 196 additions and 164 deletions
--- a/25
+++ b/25
@ -262,12 +262,21 @@ golangci-lint: install-golangci-lint
 install-golangci-lint:
 	which golangci-lint || curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(shell go env GOPATH)/bin v1.29.0

+copy-docs:
+	echo "---\nsort: ${ORDER}\n---\n" > ${DST}
+	cat ${SRC} >> ${DST}
+
+# Copies docs for all components and adds the order tag.
+# Cluster docs are supposed to be ordered as 9th.
+# For The rest of docs is ordered manually.t
 docs-sync:
-	cp app/vmagent/README.md docs/vmagent.md
-	cp app/vmalert/README.md docs/vmalert.md
-	cp app/vmauth/README.md docs/vmauth.md
-	cp app/vmbackup/README.md docs/vmbackup.md
-	cp app/vmrestore/README.md docs/vmrestore.md
-	cp app/vmctl/README.md docs/vmctl.md
-	cp app/vmgateway/README.md docs/vmgateway.md
-	cp README.md docs/Single-server-VictoriaMetrics.md
+	SRC=README.md DST=docs/Single-server-VictoriaMetrics.md ORDER=1 $(MAKE) copy-docs
+	SRC=app/vmagent/README.md DST=docs/vmagent.md ORDER=2 $(MAKE) copy-docs
+	SRC=app/vmalert/README.md DST=docs/vmalert.md ORDER=3 $(MAKE) copy-docs
+	SRC=app/vmauth/README.md DST=docs/vmauth.md ORDER=4 $(MAKE) copy-docs
+	SRC=app/vmbackup/README.md DST=docs/vmbackup.md ORDER=5 $(MAKE) copy-docs
+	SRC=app/vmrestore/README.md DST=docs/vmrestore.md ORDER=6 $(MAKE) copy-docs
+	SRC=app/vmctl/README.md DST=docs/vmctl.md ORDER=7 $(MAKE) copy-docs
+	SRC=app/vmgateway/README.md DST=docs/vmgateway.md ORDER=8 $(MAKE) copy-docs
+
+
--- a/README.md
+++ b/README.md
@ -1,3 +1,5 @@
+# VictoriaMetrics
+
 [![Latest Release](https://img.shields.io/github/release/VictoriaMetrics/VictoriaMetrics.svg?style=flat-square)](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/latest)
 [![Docker Pulls](https://img.shields.io/docker/pulls/victoriametrics/victoria-metrics.svg?maxAge=604800)](https://hub.docker.com/r/victoriametrics/victoria-metrics)
 [![Slack](https://img.shields.io/badge/join%20slack-%23victoriametrics-brightgreen.svg)](http://slack.victoriametrics.com/)
@ -6,9 +8,7 @@
 [![Build Status](https://github.com/VictoriaMetrics/VictoriaMetrics/workflows/main/badge.svg)](https://github.com/VictoriaMetrics/VictoriaMetrics/actions)
 [![codecov](https://codecov.io/gh/VictoriaMetrics/VictoriaMetrics/branch/master/graph/badge.svg)](https://codecov.io/gh/VictoriaMetrics/VictoriaMetrics)

-![Victoria Metrics logo](logo.png "Victoria Metrics")
-
-## VictoriaMetrics
+<img src="logo.png" width="300" alt="Victoria Metrics logo">

 VictoriaMetrics is a fast, cost-effective and scalable monitoring solution and time series database.

--- a/app/vmagent/README.md
+++ b/app/vmagent/README.md
@ -1,4 +1,4 @@
-## vmagent
+# vmagent

 `vmagent` is a tiny but mighty agent which helps you collect metrics from various sources
 and store them in [VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics)
--- a/app/vmalert/README.md
+++ b/app/vmalert/README.md
@ -1,10 +1,10 @@
-## vmalert
+# vmalert

 `vmalert` executes a list of given [alerting](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/)
 or [recording](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/)
 rules against configured address.

-### Features:
+## Features
 * Integration with [VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics) TSDB;
 * VictoriaMetrics [MetricsQL](https://victoriametrics.github.io/MetricsQL.html)
 support and expressions validation;
@ -15,7 +15,7 @@ rules against configured address.
 * Graphite datasource can be used for alerting and recording rules. See [these docs](#graphite) for details.
 * Lightweight without extra dependencies.

-### Limitations:
+## Limitations
 * `vmalert` execute queries against remote datasource which has reliability risks because of network.
 It is recommended to configure alerts thresholds and rules expressions with understanding that network request
 may fail;
@ -24,7 +24,7 @@ storage is asynchronous. Hence, user shouldn't rely on recording rules chaining
 recording rule is reused in next one;
 * `vmalert` has no UI, just an API for getting groups and rules statuses.

-### QuickStart
+## QuickStart

 To build `vmalert` from sources:
 ```
@ -67,7 +67,7 @@ groups:
  [ - <rule_group> ]
 ```

-#### Groups
+### Groups

 Each group has following attributes:
 ```yaml
@ -89,7 +89,7 @@ rules:
  [ - <rule> ... ]
 ```

-#### Rules
+### Rules

 There are two types of Rules:
 * [alerting](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/) -
@ -102,7 +102,7 @@ and save their result as a new set of time series.
 `vmalert` forbids to define duplicates - rules with the same combination of name, expression and labels
 within one group.

-##### Alerting rules
+#### Alerting rules

 The syntax for alerting rule is following:
 ```yaml
@ -131,7 +131,7 @@ annotations:
  [ <labelname>: <tmpl_string> ]
 ```

-##### Recording rules
+#### Recording rules

 The syntax for recording rules is following:
 ```yaml
@ -155,7 +155,7 @@ labels:
 For recording rules to work `-remoteWrite.url` must specified.


-#### Alerts state on restarts
+### Alerts state on restarts

 `vmalert` has no local storage, so alerts state is stored in the process memory. Hence, after reloading of `vmalert`
 the process alerts state will be lost. To avoid this situation, `vmalert` should be configured via the following flags:
@ -171,7 +171,7 @@ in configured `-remoteRead.url`, weren't updated in the last `1h` or received st
 rules configuration.


-#### WEB
+### WEB

 `vmalert` runs a web-server (`-httpListenAddr`) for serving metrics and alerts endpoints:
 * `http://<vmalert-addr>/api/v1/groups` - list of all loaded groups and rules;
@ -182,7 +182,7 @@ Used as alert source in AlertManager.
 * `http://<vmalert-addr>/-/reload` - hot configuration reload.


-### Graphite
+## Graphite

 vmalert sends requests to `<-datasource.url>/render?format=json` during evaluation of alerting and recording rules
 if the corresponding group or rule contains `type: "graphite"` config option. It is expected that the `<-datasource.url>/render`
@ -191,7 +191,7 @@ When using vmalert with both `graphite` and `prometheus` rules configured agains
 to set `-datasource.appendTypePrefix` flag to `true`, so vmalert can adjust URL prefix automatically based on query type.


-### Configuration
+## Configuration

 The shortlist of configuration flags is the following:
 ```
@ -375,43 +375,43 @@ command-line flags with their descriptions.
 To reload configuration without `vmalert` restart send SIGHUP signal
 or send GET request to `/-/reload` endpoint.

-### Contributing
+## Contributing

 `vmalert` is mostly designed and built by VictoriaMetrics community.
 Feel free to share your experience and ideas for improving this
 software. Please keep simplicity as the main priority.

-### How to build from sources
+## How to build from sources

 It is recommended using
 [binary releases](https://github.com/VictoriaMetrics/VictoriaMetrics/releases)
 - `vmalert` is located in `vmutils-*` archives there.


-#### Development build
+### Development build

 1. [Install Go](https://golang.org/doc/install). The minimum supported version is Go 1.15.
 2. Run `make vmalert` from the root folder of [the repository](https://github.com/VictoriaMetrics/VictoriaMetrics).
   It builds `vmalert` binary and puts it into the `bin` folder.

-#### Production build
+### Production build

 1. [Install docker](https://docs.docker.com/install/).
 2. Run `make vmalert-prod` from the root folder of [the repository](https://github.com/VictoriaMetrics/VictoriaMetrics).
   It builds `vmalert-prod` binary and puts it into the `bin` folder.


-#### ARM build
+### ARM build

 ARM build may run on Raspberry Pi or on [energy-efficient ARM servers](https://blog.cloudflare.com/arm-takes-wing/).

-#### Development ARM build
+### Development ARM build

 1. [Install Go](https://golang.org/doc/install). The minimum supported version is Go 1.15.
 2. Run `make vmalert-arm` or `make vmalert-arm64` from the root folder of [the repository](https://github.com/VictoriaMetrics/VictoriaMetrics).
   It builds `vmalert-arm` or `vmalert-arm64` binary respectively and puts it into the `bin` folder.

-#### Production ARM build
+### Production ARM build

 1. [Install docker](https://docs.docker.com/install/).
 2. Run `make vmalert-arm-prod` or `make vmalert-arm64-prod` from the root folder of [the repository](https://github.com/VictoriaMetrics/VictoriaMetrics).
--- a/app/vmauth/README.md
+++ b/app/vmauth/README.md
@ -1,4 +1,4 @@
-## vmauth
+# vmauth

 `vmauth` is a simple auth proxy and router for [VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics).
 It reads username and password from [Basic Auth headers](https://en.wikipedia.org/wiki/Basic_access_authentication),
--- a/app/vmbackup/README.md
+++ b/app/vmbackup/README.md
@ -1,4 +1,4 @@
-## vmbackup
+# vmbackup

 `vmbackup` creates VictoriaMetrics data backups from [instant snapshots](https://victoriametrics.github.io/Single-server-VictoriaMetrics.html#how-to-work-with-snapshots).

--- a/app/vmctl/README.md
+++ b/app/vmctl/README.md
@ -9,33 +9,6 @@ Features:
 - [x] InfluxDB: migrate data from InfluxDB to VictoriaMetrics
 - [ ] Storage Management: data re-balancing between nodes 

-# Table of contents
-
-* [Articles](#articles)
-* [How to build](#how-to-build)
-* [Migrating data from InfluxDB 1.x](#migrating-data-from-influxdb-1x)
-   * [Data mapping](#data-mapping)
-   * [Configuration](#configuration)
-   * [Filtering](#filtering)
-* [Migrating data from InfluxDB 2.x](#migrating-data-from-influxdb-2x)  
-* [Migrating data from Prometheus](#migrating-data-from-prometheus)
-   * [Data mapping](#data-mapping-1)
-   * [Configuration](#configuration-1)
-   * [Filtering](#filtering-1)
-* [Migrating data from Thanos](#migrating-data-from-thanos)
-   * [Current data](#current-data)
-   * [Historical data](#historical-data)
-* [Migrating data from VictoriaMetrics](#migrating-data-from-victoriametrics)
-   * [Native protocol](#native-protocol)
-* [Tuning](#tuning)
-   * [Influx mode](#influx-mode)
-   * [Prometheus mode](#prometheus-mode)
-   * [VictoriaMetrics importer](#victoriametrics-importer)
-   * [Importer stats](#importer-stats)
-* [Significant figures](#significant-figures)
-* [Adding extra labels](#adding-extra-labels)
-
-
 ## Articles

 * [How to migrate data from Prometheus](https://medium.com/@romanhavronenko/victoriametrics-how-to-migrate-data-from-prometheus-d44a6728f043)
--- a/app/vmgateway/README.md
+++ b/app/vmgateway/README.md
@ -1,4 +1,4 @@
-## vmgateway
+# vmgateway


 <img alt="vmgateway" src="vmgateway-overview.jpeg">
@ -15,7 +15,7 @@
 `vmgateway` is included in an [enterprise package](https://victoriametrics.com/enterprise.html).


-### Access Control
+## Access Control

 <img alt="vmgateway-ac" src="vmgateway-access-control.jpg">

@ -45,7 +45,7 @@ Where:
 - `extra_labels` - optional, key-value pairs for label filters - added to ingested or selected metrics.
 - `mode` - optional, access mode for api - read, write, full. supported values: 0 - full (default value), 1 - read, 2 - write.

-#### QuickStart
+## QuickStart

 Start single version of Victoria Metrics

@ -74,7 +74,7 @@ curl 'http://localhost:8431/api/v1/series/count' -H 'Authorization: Bearer incor
 ```


-### Rate Limiter
+## Rate Limiter

 <img alt="vmgateway-rl" src="vmgateway-rate-limiting.jpg">

@ -112,7 +112,7 @@ limits:
    account_id: 1
 ```

-#### QuickStart
+## QuickStart

 cluster version required for rate limiting.
 ```bash
@ -162,7 +162,7 @@ curl 'http://localhost:8431/api/v1/labels' -H 'Authorization: Bearer eyJhbGciOiJ
 # check rate limit 
 ```

-### Configuration
+## Configuration

 The shortlist of configuration flags is the following:
 ```bash
@ -269,7 +269,7 @@ The shortlist of configuration flags is the following:

 ```

-### TroubleShooting
+## TroubleShooting

 * Access control:
  * incorrect `jwt` format, try https://jwt.io/#debugger-io with our tokens
@ -278,7 +278,7 @@ The shortlist of configuration flags is the following:
  * `scrape_interval` at datasource, reduce it to apply limits faster.


-### Limitations
+## Limitations

 * Access Control:
  * `jwt` token must be validated by external system, currently `vmgateway` can't validate the signature.
--- a/app/vmrestore/README.md
+++ b/app/vmrestore/README.md
@ -1,4 +1,4 @@
-## vmrestore
+# vmrestore

 `vmrestore` restores data from backups created by [vmbackup](https://victoriametrics.github.io/vbackup.html).
 VictoriaMetrics `v1.29.0` and newer versions must be used for working with the restored data.
--- a/docs/Articles.md
+++ b/docs/Articles.md
@ -1,3 +1,7 @@
+---
+sort: 16
+---
+
 # Articles

 ## Third-party articles and slides about VictoriaMetrics
--- a/docs/BestPractices.md
+++ b/docs/BestPractices.md
@ -1,3 +1,7 @@
+---
+sort: 12
+---
+
 # VM best practices 

 VictoriaMetrics is a fast, cost-effective and scalable monitoring solution and time series database. It can be used as a long-term, remote storage for Prometheus which allows it to gather metrics from different systems and store them in a single location or separate them for different purposes (short-, long-term, responsibility zones etc). 
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@ -1,6 +1,10 @@
+---
+sort: 13
+---
+
 # CHANGELOG

-# tip
+## tip

 * FEATURE: vminsert and vmagent: add `-sortLabels` command-line flag for sorting metric labels before pushing them to `vmstorage`. This should reduce the size of `MetricName -> internal_series_id` cache (aka `vm_cache_size_bytes{type="storage/tsid"}`) when ingesting samples for the same time series with distinct order of labels. For example, `foo{k1="v1",k2="v2"}` and `foo{k2="v2",k1="v1"}` represent a single time series. Labels sorting is disabled by default, since the majority of established exporters preserve the order of labels for the exported metrics.
 * FEATURE: allow specifying label value alongside label name for the `others sum` time series returned from `topk_*` and `bottomk_*` functions from [MetricsQL](https://victoriametrics.github.io/MetricsQL.html). For example, `topk_avg(3, max(process_resident_memory_bytes) by (instance), "instance=other_sum")` would return top 3 series from `max(process_resident_memory_bytes) by (instance)` plus a series containing the sum of other series. The `others sum` series will have `{instance="other_sum"}` label.
@ -25,7 +29,7 @@
 * BUGFIX: properly generate filename for `*.tar.gz` archive inside `_checksums.txt` file posted at [releases page](https://github.com/VictoriaMetrics/VictoriaMetrics/releases). See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/1171).


-# [v1.57.1](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.57.1)
+## [v1.57.1](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.57.1)

 * FEATURE: publish vmutils for `GOOS=arm` on [releases page](https://github.com/VictoriaMetrics/VictoriaMetrics/releases).

@ -34,7 +38,7 @@
 * BUGFIX: vminsert: return back `type` label to per-tenant metric `vm_tenant_inserted_rows_total`. See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/932).


-# [v1.57.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.57.0)
+## [v1.57.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.57.0)

 * FEATURE: optimize query performance by up to 10x on systems with many CPU cores. See [this tweet](https://twitter.com/MetricsVictoria/status/1375064484860067840).
 * FEATURE: add the following metrics at `/metrics` page for every VictoraMetrics app:
@ -57,7 +61,7 @@
 * BUGFIX: properly calculate `summarize` and `*Series` functions in [Graphite Render API](https://victoriametrics.github.io/#graphite-render-api-usage).


-# [v1.56.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.56.0)
+## [v1.56.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.56.0)

 * FEATURE: add the following functions to [MetricsQL](https://victoriametrics.github.io/MetricsQL.html):
  - `histogram_avg(buckets)` - returns the average value for the given buckets.
@ -86,13 +90,13 @@
 * BUGFIX: do not crash if a query contains `histogram_over_time()` function name with uppercase chars. For example, `Histogram_Over_Time(m[5m])`.


-# [v1.55.1](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.55.1)
+## [v1.55.1](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.55.1)

 * BUGFIX: vmagent: fix a panic in Kubernetes service discovery when a target is filtered out with relabeling. See https://github.com/VictoriaMetrics/VictoriaMetrics/issues/1107
 * BUGFIX: vmagent: fix Kubernetes service discovery for `role: ingress`. See https://github.com/VictoriaMetrics/VictoriaMetrics/pull/1110


-# [v1.55.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.55.0)
+## [v1.55.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.55.0)


 * FEATURE: add `sign(q)` and `clamp(q, min, max)` functions, which are planned to be added in [the upcoming Prometheus release](https://twitter.com/roidelapluie/status/1363428376162295811) . The `last_over_time(m[d])` function is already supported in [MetricsQL](https://victoriametrics.github.io/MetricsQL.html).
@ -128,12 +132,12 @@
 * BUGFIX: unescape only `\\`, `\n` and `\"` in label names when parsing Prometheus text exposition format as Prometheus does. Previously other escape sequences could be improperly unescaped.


-# [v1.54.1](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.54.1)
+## [v1.54.1](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.54.1)

 * BUGFIX: properly handle queries containing a filter on metric name plus any number of negative filters and zero non-negative filters. For example, `node_cpu_seconds_total{mode!="idle"}`. The bug was introduced in [v1.54.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.54.0).


-# [v1.54.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.54.0)
+## [v1.54.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.54.0)

 * FEATURE: optimize searching for matching metrics for `metric{<label_filters>}` queries if `<label_filters>` contains at least a single filter. For example, the query `up{job="foobar"}` should find the matching time series much faster than previously.
 * FEATURE: reduce execution times for `q1 <binary_op> q2` queries by executing `q1` and `q2` in parallel.
@ -154,12 +158,12 @@
 * BUGFIX: vmagent: return back unsent block to the queue during graceful shutdown. Previously this block could be dropped if remote storage is unavailable during vmagent shutdown. See https://github.com/VictoriaMetrics/VictoriaMetrics/issues/1065 .


-# [v1.53.1](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.53.1)
+## [v1.53.1](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.53.1)

 * BUGFIX: vmselect: fix the bug peventing from proper searching by Graphite filter with wildcards such as `{__graphite__="foo.*.bar"}`.


-# [v1.53.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.53.0)
+## [v1.53.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.53.0)

 * FEATURE: added [vmctl tool](https://victoriametrics.github.io/vmctl.html) to VictoriaMetrics release process. Now it is packaged in `vmutils-*.tar.gz` archive on [the releases page](https://github.com/VictoriaMetrics/VictoriaMetrics/releases). Source code for `vmctl` tool has been moved from [github.com/VictoriaMetrics/vmctl](https://github.com/VictoriaMetrics/vmctl) to [github.com/VictoriaMetrics/VictoriaMetrics/app/vmctl](https://github.com/VictoriaMetrics/VictoriaMetrics/tree/master/app/vmctl).
 * FEATURE: added `-loggerTimezone` command-line flag for adjusting time zone for timestamps in log messages. By default UTC is used.
@ -184,7 +188,7 @@ in front of VictoriaMetrics. [Contact us](mailto:sales@victoriametrics.com) if y
 * BUGFIX: vmagent: retry scrape and service discovery requests when the remote server closes HTTP keep-alive connection. Previously `disable_keepalive: true` option could be used under `scrape_configs` section when working with such servers.


-# [v1.52.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.52.0)
+## [v1.52.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.52.0)

 * FEATURE: provide a sample list of alerting rules for VictoriaMetrics components. It is available [here](https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/deployment/docker/alerts.yml).
 * FEATURE: disable final merge for data for the previous month at the beginning of new month, since it may result in high disk IO and CPU usage. Final merge can be enabled by setting `-finalMergeDelay` command-line flag to positive duration.
@ -204,7 +208,7 @@ in front of VictoriaMetrics. [Contact us](mailto:sales@victoriametrics.com) if y
 * BUGFIX: upgrade base image for Docker packages from Alpine 3.12.1 to Alpine 3.12.3 in order to fix potential security issues. See https://github.com/VictoriaMetrics/VictoriaMetrics/issues/1010


-# [v1.51.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.51.0)
+## [v1.51.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.51.0)

 * FEATURE: add `/api/v1/status/top_queries` handler, which returns the most frequently executed queries and queries that took the most time for execution. See https://github.com/VictoriaMetrics/VictoriaMetrics/issues/907
 * FEATURE: vmagent: add support for `proxy_url` config option in Prometheus scrape configs. See https://github.com/VictoriaMetrics/VictoriaMetrics/issues/503
@ -216,23 +220,23 @@ in front of VictoriaMetrics. [Contact us](mailto:sales@victoriametrics.com) if y
 * BUGFIX: do not adjust `offset` value provided in MetricsQL query. Previously it could be modified in order to improve response cache hit ratio. This is unneeded, since cache hit ratio should remain good because the query time range should be already aligned to multiple of `step` values. See https://github.com/VictoriaMetrics/VictoriaMetrics/issues/976


-# [v1.50.2](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.50.2)
+## [v1.50.2](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.50.2)

 * FEATURE: do not publish duplicate Docker images with `-cluster` tag suffix for [vmagent](https://victoriametrics.github.io/vmagent.html), [vmalert](https://victoriametrics.github.io/vmalert.html), [vmauth](https://victoriametrics.github.io/vmauth.html), [vmbackup](https://victoriametrics.github.io/vmbackup.html) and [vmrestore](https://victoriametrics.github.io/vmrestore.html), since they are identical to images without `-cluster` tag suffix.

 * BUGFIX: vmalert: properly populate template variables. This has been broken in v1.50.0. See https://github.com/VictoriaMetrics/VictoriaMetrics/issues/974
 * BUGFIX: properly parse negative combined duration in MetricsQL such as `-1h3m4s`. It must be parsed as `-(1h + 3m + 4s)`. Prevsiously it was parsed as `-1h + 3m + 4s`.
-* BUGFIX: properly parse lines in [Prometheus exposition format](https://github.com/prometheus/docs/blob/master/content/docs/instrumenting/exposition_formats.md) and in [OpenMetrics format](https://github.com/OpenObservability/OpenMetrics/blob/master/specification/OpenMetrics.md) with whitespace after the timestamp. For example, `foo 123 456 # some comment here`. See https://github.com/VictoriaMetrics/VictoriaMetrics/pull/970
+* BUGFIX: properly parse lines in [Prometheus exposition format](https://github.com/prometheus/docs/blob/master/content/docs/instrumenting/exposition_formats.md) and in [OpenMetrics format](https://github.com/OpenObservability/OpenMetrics/blob/master/specification/OpenMetrics.md) with whitespace after the timestamp. For example, `foo 123 456 ## some comment here`. See https://github.com/VictoriaMetrics/VictoriaMetrics/pull/970


-# [v1.50.1](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.50.1)
+## [v1.50.1](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.50.1)

 * FEATURE: vmagent: export `vmagent_remotewrite_blocks_sent_total` and `vmagent_remotewrite_blocks_sent_total` metrics for each `-remoteWrite.url`.

 * BUGFIX: vmagent: properly delete unregistered scrape targets from `/targets` and `/api/v1/targets` pages. They weren't deleted due to the bug in `v1.50.0`.


-# [v1.50.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.50.0)
+## [v1.50.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.50.0)

 * FEATURE: automatically reset response cache when samples with timestamps older than `now - search.cacheTimestampOffset` are ingested to VictoriaMetrics. This makes unnecessary disabling response cache during data backfilling or resetting it after backfilling is complete as described [in these docs](https://victoriametrics.github.io/#backfilling). This feature applies only to single-node VictoriaMetrics. It doesn't apply to cluster version of VictoriaMetrics because `vminsert` nodes don't know about `vmselect` nodes where the response cache must be reset.
 * FEATURE: vmalert: add `query`, `first` and `value` functions to alert templates. See https://github.com/VictoriaMetrics/VictoriaMetrics/issues/539
@ -257,7 +261,7 @@ in front of VictoriaMetrics. [Contact us](mailto:sales@victoriametrics.com) if y
 * BUGFIX: assume the previous value is 0 when calculating `increase()` for the first point on the graph if its value doesn't exceed 100 and the delta between two first points equals to 0. See https://github.com/VictoriaMetrics/VictoriaMetrics/issues/962


-# [v1.49.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.49.0)
+## [v1.49.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.49.0)

 * FEATURE: optimize Consul service discovery speed when discovering big number of services. See https://github.com/VictoriaMetrics/VictoriaMetrics/issues/574
 * FEATURE: add `label_uppercase(q, label1, ... labelN)` and `label_lowercase(q, label1, ... labelN)` function to [MetricsQL](https://victoriametrics.github.io/MetricsQL.html)
@ -277,7 +281,7 @@ in front of VictoriaMetrics. [Contact us](mailto:sales@victoriametrics.com) if y
  `days_in_month`, `hour`, `month` and `year`.


-# [v1.48.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.48.0)
+## [v1.48.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.48.0)

 * FEATURE: added [Snap package for single-node VictoriaMetrics](https://snapcraft.io/victoriametrics). This simplifies installation under Ubuntu to a single command:
  ```bash
@ -298,12 +302,12 @@ in front of VictoriaMetrics. [Contact us](mailto:sales@victoriametrics.com) if y
 * FEATURE: log metric name plus all its labels when the metric timestamp is out of the configured retention. This should simplify detecting the source of metrics with unexpected timestamps.
 * FEATURE: add `-dryRun` command-line flag to single-node VictoriaMetrics in order to check config file pointed by `-promscrape.config`.

-* BUGFIX: properly parse Prometheus metrics with [exemplars](https://github.com/OpenObservability/OpenMetrics/blob/master/OpenMetrics.md#exemplars-1) such as `foo 123 # {bar="baz"} 1`.
+* BUGFIX: properly parse Prometheus metrics with [exemplars](https://github.com/OpenObservability/OpenMetrics/blob/master/OpenMetrics.md#exemplars-1) such as `foo 123 ## {bar="baz"} 1`.
 * BUGFIX: properly parse "infinity" values in [OpenMetrics format](https://github.com/OpenObservability/OpenMetrics/blob/master/OpenMetrics.md#abnf).
  See https://github.com/VictoriaMetrics/VictoriaMetrics/issues/924


-# [v1.47.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.47.0)
+## [v1.47.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.47.0)

 * FEATURE: vmselect: return the original error from `vmstorage` node in query response if `-search.denyPartialResponse` is set.
  See https://github.com/VictoriaMetrics/VictoriaMetrics/issues/891
@ -333,7 +337,7 @@ in front of VictoriaMetrics. [Contact us](mailto:sales@victoriametrics.com) if y
 * BUGFIX: vminsert: properly return HTTP 503 status code when all the vmstorage nodes are unavailable. See https://github.com/VictoriaMetrics/VictoriaMetrics/issues/896


-# [v1.46.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.46.0)
+## [v1.46.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.46.0)

 * FEATURE: optimize requests to `/api/v1/labels` and `/api/v1/label/<name>/values` when `start` and `end` args are set.
 * FEATURE: reduce memory usage when query touches big number of time series.
@ -351,7 +355,7 @@ in front of VictoriaMetrics. [Contact us](mailto:sales@victoriametrics.com) if y
  See https://github.com/VictoriaMetrics/VictoriaMetrics/pull/883


-# [v1.45.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.45.0)
+## [v1.45.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.45.0)

 * FEATURE: allow setting `-retentionPeriod` smaller than one month. I.e. `-retentionPeriod=3d`, `-retentionPeriod=2w`, etc. is supported now.
  See https://github.com/VictoriaMetrics/VictoriaMetrics/issues/173
@ -385,7 +389,7 @@ in front of VictoriaMetrics. [Contact us](mailto:sales@victoriametrics.com) if y
 * BUGFIX: vmagent: properly handle 301 redirects. See https://github.com/VictoriaMetrics/VictoriaMetrics/issues/869


-# [v1.44.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.44.0)
+## [v1.44.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.44.0)

 * FEATURE: automatically add missing label filters to binary operands as described at https://utcc.utoronto.ca/~cks/space/blog/sysadmin/PrometheusLabelNonOptimization .
  This should improve performance for queries with missing label filters in binary operands. For example, the following query should work faster now, because it shouldn't
@ -445,7 +449,7 @@ in front of VictoriaMetrics. [Contact us](mailto:sales@victoriametrics.com) if y
 * BUGFIX: fix `mode_over_time(m[d])` calculations. Previously the function could return incorrect results.


-# [v1.43.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.43.0)
+## [v1.43.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.43.0)

 * FEATURE: reduce CPU usage for repeated queries over sliding time window when no new time series are added to the database.
  Typical use cases: repeated evaluation of alerting rules in [vmalert](https://victoriametrics.github.io/vmalert.html) or dashboard auto-refresh in Grafana.
@ -464,7 +468,7 @@ in front of VictoriaMetrics. [Contact us](mailto:sales@victoriametrics.com) if y
 * BUGFIX: support parsing floating-point timestamp like Graphite Carbon does. Such timestmaps are truncated to seconds.


-# [v1.42.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.42.0)
+## [v1.42.0](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/tag/v1.42.0)

 * FEATURE: use all the available CPU cores when accepting data via a single TCP connection
  for [all the supported protocols](https://victoriametrics.github.io/#how-to-import-time-series-data).
@ -494,6 +498,6 @@ in front of VictoriaMetrics. [Contact us](mailto:sales@victoriametrics.com) if y
  In this case only the node must be returned with stripped dot in the end of id as carbonapi does.


-# Previous releases
+## Previous releases

 See [releases page](https://github.com/VictoriaMetrics/VictoriaMetrics/releases).
--- a/docs/CaseStudies.md
+++ b/docs/CaseStudies.md
@ -1,3 +1,7 @@
+---
+sort: 17
+---
+
 # Case studies and talks

 Below please find public case studies and talks from VictoriaMetrics users. You can also join our [community Slack channel](http://slack.victoriametrics.com/)
--- a/docs/Cluster-VictoriaMetrics.md
+++ b/docs/Cluster-VictoriaMetrics.md
@ -1,6 +1,10 @@
+---
+sort: 9
+---
+
 # Cluster version

-<img alt="Victoria Metrics" src="logo.png">
+<img src="logo.png" width="300" alt="Victoria Metrics logo">

 VictoriaMetrics is a fast, cost-effective and scalable time series database. It can be used as a long-term remote storage for Prometheus.

--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@ -1,3 +1,7 @@
+---
+sort: 18
+---
+
 # FAQ

 ### What is the main purpose of VictoriaMetrics?
--- a/docs/Home.md
+++ b/docs/Home.md
@ -1,3 +1,7 @@
+---
+sort: 19
+---
+
 # Docs

 * [Quick start](Quick-Start)
--- a/docs/MetricsQL.md
+++ b/docs/MetricsQL.md
@ -1,3 +1,7 @@
+---
+sort: 11
+---
+
 # MetricsQL

 VictoriaMetrics implements MetricsQL - query language inspired by [PromQL](https://prometheus.io/docs/prometheus/latest/querying/basics/).
--- a/docs/Quick-Start.md
+++ b/docs/Quick-Start.md
@ -1,3 +1,7 @@
+---
+sort: 10
+---
+
 # Quick Start

 1. If you run Ubuntu please run the `snap install victoriametrics` command to install and start VictoriaMetrics. Then read [these docs](https://snapcraft.io/victoriametrics).
--- a/docs/Release-Guide.md
+++ b/docs/Release-Guide.md
@ -1,4 +1,8 @@
-Release process guidance
+---
+sort: 14
+---
+
+# Release process guidance

 ## Release version and Docker images

--- a/docs/SampleSizeCalculations.md
+++ b/docs/SampleSizeCalculations.md
@ -1,3 +1,7 @@
+---
+sort: 15
+---
+
 # Sample size calculations

 These calculations are for the “Lowest sample size” graph at https://victoriametrics.com/ .
@ -14,7 +18,7 @@ That means each metric will contain 6307200 points.
 2tb disk contains
 2 (tb) * 1024 (gb) * 1024 (mb) * 1024 (kb) * 1024 (b)  = 2199023255552 bytes

-# VictoriaMetrics
+## VictoriaMetrics
 Based on production data from our customers, sample size is 0.4 byte
 That means one metric with 10 seconds resolution will need
 6307200 points * 0.4 bytes/point = 2522880 bytes or 2.4 megabytes.
@ -22,13 +26,13 @@ Calculation for number of metrics can be stored in 2 tb disk:
 2199023255552 (disk size) / 2522880 (one metric for 2 year) = 871632 metrics
 So in 2tb we can store 871 632 metrics

-# Graphite
+## Graphite
 Based on https://m30m.github.io/whisper-calculator/ sample size of graphite metrics is 12b + 28b for each metric
 That means, one metric with 10 second resolution will need 75686428 bytes or 72.18 megabytes
 Calculation for number of metrics can be stored in 2 tb disk:
 2199023255552 / 75686428 = 29 054 metrics

-# OpenTSDB
+## OpenTSDB
 Let's check official openTSDB site
 http://opentsdb.net/faq.html
 16 bytes of HBase overhead, 3 bytes for the metric, 4 bytes for the timestamp, 6 bytes per tag, 2 bytes of OpenTSDB overhead, up to 8 bytes for the value. Integers are stored with variable length encoding and can consume 1, 2, 4 or 8 bytes.
@ -46,14 +50,15 @@ Also, openTSDB allows to use compression
 So, let's multiply numbers on 4.2
 69 730 * 4,2 = 292 866 metrics for best scenario
 29 054 * 4,2 = 122 026 metrics for worst scenario
-# m3db
+
+## M3DB
 Let's look at official m3db site https://m3db.github.io/m3/m3db/architecture/engine/
 They can achieve a sample size of 1.45 bytes/datapoint
 That means, one metric with 10 second resolution will need 9145440 bytes or 8,72177124 megabytes
 Calculation for number of metrics can be stored in 2 tb disk:
 2199023255552 / 9145440  = 240 450 metrics

-# InfluxDB
+## InfluxDB
 Based on official influxDB site https://docs.influxdata.com/influxdb/v1.8/guides/hardware_sizing/#bytes-and-compression
 "Non-string values require approximately three bytes". That means, one metric with 10 second resolution will need
 6307200 * 3 = 18921600 bytes or 18 megabytes
@ -61,7 +66,7 @@ Calculation for number of metrics can be stored in 2 tb disk:

 2199023255552 / 18921600 = 116 217 metrics

-# Prometheus
+## Prometheus
 Let's check official site: https://prometheus.io/docs/prometheus/latest/storage/
 "On average, Prometheus uses only around 1-2 bytes per sample."
 That means, one metric with 10 second resolution will need
--- a/docs/Single-server-VictoriaMetrics.md
+++ b/docs/Single-server-VictoriaMetrics.md
@ -1,3 +1,9 @@
+---
+sort: 1
+---
+
+# VictoriaMetrics
+
 [![Latest Release](https://img.shields.io/github/release/VictoriaMetrics/VictoriaMetrics.svg?style=flat-square)](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/latest)
 [![Docker Pulls](https://img.shields.io/docker/pulls/victoriametrics/victoria-metrics.svg?maxAge=604800)](https://hub.docker.com/r/victoriametrics/victoria-metrics)
 [![Slack](https://img.shields.io/badge/join%20slack-%23victoriametrics-brightgreen.svg)](http://slack.victoriametrics.com/)
@ -6,9 +12,7 @@
 [![Build Status](https://github.com/VictoriaMetrics/VictoriaMetrics/workflows/main/badge.svg)](https://github.com/VictoriaMetrics/VictoriaMetrics/actions)
 [![codecov](https://codecov.io/gh/VictoriaMetrics/VictoriaMetrics/branch/master/graph/badge.svg)](https://codecov.io/gh/VictoriaMetrics/VictoriaMetrics)

-![Victoria Metrics logo](logo.png "Victoria Metrics")
-
-## VictoriaMetrics
+<img src="logo.png" width="300" alt="Victoria Metrics logo">

 VictoriaMetrics is a fast, cost-effective and scalable monitoring solution and time series database.

--- a/docs/vmagent.md
+++ b/docs/vmagent.md
@ -1,4 +1,8 @@
-## vmagent
+---
+sort: 2
+---
+
+# vmagent

 `vmagent` is a tiny but mighty agent which helps you collect metrics from various sources
 and store them in [VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics)
--- a/docs/vmalert.md
+++ b/docs/vmalert.md
@ -1,10 +1,14 @@
-## vmalert
+---
+sort: 3
+---
+
+# vmalert

 `vmalert` executes a list of given [alerting](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/)
 or [recording](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/)
 rules against configured address.

-### Features:
+## Features
 * Integration with [VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics) TSDB;
 * VictoriaMetrics [MetricsQL](https://victoriametrics.github.io/MetricsQL.html)
 support and expressions validation;
@ -15,7 +19,7 @@ rules against configured address.
 * Graphite datasource can be used for alerting and recording rules. See [these docs](#graphite) for details.
 * Lightweight without extra dependencies.

-### Limitations:
+## Limitations
 * `vmalert` execute queries against remote datasource which has reliability risks because of network.
 It is recommended to configure alerts thresholds and rules expressions with understanding that network request
 may fail;
@ -24,7 +28,7 @@ storage is asynchronous. Hence, user shouldn't rely on recording rules chaining
 recording rule is reused in next one;
 * `vmalert` has no UI, just an API for getting groups and rules statuses.

-### QuickStart
+## QuickStart

 To build `vmalert` from sources:
 ```
@ -67,7 +71,7 @@ groups:
  [ - <rule_group> ]
 ```

-#### Groups
+### Groups

 Each group has following attributes:
 ```yaml
@ -89,7 +93,7 @@ rules:
  [ - <rule> ... ]
 ```

-#### Rules
+### Rules

 There are two types of Rules:
 * [alerting](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/) -
@ -102,7 +106,7 @@ and save their result as a new set of time series.
 `vmalert` forbids to define duplicates - rules with the same combination of name, expression and labels
 within one group.

-##### Alerting rules
+#### Alerting rules

 The syntax for alerting rule is following:
 ```yaml
@ -131,7 +135,7 @@ annotations:
  [ <labelname>: <tmpl_string> ]
 ```

-##### Recording rules
+#### Recording rules

 The syntax for recording rules is following:
 ```yaml
@ -155,7 +159,7 @@ labels:
 For recording rules to work `-remoteWrite.url` must specified.


-#### Alerts state on restarts
+### Alerts state on restarts

 `vmalert` has no local storage, so alerts state is stored in the process memory. Hence, after reloading of `vmalert`
 the process alerts state will be lost. To avoid this situation, `vmalert` should be configured via the following flags:
@ -171,7 +175,7 @@ in configured `-remoteRead.url`, weren't updated in the last `1h` or received st
 rules configuration.


-#### WEB
+### WEB

 `vmalert` runs a web-server (`-httpListenAddr`) for serving metrics and alerts endpoints:
 * `http://<vmalert-addr>/api/v1/groups` - list of all loaded groups and rules;
@ -182,7 +186,7 @@ Used as alert source in AlertManager.
 * `http://<vmalert-addr>/-/reload` - hot configuration reload.


-### Graphite
+## Graphite

 vmalert sends requests to `<-datasource.url>/render?format=json` during evaluation of alerting and recording rules
 if the corresponding group or rule contains `type: "graphite"` config option. It is expected that the `<-datasource.url>/render`
@ -191,7 +195,7 @@ When using vmalert with both `graphite` and `prometheus` rules configured agains
 to set `-datasource.appendTypePrefix` flag to `true`, so vmalert can adjust URL prefix automatically based on query type.


-### Configuration
+## Configuration

 The shortlist of configuration flags is the following:
 ```
@ -375,43 +379,43 @@ command-line flags with their descriptions.
 To reload configuration without `vmalert` restart send SIGHUP signal
 or send GET request to `/-/reload` endpoint.

-### Contributing
+## Contributing

 `vmalert` is mostly designed and built by VictoriaMetrics community.
 Feel free to share your experience and ideas for improving this
 software. Please keep simplicity as the main priority.

-### How to build from sources
+## How to build from sources

 It is recommended using
 [binary releases](https://github.com/VictoriaMetrics/VictoriaMetrics/releases)
 - `vmalert` is located in `vmutils-*` archives there.


-#### Development build
+### Development build

 1. [Install Go](https://golang.org/doc/install). The minimum supported version is Go 1.15.
 2. Run `make vmalert` from the root folder of [the repository](https://github.com/VictoriaMetrics/VictoriaMetrics).
   It builds `vmalert` binary and puts it into the `bin` folder.

-#### Production build
+### Production build

 1. [Install docker](https://docs.docker.com/install/).
 2. Run `make vmalert-prod` from the root folder of [the repository](https://github.com/VictoriaMetrics/VictoriaMetrics).
   It builds `vmalert-prod` binary and puts it into the `bin` folder.


-#### ARM build
+### ARM build

 ARM build may run on Raspberry Pi or on [energy-efficient ARM servers](https://blog.cloudflare.com/arm-takes-wing/).

-#### Development ARM build
+### Development ARM build

 1. [Install Go](https://golang.org/doc/install). The minimum supported version is Go 1.15.
 2. Run `make vmalert-arm` or `make vmalert-arm64` from the root folder of [the repository](https://github.com/VictoriaMetrics/VictoriaMetrics).
   It builds `vmalert-arm` or `vmalert-arm64` binary respectively and puts it into the `bin` folder.

-#### Production ARM build
+### Production ARM build

 1. [Install docker](https://docs.docker.com/install/).
 2. Run `make vmalert-arm-prod` or `make vmalert-arm64-prod` from the root folder of [the repository](https://github.com/VictoriaMetrics/VictoriaMetrics).
--- a/docs/vmauth.md
+++ b/docs/vmauth.md
@ -1,4 +1,8 @@
-## vmauth
+---
+sort: 4
+---
+
+# vmauth

 `vmauth` is a simple auth proxy and router for [VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics).
 It reads username and password from [Basic Auth headers](https://en.wikipedia.org/wiki/Basic_access_authentication),
--- a/docs/vmbackup.md
+++ b/docs/vmbackup.md
@ -1,4 +1,8 @@
-## vmbackup
+---
+sort: 5
+---
+
+# vmbackup

 `vmbackup` creates VictoriaMetrics data backups from [instant snapshots](https://victoriametrics.github.io/Single-server-VictoriaMetrics.html#how-to-work-with-snapshots).

--- a/docs/vmctl.md
+++ b/docs/vmctl.md
@ -1,3 +1,7 @@
+---
+sort: 7
+---
+
 # vmctl

 Victoria metrics command-line tool
@ -9,33 +13,6 @@ Features:
 - [x] InfluxDB: migrate data from InfluxDB to VictoriaMetrics
 - [ ] Storage Management: data re-balancing between nodes 

-# Table of contents
-
-* [Articles](#articles)
-* [How to build](#how-to-build)
-* [Migrating data from InfluxDB 1.x](#migrating-data-from-influxdb-1x)
-   * [Data mapping](#data-mapping)
-   * [Configuration](#configuration)
-   * [Filtering](#filtering)
-* [Migrating data from InfluxDB 2.x](#migrating-data-from-influxdb-2x)  
-* [Migrating data from Prometheus](#migrating-data-from-prometheus)
-   * [Data mapping](#data-mapping-1)
-   * [Configuration](#configuration-1)
-   * [Filtering](#filtering-1)
-* [Migrating data from Thanos](#migrating-data-from-thanos)
-   * [Current data](#current-data)
-   * [Historical data](#historical-data)
-* [Migrating data from VictoriaMetrics](#migrating-data-from-victoriametrics)
-   * [Native protocol](#native-protocol)
-* [Tuning](#tuning)
-   * [Influx mode](#influx-mode)
-   * [Prometheus mode](#prometheus-mode)
-   * [VictoriaMetrics importer](#victoriametrics-importer)
-   * [Importer stats](#importer-stats)
-* [Significant figures](#significant-figures)
-* [Adding extra labels](#adding-extra-labels)
-
-
 ## Articles

 * [How to migrate data from Prometheus](https://medium.com/@romanhavronenko/victoriametrics-how-to-migrate-data-from-prometheus-d44a6728f043)
--- a/docs/vmgateway.md
+++ b/docs/vmgateway.md
@ -1,4 +1,8 @@
-## vmgateway
+---
+sort: 8
+---
+
+# vmgateway


 <img alt="vmgateway" src="vmgateway-overview.jpeg">
@ -15,7 +19,7 @@
 `vmgateway` is included in an [enterprise package](https://victoriametrics.com/enterprise.html).


-### Access Control
+## Access Control

 <img alt="vmgateway-ac" src="vmgateway-access-control.jpg">

@ -45,7 +49,7 @@ Where:
 - `extra_labels` - optional, key-value pairs for label filters - added to ingested or selected metrics.
 - `mode` - optional, access mode for api - read, write, full. supported values: 0 - full (default value), 1 - read, 2 - write.

-#### QuickStart
+## QuickStart

 Start single version of Victoria Metrics

@ -74,7 +78,7 @@ curl 'http://localhost:8431/api/v1/series/count' -H 'Authorization: Bearer incor
 ```


-### Rate Limiter
+## Rate Limiter

 <img alt="vmgateway-rl" src="vmgateway-rate-limiting.jpg">

@ -112,7 +116,7 @@ limits:
    account_id: 1
 ```

-#### QuickStart
+## QuickStart

 cluster version required for rate limiting.
 ```bash
@ -162,7 +166,7 @@ curl 'http://localhost:8431/api/v1/labels' -H 'Authorization: Bearer eyJhbGciOiJ
 # check rate limit 
 ```

-### Configuration
+## Configuration

 The shortlist of configuration flags is the following:
 ```bash
@ -269,7 +273,7 @@ The shortlist of configuration flags is the following:

 ```

-### TroubleShooting
+## TroubleShooting

 * Access control:
  * incorrect `jwt` format, try https://jwt.io/#debugger-io with our tokens
@ -278,7 +282,7 @@ The shortlist of configuration flags is the following:
  * `scrape_interval` at datasource, reduce it to apply limits faster.


-### Limitations
+## Limitations

 * Access Control:
  * `jwt` token must be validated by external system, currently `vmgateway` can't validate the signature.
--- a/docs/vmrestore.md
+++ b/docs/vmrestore.md
@ -1,4 +1,8 @@
-## vmrestore
+---
+sort: 6
+---
+
+# vmrestore

 `vmrestore` restores data from backups created by [vmbackup](https://victoriametrics.github.io/vbackup.html).
 VictoriaMetrics `v1.29.0` and newer versions must be used for working with the restored data.