From c0c7686926f5f997ef38c817600523c934d05c44 Mon Sep 17 00:00:00 2001
From: t <t@tjp.lol>
Date: Fri, 31 Jul 2026 16:40:49 -0600
Subject: Add recursive Markdown rendering templates

---
 README.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index fb0e97f..477a95b 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,77 @@ walking toward the site root before using the fallback. For example,
 `notes/recipes`, `notes`, then `page`. Set a different fallback with
 `-fallback template`; it defaults to `page`.
 
+### Markdown element templates
+
+Templates named with the `markdown/` prefix can replace the HTML wrapper for
+individual Markdown elements. Their `.Content` is the recursively rendered
+content, so nested overrides continue to apply. Undefined element templates use
+Goldmark's default HTML. A build fails if it finds an unsupported
+`markdown/` template name.
+
+| Template | Fields |
+| --- | --- |
+| `markdown/heading1` through `markdown/heading6` | `Content template.HTML`, `ID string` |
+| `markdown/paragraph` | `Content template.HTML` |
+| `markdown/blockquote` | `Content template.HTML` |
+| `markdown/code_block` | `Content template.HTML` |
+| `markdown/fenced_code_block` | `Content template.HTML`, `HighlightedContent template.HTML`, `Language string` |
+| `markdown/unordered_list` | `Content template.HTML`, `Tight bool` |
+| `markdown/ordered_list` | `Content template.HTML`, `Start int`, `Tight bool` |
+| `markdown/list_item` | `Content template.HTML` |
+| `markdown/thematic_break` | no fields |
+| `markdown/emphasis` | `Content template.HTML` |
+| `markdown/strong` | `Content template.HTML` |
+| `markdown/code_span` | `Content template.HTML` |
+| `markdown/link` | `Content template.HTML`, `Destination string`, `Title string` |
+| `markdown/autolink` | `Content template.HTML`, `Destination string` |
+| `markdown/email_autolink` | `Content template.HTML`, `Destination string` |
+| `markdown/image` | `Alt string`, `Destination string`, `Title string` |
+| `markdown/hard_break` | no fields |
+| `markdown/strikethrough` | `Content template.HTML` |
+| `markdown/task_checkbox` | `Checked bool` |
+| `markdown/table` | `Content template.HTML` |
+| `markdown/table_header` | `Content template.HTML` |
+| `markdown/table_body` | `Content template.HTML` |
+| `markdown/table_row` | `Content template.HTML` |
+| `markdown/table_header_cell` | `Content template.HTML`, `Alignment string` |
+| `markdown/table_cell` | `Content template.HTML`, `Alignment string` |
+
+`.Content` is trusted, already-rendered HTML. For code spans and code blocks it
+is escaped source text instead. Images flatten their description to plain
+`.Alt`; elements without child content omit `.Content`. Destinations, titles,
+language names, IDs, and alt text remain plain strings and are contextually
+escaped by `html/template`. Raw Markdown HTML stays disabled and has no
+override.
+
+`Tight` follows CommonMark: tight list items contain unwrapped inline content,
+while loose-list paragraphs pass through `markdown/paragraph`. `Start` is the
+first ordered-list marker, including `1`; later markers do not change item
+numbers. Table cell `.Alignment` is `left`, `right`, `center`, or `none`.
+`markdown/table_body` represents the generated `<tbody>` and is omitted when a
+table has no body rows.
+
+Defining `markdown/fenced_code_block` also enables build-time highlighting.
+`.Language` is the first word of the fence info string. For a known exact
+Chroma language, `.HighlightedContent` contains escaped, class-based token
+markup with the fixed `chroma-` CSS-class prefix and no `<pre>` or `<code>`
+wrapper. It is empty for blank or unknown languages and on highlighting errors;
+`.Content` always provides escaped source as a safe fallback. Weft does not
+generate CSS or client-side JavaScript.
+
+```gotemplate
+{{define "markdown/paragraph"}}<p class="weft">{{.Content}}</p>{{end}}
+{{define "markdown/ordered_list"}}
+<ol class="weft"{{if ne .Start 1}} start="{{.Start}}"{{end}}>{{.Content}}</ol>
+{{end}}
+{{define "markdown/list_item"}}<li class="weft">{{.Content}}</li>{{end}}
+{{define "markdown/fenced_code_block"}}
+<pre class="weft chroma"><code class="weft language-{{.Language}}">{{if .HighlightedContent}}{{.HighlightedContent}}{{else}}{{.Content}}{{end}}</code></pre>
+{{end}}
+{{define "markdown/table_header"}}<thead class="weft"><tr class="weft">{{.Content}}</tr></thead>{{end}}
+{{define "markdown/table_body"}}<tbody class="weft">{{.Content}}</tbody>{{end}}
+```
+
 ## Template data
 
 Every template receives this root value:
-- 
cgit v1.3