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

* 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>

changelogs/room_versions/newsfragments/1884.clarification

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

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

@@ -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
 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.

content/rooms/fragments/v3-handling-redactions.md

@@ -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)
 under Rule 11. As of room version 3, these conditions no longer exist as
 represented by [this version's authorization rules](#authorization-rules).

content/rooms/fragments/v4-event-ids.md

@@ -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
 the event encoded using a variation of [Unpadded
 Base64](/appendices#unpadded-base64) which replaces the 62nd and

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

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

content/rooms/v1.md

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

content/rooms/v10.md

@@ -2,6 +2,7 @@
 title: Room Version 10
 type: docs
 weight: 100
+version: 10
 ---
 
 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.
         4.  If the `join_rule` is `invite` or `knock` then allow if
             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`:
             1.  If membership state is `join` or `invite`, allow.
             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.
         3.  Otherwise, reject.
     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
             `knock_restricted`, 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
     match the `sender`, reject.
 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`,
         `ban`, `redact`, `kick`, or `invite` in `content` are present and
         not an integer, reject.
-    2.  {{< added-in this="true" >}}
+    2.  {{< added-in v=10 >}}
         If either of the properties `events` or `notifications` in `content`
         are present and not an object with values that are integers,
         reject.

content/rooms/v11.md

@@ -2,6 +2,7 @@
 title: Room Version 11
 type: docs
 weight: 100
+version: 11
 ---
 
 This room version builds on [version 10](/rooms/v10) while clarifying redaction
@@ -11,7 +12,7 @@ rules.
 
 ### 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)
 event now keeps the entire `content` property. The [`m.room.redaction`](/client-server-api#mroomredaction)
 event keeps the `redacts` property under `content`. The
@@ -111,7 +112,7 @@ the [Handling redactions](#handling-redactions) section.
 
 The rules are as follows:
 
-1.  {{< changed-in this="true" >}}
+1.  {{< changed-in v=11 >}}
     If type is `m.room.create`:
     1.  If it has any `prev_events`, reject.
     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
             by the key, reject.
     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
             `state_key` is the sender, allow.
         2.  If the `sender` does not match `state_key`, reject.

content/rooms/v2.md

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

content/rooms/v3.md

@@ -2,6 +2,7 @@
 title: Room Version 3
 type: docs
 weight: 30
+version: 3
 ---
 
 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
 
-<!-- set withVersioning=true so we get all the "new in this version" stuff -->
-{{% rver-fragment name="v3-handling-redactions" withVersioning=true %}}
+{{% rver-fragment name="v3-handling-redactions" %}}
 
 ### 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.
 {{% /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
 the event encoded using [Unpadded
 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
 
 {{% 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
 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
@@ -101,8 +101,7 @@ be performed. Receiving servers must perform additional checks, as described in
 the [Handling Redactions](#handling-redactions) section.
 {{% /boxes/note %}}
 
-<!-- set withVersioning=true so we get all the "new in this version" stuff -->
-{{< rver-fragment name="v3-auth-rules" withVersioning=true >}}
+{{% rver-fragment name="v3-auth-rules" %}}
 
 ## Unchanged from v2
 

content/rooms/v4.md

@@ -2,6 +2,7 @@
 title: Room Version 4
 type: docs
 weight: 40
+version: 4
 ---
 
 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.
 {{% /boxes/rationale %}}
 
-{{% rver-fragment name="v4-event-ids" withVersioning="true" %}}
+{{% rver-fragment name="v4-event-ids" %}}
 
 ## Unchanged from v3
 

content/rooms/v5.md

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

content/rooms/v6.md

@@ -2,6 +2,7 @@
 title: Room Version 6
 type: docs
 weight: 60
+version: 6
 ---
 
 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
 
-{{< 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
 the same as past room versions.
 
@@ -40,11 +41,11 @@ in [room version 5](/rooms/v5).
 
 ### 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
 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
 `content`.  This updates rules 10.4 and 10.5 (now 9.4 and 9.5), which checked
 the `events` property.
@@ -174,12 +175,12 @@ The rules are as follows:
             power level, reject.
         2.  If the new value is higher than the `sender`'s current power
             level, reject.
-    4.  {{< changed-in this="true" >}}
+    4.  {{< changed-in v=6 >}}
         For each entry being changed in, or removed from, the `events` or
         `notifications` properties:
         1.  If the current value is greater than the `sender`'s current
             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
         `notifications` properties:
         1.  If the new value is greater than the `sender`'s current power

content/rooms/v7.md

@@ -2,6 +2,7 @@
 title: Room Version 7
 type: docs
 weight: 70
+version: 7
 ---
 
 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
 
-{{< 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.
 
 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.
         2.  If the `sender` does not match `state_key`, 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
             membership state is `invite` or `join`.
         5.  If the `join_rule` is `public`, allow.
@@ -121,7 +122,7 @@ The rules are as follows:
             the *invite level*, allow.
         5.  Otherwise, reject.
     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
             that user's current membership state is `invite`, `join`,
             or `knock`.
@@ -141,7 +142,7 @@ The rules are as follows:
             the *ban level*, and the *target user*'s power level is less
             than the `sender`'s power level, allow.
         3.  Otherwise, reject.
-    6.  {{< added-in this=true >}}
+    6.  {{< added-in v=7 >}}
         If `membership` is `knock`:
         1.  If the `join_rule` is anything other than `knock`, reject.
         2.  If `sender` does not match `state_key`, reject.

content/rooms/v8.md

@@ -2,6 +2,7 @@
 title: Room Version 8
 type: docs
 weight: 80
+version: 8
 ---
 
 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
 
-{{% 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.
 
 {{% boxes/warning %}}
@@ -83,11 +84,11 @@ room without invite. Otherwise, the room version inherits all properties of
 
 ### 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
 and 4.3.5).
 
-{{< rver-fragment name="v8-auth-rules" withVersioning=true >}}
+{{% rver-fragment name="v8-auth-rules" %}}
 
 ### Redactions
 

content/rooms/v9.md

@@ -2,6 +2,7 @@
 title: Room Version 9
 type: docs
 weight: 90
+version: 9
 ---
 
 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
 
-{{< 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`
 when being redacted.
 
@@ -38,7 +39,7 @@ information.
 The full redaction algorithm follows.
 
 
-{{% rver-fragment name="v9-redactions" withVersioning="true" %}}
+{{% rver-fragment name="v9-redactions" %}}
 
 ## Server implementation components
 
@@ -83,7 +84,7 @@ completeness.
 
 ### Authorization rules
 
-{{< rver-fragment name="v8-auth-rules" >}}
+{{% rver-fragment name="v8-auth-rules" %}}
 
 ### State resolution
 

layouts/shortcodes/added-in.html

@@ -1,8 +1,9 @@
-{{ $ver := .Params.v }}
-{{ $this := .Params.this }}
+{{- $ver := .Params.v -}}
 
-{{ if $this }}
+{{- with page.Params.version -}}
+  {{- if eq $ver . -}}
     <span><strong>[New in this version]</strong></span>
-{{ else }}
+  {{- end -}}
+{{- else -}}
   <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 -}}

layouts/shortcodes/changed-in.html

@@ -1,8 +1,9 @@
-{{ $ver := .Params.v }}
-{{ $this := .Params.this }}
+{{- $ver := .Params.v -}}
 
-{{ if $this }}
+{{- with page.Params.version -}}
+  {{- if eq $ver . -}}
     <span><strong>[Changed in this version]</strong></span>
-{{ else }}
+  {{- end -}}
+{{- else -}}
   <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 -}}

layouts/shortcodes/rver-fragment.html

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

meta/documentation_style.rst

@@ -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.
 * `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,
 try replacing the `%` symbols with `<` and `>`, changing how Hugo renders the shortcode.