Fix relative URLs when serving the specification with a custom baseURL (#1984)

.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: ${{ env.HUGO_VERSION }}
-          hugo-version: '0.124.1'
           extended: true
       - name: "📥 Source checkout"
         uses: actions/checkout@v4

assets/css/fonts/README.md

@@ -16,7 +16,7 @@ load them. Example call:
 ```sh
 python3 download_google_fonts_css.py \
   "https://fonts.googleapis.com/css?family=Inter:300,300i,400,400i,700,700i" \
-  ../../fonts \
+  ../../../static/fonts \
   ../../fonts 
 ```
   

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
@@ -146,4 +142,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
+      in [Server-side key backups](/client-server-api/#server-side-key-backups)
-      `room_id` and `session_id` fields.
+      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
+        Only [`m.space.child`](/client-server-api/#mspacechild) state events of the room are considered.
-        rooms and parent events are not covered by this endpoint.
+        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
+            suggested rooms. Suggested rooms are annotated in their [`m.space.child`](/client-server-api/#mspacechild)
-            contents.
+            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
+                                The [`m.space.child`](/client-server-api/#mspacechild) events of the space-room, represented
-                                as [Stripped State Events](#stripped-state) with an added `origin_server_ts` key.
+                                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:

data/api/client-server/sync.yaml

@@ -223,8 +223,8 @@ paths:
                                   The new ephemeral events in the room (events that
                                   aren't recorded in the timeline or state of the
                                   room). In this version of the spec, these are
-                                  [typing notification](#typing-notifications) and
+                                  [typing notification](/client-server-api/#typing-notifications)
-                                  [read receipt](#receipts) events.
+                                  and [read receipt](/client-server-api/#receipts) events.
                                 allOf:
                                   - $ref: definitions/event_batch.yaml
                               account_data:
@@ -245,7 +245,7 @@ paths:
 
                                   If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`,
                                   these counts will only be for the main timeline rather than all events in the room.
-                                  See the [threading module](#threading) for more information.
+                                  See the [threading module](/client-server-api/#threading) for more information.
                                 x-changedInMatrixVersion:
                                   "1.4": |
                                     Updated to reflect behaviour of having `unread_thread_notifications` as `true` in
@@ -265,8 +265,8 @@ paths:
                                 type: object
                                 description: |-
                                   If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`,
-                                  the notification counts for each [thread](#threading) in this room. The object is
+                                  the notification counts for each [thread](/client-server-api/#threading) in this room.
-                                  keyed by thread root ID, with values matching `unread_notifications`.
+                                  The object is keyed by thread root ID, with values matching `unread_notifications`.
 
                                   If a thread does not have any notifications it can be omitted from this object. If
                                   no threads have notification counts, this whole object can be omitted.
@@ -302,12 +302,13 @@ paths:
                                 title: InviteState
                                 type: object
                                 description: |-
-                                  The [stripped state](#stripped-state) of a room that the user has been invited
+                                  The [stripped state](/client-server-api/#stripped-state) of a room that the user has
-                                  to.
+                                  been invited to.
                                 properties:
                                   events:
-                                    description: The [stripped state events](#stripped-state) that form the invite
+                                    description: |-
-                                      state.
+                                      The [stripped state events](/client-server-api/#stripped-state) that form the
+                                      invite state.
                                     items:
                                       $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
                                     type: array
@@ -325,12 +326,14 @@ paths:
                               knock_state:
                                 title: KnockState
                                 type: object
-                                description: The [stripped state](#stripped-state) of a room that the user has
+                                description: |-
+                                  The [stripped state](/client-server-api/#stripped-state) of a room that the user has
                                   knocked upon.
                                 properties:
                                   events:
-                                    description: The [stripped state events](#stripped-state) that form the knock
+                                    description: |-
-                                      state.
+                                      The [stripped state events](/client-server-api/#stripped-state) that form the
+                                      knock state.
                                     items:
                                       $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
                                     type: array

data/api/client-server/whoami.yaml

@@ -57,9 +57,9 @@ paths:
                     x-addedInMatrixVersion: "1.2"
                     type: boolean
                     description: |-
-                      When `true`, the user is a [Guest User](#guest-access). When
+                      When `true`, the user is a [Guest User](/client-server-api/#guest-access).
-                      not present or `false`, the user is presumed to be a non-guest
+                      When not present or `false`, the user is presumed to be a 
-                      user.
+                      non-guest user.
               examples:
                 response:
                   value: {

data/api/server-server/events.yaml

@@ -216,8 +216,8 @@ paths:
         using the `origin_server_ts` property, whether the returned event is
         closer to the requested timestamp than the closest event that it could
         find locally.  If so, it should try to backfill this event via the
-        [`/event/{event_id}`](#get_matrixfederationv1eventeventid) endpoint so
+        [`/event/{event_id}`](/server-server-api/#get_matrixfederationv1eventeventid)
-        that it is available to for a client to query.
+        endpoint so that it is available to for a client to query.
       operationId: getEventByTimestamp
       security:
         - accessToken: []

data/api/server-server/joins-v1.yaml

@@ -155,7 +155,7 @@ paths:
             The request is invalid, the room the server is attempting
             to join has a version that is not listed in the `ver`
             parameters, or the server was unable to validate
-            [restricted room conditions](#restricted-rooms).
+            [restricted room conditions](/server-server-api/#restricted-rooms).
 
             The error should be passed through to clients so that they
             may give better feedback to users.

data/api/server-server/space_hierarchy.yaml

@@ -75,7 +75,7 @@ paths:
                             items:
                               type: string
                             description: |-
-                              If the room is a [restricted room](#restricted-rooms), these are the room IDs which
+                              If the room is a [restricted room](/server-server-api/#restricted-rooms), these are the room IDs which
                               are specified by the join rules. Empty or omitted otherwise.
                           children_state:
                             type: array
@@ -119,7 +119,7 @@ paths:
                               items:
                                 type: string
                               description: |-
-                                If the room is a [restricted room](#restricted-rooms), these are the room IDs which
+                                If the room is a [restricted room](/server-server-api/#restricted-rooms), these are the room IDs which
                                 are specified by the join rules. Empty or omitted otherwise.
                   inaccessible_children:
                     type: array

data/event-schemas/schema/m.forwarded_room_key.yaml

@@ -4,7 +4,7 @@ allOf:
 
 description: |-
   This event type is used to forward keys for end-to-end encryption.
-  It is encrypted as an `m.room.encrypted` event using [Olm](#molmv1curve25519-aes-sha2),
+  It is encrypted as an `m.room.encrypted` event using [Olm](/client-server-api/#molmv1curve25519-aes-sha2),
   then sent as a [to-device](/client-server-api/#send-to-device-messaging) event.
 properties:
   content:

data/event-schemas/schema/m.key.verification.request.yaml

@@ -5,7 +5,8 @@ allOf:
 description: |-
   Requests a key verification using to-device messaging.  When requesting a key
   verification in a room, a `m.room.message` should be used, with
-  [`m.key.verification.request`](#mroommessagemkeyverificationrequest) as msgtype.
+  [`m.key.verification.request`](/client-server-api/#mroommessagemkeyverificationrequest)
+  as msgtype.
 properties:
   content:
     properties:

data/event-schemas/schema/m.room.create.yaml

@@ -18,7 +18,8 @@ properties:
         type: string
       type:
         description: |-
-          Optional [room type](#types) to denote a room's intended function outside of traditional conversation.
+          Optional [room type](/client-server-api/#types) to denote a room's intended function outside of traditional
+          conversation.
 
           Unspecified room types are possible using [Namespaced Identifiers](/appendices/#common-namespaced-identifier-grammar).
         type: string

data/event-schemas/schema/m.room.encrypted.yaml

@@ -46,14 +46,15 @@ properties:
           "1.3": |-
             Previously this field was required, however given it offers no additional
             security or privacy benefit it has been deprecated for Megolm messages.
-            See [`m.megolm.v1.aes-sha2`](#mmegolmv1aes-sha2) for more information.
+            See [`m.megolm.v1.aes-sha2`](/client-server-api/#mmegolmv1aes-sha2) for
+            more information.
         description: |-
           The Curve25519 key of the sender. Required (not deprecated) if not using Megolm.
 
           **Deprecated**: This field provides no additional security or privacy benefit
           for Megolm messages and must not be read from if the encrypted event is using
           Megolm. It should still be included on outgoing messages, however must not be
-          used to find the corresponding session. See [`m.megolm.v1.aes-sha2`](#mmegolmv1aes-sha2)
+          used to find the corresponding session. See [`m.megolm.v1.aes-sha2`](/client-server-api/#mmegolmv1aes-sha2)
           for more information.
       device_id:
         type: string
@@ -62,15 +63,15 @@ properties:
           "1.3": |-
             Previously this field was required for Megolm messages, however given it
             offers no additional security or privacy benefit it has been deprecated
-            for Megolm messages. See [`m.megolm.v1.aes-sha2`](#mmegolmv1aes-sha2) for
+            for Megolm messages. See [`m.megolm.v1.aes-sha2`](/client-server-api/#mmegolmv1aes-sha2)
-            more information.
+            for more information.
         description: |-
           The ID of the sending device.
 
           **Deprecated**: This field provides no additional security or privacy benefit
           for Megolm messages and must not be read from if the encrypted event is using
           Megolm. It should still be included on outgoing messages, however must not be
-          used to find the corresponding session. See [`m.megolm.v1.aes-sha2`](#mmegolmv1aes-sha2)
+          used to find the corresponding session. See [`m.megolm.v1.aes-sha2`](/client-server-api/#mmegolmv1aes-sha2)
           for more information.
       session_id:
         type: string

data/event-schemas/schema/m.room.member.yaml

@@ -64,7 +64,7 @@ properties:
         type: string
         description: |-
           Usually found on `join` events, this field is used to denote which homeserver (through representation of a user with sufficient power level)
-          authorised the user's join. More information about this field can be found in the [Restricted Rooms Specification](#restricted-rooms).
+          authorised the user's join. More information about this field can be found in the [Restricted Rooms Specification](/client-server-api/#restricted-rooms).
 
           Client and server implementations should be aware of the [signing implications](/rooms/v8/#authorization-rules) of including this
           field in further events: in particular, the event must be signed by the server which

data/event-schemas/schema/m.room.message$m.key.verification.request.yaml

@@ -3,7 +3,7 @@ allOf:
   - $ref: core-event-schema/room_event.yaml
 description:
   Requests a key verification in a room.  When requesting a key verification
-  using to-device messaging, an event with type [`m.key.verification.request`](#mkeyverificationrequest)
+  using to-device messaging, an event with type [`m.key.verification.request`](/client-server-api/#mkeyverificationrequest)
   should be used.
 properties:
   content:

data/event-schemas/schema/m.room_key.yaml

@@ -4,7 +4,7 @@ allOf:
 
 description: |-
   This event type is used to exchange keys for end-to-end encryption.
-  It is encrypted as an `m.room.encrypted` event using [Olm](#molmv1curve25519-aes-sha2),
+  It is encrypted as an `m.room.encrypted` event using [Olm](/client-server-api/#molmv1curve25519-aes-sha2),
   then sent as a [to-device](/client-server-api/#send-to-device-messaging) event.
 properties:
   content:

data/event-schemas/schema/m.room_key_request.yaml

@@ -26,7 +26,7 @@ properties:
             x-changedInMatrixVersion:
               "1.3": |-
                 Previously this field was required, however given it offers no additional
-                security or privacy benefit it has been deprecated. See [`m.megolm.v1.aes-sha2`](#mmegolmv1aes-sha2)
+                security or privacy benefit it has been deprecated. See [`m.megolm.v1.aes-sha2`](/client-server-api/#mmegolmv1aes-sha2)
                 for more information.
             description: |-
               The Curve25519 key of the device which initiated the session originally.
@@ -34,7 +34,7 @@ properties:
               **Deprecated**: This field provides no additional security or privacy benefit
               and must not be read from. It should still be included on outgoing messages
               (if the event for which keys are being requested for *also* has a `sender_key`),
-              however must not be used to find the corresponding session. See [`m.megolm.v1.aes-sha2`](#mmegolmv1aes-sha2)
+              however must not be used to find the corresponding session. See [`m.megolm.v1.aes-sha2`](/client-server-api/#mmegolmv1aes-sha2)
               for more information.
           session_id:
             type: string

data/event-schemas/schema/m.secret.send.yaml

@@ -4,7 +4,8 @@ allOf:
 description: |-
   Sent by a client to share a secret with another device, in response to an
   `m.secret.request` event. It must be encrypted as an `m.room.encrypted` event
-  using [Olm](#molmv1curve25519-aes-sha2), then sent as a to-device event.
+  using [Olm](/client-server-api/#molmv1curve25519-aes-sha2), then sent as a
+  to-device event.
 
   The `request_id` must match the ID previously given in an `m.secret.request`
   event. The recipient must ensure that this event comes from a device that the

data/event-schemas/schema/m.space.child.yaml

@@ -1,7 +1,7 @@
 ---
 allOf:
   - $ref: core-event-schema/state_event.yaml
-description: Defines the relationship of a child room to a space-room. Has no effect in rooms which are not [spaces](#spaces).
+description: Defines the relationship of a child room to a space-room. Has no effect in rooms which are not [spaces](/client-server-api/#spaces).
 properties:
   content:
     properties:

data/string-formats.yaml

@@ -38,27 +38,27 @@
 
 mx-user-id:
   title: User ID
-  url: /appendices#user-identifiers
+  url: appendices#user-identifiers
   # regex: "^@"
 
 mx-event-id:
   title: Event ID
-  url: /appendices#event-ids
+  url: appendices#event-ids
   # regex: "^\\$"
 
 mx-room-id:
   title: Room ID
-  url: /appendices#room-ids
+  url: appendices#room-ids
   # regex: "^!"
 
 mx-server-name:
   title: Server Name
-  url: /appendices#server-name
+  url: appendices#server-name
   # no regex
 
 mx-mxc-uri:
   title: Matrix Content URI
-  url: /client-server-api#matrix-content-mxc-uris
+  url: client-server-api#matrix-content-mxc-uris
   # regex: "^mxc:\\/\\/"
 
 uri:

go.mod

@@ -2,4 +2,4 @@ module github.com/matrix-org/matrix-spec
 
 go 1.12
 
-require github.com/matrix-org/docsy v0.0.0-20231227121313-d55dbaf3aaaf // indirect
+require github.com/matrix-org/docsy v0.0.0-20241030165433-a14705b7e3ca // indirect

go.sum

@@ -1,4 +1,4 @@
 github.com/FortAwesome/Font-Awesome v0.0.0-20230327165841-0698449d50f2/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
-github.com/matrix-org/docsy v0.0.0-20231227121313-d55dbaf3aaaf h1:e1mutHvMYJ92F/VkAp2ixQthXf6zNHJll4wYGbBHznI=
+github.com/matrix-org/docsy v0.0.0-20241030165433-a14705b7e3ca h1:WqKYQIF3JdWxY6b+OZQbdCjczOmELuUxpXhXSXJ/F58=
-github.com/matrix-org/docsy v0.0.0-20231227121313-d55dbaf3aaaf/go.mod h1:TAN2cSMJzy0hnx9OYDbBYluS8raV61UHxT/tfjaLt3g=
+github.com/matrix-org/docsy v0.0.0-20241030165433-a14705b7e3ca/go.mod h1:TAN2cSMJzy0hnx9OYDbBYluS8raV61UHxT/tfjaLt3g=
 github.com/twbs/bootstrap v5.2.3+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=

layouts/404.html

@@ -2,7 +2,7 @@
     <main id="main">
       <div>
        <h1 id="title">Not found</h1>
-          <p>This page doesn't exist. Try going back to the <a href="{{ "/" | relURL }}">main page for the Matrix Specification</a>.</p>
+          <p>This page doesn't exist. Try going back to the <a href="{{ "" | relURL }}">main page for the Matrix Specification</a>.</p>
       </div>
     </main>
 {{ end }}

layouts/partials/alert.html

@@ -16,5 +16,5 @@
 {{ $omit_title := .omit_title }}
 
 <div class="alert {{ $type }} {{ if $omit_title }}omit-title{{end}}" role="alert">
-{{ $content | markdownify }}
+{{ $content }}
 </div>

layouts/partials/hooks/body-end.html

@@ -6,5 +6,5 @@
   the place we are at in the document.
 
 */}}
-
+{{ $toc := resources.Get "js/toc.js" -}}
-<script defer language="javascript" type="text/javascript"  src="{{ "js/toc.js" | relURL }}"></script>
+<script defer language="javascript" type="text/javascript"  src="{{ $toc.RelPermalink }}"></script>

layouts/partials/hooks/head-end.html

@@ -13,5 +13,6 @@
  Google Fonts manually via a script:
  https://github.com/matrix-org/matrix-spec/tree/main/static/css/fonts
 */}}
-<link rel="preload" href="{{ "/css/fonts/Inter.css" | relURL }}" as="style">
+{{ $inter := resources.Get "css/fonts/Inter.css" -}}
-<link rel="stylesheet" href="{{ "/css/fonts/Inter.css" | relURL }}">
+<link rel="preload" href="{{ $inter.RelPermalink }}" as="style">
+<link rel="stylesheet" href="{{ $inter.RelPermalink }}">

layouts/partials/openapi/render-object-table.html

@@ -335,7 +335,7 @@ resolve-additional-types.)
   {{ $stringFormat := "" }}
 
   {{ with index site.Data "string-formats" . }}
-    {{ $stringFormat = printf "<a href=\"%s\">%s</a>" (htmlEscape .url) (htmlEscape .title) }}
+    {{ $stringFormat = printf "<a href=\"%s\">%s</a>" (htmlEscape .url | relURL) (htmlEscape .title) }}
   {{ end }}
 
   {{ return $stringFormat }}