Support alerts (notes, warnings, rationales)

assets-hugo/scss/custom.scss

@@ -209,6 +209,39 @@ footer {
 
 }
 
+/* Styles for alert boxes */
+.alert {
+  &.note {
+    &:not(.omit-title):before {
+      content: "INFO: ";
+      font-weight: $font-weight-bold;
+    }
+    border: 2px solid $note;
+    border-left-width: 5px;
+    background: $note-background;
+  }
+
+  &.rationale {
+    &:not(.omit-title):before {
+      content: "RATIONALE: ";
+      font-weight: $font-weight-bold;
+    }
+    border: 2px solid $note;
+    border-left-width: 5px;
+    background: $note-background;
+  }
+
+  &.warning {
+    &:not(.omit-title):before {
+      content: "WARNING: ";
+      font-weight: $font-weight-bold;
+    }
+    border: 2px solid $warning;
+    border-left-width: 5px;
+    background: $warning-background;
+  }
+}
+
 /* Miscellaneous custom bits */
 
 /* Update link colours for MAtrix style */

content/_index.md

@@ -35,13 +35,13 @@ browsing the Client-Server API.
 
 ### Matrix versions
 
-Note
-
+{{% boxes/note %}}
 As of June 10th 2019, the Matrix specification is considered out of beta
 -indicating that all currently released APIs are considered stable and
 secure to the best of our knowledge, and the spec should contain the
 complete information necessary to develop production-grade
 implementations of Matrix without the need for external reference.
+{{% /boxes/note %}}
 
 Matrix 1.0 (released June 10th, 2019) consists of the following minimum
 API versions:
@@ -335,13 +335,13 @@ participating servers in a room, currently using full mesh topology.
 Servers may also request backfill of events over federation from the
 other servers participating in a room.
 
-Note
-
+{{% boxes/note %}}
 Events are not limited to the types defined in this specification. New
 or custom event types can be created on a whim using the Java package
 naming convention. For example, a `com.example.game.score` event can be
 sent by clients and other clients would receive it through Matrix,
 assuming the client has access to the `com.example` namespace.
+{{% /boxes/note %}}
 
 #### Room Aliases
 

content/appendices.md

@@ -74,18 +74,18 @@ to be in the range where they can be accurately represented using IEEE
 double precision floating point numbers since a number of JSON libraries
 represent all numbers using this representation.
 
-Warning
-
+{{% boxes/warning %}}
 Events in room versions 1, 2, 3, 4, and 5 might not be fully compliant
 with these restrictions. Servers SHOULD be capable of handling JSON
 which is considered invalid by these restrictions where possible.
 
 The most notable consideration is that integers might not be in the
 range specified above.
+{{% /boxes/warning %}}
 
-Note
-
+{{% boxes/note %}}
 Float values are not permitted by this encoding.
+{{% /boxes/note %}}
 
 ```py
 import json
@@ -415,12 +415,12 @@ Examples of valid server names are:
 -   `[1234:5678::abcd]` (IPv6 literal)
 -   `[1234:5678::abcd]:5678` (IPv6 literal with explicit port)
 
-Note
-
+{{% boxes/note %}}
 This grammar is based on the standard for internet host names, as
 specified by [RFC1123, section
 2.1](https://tools.ietf.org/html/rfc1123#page-13), with an extension for
 IPv6 literals.
+{{% /boxes/note %}}
 
 Server names must be treated case-sensitively: in other words,
 `@user:matrix.org` is a different person from `@user:MATRIX.ORG`.
@@ -490,8 +490,7 @@ The complete grammar for a legal user ID is:
                  / %x61-7A                   ; a-z
                  / "-" / "." / "=" / "_" / "/"
 
-Rationale
-
+{{% boxes/rationale %}}
 A number of factors were considered when defining the allowable
 characters for a user ID.
 
@@ -525,6 +524,7 @@ The length restriction is derived from the limit on the length of the
 `sender` key on events; since the user ID appears in every event sent by
 the user, it is limited to ensure that the user ID does not dominate
 over the actual content of the events.
+{{% /boxes/rationale %}}
 
 Matrix user IDs are sometimes informally referred to as MXIDs.
 
@@ -564,12 +564,12 @@ consistently. However, we suggest the following algorithm:
     well as `=`, as their hexadecimal value, prefixed with `=`. For
     example, `#` becomes `=23`; `á` becomes `=c3=a1`.
 
-Rationale
-
+{{% boxes/rationale %}}
 The suggested mapping is an attempt to preserve human-readability of
 simple ASCII identifiers (unlike, for example, base-32), whilst still
 allowing representation of *any* character (unlike punycode, which
 provides no way to encode ASCII punctuation).
+{{% /boxes/rationale %}}
 
 #### Room IDs and Event IDs
 
@@ -631,11 +631,11 @@ domain).
 
 #### matrix.to navigation
 
-Note
-
+{{% boxes/note %}}
 This namespacing is in place pending a `matrix://` (or similar) URI
 scheme. This is **not** meant to be interpreted as an available web
 service - see below for more details.
+{{% /boxes/note %}}
 
 Rooms, users, aliases, and groups may be represented as a "matrix.to"
 URI. This URI can be used to reference particular objects in a given
@@ -676,19 +676,19 @@ Examples of matrix.to URIs are:
 -   User: `https://matrix.to/#/%40alice%3Aexample.org`
 -   Group: `https://matrix.to/#/%2Bexample%3Aexample.org`
 
-Note
-
+{{% boxes/note %}}
 Historically, clients have not produced URIs which are fully encoded.
 Clients should try to interpret these cases to the best of their
 ability. For example, an unencoded room alias should still work within
 the client if possible.
+{{% /boxes/note %}}
 
-Note
-
+{{% boxes/note %}}
 Clients should be aware that decoding a matrix.to URI may result in
 extra slashes appearing due to some [room
 versions](index.html#room-versions). These slashes should normally be
 encoded when producing matrix.to URIs, however.
+{{% /boxes/note %}}
 
 ##### Routing
 

content/application-service-api.md

@@ -48,8 +48,7 @@ service.
 
 ### Registration
 
-Note
-
+{{% boxes/note %}}
 Previously, application services could register with a homeserver via
 HTTP APIs. This was removed as it was seen as a security risk. A
 compromised application service could re-register for a global `*` regex
@@ -58,6 +57,7 @@ application services now have to register via configuration files which
 are linked to the homeserver configuration file. The addition of
 configuration files allows homeserver admins to sanity check the
 registration for suspicious regex strings.
+{{% /boxes/note %}}
 
 Application services register "namespaces" of user IDs, room aliases and
 room IDs. These namespaces are represented as regular expressions. An
@@ -213,12 +213,12 @@ below:
           regex: "#_irc_bridge_.*"
       rooms: []
 
-Warning
-
+{{% boxes/warning %}}
 If the homeserver in question has multiple application services, each
 `as_token` and `id` MUST be unique per application service as these are
 used to identify the application service. The homeserver MUST enforce
 this.
+{{% /boxes/warning %}}
 
 ### Homeserver -> Application Service API
 
@@ -314,8 +314,7 @@ homeserver should retry several times before timing out. This should
 result in an HTTP status 408 "Request Timeout" on the client which
 initiated this request (e.g. to join a room alias).
 
-Rationale
-
+{{% boxes/rationale %}}
 Blocking the homeserver and expecting the application service to create
 the entity using the client-server API is simpler and more flexible than
 alternative methods such as returning an initial sync style JSON blob
@@ -323,6 +322,7 @@ and get the HS to provision the room/user. This also meant that there
 didn't need to be a "backchannel" to inform the application service
 about information about the entity such as room ID to room alias
 mappings.
+{{% /boxes/rationale %}}
 
 {{query\_user\_as\_http\_api}}
 

content/client-server-api/_index.md

@@ -62,11 +62,11 @@ convention of using underscores to separate words (for example
 `/delete_devices`). The key names in JSON objects passed over the API
 also follow this convention.
 
-Note
-
+{{% boxes/note %}}
 There are a few historical exceptions to this rule, such as
 `/createRoom`. A future version of this specification will address the
 inconsistency.
+{{% /boxes/note %}}
 
 Any errors which occur at the Matrix API level MUST return a "standard
 error response". This is a JSON object which looks like:
@@ -296,10 +296,10 @@ conscientious decision what to do next.
 
 ### Well-known URI
 
-Note
-
+{{% boxes/note %}}
 Servers hosting the `.well-known` JSON file SHOULD offer CORS headers,
 as per the [CORS](#CORS) section in this specification.
+{{% /boxes/note %}}
 
 The `.well-known` method uses a JSON file at a predetermined location to
 specify parameter values. The flow for this method is as follows:
@@ -344,12 +344,12 @@ parameter or through an Authorization Header of `Bearer $access_token`.
 An access token is typically obtained via the [Login](#login) or
 [Registration](#Registration) processes.
 
-Note
-
+{{% boxes/note %}}
 This specification does not mandate a particular format for the access
 token. Clients should treat it as an opaque byte sequence. Servers are
 free to choose an appropriate format. Server implementors may like to
 investigate [macaroons](http://research.google.com/pubs/pub41892.html).
+{{% /boxes/note %}}
 
 ### Using access tokens
 
@@ -1096,12 +1096,12 @@ the login endpoint during the login process. For example:
 
 ##### Notes on password management
 
-Warning
-
+{{% boxes/warning %}}
 Clients SHOULD enforce that the password provided is suitably complex.
 The password SHOULD include a lower-case letter, an upper-case letter, a
 number and a symbol and be at a minimum 8 characters in length. Servers
 MAY reject weak passwords with an error code `M_WEAK_PASSWORD`.
+{{% /boxes/warning %}}
 
 ### Adding Account Administrative Contact Information
 
@@ -1109,13 +1109,13 @@ A homeserver may keep some contact information for administrative use.
 This is independent of any information kept by any identity servers,
 though can be proxied (bound) to the identity server in many cases.
 
-Note
-
+{{% boxes/note %}}
 This section deals with two terms: "add" and "bind". Where "add" (or
 "remove") is used, it is speaking about an identifier that was not bound
 to an identity server. As a result, "bind" (or "unbind") references an
 identifier that is found in an identity server. Note that an identifier
 can be added and bound at the same time, depending on context.
+{{% /boxes/note %}}
 
 {{administrative\_contact\_cs\_http\_api}}
 
@@ -1261,10 +1261,10 @@ default and only stable `available` room version.
 
 ## Pagination
 
-Note
-
+{{% boxes/note %}}
 The paths referred to in this section are not actual endpoints. They
 only serve as examples to explain how pagination functions.
+{{% /boxes/note %}}
 
 Pagination is the process of dividing a dataset into multiple discrete
 pages. Matrix makes use of pagination to allow clients to view extremely
@@ -1415,8 +1415,7 @@ any given point in time:
 
     [E0]->[E1]->[E2]->[E3]->[E4]->[E5]
 
-Warning
-
+{{% boxes/warning %}}
 The format of events can change depending on room version. Check the
 [room version specification](../index.html#room-versions) for specific
 details on what to expect for event formats. Examples contained within
@@ -1428,6 +1427,7 @@ the event ID format being different depending on room version. Clients
 should not be parsing the event ID, and instead be treating it as an
 opaque string. No changes should be required to support the currently
 available room versions.
+{{% /boxes/warning %}}
 
 ### Types of room events
 
@@ -1453,13 +1453,13 @@ follow the Java package naming convention, e.g.
 `com.example.myapp.event`. This ensures event types are suitably
 namespaced for each application and reduces the risk of clashes.
 
-Note
-
+{{% boxes/note %}}
 Events are not limited to the types defined in this specification. New
 or custom event types can be created on a whim using the Java package
 naming convention. For example, a `com.example.game.score` event can be
 sent by clients and other clients would receive it through Matrix,
 assuming the client has access to the `com.example` namespace.
+{{% /boxes/note %}}
 
 Note that the structure of these events may be different than those in
 the server-server API.
@@ -1522,9 +1522,9 @@ than that implied by the total 65 KB limit on events.
 
 ### Room Events
 
-Note
-
+{{% boxes/note %}}
 This section is a work in progress.
+{{% /boxes/note %}}
 
 This specification outlines several standard event types, all of which
 are prefixed with `m.`
@@ -1607,17 +1607,16 @@ of the message timeline. The client can fill these gaps using the
      prev_batch: 'd-e-f'       next_batch: 'u-v-w'
 ```
 
-Warning
-
+{{% boxes/warning %}}
 Events are ordered in this API according to the arrival time of the
 event on the homeserver. This can conflict with other APIs which order
 events based on their partial ordering in the event graph. This can
 result in duplicate events being received (once per distinct API
 called). Clients SHOULD de-duplicate events based on the event ID when
 this happens.
+{{% /boxes/warning %}}
 
-Note
-
+{{% boxes/note %}}
 The `/sync` API returns a `state` list which is separate from the
 `timeline`. This `state` list allows clients to keep their model of the
 room state in sync with that on the server. In the case of an initial
@@ -1635,9 +1634,9 @@ In both cases, it should be noted that the events returned in the
 `state` list did **not** necessarily take place just before the returned
 `timeline`, so clients should not display them to the user in the
 timeline.
+{{% /boxes/note %}}
 
-Rationale
-
+{{% boxes/rationale %}}
 An early design of this specification made the `state` list represent
 the room state at the end of the returned timeline, instead of the
 start. This was unsatisfactory because it led to duplication of events
@@ -1650,6 +1649,7 @@ where that user changes their displayname. If the `state` list
 represents the room state at the end of the timeline, the client must
 take a copy of the state dictionary, and *rewind* S1, in order to
 correctly calculate the display name for M0.
+{{% /boxes/rationale %}}
 
 {{sync\_cs\_http\_api}}
 
@@ -1739,8 +1739,7 @@ property of the redacted event, under the `redacted_because` key. When a
 client receives a redaction event it should change the redacted event in
 the same way a server does.
 
-Note
-
+{{% boxes/note %}}
 Redacted events can still affect the state of the room. When redacted,
 state events behave as though their properties were simply not
 specified, except those protected by the redaction algorithm. For
@@ -1748,6 +1747,7 @@ example, a redacted `join` event will still result in the user being
 considered joined. Similarly, a redacted topic does not necessarily
 cause the topic to revert to what it was prior to the event - it causes
 the topic to be removed from the room.
+{{% /boxes/note %}}
 
 ##### Events
 
@@ -1804,9 +1804,9 @@ request.
 
 ### Permissions
 
-Note
-
+{{% boxes/note %}}
 This section is a work in progress.
+{{% /boxes/note %}}
 
 Permissions for rooms are done via the concept of power levels - to do
 any action in a room a user must have a suitable power level. Power

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

@@ -194,8 +194,7 @@ process:
     those already flagged as outdated, and initiates a `/keys/query`\_
     request for all of them.
 
-Warning
-
+{{% boxes/warning %}}
 Bob may update one of his devices while Alice has a request to
 `/keys/query` in flight. Alice's client may therefore see Bob's user ID
 in the `device_lists` field of the `/sync` response while the first
@@ -218,9 +217,9 @@ each user, by queuing additional requests until the first completes.
 Alternatively, the client could make a new request immediately, but
 ensure that the first request's results are ignored (possibly by
 cancelling the request).
+{{% /boxes/warning %}}
 
-Note
-
+{{% boxes/note %}}
 When Bob and Alice share a room, with Bob tracking Alice's devices, she
 may leave the room and then add a new device. Bob will not be notified
 of this change, as he doesn't share a room anymore with Alice. When they
@@ -231,6 +230,7 @@ thus Bob will update his list of Alice's devices as part of his normal
 processing. Note that Bob can also be notified when he stops sharing any
 room with Alice by inspecting the `left` property of the `device_lists`
 field, and as a result should remove her from its list of tracked users.
+{{% /boxes/note %}}
 
 ##### Sending encrypted attachments
 
@@ -243,12 +243,12 @@ AES key, and encrypt the file using AES-CTR. The counter should be
 Initialization Vector (IV), which together form a 128-bit unique counter
 block.
 
-Warning
-
+{{% boxes/warning %}}
 An IV must never be used multiple times with the same key. This implies
 that if there are multiple files to encrypt in the same message,
 typically an image and its thumbnail, the files must not share both the
 same key and IV.
+{{% /boxes/warning %}}
 
 Then, the encrypted file can be uploaded to the homeserver. The key and
 the IV must be included in the room event along with the resulting
@@ -392,13 +392,13 @@ Device verification may reach one of several conclusions. For example:
     reason to suspect otherwise. The encryption protocol continues to
     protect against passive eavesdroppers.
 
-Note
-
+{{% boxes/note %}}
 Once the signing key has been verified, it is then up to the encryption
 protocol to verify that a given message was sent from a device holding
 that Ed25519 private key, or to encrypt a message so that it may only be
 decrypted by such a device. For the Olm protocol, this is documented at
 <https://matrix.org/docs/olm_signing.html>.
+{{% /boxes/note %}}
 
 ##### Key verification framework
 
@@ -700,10 +700,10 @@ the info parameter is the concatenation of:
 New implementations are discouraged from implementing the `curve25519`
 method.
 
-Rationale
-
+{{% boxes/rationale %}}
 HKDF is used over the plain shared secret as it results in a harder
 attack as well as more uniform data to work with.
+{{% /boxes/rationale %}}
 
 For verification of each party's device keys, HKDF is as defined in RFC
 5869 and uses SHA-256 as the hash function. The shared secret is
@@ -746,13 +746,12 @@ following table to get the corresponding emoji:
 
 {{sas\_emoji\_table}}
 
-Note
-
+{{% boxes/note %}}
 This table is available as JSON at
 <https://github.com/matrix-org/matrix-doc/blob/master/data-definitions/sas-emoji.json>
+{{% /boxes/note %}}
 
-Rationale
-
+{{% boxes/rationale %}}
 The emoji above were chosen to:
 
 -   Be recognisable without colour.
@@ -762,17 +761,18 @@ The emoji above were chosen to:
 -   Easily described by a few words.
 -   Avoid symbols with negative connotations.
 -   Be likely similar across multiple platforms.
+{{% /boxes/rationale %}}
 
 Clients SHOULD show the emoji with the descriptions from the table, or
 appropriate translation of those descriptions. Client authors SHOULD
 collaborate to create a common set of translations for all languages.
 
-Note
-
+{{% boxes/note %}}
 Known translations for the emoji are available from
 <https://github.com/matrix-org/matrix-doc/blob/master/data-definitions/>
 and can be translated online:
 <https://translate.riot.im/projects/matrix-doc/sas-emoji-v1>
+{{% /boxes/note %}}
 
 ##### Cross-signing
 
@@ -950,11 +950,11 @@ indicate this by sending an [m.room\_key.withheld]() to-device message,
 as described in [Reporting that decryption keys are
 withheld](#reporting-that-decryption-keys-are-withheld).
 
-Note
-
+{{% boxes/note %}}
 Key sharing can be a big attack vector, thus it must be done very
 carefully. A reasonable strategy is for a user's client to only send
 keys requested by the verified devices of the same user.
+{{% /boxes/note %}}
 
 ##### Server-side key backups
 
@@ -1388,13 +1388,13 @@ of reasons. When this happens to an Olm-encrypted message, the client
 should assume that the Olm session has become corrupted and create a new
 one to replace it.
 
-Note
-
+{{% boxes/note %}}
 Megolm-encrypted messages generally do not have the same problem.
 Usually the key for an undecryptable Megolm-encrypted message will come
 later, allowing the client to decrypt it successfully. Olm does not have
 a way to recover from the failure, making this session replacement
 process required.
+{{% /boxes/note %}}
 
 To establish a new session, the client sends an [m.dummy](#m-dummy)
 to-device event to the other party to notify them of the new session
@@ -1555,14 +1555,14 @@ difference with the `one_time_key_counts` property in the
 </tbody>
 </table>
 
-Note
-
+{{% boxes/note %}}
 For optimal performance, Alice should be added to `changed` in Bob's
 sync only when she updates her devices or cross-signing keys, or when
 Alice and Bob now share a room but didn't share any room previously.
 However, for the sake of simpler logic, a server may add Alice to
 `changed` when Alice and Bob share a new room, even if they previously
 already shared a room.
+{{% /boxes/note %}}
 
 Example response:
 

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

@@ -33,13 +33,13 @@ The four options for the `m.room.history_visibility` event are:
     point they joined the room onwards. Events stop being accessible
     when the member's state changes to something other than `join`.
 
-Warning
-
+{{% boxes/warning %}}
 These options are applied at the point an event is *sent*. Checks are
 performed with the state of the `m.room.history_visibility` event when
 the event in question is added to the DAG. This means clients cannot
 retrospectively choose to show or hide history to new users if the
 setting at that time was more restrictive.
+{{% /boxes/warning %}}
 
 #### Events
 

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

@@ -110,11 +110,11 @@ treated similar to a `div`. Clients that support rich replies will end
 up stripping the tag and its contents and therefore may wish to exclude
 the tag entirely.
 
-Note
-
+{{% boxes/note %}}
 A future iteration of the specification will support more powerful and
 extensible message formatting options, such as the proposal
 [MSC1767](https://github.com/matrix-org/matrix-doc/pull/1767).
+{{% /boxes/note %}}
 
 {{msgtype\_events}}
 

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

@@ -18,19 +18,19 @@ any other server, similar to setting the `m.federate` value on the
 
 {{m\_room\_server\_acl\_event}}
 
-Note
-
+{{% boxes/note %}}
 Port numbers are not supported because it is unclear to parsers whether
 a port number should be matched or an IP address literal. Additionally,
 it is unlikely that one would trust a server running on a particular
 domain's port but not a different port, especially considering the
 server host can easily change ports.
+{{% /boxes/note %}}
 
-Note
-
+{{% boxes/note %}}
 CIDR notation is not supported for IP addresses because Matrix does not
 encourage the use of IPs for identifying servers. Instead, a blanket
 `allow_ip_literals` is provided to cover banning them.
+{{% /boxes/note %}}
 
 #### Client behaviour
 

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

@@ -85,8 +85,7 @@ These steps are illustrated as follows:
         |<-------------access token-------------|                   |
 ```
 
-Note
-
+{{% boxes/note %}}
 In the older [r0.4.0
 version](https://matrix.org/docs/spec/client_server/r0.4.0.html#cas-based-client-login)
 of this specification it was possible to authenticate via CAS when the
@@ -96,6 +95,7 @@ which is the same process with the only change being which redirect
 endpoint to use: for `m.login.cas`, use `/cas/redirect` and for
 `m.login.sso` use `/sso/redirect` (described below). The endpoints are
 otherwise the same.
+{{% /boxes/note %}}
 
 ##### Client behaviour
 

content/identity-service-api.md

@@ -254,10 +254,10 @@ characteristics than the service's long-term keys.
 
 ### Client behaviour
 
-Note
-
+{{% boxes/note %}}
 This section only covers the v2 lookup endpoint. The v1 endpoint is
 described in isolation above.
+{{% /boxes/note %}}
 
 Prior to performing a lookup clients SHOULD make a request to the
 `/hash_details` endpoint to determine what algorithms the server
@@ -269,10 +269,10 @@ Clients MUST support at least the `sha256` algorithm.
 
 ### Server behaviour
 
-Note
-
+{{% boxes/note %}}
 This section only covers the v2 lookup endpoint. The v1 endpoint is
 described in isolation above.
+{{% /boxes/note %}}
 
 Servers, upon receipt of a `/lookup` request, will compare the query
 against known bindings it has, hashing the identifiers it knows about as
@@ -299,11 +299,11 @@ the 3PID to search for. For example, if the client wanted to know about
 `alice@example.org`'s bindings, it would first format the query as
 `alice@example.org email ThePepperGoesHere`.
 
-Rationale
-
+{{% boxes/rationale %}}
 Mediums and peppers are appended to the address to prevent a common
 prefix for each 3PID, helping prevent attackers from pre-computing the
 internal state of the hash function.
+{{% /boxes/rationale %}}
 
 After formatting each query, the string is run through SHA-256 as
 defined by [RFC 4634](https://tools.ietf.org/html/rfc4634). The
@@ -342,12 +342,12 @@ the client has made an appropriate request to `/hash_details` first.
 
 ### Security considerations
 
-Note
-
+{{% boxes/note %}}
 [MSC2134](https://github.com/matrix-org/matrix-doc/pull/2134) has much
 more information about the security considerations made for this section
 of the specification. This section covers the high-level details for why
 the specification is the way it is.
+{{% /boxes/note %}}
 
 Typically the lookup endpoint is used when a client has an unknown 3PID
 it wants to find a Matrix User ID for. Clients normally do this kind of
@@ -359,8 +359,7 @@ protect the privacy of users who might not have a Matrix identifier
 bound to their 3PID addresses, the specification attempts to make it
 difficult to harvest 3PIDs.
 
-Rationale
-
+{{% boxes/rationale %}}
 Hashing identifiers, while not perfect, helps make the effort required
 to harvest identifiers significantly higher. Phone numbers in particular
 are still difficult to protect with hashing, however hashing is
@@ -369,6 +368,7 @@ objectively better than not.
 An alternative to hashing would be using bcrypt or similar with many
 rounds, however by nature of needing to serve mobile clients and clients
 on limited hardware the solution needs be kept relatively lightweight.
+{{% /boxes/rationale %}}
 
 Clients should be cautious of servers not rotating their pepper very
 often, and potentially of servers which use a weak pepper - these

content/rooms/v1.md

@@ -46,30 +46,29 @@ of one of the following event types:
 
 ## Server implementation components
 
-Warning
-
+{{% boxes/warning %}}
 The information contained in this section is strictly for server
 implementors. Applications which use the Client-Server API are generally
 unaffected by the intricacies contained here. The section above
 regarding client considerations is the resource that Client-Server API
 use cases should reference.
+{{% /boxes/warning %}}
 
 The algorithms defined here should only apply to version 1 rooms. Other
 algorithms may be used by other room versions, and as such servers
 should be aware of which version room they are dealing with prior to
 executing a given algorithm.
 
-Warning
-
+{{% boxes/warning %}}
 Although there are many rooms using room version 1, it is known to have
 undesirable effects. Servers implementing support for room version 1
 should be aware that restrictions should be generally relaxed and that
 inconsistencies may occur.
+{{% /boxes/warning %}}
 
 ### State resolution
 
-Warning
-
+{{% boxes/warning %}}
 Room version 1 is known to have bugs that can cause the state of rooms
 to reset to older versions of the room's state. For example this could
 mean that users who had joined the room may be removed from the room,
@@ -79,6 +78,7 @@ as the the room's name or topic could also reset to a previous version.
 
 This is fixed in the state resolution algorithm introduced in room
 version 2.
+{{% /boxes/warning %}}
 
 The room state *S*′(*E*) after an event *E* is defined in terms of the
 room state *S*(*E*) before *E*, and depends on whether *E* is a state
@@ -135,11 +135,11 @@ The types of state events that affect authorization are:
 -   `m.room.power_levels`
 -   `m.room.third_party_invite`
 
-Note
-
+{{% boxes/note %}}
 Power levels are inferred from defaults when not explicitly supplied.
 For example, mentions of the `sender`'s power level can also refer to
 the default power level for users in the room.
+{{% /boxes/note %}}
 
 The rules are as follows:
 
@@ -261,8 +261,7 @@ The rules are as follows:
     3.  Otherwise, reject.
 12. Otherwise, allow.
 
-Note
-
+{{% boxes/note %}}
 Some consequences of these rules:
 
 -   Unless you are a member of the room, the only permitted operations
@@ -271,6 +270,7 @@ Some consequences of these rules:
 -   To unban somebody, you must have power level greater than or equal
     to both the kick *and* ban levels, *and* greater than the target
     user's power level.
+{{% /boxes/note %}}
 
 ### Event format
 

content/rooms/v2.md

@@ -9,12 +9,12 @@ state resolution algorithm.
 
 ## Server implementation components
 
-Warning
-
+{{% boxes/warning %}}
 The information contained in this section is strictly for server
 implementors. Applications which use the Client-Server API are generally
 unaffected by the details contained here, and can safely ignore their
 presence.
+{{% /boxes/warning %}}
 
 Room version 2 uses the base components of [room version 1](v1.html),
 changing only the state resolution algorithm.
@@ -157,8 +157,7 @@ chain should appear in the process, as they should not appear in state
 (the algorithm only uses events that appear in either the state sets or
 in the auth chain of the events in the state sets).
 
-Rationale
-
+{{% boxes/rationale %}}
 This helps ensure that different servers' view of state is more likely
 to converge, since rejection state of an event may be different. This
 can happen if a third server gives an incorrect version of the state
@@ -182,6 +181,7 @@ Intuitively, using rejected events feels dangerous, however:
     the event. The duplicated event would then pass the auth checks.
     Ignoring rejected events would therefore not eliminate any potential
     attack vectors.
+{{% /boxes/rationale %}}
 
 Rejected auth events are deliberately excluded from use in the iterative
 auth checks, as auth events aren't re-authed (although non-auth events

content/rooms/v3.md

@@ -22,21 +22,20 @@ and the potentially problematic slash).
 
 ## Server implementation components
 
-Warning
-
+{{% boxes/warning %}}
 The information contained in this section is strictly for server
 implementors. Applications which use the Client-Server API are generally
 unaffected by the intricacies contained here. The section above
 regarding client considerations is the resource that Client-Server API
 use cases should reference.
+{{% /boxes/warning %}}
 
 Room version 3 uses the state resolution algorithm defined in [room
 version 2](v2.html), and the event format defined here.
 
 ### Event IDs
 
-Rationale
-
+{{% boxes/rationale %}}
 In other room versions (namely version 1 and 2) the event ID is a
 distinct field from the remainder of the event, which must be tracked as
 such. This leads to complications where servers receive multiple events
@@ -44,6 +43,7 @@ with the same ID in either the same or different rooms where the server
 cannot easily keep track of which event it should be using. By removing
 the use of a dedicated event ID, servers are required to track the
 hashes on an event to determine its ID.
+{{% /boxes/rationale %}}
 
 The event ID is the [reference
 hash](../server_server/%SERVER_RELEASE_LABEL%.html#reference-hashes) of

content/rooms/v4.md

@@ -21,26 +21,26 @@ domain).
 
 ## Server implementation components
 
-Warning
-
+{{% boxes/warning %}}
 The information contained in this section is strictly for server
 implementors. Applications which use the Client-Server API are generally
 unaffected by the intricacies contained here. The section above
 regarding client considerations is the resource that Client-Server API
 use cases should reference.
+{{% /boxes/warning %}}
 
 Room version 4 uses the same algorithms defined in [room version
 3](v3.html), however using URL-safe base64 to generate the event ID.
 
 ### Event IDs
 
-Rationale
-
+{{% boxes/rationale %}}
 Room version 3 generated event IDs that were difficult for client
 implementations which were not encoding the event ID to function in
 those rooms. It additionally raised concern due to the `/` character
 being interpretted differently by some reverse proxy software, and
 generally made administration harder.
+{{% /boxes/rationale %}}
 
 The event ID is the [reference
 hash](../server_server/%SERVER_RELEASE_LABEL%.html#reference-hashes) of

content/rooms/v5.md

@@ -15,13 +15,13 @@ Clients should be aware of event ID changes in [room version
 
 ## Server implementation components
 
-Warning
-
+{{% boxes/warning %}}
 The information contained in this section is strictly for server
 implementors. Applications which use the Client-Server API are generally
 unaffected by the intricacies contained here. The section above
 regarding client considerations is the resource that Client-Server API
 use cases should reference.
+{{% /boxes/warning %}}
 
 Room version 5 uses the same algorithms defined in [room version
 4](v4.html), ensuring that signing key validity is respected.

content/rooms/v6.md

@@ -16,13 +16,13 @@ otherwise unchanged.
 
 ## Server implementation components
 
-Warning
-
+{{% boxes/warning %}}
 The information contained in this section is strictly for server
 implementors. Applications which use the Client-Server API are generally
 unaffected by the intricacies contained here. The section above
 regarding client considerations is the resource that Client-Server API
 use cases should reference.
+{{% /boxes/warning %}}
 
 Room version 6 makes the following alterations to algorithms described
 in [room version 5](v5.html).

content/server-server-api.md

@@ -184,12 +184,12 @@ Transparency](https://www.certificate-transparency.org/) project.
 
 ### Retrieving server keys
 
-Note
-
+{{% boxes/note %}}
 There was once a "version 1" of the key exchange. It has been removed
 from the specification due to lack of significance. It may be reviewed
 [from the historical
 draft](https://github.com/matrix-org/matrix-doc/blob/51faf8ed2e4a63d4cfd6d23183698ed169956cc0/specification/server_server_api.rst#232version-1).
+{{% /boxes/note %}}
 
 Each homeserver publishes its public keys under
 `/_matrix/key/v2/server/{keyId}`. Homeservers query for keys by either
@@ -451,21 +451,20 @@ rejected event where it is a state event.
 If an event in an incoming transaction is rejected, this should not
 cause the transaction request to be responded to with an error response.
 
-Note
-
+{{% boxes/note %}}
 This means that events may be included in the room DAG even though they
 should be rejected.
+{{% /boxes/note %}}
 
-Note
-
+{{% boxes/note %}}
 This is in contrast to redacted events which can still affect the state
 of the room. For example, a redacted `join` event will still result in
 the user being considered joined.
+{{% /boxes/note %}}
 
 #### Soft failure
 
-Rationale
-
+{{% boxes/rationale %}}
 It is important that we prevent users from evading bans (or other power
 restrictions) by creating events which reference old parts of the DAG.
 For example, a banned user could continue to send messages to a room by
@@ -486,6 +485,7 @@ clients about the new event.
 
 This discourages servers from sending events that evade bans etc. in
 this way, as end users won't actually see the events.
+{{% /boxes/rationale %}}
 
 When the homeserver receives a new event over federation it should also
 check whether the event passes auth checks based on the current state of
@@ -499,28 +499,28 @@ nor be referenced by new events created by the homeserver (i.e. they
 should not be added to the server's list of forward extremities of the
 room). Soft failed events are otherwise handled as usual.
 
-Note
-
+{{% boxes/note %}}
 Soft failed events participate in state resolution as normal if further
 events are received which reference it. It is the job of the state
 resolution algorithm to ensure that malicious events cannot be injected
 into the room state via this mechanism.
+{{% /boxes/note %}}
 
-Note
-
+{{% boxes/note %}}
 Because soft failed state events participate in state resolution as
 normal, it is possible for such events to appear in the current state of
 the room. In that case the client should be told about the soft failed
 event in the usual way (e.g. by sending it down in the `state` section
 of a sync response).
+{{% /boxes/note %}}
 
-Note
-
+{{% boxes/note %}}
 A soft failed event should be returned in response to federation
 requests where appropriate (e.g. in `/event/<event_id>`). Note that soft
 failed events are returned in `/backfill` and `/get_missing_events`
 responses only if the requests include events referencing the soft
 failed events.
+{{% /boxes/note %}}
 
 Example
 
@@ -783,11 +783,11 @@ the event to other servers in the room.
 
 ## Third-party invites
 
-Note
-
+{{% boxes/note %}}
 More information about third party invites is available in the
 [Client-Server API](../client_server/%CLIENT_RELEASE_LABEL%.html) under
 the Third Party Invites module.
+{{% /boxes/note %}}
 
 When a user wants to invite another user in a room but doesn't know the
 Matrix ID to invite, they can do so using a third-party identifier (e.g.

layouts/partials/alert.html

@@ -0,0 +1,20 @@
+{{/*
+
+  Display an alert box of the given type, containing the given content.
+
+  Supported types are "warning", "info", and "rationale".
+  The type determines the colors used in the box and, by default,
+  the title for the box: WARNING, INFO, RATIONALE.
+
+  By passing "omit_title", a caller can suppress the title, and just get
+  a box using the colors and styles for the given type.
+
+*/}}
+
+{{ $type := .type}}
+{{ $content := .content}}
+{{ $omit_title := .omit_title }}
+
+<div class="alert {{ $type }} {{ if $omit_title }}omit-title{{end}}" role="alert">
+{{ $content | markdownify }}
+</div>

layouts/shortcodes/boxes/note.html

@@ -0,0 +1 @@
+{{ partial "alert" (dict "type" "note" "content" .Inner) }}

layouts/shortcodes/boxes/rationale.html

@@ -0,0 +1 @@
+{{ partial "alert" (dict "type" "rationale" "content" .Inner) }}

layouts/shortcodes/boxes/warning.html

@@ -0,0 +1 @@
+{{ partial "alert" (dict "type" "warning" "content" .Inner) }}