From aee4df6dc1509fc38fb868c06bc58351446a5871 Mon Sep 17 00:00:00 2001
From: Daniel Thwaites <danth@danth.me>
Date: Wed, 2 Apr 2025 15:26:00 +0100
Subject: [PATCH] doc: add link to CommonMark Spec (#1081)

---
 docs/default.nix | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/default.nix b/docs/default.nix
index dacb0978..6fe0f9b4 100644
--- a/docs/default.nix
+++ b/docs/default.nix
@@ -305,8 +305,9 @@ let
       builtins.throw "declaration not in ${declarationPrefix}: ${declarationString}";
 
   # You can embed HTML inside a Markdown document, but to render further
-  # Markdown within that HTML, it must be surrounded by blank lines.
-  # This function helps with that.
+  # Markdown between the HTML tags, it must be surrounded by blank lines:
+  # see https://spec.commonmark.org/0.31.2/#html-blocks. This function
+  # helps with that.
   #
   # In the following functions, we use concatStrings to build embedded HTML,
   # rather than ${} and multiline strings, because Markdown is sensitive to