Add link checker to CI

.github/workflows/main.yml

@@ -142,6 +142,28 @@ jobs:
           name: spec-artifact
           path: spec.tar.gz
 
+  htmlcheck:
+    name: "🔎 Validate generated HTML"
+    runs-on: ubuntu-latest
+    needs: [build-spec]
+    steps:
+      - name: "📥 Source checkout"
+        uses: actions/checkout@v2
+
+      - name: "📥 Fetch built spec"
+        uses: actions/download-artifact@v2
+        with:
+          name: spec-artifact
+
+      - name: "📝 Unpack the spec"
+        run: |
+          tar -xvzf spec.tar.gz
+
+      - name: "Run htmltest"
+        uses: wjdp/htmltest-action@master
+        with:
+          config: .htmltest.yaml
+
   build-historical-spec:
     name: "📖 Build the historical backup spec"
     runs-on: ubuntu-latest

.htmltest.yaml

@@ -0,0 +1,6 @@
+# config file for htmltest. This is used by one of the checks in Github
+# Actions.
+
+IgnoreDirectoryMissingTrailingSlash: true
+DirectoryPath: spec
+CheckExternal: false

changelogs/client_server/newsfragments/1330.clarification

@@ -0,0 +1 @@
+Fix a number of broken links in the specification.

changelogs/identity_service/newsfragments/1330.clarification

@@ -0,0 +1 @@
+Fix a number of broken links in the specification.

changelogs/internal/newsfragments/1329.clarification

@@ -0,0 +1 @@
+Use a link checker to ensure that we do not have broken links.

changelogs/room_versions/newsfragments/1330.clarification

@@ -0,0 +1 @@
+Fix a number of broken links in the specification.

changelogs/server_server/newsfragments/1330.clarification

@@ -0,0 +1 @@
+Fix a number of broken links in the specification.

content/client-server-api/_index.md

@@ -2527,7 +2527,7 @@ that profile.
 | [Instant Messaging](#instant-messaging)                    | Required  | Required | Required | Required | Optional |
 | [Rich replies](#rich-replies)                              | Optional  | Optional | Optional | Optional | Optional |
 | [Direct Messaging](#direct-messaging)                      | Required  | Required | Required | Required | Optional |
-| [Mentions](#user-room-and-group-mentions)                  | Required  | Required | Required | Optional | Optional |
+| [Mentions](#user-and-room-mentions)                        | Required  | Required | Required | Optional | Optional |
 | [Presence](#presence)                                      | Required  | Required | Required | Required | Optional |
 | [Push Notifications](#push-notifications)                  | Optional  | Required | Optional | Optional | Optional |
 | [Receipts](#receipts)                                      | Required  | Required | Required | Required | Optional |

content/client-server-api/modules/end_to_end_encryption.md

@@ -180,7 +180,7 @@ process:
     the resulting list of devices in persistent storage, and clears the
     'outdated' flag.
 3.  During its normal processing of responses to [`/sync`](/client-server-api/#get_matrixclientv3sync), Alice's client
-    inspects the `changed` property of the [`device_lists`](/client-server-api/#extensions-to-sync-1) field. If it
+    inspects the `changed` property of the [`device_lists`](#e2e-extensions-to-sync) field. If it
     is tracking the device lists of any of the listed users, then it
     marks the device lists for those users outdated, and initiates
     another request to [`/keys/query`](/client-server-api/#post_matrixclientv3keysquery) for them.
@@ -1614,7 +1614,7 @@ When a client is updating a Megolm session (room key) in its store, the client M
 
 {{% http-api spec="client-server" api="keys" %}}
 
-##### Extensions to /sync
+##### <a name="e2e-extensions-to-sync"> Extensions to /sync
 
 This module adds an optional `device_lists` property to the [`/sync`](/client-server-api/#get_matrixclientv3sync)  response,
 as specified below. The server need only populate this property for an

content/client-server-api/modules/event_replacements.md

@@ -256,8 +256,8 @@ unable to do so. This happens in the following situations:
  * The original event (and hence its replacement) are encrypted.
 
 Client authors are reminded to take note of the requirements for [Validity of
-message edit events](#validity-of-message-edit-events), and to ignore any
-invalid edit events that are received.
+replacement events](#validity-of-replacement-events), and to ignore any
+invalid replacement events that are received.
 
 ##### Permalinks
 

content/client-server-api/modules/spaces.md

@@ -99,7 +99,7 @@ relevant state event, such as through redaction or otherwise clearing the `conte
 
 {{% event event="m.space.child" %}}
 
-###### Ordering
+###### Ordering of children within a space
 
 When the client is displaying the children of a space, the children should be ordered
 using the algorithm below. In some cases, like a traditional left side room list, the

content/client-server-api/modules/typing_notifications.md

@@ -4,7 +4,7 @@
 Users may wish to be informed when another user is typing in a room.
 This can be achieved using typing notifications. These are ephemeral
 events, so they do not form part of the
-[Event Graph](index.html#event-graphs). Typing notifications are scoped
+[Event Graph](/#event-graphs). Typing notifications are scoped
 to a room.
 
 #### Events

content/identity-service-api.md

@@ -31,7 +31,7 @@ not necessarily provide evidence that they have validated associations,
 but claim to have done so. Establishing the trustworthiness of an
 individual identity server is left as an exercise for the client.
 
-3PID types are described in [3PID Types](/appendices#pid-types)
+3PID types are described in [3PID Types](/appendices#3pid-types)
 Appendix.
 
 ## API standards

content/rooms/fragments/v1-auth-rules.md

@@ -3,7 +3,7 @@ The types of state events that affect authorization are:
 
 -   [`m.room.create`](/client-server-api#mroomcreate)
 -   [`m.room.member`](/client-server-api#mroommember)
--   [`m.room.join_rules`](/client-server-api#mroom)
+-   [`m.room.join_rules`](/client-server-api#mroomjoin_rules)
 -   [`m.room.power_levels`](/client-server-api#mroompower_levels)
 -   [`m.room.third_party_invite`](/client-server-api#mroomthird_party_invite)
 
@@ -32,7 +32,7 @@ The rules are as follows:
         algorithm described in the server specification, reject.
     3.  If there are entries which were themselves rejected under the [checks
         performed on receipt of a
-        PDU](server-server-api/#checks-performed-on-receipt-of-a-pdu), reject.
+        PDU](/server-server-api/#checks-performed-on-receipt-of-a-pdu), reject.
     4. If there is no `m.room.create` event among the entries, reject.
 3. If the `content` of the `m.room.create` event in the room state has the
    property `m.federate` set to `false`, and the `sender` domain of the event

content/rooms/fragments/v3-auth-rules.md

@@ -11,7 +11,7 @@ The types of state events that affect authorization are:
 
 -   [`m.room.create`](/client-server-api#mroomcreate)
 -   [`m.room.member`](/client-server-api#mroommember)
--   [`m.room.join_rules`](/client-server-api#mroom)
+-   [`m.room.join_rules`](/client-server-api#mroomjoin_rules)
 -   [`m.room.power_levels`](/client-server-api#mroompower_levels)
 -   [`m.room.third_party_invite`](/client-server-api#mroomthird_party_invite)
 
@@ -40,7 +40,7 @@ The complete list of rules, as of room version 3, is as follows:
         algorithm described in the server specification, reject.
     3.  If there are entries which were themselves rejected under the [checks
         performed on receipt of a
-        PDU](server-server-api/#checks-performed-on-receipt-of-a-pdu), reject.
+        PDU](/server-server-api/#checks-performed-on-receipt-of-a-pdu), reject.
     4. If there is no `m.room.create` event among the entries, reject.
 3. If the `content` of the `m.room.create` event in the room state has the
    property `m.federate` set to `false`, and the `sender` domain of the event

content/rooms/fragments/v8-auth-rules.md

@@ -11,7 +11,7 @@ The types of state events that affect authorization are:
 
 -   [`m.room.create`](/client-server-api#mroomcreate)
 -   [`m.room.member`](/client-server-api#mroommember)
--   [`m.room.join_rules`](/client-server-api#mroom)
+-   [`m.room.join_rules`](/client-server-api#mroomjoin_rules)
 -   [`m.room.power_levels`](/client-server-api#mroompower_levels)
 -   [`m.room.third_party_invite`](/client-server-api#mroomthird_party_invite)
 
@@ -40,7 +40,7 @@ The rules are as follows:
         algorithm described in the server specification, reject.
     3.  If there are entries which were themselves rejected under the [checks
         performed on receipt of a
-        PDU](server-server-api/#checks-performed-on-receipt-of-a-pdu), reject.
+        PDU](/server-server-api/#checks-performed-on-receipt-of-a-pdu), reject.
     4. If there is no `m.room.create` event among the entries, reject.
 3. If the `content` of the `m.room.create` event in the room state has the
    property `m.federate` set to `false`, and the `sender` domain of the event

content/rooms/v10.md

@@ -86,7 +86,7 @@ The types of state events that affect authorization are:
 
 -   [`m.room.create`](/client-server-api#mroomcreate)
 -   [`m.room.member`](/client-server-api#mroommember)
--   [`m.room.join_rules`](/client-server-api#mroom)
+-   [`m.room.join_rules`](/client-server-api#mroomjoin_rules)
 -   [`m.room.power_levels`](/client-server-api#mroompower_levels)
 -   [`m.room.third_party_invite`](/client-server-api#mroomthird_party_invite)
 
@@ -115,7 +115,7 @@ The rules are as follows:
         algorithm described in the server specification, reject.
     3.  If there are entries which were themselves rejected under the [checks
         performed on receipt of a
-        PDU](server-server-api/#checks-performed-on-receipt-of-a-pdu), reject.
+        PDU](/server-server-api/#checks-performed-on-receipt-of-a-pdu), reject.
     4. If there is no `m.room.create` event among the entries, reject.
 3. If the `content` of the `m.room.create` event in the room state has the
    property `m.federate` set to `false`, and the `sender` domain of the event

content/rooms/v6.md

@@ -61,7 +61,7 @@ The types of state events that affect authorization are:
 
 -   [`m.room.create`](/client-server-api#mroomcreate)
 -   [`m.room.member`](/client-server-api#mroommember)
--   [`m.room.join_rules`](/client-server-api#mroom)
+-   [`m.room.join_rules`](/client-server-api#mroomjoin_rules)
 -   [`m.room.power_levels`](/client-server-api#mroompower_levels)
 -   [`m.room.third_party_invite`](/client-server-api#mroomthird_party_invite)
 

content/rooms/v7.md

@@ -47,7 +47,7 @@ The types of state events that affect authorization are:
 
 -   [`m.room.create`](/client-server-api#mroomcreate)
 -   [`m.room.member`](/client-server-api#mroommember)
--   [`m.room.join_rules`](/client-server-api#mroom)
+-   [`m.room.join_rules`](/client-server-api#mroomjoin_rules)
 -   [`m.room.power_levels`](/client-server-api#mroompower_levels)
 -   [`m.room.third_party_invite`](/client-server-api#mroomthird_party_invite)
 

content/server-server-api.md

@@ -853,7 +853,7 @@ on the resulting `m.room.member` event.
 If the joining server fails all conditions then a 403 `M_FORBIDDEN` error
 is used by the resident server.
 
-## Knocking upon a room
+## <a name="knocking-rooms"> Knocking upon a room
 
 Rooms can permit knocking through the join rules, and if permitted this
 gives users a way to request to join (be invited) to the room. Users who

data/api/client-server/inviting.yaml

@@ -35,8 +35,8 @@ paths:
       description: |-
         *Note that there are two forms of this API, which are documented separately.
         This version of the API requires that the inviter knows the Matrix
-        identifier of the invitee. The other is documented in the*
-        [third party invites section](/client-server-api/#post_matrixclientv3roomsroomidinvite-1).
+        identifier of the invitee. The other is documented in the
+        [third party invites](/client-server-api/#third-party-invites) section.*
 
         This API invites a user to participate in a particular room.
         They do not start participating in the room until they actually join the

data/api/client-server/sync.yaml

@@ -383,15 +383,15 @@ paths:
                 type: object
                 description: |-
                   Information on end-to-end device updates, as specified in
-                  [End-to-end encryption](/client-server-api/#extensions-to-sync-1).
+                  [End-to-end encryption](/client-server-api/#e2e-extensions-to-sync).
               device_one_time_keys_count:
                 title: One-time keys count
                 type: object
                 additionalProperties:
                   type: integer
                 description: |-
                   Information on end-to-end encryption keys, as specified
-                  in [End-to-end encryption](/client-server-api/#extensions-to-sync-1).
+                  in [End-to-end encryption](/client-server-api/#e2e-extensions-to-sync).
             required:
               - next_batch
           examples:

data/api/client-server/threads_list.yaml

@@ -51,7 +51,7 @@ paths:
           description: |-
             Optional (default `all`) flag to denote which thread roots are of interest to the caller.
             When `all`, all thread roots found in the room are returned. When `participated`, only
-            thread roots for threads the user has [participated in](/client-server-api/#server-side-aggreagtion-of-mthread-relationships)
+            thread roots for threads the user has [participated in](/client-server-api/#server-side-aggregation-of-mthread-relationships)
             will be returned.
           x-example: "all"
         - in: query

data/api/identity/v2_lookup.yaml

@@ -103,7 +103,7 @@ paths:
                   hashed or formatted will lead to no matches.
 
                   Note that addresses are case sensitive: review the
-                  [3PID Types](/appendices#pid-types) to verify the intended case an
+                  [3PID Types](/appendices#3pid-types) to verify the intended case an
                   identifier should be prior to submission/hashing.
                 example: [
                   "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc",

data/api/server-server/space_hierarchy.yaml

@@ -36,7 +36,7 @@ paths:
         the space-room's children the requesting server could feasibly peek/join are returned. The
         requesting server is responsible for filtering the results further down for the user's request.
 
-        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. Invalid child
         rooms and parent events are not covered by this endpoint.
 
         Responses to this endpoint should be cached for a period of time.
@@ -55,7 +55,7 @@ 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) event
             contents.
           x-example: true
       responses:

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

@@ -4,7 +4,8 @@ allOf:
 
 description: |-
   This event type is used when sending encrypted events. It can be used either
-  within a room (in which case it will have all of the [Room Event fields](/client-server-api/#room-event-fields)), or
+  within a room (in which case it will have all of the normal properties in
+  [Room events](/client-server-api/#room-event-format)), or
   as a [to-device](/client-server-api/#send-to-device-messaging) event.
 
 properties:

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

@@ -27,7 +27,7 @@ properties:
           `order` values with the wrong type, or otherwise invalid contents, are to be treated
           as though the `order` key was not provided.
 
-          See [Ordering](/client-server-api/#ordering-1) for information on how the ordering works.
+          See [Ordering of children within a space](/client-server-api/#ordering-of-children-within-a-space) for information on how the ordering works.
       suggested:
         type: boolean
         description: |-