Fix relative URLs when serving the specification with a custom baseURL

.github/workflows/main.yml

@@ -1,4 +1,9 @@
 name: "Spec"
+
+env:
+  # Cannot build the spec with Hugo 0.125.0 and docsy < 0.10.0 because of https://github.com/google/docsy/issues/1930
+  HUGO_VERSION: 0.124.1
+
 on:
   push:
     branches:
@@ -193,7 +198,7 @@ jobs:
       - name: "➕ Setup Hugo"
         uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
         with:
-          hugo-version: '0.117.0'
+          hugo-version: ${{ env.HUGO_VERSION }}
           extended: true
       - name: "📥 Source checkout"
         uses: actions/checkout@v4
@@ -270,8 +275,7 @@ jobs:
       - name: "➕ Setup Hugo"
         uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
         with:
-          # Cannot build the spec with Hugo 0.125.0 because of https://github.com/google/docsy/issues/1930
-          hugo-version: '0.124.1'
+          hugo-version: ${{ env.HUGO_VERSION }}
           extended: true
       - name: "📥 Source checkout"
         uses: actions/checkout@v4

changelogs/header.md

@@ -9,7 +9,7 @@ Variables:
 <table class="release-info">
 <tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/VERSION">https://github.com/matrix-org/matrix-spec/tree/VERSION</a></td>
 <tr><th>Release date</th><td>DATE</td>
-<tr><th>Checklist</th><td><a href="/changelog/VERSION/checklist.md">checklist.md</a></td>
+<tr><th>Checklist</th><td><a href="{{< relref path="changelog/VERSION" outputFormat="Checklist" >}}">checklist.md</a></td>
 </table>
 
 <!-- Intentionally blank line to ensure headers work in the concatenated changelog -->

changelogs/internal/newsfragments/1984.clarification

@@ -0,0 +1 @@
+Fix relative URLs when serving the specification with a custom `baseURL`.

config.toml

@@ -1,10 +1,6 @@
 baseURL = "/"
 title = "Matrix Specification"
 
-# Prepends absolute URLs with the baseURL. Useful when hosting on non-root
-# paths, such as /unstable.
-canonifyURLs = true
-
 enableRobotsTXT = true
 
 # We disable RSS, because (a) it's useless, (b) Hugo seems to generate broken
@@ -138,6 +134,15 @@ sidebar_menu_compact = true
   [[module.imports]]
     path = "github.com/matrix-org/docsy"
     disable = false
+  # Mounting /assets and /static as assets directories helps Hugo to generate
+  # the correct URL.
+  [[module.mounts]]
+    source = 'assets'
+    target = 'assets'
+  [[module.mounts]]
+    source = 'static'
+    target = 'assets'
+
 
 # custom output formats
 
@@ -146,4 +151,3 @@ sidebar_menu_compact = true
     mediaType = "text/markdown"
     isPlainText = true
     baseName = "checklist"
-    notAlternative = true

content/changelog/v1.1.md

@@ -18,7 +18,7 @@ Variables:
 <table class="release-info">
 <tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-doc/tree/v1.1">https://github.com/matrix-org/matrix-doc/tree/v1.1</a></td>
 <tr><th>Release date</th><td>November 09, 2021</td>
-<tr><th>Checklist</th><td><a href="/changelog/v1.1/checklist.md">checklist.md</a></td>
+<tr><th>Checklist</th><td><a href="{{< relref path="changelog/v1.1" outputFormat="Checklist" >}}">checklist.md</a></td>
 </table>
 
 <!-- Intentionally blank line to ensure headers work in the concatenated changelog -->

content/changelog/v1.10.md

@@ -18,7 +18,7 @@ Variables:
 <table class="release-info">
 <tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.10">https://github.com/matrix-org/matrix-spec/tree/v1.10</a></td>
 <tr><th>Release date</th><td>March 22, 2024</td>
-<tr><th>Checklist</th><td><a href="/changelog/v1.10/checklist.md">checklist.md</a></td>
+<tr><th>Checklist</th><td><a href="{{< relref path="changelog/v1.10" outputFormat="Checklist" >}}">checklist.md</a></td>
 </table>
 
 <!-- Intentionally blank line to ensure headers work in the concatenated changelog -->

content/changelog/v1.11.md

@@ -18,7 +18,7 @@ Variables:
 <table class="release-info">
 <tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.11">https://github.com/matrix-org/matrix-spec/tree/v1.11</a></td>
 <tr><th>Release date</th><td>June 20, 2024</td>
-<tr><th>Checklist</th><td><a href="/changelog/v1.11/checklist.md">checklist.md</a></td>
+<tr><th>Checklist</th><td><a href="{{< relref path="changelog/v1.11" outputFormat="Checklist" >}}">checklist.md</a></td>
 </table>
 
 <!-- Intentionally blank line to ensure headers work in the concatenated changelog -->

content/changelog/v1.12.md

@@ -18,7 +18,7 @@ Variables:
 <table class="release-info">
 <tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.12">https://github.com/matrix-org/matrix-spec/tree/v1.12</a></td>
 <tr><th>Release date</th><td>October 07, 2024</td>
-<tr><th>Checklist</th><td><a href="/changelog/v1.12/checklist.md">checklist.md</a></td>
+<tr><th>Checklist</th><td><a href="{{< relref path="changelog/v1.12" outputFormat="Checklist" >}}">checklist.md</a></td>
 </table>
 
 <!-- Intentionally blank line to ensure headers work in the concatenated changelog -->

content/changelog/v1.2.md

@@ -18,7 +18,7 @@ Variables:
 <table class="release-info">
 <tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-doc/tree/v1.2">https://github.com/matrix-org/matrix-doc/tree/v1.2</a></td>
 <tr><th>Release date</th><td>February 02, 2022</td>
-<tr><th>Checklist</th><td><a href="/changelog/v1.2/checklist.md">checklist.md</a></td>
+<tr><th>Checklist</th><td><a href="{{< relref path="changelog/v1.2" outputFormat="Checklist" >}}">checklist.md</a></td>
 </table>
 
 <!-- Intentionally blank line to ensure headers work in the concatenated changelog -->

content/changelog/v1.3.md

@@ -18,7 +18,7 @@ Variables:
 <table class="release-info">
 <tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.3">https://github.com/matrix-org/matrix-spec/tree/v1.3</a></td>
 <tr><th>Release date</th><td>June 15, 2022</td>
-<tr><th>Checklist</th><td><a href="/changelog/v1.3/checklist.md">checklist.md</a></td>
+<tr><th>Checklist</th><td><a href="{{< relref path="changelog/v1.3" outputFormat="Checklist" >}}">checklist.md</a></td>
 </table>
 
 <!-- Intentionally blank line to ensure headers work in the concatenated changelog -->

content/changelog/v1.4.md

@@ -18,7 +18,7 @@ Variables:
 <table class="release-info">
 <tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.4">https://github.com/matrix-org/matrix-spec/tree/v1.4</a></td>
 <tr><th>Release date</th><td>September 29, 2022</td>
-<tr><th>Checklist</th><td><a href="/changelog/v1.4/checklist.md">checklist.md</a></td>
+<tr><th>Checklist</th><td><a href="{{< relref path="changelog/v1.4" outputFormat="Checklist" >}}">checklist.md</a></td>
 </table>
 
 <!-- Intentionally blank line to ensure headers work in the concatenated changelog -->

content/changelog/v1.5.md

@@ -18,7 +18,7 @@ Variables:
 <table class="release-info">
 <tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.5">https://github.com/matrix-org/matrix-spec/tree/v1.5</a></td>
 <tr><th>Release date</th><td>November 17, 2022</td>
-<tr><th>Checklist</th><td><a href="/changelog/v1.5/checklist.md">checklist.md</a></td>
+<tr><th>Checklist</th><td><a href="{{< relref path="changelog/v1.5" outputFormat="Checklist" >}}">checklist.md</a></td>
 </table>
 
 <!-- Intentionally blank line to ensure headers work in the concatenated changelog -->

content/changelog/v1.6.md

@@ -18,7 +18,7 @@ Variables:
 <table class="release-info">
 <tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.6">https://github.com/matrix-org/matrix-spec/tree/v1.6</a></td>
 <tr><th>Release date</th><td>February 14, 2023</td>
-<tr><th>Checklist</th><td><a href="/changelog/v1.6/checklist.md">checklist.md</a></td>
+<tr><th>Checklist</th><td><a href="{{< relref path="changelog/v1.6" outputFormat="Checklist" >}}">checklist.md</a></td>
 </table>
 
 <!-- Intentionally blank line to ensure headers work in the concatenated changelog -->

content/changelog/v1.7.md

@@ -18,7 +18,7 @@ Variables:
 <table class="release-info">
 <tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.7">https://github.com/matrix-org/matrix-spec/tree/v1.7</a></td>
 <tr><th>Release date</th><td>May 25, 2023</td>
-<tr><th>Checklist</th><td><a href="/changelog/v1.7/checklist.md">checklist.md</a></td>
+<tr><th>Checklist</th><td><a href="{{< relref path="changelog/v1.7" outputFormat="Checklist" >}}">checklist.md</a></td>
 </table>
 
 <!-- Intentionally blank line to ensure headers work in the concatenated changelog -->

content/changelog/v1.8.md

@@ -18,7 +18,7 @@ Variables:
 <table class="release-info">
 <tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.8">https://github.com/matrix-org/matrix-spec/tree/v1.8</a></td>
 <tr><th>Release date</th><td>August 23, 2023</td>
-<tr><th>Checklist</th><td><a href="/changelog/v1.8/checklist.md">checklist.md</a></td>
+<tr><th>Checklist</th><td><a href="{{< relref path="changelog/v1.8" outputFormat="Checklist" >}}">checklist.md</a></td>
 </table>
 
 <!-- Intentionally blank line to ensure headers work in the concatenated changelog -->

content/changelog/v1.9.md

@@ -18,7 +18,7 @@ Variables:
 <table class="release-info">
 <tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.9">https://github.com/matrix-org/matrix-spec/tree/v1.9</a></td>
 <tr><th>Release date</th><td>November 29, 2023</td>
-<tr><th>Checklist</th><td><a href="/changelog/v1.9/checklist.md">checklist.md</a></td>
+<tr><th>Checklist</th><td><a href="{{< relref path="changelog/v1.9" outputFormat="Checklist" >}}">checklist.md</a></td>
 </table>
 
 <!-- Intentionally blank line to ensure headers work in the concatenated changelog -->

data/api/client-server/account-data.yaml

@@ -23,7 +23,7 @@ paths:
         Set some account data for the client. This config is only visible to the user
         that set the account data. The config will be available to clients through the
         top-level `account_data` field in the homeserver response to
-        [/sync](#get_matrixclientv3sync).
+        [/sync](/client-server-api/#get_matrixclientv3sync).
       operationId: setAccountData
       security:
         - accessTokenQuery: []
@@ -185,7 +185,7 @@ paths:
       description: |-
         Set some account data for the client on a given room. This config is only
         visible to the user that set the account data. The config will be delivered to
-        clients in the per-room entries via [/sync](#get_matrixclientv3sync).
+        clients in the per-room entries via [/sync](/client-server-api/#get_matrixclientv3sync).
       operationId: setAccountDataPerRoom
       security:
         - accessTokenQuery: []

data/api/client-server/appservice_ping.yaml

@@ -23,7 +23,7 @@ paths:
         connection works.
       description: |-
         This API asks the homeserver to call the
-        [`/_matrix/app/v1/ping`](#post_matrixappv1ping) endpoint on the
+        [`/_matrix/app/v1/ping`](/application-service-api/#post_matrixappv1ping) endpoint on the
         application service to ensure that the homeserver can communicate
         with the application service.
 
@@ -71,7 +71,7 @@ paths:
                     type: integer
                     description: |-
                       The duration in milliseconds that the
-                      [`/_matrix/app/v1/ping`](#post_matrixappv1ping)
+                      [`/_matrix/app/v1/ping`](/application-service-api/#post_matrixappv1ping)
                       request took from the homeserver's point of view.
                 required:
                   - duration_ms

data/api/client-server/definitions/auth_data.yaml

@@ -21,7 +21,7 @@ properties:
       The authentication type that the client is attempting to complete.
       May be omitted if `session` is given, and the client is reissuing a
       request which it believes has been completed out-of-band (for example,
-      via the [fallback mechanism](#fallback)).
+      via the [fallback mechanism](/client-server-api/#fallback)).
     type: string
   session:
     description: The value of the session key given by the homeserver.

data/api/client-server/definitions/key_backup_session_data.yaml

@@ -28,7 +28,8 @@ properties:
     items:
       type: string
     description: |-
-      Chain of Curve25519 keys through which this session was forwarded, via [m.forwarded_room_key](#mforwarded_room_key) events.
+      Chain of Curve25519 keys through which this session was forwarded, via [m.forwarded_room_key](/client-server-api/#mforwarded_room_key)
+      events.
   sender_key:
     type: string
     description: |-

data/api/client-server/definitions/megolm_export_session_data.yaml

@@ -21,8 +21,8 @@ allOf:
       The format used to encode a Megolm session key for export.
 
       This is similar to the format before encryption used for the session keys
-      in [Server-side key backups](#server-side-key-backups) but adds the
-      `room_id` and `session_id` fields.
+      in [Server-side key backups](/client-server-api/#server-side-key-backups)
+      but adds the `room_id` and `session_id` fields.
     properties:
       room_id:
         type: string

data/api/client-server/definitions/timeline_batch.yaml

@@ -19,7 +19,7 @@ properties:
     type: boolean
   prev_batch:
     description: A token that can be supplied to the `from` parameter of the
-      [`/rooms/<room_id>/messages`](#get_matrixclientv3roomsroomidmessages)
+      [`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages)
       endpoint in order to retrieve earlier events.
 
       If no earlier events are available, this property may be omitted from

data/api/client-server/old_sync.yaml

@@ -173,7 +173,7 @@ paths:
                               description: |-
                                 A token which correlates to the start of `chunk`.
                                 Can be passed to
-                                [`/rooms/<room_id>/messages`](#get_matrixclientv3roomsroomidmessages)
+                                [`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages)
                                 to retrieve earlier events.
 
                                 If no earlier events are available, this property may be omitted from
@@ -183,7 +183,7 @@ paths:
                               description: |-
                                 A token which correlates to the end of `chunk`.
                                 Can be passed to
-                                [`/rooms/<room_id>/messages`](#get_matrixclientv3roomsroomidmessages)
+                                [`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages)
                                 to retrieve later events.
                             chunk:
                               type: array

data/api/client-server/room_event_by_timestamp.yaml

@@ -30,7 +30,7 @@ paths:
         to ask other servers for a suitable event.
 
         After calling this endpoint, clients can call
-        [`/rooms/{roomId}/context/{eventId}`](#get_matrixclientv3roomsroomidcontexteventid)
+        [`/rooms/{roomId}/context/{eventId}`](/client-server-api/#get_matrixclientv3roomsroomidcontexteventid)
         to obtain a pagination token to retrieve the events around the returned event.
 
         The event returned by this endpoint could be an event that the client

data/api/client-server/room_initial_sync.yaml

@@ -54,7 +54,7 @@ paths:
                         type: string
                         description: |-
                           A token which correlates to the start of `chunk`. Can be passed to
-                          [`/rooms/<room_id>/messages`](#get_matrixclientv3roomsroomidmessages)
+                          [`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages)
                           to retrieve earlier events.
 
                           If no earlier events are available, this property may be omitted from
@@ -63,7 +63,7 @@ paths:
                         type: string
                         description: |-
                           A token which correlates to the end of `chunk`. Can be passed to
-                          [`/rooms/<room_id>/messages`](#get_matrixclientv3roomsroomidmessages)
+                          [`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages)
                           to retrieve later events.
                       chunk:
                         type: array

data/api/client-server/space_hierarchy.yaml

@@ -26,8 +26,8 @@ paths:
         Where a child room is unknown to the local server, federation is used to fill in the details.
         The servers listed in the `via` array should be contacted to attempt to fill in missing rooms.
 
-        Only [`m.space.child`](#mspacechild) state events of the room are considered. Invalid child
-        rooms and parent events are not covered by this endpoint.
+        Only [`m.space.child`](/client-server-api/#mspacechild) state events of the room are considered.
+        Invalid child rooms and parent events are not covered by this endpoint.
       operationId: getSpaceHierarchy
       security:
         - accessTokenQuery: []
@@ -44,8 +44,8 @@ paths:
           name: suggested_only
           description: |-
             Optional (default `false`) flag to indicate whether or not the server should only consider
-            suggested rooms. Suggested rooms are annotated in their [`m.space.child`](#mspacechild) event
-            contents.
+            suggested rooms. Suggested rooms are annotated in their [`m.space.child`](/client-server-api/#mspacechild)
+            event contents.
           example: true
           schema:
             type: boolean
@@ -103,8 +103,8 @@ paths:
                             children_state:
                               type: array
                               description: |-
-                                The [`m.space.child`](#mspacechild) events of the space-room, represented
-                                as [Stripped State Events](#stripped-state) with an added `origin_server_ts` key.
+                                The [`m.space.child`](/client-server-api/#mspacechild) events of the space-room, represented
+                                as [Stripped State Events](/client-server-api/#stripped-state) with an added `origin_server_ts` key.
 
                                 If the room is not a space-room, this should be empty.
                               items: