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

1 year ago · bf8dee74eb
parent b1f66d1b71
commit bf8dee74eb
61 changed files with 101 additions and 92 deletions
--- a/.github/workflows/main.yml
+++ b/.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
--- a/assets/css/fonts/Inter.css
+++ b/assets/css/fonts/Inter.css
--- a/assets/css/fonts/README.md
+++ b/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 
 ```
  
--- a/assets/css/fonts/download_google_fonts_css.py
+++ b/assets/css/fonts/download_google_fonts_css.py
--- a/assets/css/fonts/requirements.txt
+++ b/assets/css/fonts/requirements.txt
--- a/assets/diagrams/README.md
+++ b/assets/diagrams/README.md
--- a/assets/diagrams/membership.drawio
+++ b/assets/diagrams/membership.drawio
--- a/assets/diagrams/membership.png
+++ b/assets/diagrams/membership.png
--- a/assets/diagrams/threaded-dag-threads.drawio
+++ b/assets/diagrams/threaded-dag-threads.drawio
--- a/assets/diagrams/threaded-dag-threads.png
+++ b/assets/diagrams/threaded-dag-threads.png
--- a/assets/diagrams/threaded-dag.drawio
+++ b/assets/diagrams/threaded-dag.drawio
--- a/assets/diagrams/threaded-dag.png
+++ b/assets/diagrams/threaded-dag.png
--- a/assets/js/toc.js
+++ b/assets/js/toc.js
--- a/changelogs/header.md
+++ b/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 -->
--- a/changelogs/internal/newsfragments/1984.clarification
+++ b/changelogs/internal/newsfragments/1984.clarification
@ -0,0 +1 @@
+Fix relative URLs when serving the specification with a custom `baseURL`.
--- a/config.toml
+++ b/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
--- a/content/changelog/v1.1.md
+++ b/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 -->
--- a/content/changelog/v1.10.md
+++ b/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 -->
--- a/content/changelog/v1.11.md
+++ b/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 -->
--- a/content/changelog/v1.12.md
+++ b/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 -->
--- a/content/changelog/v1.2.md
+++ b/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 -->
--- a/content/changelog/v1.3.md
+++ b/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 -->
--- a/content/changelog/v1.4.md
+++ b/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 -->
--- a/content/changelog/v1.5.md
+++ b/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 -->
--- a/content/changelog/v1.6.md
+++ b/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 -->
--- a/content/changelog/v1.7.md
+++ b/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 -->
--- a/content/changelog/v1.8.md
+++ b/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 -->
--- a/content/changelog/v1.9.md
+++ b/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 -->
--- a/data/api/client-server/account-data.yaml
+++ b/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: []
--- a/data/api/client-server/appservice_ping.yaml
+++ b/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
--- a/data/api/client-server/definitions/auth_data.yaml
+++ b/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.
--- a/data/api/client-server/definitions/key_backup_session_data.yaml
+++ b/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: |-
--- a/data/api/client-server/definitions/megolm_export_session_data.yaml
+++ b/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
--- a/data/api/client-server/definitions/timeline_batch.yaml
+++ b/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
--- a/data/api/client-server/old_sync.yaml
+++ b/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
--- a/data/api/client-server/room_event_by_timestamp.yaml
+++ b/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
--- a/data/api/client-server/room_initial_sync.yaml
+++ b/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
--- a/data/api/client-server/space_hierarchy.yaml
+++ b/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:
--- a/data/api/client-server/sync.yaml
+++ b/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
-                                  [read receipt](#receipts) events.
+                                  [typing notification](/client-server-api/#typing-notifications)
+                                  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
-                                  keyed by thread root ID, with values matching `unread_notifications`.
+                                  the notification counts for each [thread](/client-server-api/#threading) in this room.
+                                  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
-                                  to.
+                                  The [stripped state](/client-server-api/#stripped-state) of a room that the user has
+                                  been invited to.
                                properties:
                                  events:
-                                    description: The [stripped state events](#stripped-state) that form the invite
-                                      state.
+                                    description: |-
+                                      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
-                                      state.
+                                    description: |-
+                                      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
--- a/data/api/client-server/whoami.yaml
+++ b/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
-                      not present or `false`, the user is presumed to be a non-guest
-                      user.
+                      When `true`, the user is a [Guest User](/client-server-api/#guest-access).
+                      When not present or `false`, the user is presumed to be a 
+                      non-guest user.
              examples:
                response:
                  value: {
--- a/data/api/server-server/events.yaml
+++ b/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
-        that it is available to for a client to query.
+        [`/event/{event_id}`](/server-server-api/#get_matrixfederationv1eventeventid)
+        endpoint so that it is available to for a client to query.
      operationId: getEventByTimestamp
      security:
        - accessToken: []
--- a/data/api/server-server/joins-v1.yaml
+++ b/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.
--- a/data/api/server-server/space_hierarchy.yaml
+++ b/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
--- a/data/event-schemas/schema/m.forwarded_room_key.yaml
+++ b/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:
--- a/data/event-schemas/schema/m.key.verification.request.yaml
+++ b/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:
--- a/data/event-schemas/schema/m.room.create.yaml
+++ b/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
--- a/data/event-schemas/schema/m.room.encrypted.yaml
+++ b/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
-            more information.
+            for Megolm messages. See [`m.megolm.v1.aes-sha2`](/client-server-api/#mmegolmv1aes-sha2)
+            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
--- a/data/event-schemas/schema/m.room.member.yaml
+++ b/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
--- a/data/event-schemas/schema/m.room.message$m.key.verification.request.yaml
+++ b/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:
--- a/data/event-schemas/schema/m.room_key.yaml
+++ b/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:
--- a/data/event-schemas/schema/m.room_key_request.yaml
+++ b/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
--- a/data/event-schemas/schema/m.secret.send.yaml
+++ b/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
--- a/data/event-schemas/schema/m.space.child.yaml
+++ b/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:
--- a/data/string-formats.yaml
+++ b/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:
--- a/go.mod
+++ b/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
--- a/go.sum
+++ b/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-20231227121313-d55dbaf3aaaf/go.mod h1:TAN2cSMJzy0hnx9OYDbBYluS8raV61UHxT/tfjaLt3g=
+github.com/matrix-org/docsy v0.0.0-20241030165433-a14705b7e3ca h1:WqKYQIF3JdWxY6b+OZQbdCjczOmELuUxpXhXSXJ/F58=
+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=
--- a/layouts/404.html
+++ b/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 }}
--- a/layouts/partials/alert.html
+++ b/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>
--- a/layouts/partials/hooks/body-end.html
+++ b/layouts/partials/hooks/body-end.html
@ -6,5 +6,5 @@
  the place we are at in the document.

 */}}
-
-<script defer language="javascript" type="text/javascript"  src="{{ "js/toc.js" | relURL }}"></script>
+{{ $toc := resources.Get "js/toc.js" -}}
+<script defer language="javascript" type="text/javascript"  src="{{ $toc.RelPermalink }}"></script>
--- a/layouts/partials/hooks/head-end.html
+++ b/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">
-<link rel="stylesheet" href="{{ "/css/fonts/Inter.css" | relURL }}">
+{{ $inter := resources.Get "css/fonts/Inter.css" -}}
+<link rel="preload" href="{{ $inter.RelPermalink }}" as="style">
+<link rel="stylesheet" href="{{ $inter.RelPermalink }}">
--- a/layouts/partials/openapi/render-object-table.html
+++ b/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 }}
				`@ -0,0 +1 @@`
				Fix relative URLs when serving the specification with a custom `baseURL`.