Merge pull request #2003 from umputun/docs/email-template-variables

Document email template variables and plain-text email setup

Author: umputun

site/src/docs/configuration/email/index.md

@@ -218,3 +218,79 @@ The easiest way to test it is to mount `error_response.html.tmpl`, and then head
 ![Error_template](images/error_template.png)
 
 If the file is mounted correctly, the page will render the new file content immediately after hitting the refresh button in your browser once you change the file.
+
+### Template variables
+
+Each template has access to different variables. All templates use Go's [text/template](https://pkg.go.dev/text/template) syntax.
+
+#### `email_reply.html.tmpl` — comment notification
+
+Used for notifying users about replies to their comments and for admin notifications about new comments.
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `{{.UserName}}` | string | Comment author name |
+| `{{.UserPicture}}` | string | Comment author avatar URL |
+| `{{.CommentText}}` | string | Comment body (HTML) |
+| `{{.CommentLink}}` | string | Direct link to the comment |
+| `{{.CommentDate}}` | time.Time | Comment timestamp, format with `{{.CommentDate.Format "02.01.2006 at 15:04"}}` |
+| `{{.ParentUserName}}` | string | Parent comment author name |
+| `{{.ParentUserPicture}}` | string | Parent comment author avatar URL |
+| `{{.ParentCommentText}}` | string | Parent comment body (HTML) |
+| `{{.ParentCommentLink}}` | string | Direct link to parent comment |
+| `{{.ParentCommentDate}}` | time.Time | Parent comment timestamp |
+| `{{.PostTitle}}` | string | Title of the post |
+| `{{.Email}}` | string | Recipient email address |
+| `{{.UnsubscribeLink}}` | string | Unsubscribe URL |
+| `{{.ForAdmin}}` | bool | True when this is an admin notification |
+
+#### `email_confirmation_subscription.html.tmpl` — subscription confirmation
+
+Sent when a user subscribes to email notifications for a comment thread.
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `{{.User}}` | string | Username |
+| `{{.Token}}` | string | Confirmation token |
+| `{{.Email}}` | string | Recipient email address |
+| `{{.Site}}` | string | Site name |
+| `{{.SubscribeURL}}` | string | Subscription confirmation base URL |
+
+#### `email_confirmation_login.html.tmpl` — login confirmation
+
+Sent when a user logs in via email authentication.
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `{{.User}}` | string | Username |
+| `{{.Token}}` | string | Login token |
+| `{{.Email}}` | string | Recipient email address |
+| `{{.Site}}` | string | Site name |
+| `{{.Address}}` | string | Recipient address |
+
+### Plain-text emails
+
+The default templates produce HTML emails. To send plain-text emails instead, set `AUTH_EMAIL_CONTENT_TYPE=text/plain` (for login confirmation) or `NOTIFY_EMAIL_CONTENT_TYPE=text/plain` (for notifications), and provide custom templates that output plain text instead of HTML.
+
+Note that `{{.CommentText}}` and `{{.ParentCommentText}}` contain HTML markup. There is no built-in HTML-to-text conversion, so for comments with rich formatting the output will include raw HTML tags.
+
+Example plain-text notification template (`email_reply.html.tmpl`):
+
+```
+New reply from {{.UserName}}{{if .PostTitle}} on "{{.PostTitle}}"{{end}}
+
+{{.CommentText}}
+{{.CommentDate.Format "02.01.2006 at 15:04"}}
+{{.CommentLink}}
+{{- if .ParentCommentText}}
+
+In reply to {{.ParentUserName}}:
+{{.ParentCommentText}}
+{{.ParentCommentLink}}
+{{- end}}
+
+Sent to {{.Email}}
+{{- if .UnsubscribeLink}}
+Unsubscribe: {{.UnsubscribeLink}}
+{{- end}}
+```