From 1f5f2c4d8380d3294781b31089138efb105f0e77 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 29 Oct 2024 16:22:15 +0100
Subject: [PATCH] Enforce consistent vertical spacing between paragraphs in
 endpoint definitions (#1969)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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               |  5 +++++
 .../internal/newsfragments/1969.clarification  |  1 +
 layouts/partials/added-in.html                 | 14 +++++++-------
 layouts/partials/changed-in.html               |  5 +++--
 .../partials/openapi/render-content-type.html  |  7 ++++++-
 .../partials/openapi/render-object-table.html  | 18 +++++++++++++++---
 6 files changed, 37 insertions(+), 13 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1969.clarification

diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss
index 2c31820b..e974a838 100644
--- a/assets/scss/_styles_project.scss
+++ b/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;
 
diff --git a/changelogs/internal/newsfragments/1969.clarification b/changelogs/internal/newsfragments/1969.clarification
new file mode 100644
index 00000000..db9e1a1a
--- /dev/null
+++ b/changelogs/internal/newsfragments/1969.clarification
@@ -0,0 +1 @@
+Enforce consistent vertical spacing between paragraphs in endpoint definitions.
\ No newline at end of file
diff --git a/layouts/partials/added-in.html b/layouts/partials/added-in.html
index c75c0676..1ab3ad4c 100644
--- a/layouts/partials/added-in.html
+++ b/layouts/partials/added-in.html
@@ -1,13 +1,13 @@
-{{ $ver := .v }}
-{{ $this := .this }}
+{{ $ver := .v -}}
+{{ $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 }}
-  **New in this version.**
-{{ else }}
-  **Added in `v{{ $ver }}`**
-{{ end }}
+{{ if $this -}}
+  <p><strong>New in this version.</strong></p>
+{{ else -}}
+  <p><strong>Added in <code>v{{ $ver }}</code></strong></p>
+{{ end -}}
diff --git a/layouts/partials/changed-in.html b/layouts/partials/changed-in.html
index 8a815904..61aba5b1 100644
--- a/layouts/partials/changed-in.html
+++ b/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 -}}
diff --git a/layouts/partials/openapi/render-content-type.html b/layouts/partials/openapi/render-content-type.html
index a7c90e1a..b1f8239d 100644
--- a/layouts/partials/openapi/render-content-type.html
+++ b/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>
diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html
index 656f556a..7343a839 100644
--- a/layouts/partials/openapi/render-object-table.html
+++ b/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" }}
-    {{ if .required }}<strong>Required: </strong>{{end -}}
-    {{ .property.description | markdownify -}}
+{{ define "partials/property-description" -}}
+    {{ $description := .property.description -}}
+    {{ 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 -}}