diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 0c8301f3b..ce54f976b 100644
--- a/.github/workflows/main.yml
+++ b/.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
diff --git a/.htmltest.yaml b/.htmltest.yaml
new file mode 100644
index 000000000..1563408b3
--- /dev/null
+++ b/.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
diff --git a/changelogs/client_server/newsfragments/1330.clarification b/changelogs/client_server/newsfragments/1330.clarification
new file mode 100644
index 000000000..5c0e57d84
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1330.clarification
@@ -0,0 +1 @@
+Fix a number of broken links in the specification.
diff --git a/changelogs/identity_service/newsfragments/1330.clarification b/changelogs/identity_service/newsfragments/1330.clarification
new file mode 100644
index 000000000..5c0e57d84
--- /dev/null
+++ b/changelogs/identity_service/newsfragments/1330.clarification
@@ -0,0 +1 @@
+Fix a number of broken links in the specification.
diff --git a/changelogs/internal/newsfragments/1329.clarification b/changelogs/internal/newsfragments/1329.clarification
new file mode 100644
index 000000000..c5b60e246
--- /dev/null
+++ b/changelogs/internal/newsfragments/1329.clarification
@@ -0,0 +1 @@
+Use a link checker to ensure that we do not have broken links.
diff --git a/changelogs/room_versions/newsfragments/1330.clarification b/changelogs/room_versions/newsfragments/1330.clarification
new file mode 100644
index 000000000..5c0e57d84
--- /dev/null
+++ b/changelogs/room_versions/newsfragments/1330.clarification
@@ -0,0 +1 @@
+Fix a number of broken links in the specification.
diff --git a/changelogs/server_server/newsfragments/1330.clarification b/changelogs/server_server/newsfragments/1330.clarification
new file mode 100644
index 000000000..5c0e57d84
--- /dev/null
+++ b/changelogs/server_server/newsfragments/1330.clarification
@@ -0,0 +1 @@
+Fix a number of broken links in the specification.
diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index d6dec7a2b..6ab6f46a4 100644
--- a/content/client-server-api/_index.md
+++ b/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 |
diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md
index f701aff8a..78e1ef29b 100644
--- a/content/client-server-api/modules/end_to_end_encryption.md
+++ b/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
+##### 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
diff --git a/content/client-server-api/modules/event_replacements.md b/content/client-server-api/modules/event_replacements.md
index 4fedf5016..a4257fc3a 100644
--- a/content/client-server-api/modules/event_replacements.md
+++ b/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
diff --git a/content/client-server-api/modules/spaces.md b/content/client-server-api/modules/spaces.md
index 797e800cf..cf192a692 100644
--- a/content/client-server-api/modules/spaces.md
+++ b/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
diff --git a/content/client-server-api/modules/typing_notifications.md b/content/client-server-api/modules/typing_notifications.md
index 3c09e9b30..55efc709f 100644
--- a/content/client-server-api/modules/typing_notifications.md
+++ b/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
diff --git a/content/identity-service-api.md b/content/identity-service-api.md
index 9c5a93c47..eac159b7c 100644
--- a/content/identity-service-api.md
+++ b/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
diff --git a/content/rooms/fragments/v1-auth-rules.md b/content/rooms/fragments/v1-auth-rules.md
index 4fd7faf4f..e15a93d5f 100644
--- a/content/rooms/fragments/v1-auth-rules.md
+++ b/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
diff --git a/content/rooms/fragments/v3-auth-rules.md b/content/rooms/fragments/v3-auth-rules.md
index f69928445..05b8065a8 100644
--- a/content/rooms/fragments/v3-auth-rules.md
+++ b/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
diff --git a/content/rooms/fragments/v8-auth-rules.md b/content/rooms/fragments/v8-auth-rules.md
index 07833ad68..98a88bf1c 100644
--- a/content/rooms/fragments/v8-auth-rules.md
+++ b/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
diff --git a/content/rooms/v10.md b/content/rooms/v10.md
index 628f14e15..46bdb4c77 100644
--- a/content/rooms/v10.md
+++ b/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
diff --git a/content/rooms/v6.md b/content/rooms/v6.md
index bcacfef8a..977f5479d 100644
--- a/content/rooms/v6.md
+++ b/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)
diff --git a/content/rooms/v7.md b/content/rooms/v7.md
index 3cc77bb31..40a9962cb 100644
--- a/content/rooms/v7.md
+++ b/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)
diff --git a/content/server-server-api.md b/content/server-server-api.md
index 2a034c355..7b33a9569 100644
--- a/content/server-server-api.md
+++ b/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
+## 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
diff --git a/data/api/client-server/inviting.yaml b/data/api/client-server/inviting.yaml
index c24e5f491..96e3dae2f 100644
--- a/data/api/client-server/inviting.yaml
+++ b/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
diff --git a/data/api/client-server/sync.yaml b/data/api/client-server/sync.yaml
index 93265cae8..dce3c63e0 100644
--- a/data/api/client-server/sync.yaml
+++ b/data/api/client-server/sync.yaml
@@ -383,7 +383,7 @@ 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
@@ -391,7 +391,7 @@ paths:
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:
diff --git a/data/api/client-server/threads_list.yaml b/data/api/client-server/threads_list.yaml
index c0c9cbd02..af875fbfd 100644
--- a/data/api/client-server/threads_list.yaml
+++ b/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
diff --git a/data/api/identity/v2_lookup.yaml b/data/api/identity/v2_lookup.yaml
index 66ac1a0a3..d5e9352c1 100644
--- a/data/api/identity/v2_lookup.yaml
+++ b/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",
diff --git a/data/api/server-server/space_hierarchy.yaml b/data/api/server-server/space_hierarchy.yaml
index ccc7c6f14..296fb6579 100644
--- a/data/api/server-server/space_hierarchy.yaml
+++ b/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:
diff --git a/data/event-schemas/schema/m.room.encrypted.yaml b/data/event-schemas/schema/m.room.encrypted.yaml
index 51024f7e2..84461013c 100644
--- a/data/event-schemas/schema/m.room.encrypted.yaml
+++ b/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:
diff --git a/data/event-schemas/schema/m.space.child.yaml b/data/event-schemas/schema/m.space.child.yaml
index afdfefa9b..feef0adcd 100644
--- a/data/event-schemas/schema/m.space.child.yaml
+++ b/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: |-