wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Fix the table of content for room versions (#1884)

Browse source 
* Fix ToC for room versions pages

Like for the cs-module shortcode, use .RenderShortcodes
instead of .Content for the rver-fragment shortcode,
so the headings are detected by Hugo.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Change the way "this version" is detected in added-in and changed-in shortcodes

Now that we use .RenderShortcodes in the rver-fragment shortcode,
we cannot remove the output of these shortcodes dynamically
because they are replaced by a temporary placeholder due to Hugo's internals.

Instead, since the `this` parameter was only used for room version,
we always use the `v` parameter and compare with the version
provided in the page's front matter.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add version front matter for v11

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Update changelogs/room_versions/newsfragments/1884.clarification

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Co-authored-by: Travis Ralston <travpc@gmail.com>
This commit is contained in:
Kévin Commaille 2024-06-20 17:47:09 +02:00 • committed by GitHub
parent 18628dc5d7
commit 3af77f0cb4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
20 changed files with 60 additions and 51 deletions
Download patch file Download diff file Expand all files Collapse all files

1
changelogs/room_versions/newsfragments/1884.clarification Normal file
View file

@ -0,0 +1 @@
Generate the Table of Contents with Hugo rather than JavaScript.

2
content/rooms/fragments/v3-auth-rules.md
View file

@ -1,6 +1,6 @@
--- ---
--- ---
{{< added-in this=true >}} In room versions 1 and 2, events need a {{< added-in v=3 >}} In room versions 1 and 2, events need a
signature from the domain of the `event_id` in order to be considered signature from the domain of the `event_id` in order to be considered
valid. This room version does not include an `event_id` over federation valid. This room version does not include an `event_id` over federation
in the same respect, so does not need a signature from that server. in the same respect, so does not need a signature from that server.

2
content/rooms/fragments/v3-handling-redactions.md
View file

@ -1,6 +1,6 @@
--- ---
--- ---
{{% added-in this=true %}} In room versions 1 and 2, redactions were {{% added-in v=3 %}} In room versions 1 and 2, redactions were
explicitly part of the [authorization rules](/rooms/v1/#authorization-rules) explicitly part of the [authorization rules](/rooms/v1/#authorization-rules)
under Rule 11. As of room version 3, these conditions no longer exist as under Rule 11. As of room version 3, these conditions no longer exist as
represented by [this version's authorization rules](#authorization-rules). represented by [this version's authorization rules](#authorization-rules).

2
content/rooms/fragments/v4-event-ids.md
View file

@ -1,6 +1,6 @@
--- ---
--- ---
{{% added-in this=true %}} The event ID is the [reference {{% added-in v=4 %}} The event ID is the [reference
hash](/server-server-api#calculating-the-reference-hash-for-an-event) of hash](/server-server-api#calculating-the-reference-hash-for-an-event) of
the event encoded using a variation of [Unpadded the event encoded using a variation of [Unpadded
Base64](/appendices#unpadded-base64) which replaces the 62nd and Base64](/appendices#unpadded-base64) which replaces the 62nd and

4
content/rooms/fragments/v8-auth-rules.md
View file

@ -54,7 +54,7 @@ The rules are as follows:
4. If type is `m.room.member`: 4. If type is `m.room.member`:
1. If there is no `state_key` property, or no `membership` property in 1. If there is no `state_key` property, or no `membership` property in
`content`, reject. `content`, reject.
2. {{< added-in this=true >}} 2. {{< added-in v=8 >}}
If `content` has a `join_authorised_via_users_server` property: If `content` has a `join_authorised_via_users_server` property:
1. If the event is not validly signed by the homeserver of the user ID denoted 1. If the event is not validly signed by the homeserver of the user ID denoted
by the key, reject. by the key, reject.
@ -65,7 +65,7 @@ The rules are as follows:
3. If the `sender` is banned, reject. 3. If the `sender` is banned, reject.
4. If the `join_rule` is `invite` or `knock` then allow if 4. If the `join_rule` is `invite` or `knock` then allow if
membership state is `invite` or `join`. membership state is `invite` or `join`.
5. {{< added-in this=true >}} 5. {{< added-in v=8 >}}
If the `join_rule` is `restricted`: If the `join_rule` is `restricted`:
1. If membership state is `join` or `invite`, allow. 1. If membership state is `join` or `invite`, allow.
2. If the `join_authorised_via_users_server` key in `content` 2. If the `join_authorised_via_users_server` key in `content`

1
content/rooms/v1.md
View file

@ -2,6 +2,7 @@
title: Room Version 1 title: Room Version 1
type: docs type: docs
weight: 10 weight: 10
version: 1
--- ---
This room version is the first ever version for rooms, and contains the This room version is the first ever version for rooms, and contains the

9
content/rooms/v10.md
View file

@ -2,6 +2,7 @@
title: Room Version 10 title: Room Version 10
type: docs type: docs
weight: 100 weight: 100
version: 10
--- ---
This room version builds on [version 9](/rooms/v9) to enforce that power level This room version builds on [version 9](/rooms/v9) to enforce that power level
@ -140,7 +141,7 @@ The rules are as follows:
3. If the `sender` is banned, reject. 3. If the `sender` is banned, reject.
4. If the `join_rule` is `invite` or `knock` then allow if 4. If the `join_rule` is `invite` or `knock` then allow if
membership state is `invite` or `join`. membership state is `invite` or `join`.
5. {{< changed-in this="true" >}} 5. {{< changed-in v=10 >}}
If the `join_rule` is `restricted` or `knock_restricted`: If the `join_rule` is `restricted` or `knock_restricted`:
1. If membership state is `join` or `invite`, allow. 1. If membership state is `join` or `invite`, allow.
2. If the `join_authorised_via_users_server` key in `content` 2. If the `join_authorised_via_users_server` key in `content`
@ -196,7 +197,7 @@ The rules are as follows:
than the `sender`'s power level, allow. than the `sender`'s power level, allow.
3. Otherwise, reject. 3. Otherwise, reject.
7. If `membership` is `knock`: 7. If `membership` is `knock`:
1. {{< changed-in this="true" >}} 1. {{< changed-in v=10 >}}
If the `join_rule` is anything other than `knock` or If the `join_rule` is anything other than `knock` or
`knock_restricted`, reject. `knock_restricted`, reject.
2. If `sender` does not match `state_key`, reject. 2. If `sender` does not match `state_key`, reject.
@ -213,11 +214,11 @@ The rules are as follows:
8. If the event has a `state_key` that starts with an `@` and does not 8. If the event has a `state_key` that starts with an `@` and does not
match the `sender`, reject. match the `sender`, reject.
9. If type is `m.room.power_levels`: 9. If type is `m.room.power_levels`:
1. {{< added-in this="true" >}} 1. {{< added-in v=10 >}}
If any of the properties `users_default`, `events_default`, `state_default`, If any of the properties `users_default`, `events_default`, `state_default`,
`ban`, `redact`, `kick`, or `invite` in `content` are present and `ban`, `redact`, `kick`, or `invite` in `content` are present and
not an integer, reject. not an integer, reject.
2. {{< added-in this="true" >}} 2. {{< added-in v=10 >}}
If either of the properties `events` or `notifications` in `content` If either of the properties `events` or `notifications` in `content`
are present and not an object with values that are integers, are present and not an object with values that are integers,
reject. reject.

7
content/rooms/v11.md
View file

@ -2,6 +2,7 @@
title: Room Version 11 title: Room Version 11
type: docs type: docs
weight: 100 weight: 100
version: 11
--- ---
This room version builds on [version 10](/rooms/v10) while clarifying redaction This room version builds on [version 10](/rooms/v10) while clarifying redaction
@ -11,7 +12,7 @@ rules.
### Redactions ### Redactions
{{< added-in this=true >}} The top-level `origin`, `membership`, and `prev_state` properties {{< added-in v=11 >}} The top-level `origin`, `membership`, and `prev_state` properties
are no longer protected from redaction. The [`m.room.create`](/client-server-api#mroomcreate) are no longer protected from redaction. The [`m.room.create`](/client-server-api#mroomcreate)
event now keeps the entire `content` property. The [`m.room.redaction`](/client-server-api#mroomredaction) event now keeps the entire `content` property. The [`m.room.redaction`](/client-server-api#mroomredaction)
event keeps the `redacts` property under `content`. The event keeps the `redacts` property under `content`. The
@ -111,7 +112,7 @@ the [Handling redactions](#handling-redactions) section.
The rules are as follows: The rules are as follows:
1. {{< changed-in this="true" >}} 1. {{< changed-in v=11 >}}
If type is `m.room.create`: If type is `m.room.create`:
1. If it has any `prev_events`, reject. 1. If it has any `prev_events`, reject.
2. If the domain of the `room_id` does not match the domain of the 2. If the domain of the `room_id` does not match the domain of the
@ -141,7 +142,7 @@ The rules are as follows:
1. If the event is not validly signed by the homeserver of the user ID denoted 1. If the event is not validly signed by the homeserver of the user ID denoted
by the key, reject. by the key, reject.
3. If `membership` is `join`: 3. If `membership` is `join`:
1. {{< changed-in this="true" >}} 1. {{< changed-in v=11 >}}
If the only previous event is an `m.room.create` and the If the only previous event is an `m.room.create` and the
`state_key` is the sender, allow. `state_key` is the sender, allow.
2. If the `sender` does not match `state_key`, reject. 2. If the `sender` does not match `state_key`, reject.

3
content/rooms/v2.md
View file

@ -2,6 +2,7 @@
title: Room Version 2 title: Room Version 2
type: docs type: docs
weight: 20 weight: 20
version: 2
--- ---
This room version builds on [version 1](/rooms/v1) with an improved This room version builds on [version 1](/rooms/v1) with an improved
@ -27,7 +28,7 @@ changing only the state resolution algorithm.
### State resolution ### State resolution
{{% added-in this=true %}} {{% added-in v=2 %}}
{{% rver-fragment name="v2-state-res" %}} {{% rver-fragment name="v2-state-res" %}}

11
content/rooms/v3.md
View file

@ -2,6 +2,7 @@
title: Room Version 3 title: Room Version 3
type: docs type: docs
weight: 30 weight: 30
version: 3
--- ---
This room version builds on [version 2](/rooms/v2) with an improved event This room version builds on [version 2](/rooms/v2) with an improved event
@ -39,8 +40,7 @@ all the remaining behaviour described by [room version 2](/rooms/v2).
### Handling redactions ### Handling redactions
<!-- set withVersioning=true so we get all the "new in this version" stuff --> {{% rver-fragment name="v3-handling-redactions" %}}
{{% rver-fragment name="v3-handling-redactions" withVersioning=true %}}
### Event IDs ### Event IDs
@ -54,7 +54,7 @@ the use of a dedicated event ID, servers are required to track the
hashes on an event to determine its ID. hashes on an event to determine its ID.
{{% /boxes/rationale %}} {{% /boxes/rationale %}}
{{% added-in this=true %}} The event ID is the [reference {{% added-in v=3 %}} The event ID is the [reference
hash](/server-server-api#calculating-the-reference-hash-for-an-event) of hash](/server-server-api#calculating-the-reference-hash-for-an-event) of
the event encoded using [Unpadded the event encoded using [Unpadded
Base64](/appendices#unpadded-base64), prefixed with `$`. A Base64](/appendices#unpadded-base64), prefixed with `$`. A
@ -90,7 +90,7 @@ The complete structure of a event in a v3 room is shown below.
### Authorization rules ### Authorization rules
{{% boxes/note %}} {{% boxes/note %}}
{{< added-in this=true >}} `m.room.redaction` events are subject to auth rules in {{< added-in v=3 >}} `m.room.redaction` events are subject to auth rules in
the same way as any other event. In practice, that means they will normally be allowed the same way as any other event. In practice, that means they will normally be allowed
by the auth rules, unless the `m.room.power_levels` event sets a power level requirement by the auth rules, unless the `m.room.power_levels` event sets a power level requirement
for `m.room.redaction`events via the `events` or `events_default` properties. In for `m.room.redaction`events via the `events` or `events_default` properties. In
@ -101,8 +101,7 @@ be performed. Receiving servers must perform additional checks, as described in
the [Handling Redactions](#handling-redactions) section. the [Handling Redactions](#handling-redactions) section.
{{% /boxes/note %}} {{% /boxes/note %}}
<!-- set withVersioning=true so we get all the "new in this version" stuff --> {{% rver-fragment name="v3-auth-rules" %}}
{{< rver-fragment name="v3-auth-rules" withVersioning=true >}}
## Unchanged from v2 ## Unchanged from v2

3
content/rooms/v4.md
View file

@ -2,6 +2,7 @@
title: Room Version 4 title: Room Version 4
type: docs type: docs
weight: 40 weight: 40
version: 4
--- ---
This room version builds on [version 3](/rooms/v3) using a different This room version builds on [version 3](/rooms/v3) using a different
@ -46,7 +47,7 @@ being interpreted differently by some reverse proxy software, and
generally made administration harder. generally made administration harder.
{{% /boxes/rationale %}} {{% /boxes/rationale %}}
{{% rver-fragment name="v4-event-ids" withVersioning="true" %}} {{% rver-fragment name="v4-event-ids" %}}
## Unchanged from v3 ## Unchanged from v3

1
content/rooms/v5.md
View file

@ -2,6 +2,7 @@
title: Room Version 5 title: Room Version 5
type: docs type: docs
weight: 50 weight: 50
version: 5
--- ---
This room version builds on [version 4](/rooms/v4) while enforcing signing This room version builds on [version 4](/rooms/v4) while enforcing signing

11
content/rooms/v6.md
View file

@ -2,6 +2,7 @@
title: Room Version 6 title: Room Version 6
type: docs type: docs
weight: 60 weight: 60
version: 6
--- ---
This room version builds on [version 5](/rooms/v5) while changing various This room version builds on [version 5](/rooms/v5) while changing various
@ -15,7 +16,7 @@ which implement the redaction algorithm locally should refer to the
### Redactions ### Redactions
{{< added-in this=true >}} All significant meaning for `m.room.aliases` {{< added-in v=6 >}} All significant meaning for `m.room.aliases`
has been removed from the redaction algorithm. The remaining rules are has been removed from the redaction algorithm. The remaining rules are
the same as past room versions. the same as past room versions.
@ -40,11 +41,11 @@ in [room version 5](/rooms/v5).
### Authorization rules ### Authorization rules
{{< added-in this=true >}} Rule 4, which related specifically to events {{< added-in v=6 >}} Rule 4, which related specifically to events
of type `m.room.aliases`, is removed. `m.room.aliases` events must still pass of type `m.room.aliases`, is removed. `m.room.aliases` events must still pass
authorization checks relating to state events. authorization checks relating to state events.
{{< added-in this=true >}} Additionally, the authorization rules for events of {{< added-in v=6 >}} Additionally, the authorization rules for events of
type `m.room.power_levels` now include a `notifications` property under type `m.room.power_levels` now include a `notifications` property under
`content`. This updates rules 10.4 and 10.5 (now 9.4 and 9.5), which checked `content`. This updates rules 10.4 and 10.5 (now 9.4 and 9.5), which checked
the `events` property. the `events` property.
@ -174,12 +175,12 @@ The rules are as follows:
power level, reject. power level, reject.
2. If the new value is higher than the `sender`'s current power 2. If the new value is higher than the `sender`'s current power
level, reject. level, reject.
4. {{< changed-in this="true" >}} 4. {{< changed-in v=6 >}}
For each entry being changed in, or removed from, the `events` or For each entry being changed in, or removed from, the `events` or
`notifications` properties: `notifications` properties:
1. If the current value is greater than the `sender`'s current 1. If the current value is greater than the `sender`'s current
power level, reject. power level, reject.
5. {{< changed-in this="true" >}} 5. {{< changed-in v=6 >}}
For each entry being added to, or changed in, the `events` or For each entry being added to, or changed in, the `events` or
`notifications` properties: `notifications` properties:
1. If the new value is greater than the `sender`'s current power 1. If the new value is greater than the `sender`'s current power

9
content/rooms/v7.md
View file

@ -2,6 +2,7 @@
title: Room Version 7 title: Room Version 7
type: docs type: docs
weight: 70 weight: 70
version: 7
--- ---
This room version builds on [version 6](/rooms/v6) to introduce knocking This room version builds on [version 6](/rooms/v6) to introduce knocking
@ -32,7 +33,7 @@ as do the versions v6 is based upon.
### Authorization rules ### Authorization rules
{{< added-in this=true >}} For checks performed upon `m.room.member` events, a {{< added-in v=7 >}} For checks performed upon `m.room.member` events, a
new point for `membership=knock` is added. new point for `membership=knock` is added.
Events must be signed by the server denoted by the `sender` property. Events must be signed by the server denoted by the `sender` property.
@ -89,7 +90,7 @@ The rules are as follows:
`state_key` is the creator, allow. `state_key` is the creator, allow.
2. If the `sender` does not match `state_key`, reject. 2. If the `sender` does not match `state_key`, reject.
3. If the `sender` is banned, reject. 3. If the `sender` is banned, reject.
4. {{< changed-in this=true >}} 4. {{< changed-in v=7 >}}
If the `join_rule` is `invite` or `knock` then allow if If the `join_rule` is `invite` or `knock` then allow if
membership state is `invite` or `join`. membership state is `invite` or `join`.
5. If the `join_rule` is `public`, allow. 5. If the `join_rule` is `public`, allow.
@ -121,7 +122,7 @@ The rules are as follows:
the *invite level*, allow. the *invite level*, allow.
5. Otherwise, reject. 5. Otherwise, reject.
4. If `membership` is `leave`: 4. If `membership` is `leave`:
1. {{< changed-in this=true >}} 1. {{< changed-in v=7 >}}
If the `sender` matches `state_key`, allow if and only if If the `sender` matches `state_key`, allow if and only if
that user's current membership state is `invite`, `join`, that user's current membership state is `invite`, `join`,
or `knock`. or `knock`.
@ -141,7 +142,7 @@ The rules are as follows:
the *ban level*, and the *target user*'s power level is less the *ban level*, and the *target user*'s power level is less
than the `sender`'s power level, allow. than the `sender`'s power level, allow.
3. Otherwise, reject. 3. Otherwise, reject.
6. {{< added-in this=true >}} 6. {{< added-in v=7 >}}
If `membership` is `knock`: If `membership` is `knock`:
1. If the `join_rule` is anything other than `knock`, reject. 1. If the `join_rule` is anything other than `knock`, reject.
2. If `sender` does not match `state_key`, reject. 2. If `sender` does not match `state_key`, reject.

7
content/rooms/v8.md
View file

@ -2,6 +2,7 @@
title: Room Version 8 title: Room Version 8
type: docs type: docs
weight: 80 weight: 80
version: 8
--- ---
This room version builds on [version 7](/rooms/v7) to introduce a new This room version builds on [version 7](/rooms/v7) to introduce a new
@ -27,7 +28,7 @@ Clients which implement the redaction algorithm locally should refer to the
### Redactions ### Redactions
{{% added-in this=true %}} `m.room.join_rules` events now keep `allow` in addition to other {{% added-in v=8 %}} `m.room.join_rules` events now keep `allow` in addition to other
keys in `content` when being redacted. keys in `content` when being redacted.
{{% boxes/warning %}} {{% boxes/warning %}}
@ -83,11 +84,11 @@ room without invite. Otherwise, the room version inherits all properties of
### Authorization rules ### Authorization rules
{{< added-in this=true >}} For checks performed upon `m.room.member` events, new {{< added-in v=8 >}} For checks performed upon `m.room.member` events, new
points for handling `content.join_authorised_via_users_server` are added (Rule 4.2 points for handling `content.join_authorised_via_users_server` are added (Rule 4.2
and 4.3.5). and 4.3.5).
{{< rver-fragment name="v8-auth-rules" withVersioning=true >}} {{% rver-fragment name="v8-auth-rules" %}}
### Redactions ### Redactions

7
content/rooms/v9.md
View file

@ -2,6 +2,7 @@
title: Room Version 9 title: Room Version 9
type: docs type: docs
weight: 90 weight: 90
version: 9
--- ---
This room version builds on [version 8](/rooms/v8) to add additional redaction This room version builds on [version 8](/rooms/v8) to add additional redaction
@ -17,7 +18,7 @@ Clients which implement the redaction algorithm locally should refer to the
### Redactions ### Redactions
{{< added-in this=true >}} [`m.room.member`](/client-server-api#mroommember) events {{< added-in v=9 >}} [`m.room.member`](/client-server-api#mroommember) events
now keep `join_authorised_via_users_server` in addition to other keys in `content` now keep `join_authorised_via_users_server` in addition to other keys in `content`
when being redacted. when being redacted.
@ -38,7 +39,7 @@ information.
The full redaction algorithm follows. The full redaction algorithm follows.
{{% rver-fragment name="v9-redactions" withVersioning="true" %}} {{% rver-fragment name="v9-redactions" %}}
## Server implementation components ## Server implementation components
@ -83,7 +84,7 @@ completeness.
### Authorization rules ### Authorization rules
{{< rver-fragment name="v8-auth-rules" >}} {{% rver-fragment name="v8-auth-rules" %}}
### State resolution ### State resolution

13
layouts/shortcodes/added-in.html
View file

@ -1,8 +1,9 @@
{{ $ver := .Params.v }} {{- $ver := .Params.v -}}
{{ $this := .Params.this }}
{{ if $this }} {{- with page.Params.version -}}
<span><strong>[New in this version]</strong></span> {{- if eq $ver . -}}
{{ else }} <span><strong>[New in this version]</strong></span>
{{- end -}}
{{- else -}}
<span><strong>[Added in <code>v{{ $ver }}</code>]</strong></span> <span><strong>[Added in <code>v{{ $ver }}</code>]</strong></span>
{{ end }} {{/* Do not leave an empty line at the end of this file otherwise the inline behaviour breaks. */}} {{- end -}}

13
layouts/shortcodes/changed-in.html
View file

@ -1,8 +1,9 @@
{{ $ver := .Params.v }} {{- $ver := .Params.v -}}
{{ $this := .Params.this }}
{{ if $this }} {{- with page.Params.version -}}
<span><strong>[Changed in this version]</strong></span> {{- if eq $ver . -}}
{{ else }} <span><strong>[Changed in this version]</strong></span>
{{- end -}}
{{- else -}}
<span><strong>[Changed in <code>v{{ $ver }}</code>]</strong></span> <span><strong>[Changed in <code>v{{ $ver }}</code>]</strong></span>
{{ end }} {{/* Do not leave an empty line at the end of this file otherwise the inline behaviour breaks. */}} {{- end -}}

2
layouts/shortcodes/rver-fragment.html
View file

@ -19,7 +19,7 @@
{{ with .Site.GetPage "rooms/fragments" }} {{ with .Site.GetPage "rooms/fragments" }}
{{ with .Resources.GetMatch (printf "%s%s" $name ".md") }} {{ with .Resources.GetMatch (printf "%s%s" $name ".md") }}
{{ $content := .Content }} {{ $content := .RenderShortcodes }}
{{ if not $withVersioning }} {{ if not $withVersioning }}
{{ $content = (replace $content "[New in this version]" "") }} {{ $content = (replace $content "[New in this version]" "") }}
{{ $content = (replace $content "[Changed in this version]" "") }} {{ $content = (replace $content "[Changed in this version]" "") }}

3
meta/documentation_style.rst
View file

@ -91,9 +91,6 @@ current version is `v1.1` then annotate your changes with `v1.2`.
* `{{% added-in v="1.2" %}}` or `{{% changed-in v="1.2" %}}` within Markdown documents. * `{{% added-in v="1.2" %}}` or `{{% changed-in v="1.2" %}}` within Markdown documents.
* `x-addedInMatrixVersion` and `x-changedInMatrixVersion` within OpenAPI. * `x-addedInMatrixVersion` and `x-changedInMatrixVersion` within OpenAPI.
In rare cases, `this=true` can be used on the Markdown syntax to adjust the wording.
This is most commonly used in room version specifications.
**Tip**: If you're trying to inline the Markdown version and getting unexpected results, **Tip**: If you're trying to inline the Markdown version and getting unexpected results,
try replacing the `%` symbols with `<` and `>`, changing how Hugo renders the shortcode. try replacing the `%` symbols with `<` and `>`, changing how Hugo renders the shortcode.