diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss
index 639536974..f28a1267d 100644
--- a/assets/scss/_styles_project.scss
+++ b/assets/scss/_styles_project.scss
@@ -410,6 +410,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 000000000..db9e1a1af
--- /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 c75c0676d..1ab3ad4cb 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 -}}
+
New in this version.
+{{ else -}}
+ Added in v{{ $ver }}
+{{ end -}}
diff --git a/layouts/partials/changed-in.html b/layouts/partials/changed-in.html
index 8a815904c..61aba5b1e 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 -}}
-
+
Changed in v{{ $ver }}
:
{{ $details | markdownify }}
-{{ end }}
+
+{{ end -}}
diff --git a/layouts/partials/openapi/render-content-type.html b/layouts/partials/openapi/render-content-type.html
index a7c90e1ac..b1f8239d6 100644
--- a/layouts/partials/openapi/render-content-type.html
+++ b/layouts/partials/openapi/render-content-type.html
@@ -21,7 +21,12 @@
{{ $mime }} |
- {{ $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 -}}
|
diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html
index 656f556a7..7343a839c 100644
--- a/layouts/partials/openapi/render-object-table.html
+++ b/layouts/partials/openapi/render-object-table.html
@@ -306,9 +306,21 @@
* `x-changedInMatrixVersion`: optional string indicating in which Matrix
spec version this property was last changed.
*/}}
-{{ define "partials/property-description" }}
- {{ if .required }}Required: {{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 "Required: %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 }}One of: [{{ delimit .property.enum ", " }}]
.
{{ 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 -}}