Enforce consistent vertical spacing between paragraphs in endpoint definitions (#1969)

Use `p` elements to separate paragraphs instead of `br` and enforce single paragraphs to be wrapped in `p` for consistency.

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

assets/scss/_styles_project.scss

@@ -387,6 +387,11 @@ footer {
       border-top: 1px $table-border-color solid;
     }
 
+    td > p:last-child {
+      // Avoid unnecessary space at the bottom of the cells.
+      margin-bottom: 0;
+    }
+
     &.object-table, &.response-table, &.content-type-table {
         border: 1px $table-border-color solid;
 

changelogs/internal/newsfragments/1969.clarification

@@ -0,0 +1 @@
+Enforce consistent vertical spacing between paragraphs in endpoint definitions.

layouts/partials/added-in.html

@@ -1,13 +1,13 @@
-{{ $ver := .v }}
+{{ $ver := .v -}}
-{{ $this := .this }}
+{{ $this := .this -}}
 
 {{/*
     This differs from the shortcode added-in by wanting to be a block instead of inline
     and by slightly altering the rendered text as a result.
 */}}
 
-{{ if $this }}
+{{ if $this -}}
-  **New in this version.**
+  <p><strong>New in this version.</strong></p>
-{{ else }}
+{{ else -}}
-  **Added in `v{{ $ver }}`**
+  <p><strong>Added in <code>v{{ $ver }}</code></strong></p>
-{{ end }}
+{{ end -}}

layouts/partials/changed-in.html

@@ -6,9 +6,10 @@
     version -> details pairs.
 */ -}}
 {{ range $ver, $details := .changes_dict -}}
-    <br><br>
+  <p>
     <strong>
       Changed in <code>v{{ $ver }}</code>:
     </strong>
     {{ $details | markdownify }}
-{{ end }}
+  </p>
+{{ end -}}

layouts/partials/openapi/render-content-type.html

@@ -21,7 +21,12 @@
  <tr>
   <td><code>{{ $mime }}</code></td>
   <td>
-   {{ $body.schema.description | markdownify -}}
+   {{/*
+     Force the rendering as a block so the description is always inside a
+     paragraph. This allows to always keep the same spacing between paragraphs
+     when adding added-in and changed-in paragraphs.
+   */}}
+   {{ $body.schema.description | page.RenderString (dict "display" "block") -}}
    {{ if (index $body.schema "x-addedInMatrixVersion") }}{{ partial "added-in" (dict "v" (index $body.schema "x-addedInMatrixVersion")) }}{{ end -}}
    {{ if (index $body.schema "x-changedInMatrixVersion") }}{{ partial "changed-in" (dict "changes_dict" (index $body.schema "x-changedInMatrixVersion")) }}{{ end -}}
   </td>

layouts/partials/openapi/render-object-table.html

@@ -306,9 +306,21 @@ resolve-additional-types.)
       * `x-changedInMatrixVersion`: optional string indicating in which Matrix
         spec version this property was last changed.
 */}}
-{{ define "partials/property-description" }}
+{{ define "partials/property-description" -}}
-    {{ if .required }}<strong>Required: </strong>{{end -}}
+    {{ $description := .property.description -}}
-    {{ .property.description | markdownify -}}
+    {{ if .required -}}
+        {{/*
+          Prepend "Required:" to make it part of the first paragraph of the
+          description.
+        */}}
+        {{- $description = printf "<strong>Required: </strong>%s" $description -}}
+    {{ end -}}
+    {{/*
+      Force the rendering as a block so the description is always inside a
+      paragraph. This allows to always keep the same spacing between paragraphs
+      when adding added-in and changed-in paragraphs.
+    */}}
+    {{ $description | page.RenderString (dict "display" "block") -}}
     {{ if .property.enum }}<p>One of: <code>[{{ delimit .property.enum ", " }}]</code>.</p>{{ end -}}
     {{ if (index .property "x-addedInMatrixVersion") }}{{ partial "added-in" (dict "v" (index .property "x-addedInMatrixVersion")) }}{{ end -}}
     {{ if (index .property "x-changedInMatrixVersion") }}{{ partial "changed-in" (dict "changes_dict" (index .property "x-changedInMatrixVersion")) }}{{ end -}}