diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 71 |
1 files changed, 71 insertions, 0 deletions
@@ -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: |