improve display of event subtypes

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

@@ -736,7 +736,7 @@ following error codes are used in addition to those already specified:
 -   `m.mismatched_commitment`: The hash commitment did not match.
 -   `m.mismatched_sas`: The SAS did not match.
 
-{{% event event="m.key.verification.start$m.sas.v1" %}}
+{{% event event="m.key.verification.start$m.sas.v1" title="`m.key.verification.start` with `method: m.sas.v1`" %}}
 
 {{% event event="m.key.verification.accept" %}}
 
@@ -1145,7 +1145,7 @@ base64).
 
 ###### Verification messages specific to QR codes
 
-{{% event event="m.key.verification.start$m.reciprocate.v1" %}}
+{{% event event="m.key.verification.start$m.reciprocate.v1" title="`m.key.verification.start` with `method: m.reciprocate.v1`" %}}
 
 #### Sharing keys between devices
 

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

@@ -35,7 +35,7 @@ maximum. New connections are being refused by the server. What defines
 "active" is left as an implementation detail, however servers are
 encouraged to treat syncing users as "active".
 
-{{% event event="m.room.message$m.server_notice" %}}
+{{% event event="m.room.message$m.server_notice" title="`m.room.message` with `msgtype: m.server_notice`" %}}
 
 #### Client behaviour
 

layouts/partials/events/example.html

@@ -0,0 +1,8 @@
+{{ $example_content := partial "json-schema/resolve-refs" (dict "schema" .example "path" "event-schemas/examples") }}
+{{ $example_json := jsonify (dict "indent" "  ") $example_content }}
+{{ $example_json = replace $example_json "\\u003c" "<" }}
+{{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
+
+```json
+{{ $example_json }}
+```

layouts/partials/events/render-event.html

@@ -2,11 +2,13 @@
 
   Renders a single event, given:
 
-    * `event_name`: the name we want to display for the event
+    * `event_name`: the name to use for the event
     * `event_data`: the event specification
     * `desired_example_name` (optional): the exact name of the examples to render.
     If `desired_example_name` is omitted we render all examples
     whose names start with the `event_name`.
+    * `title` (optional): the title to display.  May contain markdown.  Defaults to
+    `event_name` wrapped in a <code> element
 
 */}}
 
@@ -20,7 +22,7 @@
 <summary>
 
   <h1 id="{{ anchorize $event_name }}">
-   <code>{{ $event_name }}</code>
+   {{ with .title }}{{ $.title | markdownify }}{{ else }}<code>{{ $event_name }}</code>{{ end }}
   </h1>
 
   <hr/>
@@ -72,11 +74,10 @@
     */}}
     {{ if $desired_example_name }}
         {{ if eq $example_name $desired_example_name }}
-            {{ $example_content := partial "json-schema/resolve-refs" (dict "schema" $example "path" "event-schemas/examples") }}
-```json
-{{ jsonify (dict "indent" "  ") $example_content }}
-```
+            {{ partial "events/example" (dict "example" $example)}}
         {{ end }}
+    {{ else if eq $event_name $example_name }}
+        {{ partial "events/example" (dict "example" $example)}}
     {{/*
       If `$desired_example_name` is not given, we will include any
       examples whose first part (before "$") matches the event name
@@ -86,14 +87,7 @@
         {{ $pieces := split $example_name "$" }}
         {{ $example_base_name := index $pieces 0 }}
         {{ if eq $event_name $example_base_name }}
-            {{ $example_content := partial "json-schema/resolve-refs" (dict "schema" $example "path" "event-schemas/examples") }}
-            {{ $example_json := jsonify (dict "indent" "  ") $example_content }}
-            {{ $example_json = replace $example_json "\\u003c" "<" }}
-            {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
-
-```json
-{{ $example_json }}
-```
+             {{ partial "events/example" (dict "example" $example)}}
         {{ end }}
     {{ end }}
 {{ end }}

layouts/shortcodes/event.html

@@ -17,4 +17,4 @@
 {{ $event_data = partial "json-schema/resolve-refs" (dict "schema" $event_data "path" $path) }}
 {{ $event_data := partial "json-schema/resolve-allof" $event_data }}
 
-{{ partial "events/render-event" (dict "event_name" .Params.event "event_data" $event_data)}}
+{{ partial "events/render-event" (dict "event_name" .Params.event "event_data" $event_data "title" .Params.title)}}