From b077fceef78e9bda5f1402c22f8e7d4ffb47d0e3ac242ea8297981c45e30155b Mon Sep 17 00:00:00 2001
From: Nicholas Johnson <nick@nicholasjohnson.ch>
Date: Tue, 9 May 2023 00:00:00 +0000
Subject: Document gemini single page renderer

---
 TODO                        |  1 -
 layouts/_default/single.gmi | 26 ++++++++++++++++++++++++++
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/TODO b/TODO
index a777eaf..7053e36 100644
--- a/TODO
+++ b/TODO
@@ -1,5 +1,4 @@
 * fix spacing
-* document "layouts/_default/single.gmi"
 * test internationalization
 * make non-critical page elements optional
 * add color themes
diff --git a/layouts/_default/single.gmi b/layouts/_default/single.gmi
index f1218a4..cb834df 100644
--- a/layouts/_default/single.gmi
+++ b/layouts/_default/single.gmi
@@ -9,7 +9,11 @@
 # {{ .Name | safeHTML }}
 {{ $content := .RawContent }}
 {{- $scratch := newScratch }}
+
+{{/*- split text into chunks, with each chunk containing 3 parts: above, within, and below preformatted text */}}
+{{/*- the regex matching below the preformatted text matches exactly once in the entire text */}}
 {{- $chunks := findRESubmatch `(?sm)(?:(.+?)(^\x60{3}[^\x60].*?^\x60{3}$))|(.+$)` $content }}
+
 {{- $ref_index := 0 }}
 
 {{- range $chunks }}
@@ -17,26 +21,44 @@
 	{{- $pre        := index . 2 }}
 	{{- $below_pre  := index . 3 }}
 
+	{{/*- mux regex matches above and below preformatted text for rendering (the matches are mutually exclusive) */}}
 	{{- $rendered_text := print $above_pre $below_pre }}
 
 	{{- if ($.Page.Params.makerefs | default true) }}
+
+		{{/*- find all the links within a chunk */}}
 		{{- $chunk_refs := findRESubmatch `!?\[\s*(.+?)\s*\]\(\s*(.+?)(?:\s+"(.+?)")?\s*\)` $rendered_text }}
+
 		{{- $scratch.Add "refs" $chunk_refs }}
 		{{- range $chunk_refs }}
 			{{- $ref_index = add $ref_index 1 }}
 			{{- $ref_text := index . 1 }}
+
+			{{/*- replace link with reference numbers enclosed in brackets */}}
 			{{- $rendered_text = replace $rendered_text (index . 0) (print $ref_text "[" $ref_index "]") 1 }}
+
 		{{- end }}
 	{{- else }}
+
+		{{/*- render all links directly */}}
 		{{- $rendered_text = $rendered_text | replaceRE `(?m)^!?\[\s*(.+?)\s*\]\(\s*(.+?)(?:\s+"(.+?)")?\s*\)$` (print "=> $2 " $emoji "$1") }}
+
 	{{- end }}
+
+	{{/*- trim extra heading symbols */}}
 	{{- $rendered_text = $rendered_text | replaceRE `(?m)^####{1,3}` "###" }}
+
+	{{/*- remove bold and italics asterisk symbols */}}
 	{{- $rendered_text = $rendered_text | replaceRE `\*{3}(\S|\S.*?\S)\*{3}` "$1" }}
 	{{- $rendered_text = $rendered_text | replaceRE `\*{2}(\S|\S.*?\S)\*{2}` "$1" }}
 	{{- $rendered_text = $rendered_text | replaceRE `\*{1}(\S|\S.*?\S)\*{1}` "$1" }}
+
+	{{/*- convert alternative unordered lists symbols to asterisks */}}
 	{{- $rendered_text = $rendered_text | replaceRE `(?m)^[-+] ` "* " }}
+
 	{{- $rendered_text = $rendered_text | emojify }}
 
+	{{/*- demux regex matches above and below preformatted text */}}
 	{{- if $above_pre }}
 		{{- $rendered_text | safeHTML }}
 		{{- $pre | safeHTML }}
@@ -44,6 +66,7 @@
 		{{- $pre | safeHTML }}
 		{{- $rendered_text | safeHTML }}
 	{{- end }}
+
 {{- end }}
 
 {{- $refs := $scratch.Get "refs" }}
@@ -56,7 +79,10 @@
 		{{- $ref_text  := index . 1 }}
 		{{- $ref_link  := index . 2 }}
 		{{- $ref_title := index . 3 }}
+
+{{/*- render referenced links */}}
 {{ print "=> " $ref_link (emojify " :link: ") $ref_index ": " (cond (ne (len $ref_title) 0) $ref_title $ref_text) | safeHTML }}
+
 	{{- end }}
 {{- end }}
 {{- end }}
-- 
cgit v1.2.3