From 2cee8e0a98c4821a4fe06665cc1928d6c507f459 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <zecakeh@tedomum.fr>
Date: Fri, 21 Feb 2025 11:26:40 +0100
Subject: [PATCH] Deduplicate code for rendering examples
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

That way if we fix the rendering in one place, we fix it everywhere.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 layouts/partials/events/example.html          |  8 +---
 layouts/partials/openapi/render-request.html  | 19 +--------
 .../partials/openapi/render-responses.html    |  8 +---
 layouts/partials/render-example.html          | 40 +++++++++++++++++++
 layouts/shortcodes/definition.html            |  5 +--
 5 files changed, 44 insertions(+), 36 deletions(-)
 create mode 100644 layouts/partials/render-example.html

diff --git a/layouts/partials/events/example.html b/layouts/partials/events/example.html
index 90752fbd..c24cd66b 100644
--- a/layouts/partials/events/example.html
+++ b/layouts/partials/events/example.html
@@ -13,10 +13,4 @@
 {{ $path := delimit (slice "event-schemas/examples" .name) "/" }}
 
 {{ $example_content := partial "json-schema/resolve-refs" (dict "schema" .schema "path" $path) }}
-{{ $example_json := jsonify (dict "indent" "  ") $example_content }}
-{{ $example_json = replace $example_json "\\u003c" "<" }}
-{{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
-
-```json
-{{ $example_json }}
-```
+{{ partial "render-example" (dict "example" $example_content) }}
diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html
index 80b352c6..a77271d8 100644
--- a/layouts/partials/openapi/render-request.html
+++ b/layouts/partials/openapi/render-request.html
@@ -73,24 +73,7 @@
                 {{ $example = $body.example }}
             {{ end }}
 
-            {{ if eq $mime "application/json" }}
-                {{ $example_json := jsonify (dict "indent" "  ") $example }}
-                {{ $example_json = replace $example_json "\\u003c" "<" }}
-                {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
-```json
-{{ $example_json }}
-```
-            {{ else }}
-                {{ $example = $example | safeHTML }}
-                {{/*
-                    We need to set a language for the code otherwise the styling
-                    is different than other examples.
-                */}}
-```json
-{{ $example }}
-```
-            {{ end }}
-
+            {{ partial "render-example" (dict "example" $example "mime" $mime) }}
         {{ end }}
     {{ end }}
 
diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html
index 084e9481..971e58d4 100644
--- a/layouts/partials/openapi/render-responses.html
+++ b/layouts/partials/openapi/render-responses.html
@@ -112,13 +112,7 @@
                     {{ $example = $json_body.examples.response.value }}
                 {{ end }}
 
-                {{ $example_json := jsonify (dict "indent" "  ") $example }}
-                {{ $example_json = replace $example_json "\\u003c" "<" }}
-                {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
-
-```json
-{{ $example_json }}
-```
+                {{ partial "render-example" (dict "example" $example) }}
             {{ end }}
         {{  else }}
             {{/*
diff --git a/layouts/partials/render-example.html b/layouts/partials/render-example.html
new file mode 100644
index 00000000..1f6c18fb
--- /dev/null
+++ b/layouts/partials/render-example.html
@@ -0,0 +1,40 @@
+{{/*
+
+    Renders an example to be included in HTML, with support for pretty-printing
+    JSON.
+
+    Parameters:
+
+    * `example`: the example
+    * `mime`: the mime type of the example. Used to pretty-print JSON and for
+      syntax highlighting. If it is not provided, it is assumed to be
+      `application/json`.
+
+*/}}
+
+{{ $example := .example }}
+
+{{/*
+    We need to convert the mime type to a recognized language.
+    For simplicity we only support JSON, which is also the default. Other mime
+    types are not highlighted.
+*/}}
+{{ $language := "json" }}
+
+{{ if (and .mime (ne .mime "application/json")) }}
+    {{/*
+        `no-highlight` treats the value as plain text, but still styles the code
+        block like the ones with proper syntax highlighting.
+    */}}
+    {{ $language = "no-highlight" }}
+{{ end }}
+
+{{ if eq $language "json" }}
+    {{ $example = jsonify (dict "indent" "  ") $example }}
+    {{ $example = replace $example "\\u003c" "<" }}
+    {{ $example = replace $example "\\u003e" ">" }}
+{{ end }}
+
+```{{ $language }}
+{{ $example | safeHTML }}
+```
diff --git a/layouts/shortcodes/definition.html b/layouts/shortcodes/definition.html
index 10ad0e87..bf0b944a 100644
--- a/layouts/shortcodes/definition.html
+++ b/layouts/shortcodes/definition.html
@@ -61,10 +61,7 @@
 <h2>Examples</h2>
 
 {{ $example := partial "json-schema/resolve-example" $definition }}
-
-```json
-{{ jsonify (dict "indent" "  ") $example }}
-```
+{{ partial "render-example" (dict "example" $example) }}
 
 </details>