add docsorder linter (#5637)

.github/workflows/lint.yml

@@ -73,6 +73,18 @@ jobs:
 
     - run: make lint-docslinks
 
+  docsorder:
+    runs-on: ubuntu-22.04
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - uses: actions/setup-go@v6
+      with:
+        go-version: "1.25"
+
+    - run: make lint-docsorder
+
   docs:
     runs-on: ubuntu-22.04
 

docs/1-kickoff/1-introduction.md

@@ -11,16 +11,16 @@ Main features:
 - Streams are automatically converted from a protocol to another
 - Serve several streams at once in separate paths
 - Reload the configuration without disconnecting existing clients (hot reloading)
-- [Serve always-available streams](../4-other/05-always-available.md) even when the publisher is offline
-- [Record](../4-other/06-record.md) streams to disk in fMP4 or MPEG-TS format
-- [Playback](../4-other/07-playback.md) recorded streams
-- [Authenticate](../4-other/03-authentication.md) users with internal, HTTP or JWT authentication
-- [Forward](../4-other/08-forward.md) streams to other servers
-- [Proxy](../4-other/09-proxy.md) requests to other servers
-- [Control](../4-other/18-control-api.md) the server through the Control API
-- [Extract metrics](../4-other/19-metrics.md) from the server in a Prometheus-compatible format
-- [Monitor performance](../4-other/20-performance.md) to investigate CPU and RAM consumption
-- [Run hooks](../4-other/17-hooks.md) (external commands) when clients connect, disconnect, read or publish streams
+- [Serve always-available streams](../4-other/04-always-available.md) even when the publisher is offline
+- [Record](../4-other/05-record.md) streams to disk in fMP4 or MPEG-TS format
+- [Playback](../4-other/06-playback.md) recorded streams
+- [Authenticate](../4-other/02-authentication.md) users with internal, HTTP or JWT authentication
+- [Forward](../4-other/07-forward.md) streams to other servers
+- [Proxy](../4-other/08-proxy.md) requests to other servers
+- [Control](../4-other/17-control-api.md) the server through the Control API
+- [Extract metrics](../4-other/18-metrics.md) from the server in a Prometheus-compatible format
+- [Monitor performance](../4-other/19-performance.md) to investigate CPU and RAM consumption
+- [Run hooks](../4-other/16-hooks.md) (external commands) when clients connect, disconnect, read or publish streams
 - Compatible with Linux, Windows and macOS, does not require any dependency or interpreter, it's a single executable
 
 Use the menu to navigate through the documentation.

docs/2-publish/02-srt-clients.md

@@ -8,7 +8,7 @@ srt://localhost:8890?streamid=publish:mystream&pkt_size=1316
 
 Replace `mystream` with any name you want. The resulting stream will be available on path `/mystream`.
 
-If you need to use the standard stream ID syntax instead of the custom one in use by this server, read [Standard stream ID syntax](../4-other/21-srt-specific-features.md#standard-stream-id-syntax).
+If you need to use the standard stream ID syntax instead of the custom one in use by this server, read [Standard stream ID syntax](../4-other/20-srt-specific-features.md#standard-stream-id-syntax).
 
 If you want to publish a stream by using a client in listening mode (i.e. with `mode=listener` appended to the URL), read the next section.
 

docs/2-publish/04-webrtc-clients.md

@@ -14,8 +14,8 @@ WHIP is a WebRTC extension that allows to publish streams by using a URL, withou
 http://localhost:8889/mystream/whip
 ```
 
-Be aware that not all browsers can read any codec, check [Codec support in browsers](../4-other/22-webrtc-specific-features.md#codec-support-in-browsers).
+Be aware that not all browsers can read any codec, check [Codec support in browsers](../4-other/21-webrtc-specific-features.md#codec-support-in-browsers).
 
-Depending on the network it might be difficult to establish a connection between server and clients, read [Solving WebRTC connectivity issues](../4-other/22-webrtc-specific-features.md#solving-webrtc-connectivity-issues).
+Depending on the network it might be difficult to establish a connection between server and clients, read [Solving WebRTC connectivity issues](../4-other/21-webrtc-specific-features.md#solving-webrtc-connectivity-issues).
 
 Some clients that can publish with WebRTC and WHIP are [FFmpeg](15-ffmpeg.md), [GStreamer](16-gstreamer.md), [OBS Studio](17-obs-studio.md), [Unity](20-unity.md) and [Web browsers](21-web-browsers.md).

docs/2-publish/06-rtsp-clients.md

@@ -10,7 +10,7 @@ The resulting stream will be available on path `/mystream`.
 
 Some clients that can publish with RTSP are [FFmpeg](15-ffmpeg.md), [GStreamer](16-gstreamer.md), [OBS Studio](17-obs-studio.md), [Python and OpenCV](18-python-opencv.md).
 
-Advanced RTSP features and settings are described in [RTSP-specific features](../4-other/23-rtsp-specific-features.md).
+Advanced RTSP features and settings are described in [RTSP-specific features](../4-other/22-rtsp-specific-features.md).
 
 ## MPEG-TS inside RTSP
 

docs/2-publish/07-rtsp-cameras-and-servers.md

@@ -44,4 +44,4 @@ paths:
 
 All available parameters are listed in the [configuration file](../5-references/1-configuration-file.md).
 
-Advanced RTSP features and settings are described in [RTSP-specific features](../4-other/23-rtsp-specific-features.md).
+Advanced RTSP features and settings are described in [RTSP-specific features](../4-other/22-rtsp-specific-features.md).

docs/2-publish/08-rtmp-clients.md

@@ -1,6 +1,6 @@
 # RTMP clients
 
-RTMP is a protocol that allows to read and publish streams. It supports encryption, read [RTMP-specific features](../4-other/24-rtmp-specific-features.md). Streams can be published to the server by using the URL:
+RTMP is a protocol that allows to read and publish streams. It supports encryption, read [RTMP-specific features](../4-other/23-rtmp-specific-features.md). Streams can be published to the server by using the URL:
 
 ```
 rtmp://localhost/mystream

docs/2-publish/16-gstreamer.md

@@ -20,7 +20,7 @@ d.video_0 ! rtspclientsink location=rtsp://localhost:8554/mystream
 
 The resulting stream will be available on path `/mystream`.
 
-For advanced options, read [RTSP-specific features](../4-other/23-rtsp-specific-features.md).
+For advanced options, read [RTSP-specific features](../4-other/22-rtsp-specific-features.md).
 
 ## GStreamer and RTMP
 
@@ -38,7 +38,7 @@ videotestsrc ! video/x-raw,width=1280,height=720,format=I420 ! x264enc speed-pre
 audiotestsrc ! audioconvert ! avenc_aac ! mux.
 ```
 
-For advanced options, read [RTSP-specific features](../4-other/23-rtsp-specific-features.md).
+For advanced options, read [RTSP-specific features](../4-other/22-rtsp-specific-features.md).
 
 ## GStreamer and WebRTC
 

docs/3-read/02-srt.md

@@ -8,6 +8,6 @@ srt://localhost:8890?streamid=read:mystream
 
 Replace `mystream` with the path name.
 
-If you need to use the standard stream ID syntax instead of the custom one in use by this server, read [Standard stream ID syntax](../4-other/21-srt-specific-features.md#standard-stream-id-syntax).
+If you need to use the standard stream ID syntax instead of the custom one in use by this server, read [Standard stream ID syntax](../4-other/20-srt-specific-features.md#standard-stream-id-syntax).
 
 Some clients that can read with SRT are [FFmpeg](07-ffmpeg.md), [GStreamer](08-gstreamer.md) and [VLC](09-vlc.md).

docs/3-read/03-webrtc.md

@@ -12,8 +12,8 @@ WHEP is a WebRTC extension that allows to read streams by using a URL, without p
 http://localhost:8889/mystream/whep
 ```
 
-Be aware that not all browsers can read any codec, check [Codec support in browsers](../4-other/22-webrtc-specific-features.md#codec-support-in-browsers).
+Be aware that not all browsers can read any codec, check [Codec support in browsers](../4-other/21-webrtc-specific-features.md#codec-support-in-browsers).
 
-Depending on the network it may be difficult to establish a connection between server and clients, read [Solving WebRTC connectivity issues](../4-other/22-webrtc-specific-features.md#solving-webrtc-connectivity-issues).
+Depending on the network it may be difficult to establish a connection between server and clients, read [Solving WebRTC connectivity issues](../4-other/21-webrtc-specific-features.md#solving-webrtc-connectivity-issues).
 
 Some clients that can read with WebRTC and WHEP are [FFmpeg](07-ffmpeg.md), [GStreamer](08-gstreamer.md), [Unity](13-unity.md) and [web browsers](14-web-browsers.md).

docs/3-read/04-rtsp.md

@@ -1,6 +1,6 @@
 # RTSP clients
 
-RTSP is a protocol that allows to publish and read streams. It supports several underlying transport protocols and encryption (read [RTSP-specific features](../4-other/23-rtsp-specific-features.md)). In order to read a stream with the RTSP protocol, use this URL:
+RTSP is a protocol that allows to publish and read streams. It supports several underlying transport protocols and encryption (read [RTSP-specific features](../4-other/22-rtsp-specific-features.md)). In order to read a stream with the RTSP protocol, use this URL:
 
 ```
 rtsp://localhost:8554/mystream

docs/3-read/05-rtmp.md

@@ -1,6 +1,6 @@
 # RTMP clients
 
-RTMP is a protocol that allows to read and publish streams. It supports encryption, read [RTMP-specific features](../4-other/24-rtmp-specific-features.md). Streams can be read from the server by using the URL:
+RTMP is a protocol that allows to read and publish streams. It supports encryption, read [RTMP-specific features](../4-other/23-rtmp-specific-features.md). Streams can be read from the server by using the URL:
 
 ```
 rtmp://localhost/mystream

docs/3-read/08-gstreamer.md

@@ -8,7 +8,7 @@ GStreamer can read a stream from the server in several ways. The recommended one
 gst-launch-1.0 rtspsrc location=rtsp://127.0.0.1:8554/mystream latency=0 ! decodebin ! autovideosink
 ```
 
-For advanced options, read [RTSP-specific features](../4-other/23-rtsp-specific-features.md).
+For advanced options, read [RTSP-specific features](../4-other/22-rtsp-specific-features.md).
 
 ## GStreamer and WebRTC
 

docs/3-read/14-web-browsers.md

@@ -10,7 +10,7 @@ You can read a stream by using the [WebRTC protocol](03-webrtc.md) by visiting t
 http://localhost:8889/mystream
 ```
 
-See [Embed streams in a website](../4-other/14-embed-streams-in-a-website.md) for instructions on how to embed the stream into an external website.
+See [Embed streams in a website](../4-other/13-embed-streams-in-a-website.md) for instructions on how to embed the stream into an external website.
 
 ## Web browsers and HLS
 
@@ -20,4 +20,4 @@ Web browsers can also read a stream with the [HLS protocol](06-hls.md). Latency
 http://localhost:8888/mystream
 ```
 
-See [Embed streams in a website](../4-other/14-embed-streams-in-a-website.md) for instructions on how to embed the stream into an external website.
+See [Embed streams in a website](../4-other/13-embed-streams-in-a-website.md) for instructions on how to embed the stream into an external website.

docs/4-other/01-configuration.md

@@ -47,7 +47,7 @@ There are several ways to change the configuration:
    docker run --rm -it --network=host -e MTX_PATHS_TEST_SOURCE=rtsp://myurl bluenviron/mediamtx:1
    ```
 
-3. By using the [Control API](18-control-api.md).
+3. By using the [Control API](17-control-api.md).
 
 ## Encrypt the configuration
 

docs/4-other/02-authentication.md

@@ -297,7 +297,7 @@ Username and password can be passed through the `Authorization: Basic` HTTP head
 Authorization: Basic base64(user:pass)
 ```
 
-When using a web browser, a dialog is first shown to users, asking for credentials, and then the header is automatically inserted into every request. If you need to automatically fill credentials from a parent web page, read [Embed streams in a website](14-embed-streams-in-a-website.md).
+When using a web browser, a dialog is first shown to users, asking for credentials, and then the header is automatically inserted into every request. If you need to automatically fill credentials from a parent web page, read [Embed streams in a website](13-embed-streams-in-a-website.md).
 
 If the `Authorization: Basic` header cannot be used (for instance, in software like OBS Studio, which only allows to provide a "Bearer Token"), credentials can be passed through the `Authorization: Bearer` header (i.e. the "Bearer Token" in OBS), where the value is the concatenation of username and password, separated by a colon:
 
@@ -349,4 +349,4 @@ In OBS Studio, this is the "Bearer Token" field.
 
 If the `Authorization: Bearer` token cannot be directly provided (for instance, with web browsers that directly access _MediaMTX_ and show a credential dialog), you can pass the token as password, using an arbitrary user.
 
-In web browsers, if you need to automatically fill credentials from a parent web page, read [Embed streams in a website](14-embed-streams-in-a-website.md).
+In web browsers, if you need to automatically fill credentials from a parent web page, read [Embed streams in a website](13-embed-streams-in-a-website.md).

docs/4-other/15-logging.md

@@ -37,7 +37,7 @@ Log entries can be queried by using:
 journalctl SYSLOG_IDENTIFIER=mediamtx
 ```
 
-If _MediaMTX_ is also running as a [system service](15-start-on-boot.md), log entries can be queried by using:
+If _MediaMTX_ is also running as a [system service](14-start-on-boot.md), log entries can be queried by using:
 
 ```sh
 journalctl -u mediamtx

docs/4-other/17-control-api.md

@@ -14,4 +14,4 @@ curl http://127.0.0.1:9997/v3/paths/list
 
 The control API is documented in the [Control API Reference page](../5-references/2-control-api.md) and in the [OpenAPI / Swagger file](https://github.com/bluenviron/mediamtx/blob/{version_tag}/api/openapi.yaml).
 
-Be aware that by default the Control API is accessible by localhost only; to increase visibility or enforce authentication, check [Authentication](03-authentication.md).
+Be aware that by default the Control API is accessible by localhost only; to increase visibility or enforce authentication, check [Authentication](02-authentication.md).

docs/5-references/1-configuration-file.md

@@ -1,3 +1,3 @@
 # Configuration file reference
 
-This is a copy of the configuration file (`mediamtx.yml`) of the latest _MediaMTX_ release ({version_tag}), that contains all available parameters. Check the [Configuration usage page](../4-other/02-configuration.md) for instructions on how to change it.
+This is a copy of the configuration file (`mediamtx.yml`) of the latest _MediaMTX_ release ({version_tag}), that contains all available parameters. Check the [Configuration usage page](../4-other/01-configuration.md) for instructions on how to change it.

docs/5-references/2-control-api.md

@@ -1,3 +1,3 @@
 # Control API reference
 
-This is the reference of the Control API of the latest _MediaMTX_ release ({version_tag}), generated automatically from the [OpenAPI / Swagger file](https://github.com/bluenviron/mediamtx/blob/{version_tag}/api/openapi.yaml) available in the repository. Check the [Control API usage page](../4-other/18-control-api.md) for instructions on how to use the API.
+This is the reference of the Control API of the latest _MediaMTX_ release ({version_tag}), generated automatically from the [OpenAPI / Swagger file](https://github.com/bluenviron/mediamtx/blob/{version_tag}/api/openapi.yaml) available in the repository. Check the [Control API usage page](../4-other/17-control-api.md) for instructions on how to use the API.

internal/linters/docsorder/docsorder_test.go

@@ -0,0 +1,91 @@
+//go:build enable_linters
+
+package docsorder
+
+import (
+	"fmt"
+	"os"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+const repoPath = "../../.."
+
+var numberedFileRe = regexp.MustCompile(`^(\d+)-`)
+
+type numberedFile struct {
+	name   string
+	numStr string
+	num    int
+}
+
+func TestDocsOrder(t *testing.T) {
+	entries, err := os.ReadDir(repoPath + "/docs")
+	require.NoError(t, err)
+
+	for _, entry := range entries {
+		if !entry.IsDir() {
+			continue
+		}
+
+		dirPath := fmt.Sprintf("%s/docs/%s", repoPath, entry.Name())
+
+		files, err := os.ReadDir(dirPath)
+		require.NoError(t, err)
+
+		var numbered []numberedFile
+		for _, f := range files {
+			if f.IsDir() {
+				continue
+			}
+			m := numberedFileRe.FindStringSubmatch(f.Name())
+			if m == nil {
+				continue
+			}
+			num, err2 := strconv.Atoi(m[1])
+			if err2 != nil {
+				t.Errorf("docs/%s/%s: cannot parse numeric prefix %q", entry.Name(), f.Name(), m[1])
+				continue
+			}
+			numbered = append(numbered, numberedFile{
+				name:   f.Name(),
+				numStr: m[1],
+				num:    num,
+			})
+		}
+
+		if len(numbered) == 0 {
+			continue
+		}
+
+		sort.Slice(numbered, func(i, j int) bool {
+			return numbered[i].num < numbered[j].num
+		})
+
+		usesPadding := len(numbered) >= 10
+
+		for i, nf := range numbered {
+			expected := i + 1
+
+			if nf.num != expected {
+				t.Errorf("docs/%s/%s: expected number %d, got %d", entry.Name(), nf.name, expected, nf.num)
+			}
+
+			if usesPadding {
+				expectedStr := fmt.Sprintf("%02d", expected)
+				if nf.numStr != expectedStr {
+					t.Errorf("docs/%s/%s: expected zero-padded prefix %q, got %q", entry.Name(), nf.name, expectedStr, nf.numStr)
+				}
+			} else {
+				if strings.HasPrefix(nf.numStr, "0") {
+					t.Errorf("docs/%s/%s: unexpected zero-padded prefix %q (directory has fewer than 10 files)", entry.Name(), nf.name, nf.numStr)
+				}
+			}
+		}
+	}
+}

scripts/lint.mk

@@ -27,6 +27,9 @@ lint-go2api:
 lint-docslinks:
 	go test -v -tags enable_linters ./internal/linters/docslinks
 
+lint-docsorder:
+	go test -v -tags enable_linters ./internal/linters/docsorder
+
 lint-docs:
 	echo "$$DOCKERFILE_DOCS_LINT" | docker build . -f - -t temp
 	docker run --rm -v "$(shell pwd)/docs:/s" -w /s temp \
@@ -37,4 +40,4 @@ lint-api-docs:
 	docker run --rm -v "$(shell pwd)/api:/s" -w /s temp \
 	sh -c "openapi lint openapi.yaml"
 
-lint: lint-go lint-go-mod lint-conf lint-go2api lint-docslinks lint-docs lint-api-docs
+lint: lint-go lint-go-mod lint-conf lint-go2api lint-docslinks lint-docsorder lint-docs lint-api-docs