From 56f3d84b753eaff2b8a6d421fcb34b38b3b5e963 Mon Sep 17 00:00:00 2001 From: Lukas Wagner Date: Wed, 9 Apr 2025 09:47:13 +0200 Subject: [PATCH] notifications: add section about how to use custom templates This section is meant to give a basic overview on how to use custom templates for notifications. It will be expanded in the future, providing a more detailed view on how templates are resolved, existing fallback mechanisms, available templates, template variables and helpers. Signed-off-by: Lukas Wagner Reviewed-by: Alexander Zeidler Link: https://lore.proxmox.com/20250409074713.55474-1-l.wagner@proxmox.com --- notifications.adoc | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/notifications.adoc b/notifications.adoc index 331ac1d..0b0311b 100644 --- a/notifications.adoc +++ b/notifications.adoc @@ -462,3 +462,28 @@ to `auto`. The `legacy-sendmail` mode might be removed in a later release of {pve}. + +Overriding Notification Templates +--------------------------------- + +{pve} uses Handlebars templates to render notifications. The +original templates provided by {pve} are stored in +`/usr/share/pve-manager/templates/default/`. + +Notification templates can be overridden by providing a custom template +file in the override directory at `/etc/pve/notification-templates/default/`. +When rendering a notification of a given type, {pve} will first attempt +to load a template from the override directory. If this one does not +exist or fails to render, the original template will be used. + +The template files follow the naming convention of +`-..hbs`. For instance, the file +`vzdump-body.html.hbs` contains the template for rendering the HTML version +for backup notifications, while `package-updates-subject.txt.hbs` is used to +render the subject line of notifications for available package updates. + +Email-based notification targets, such as `sendmail` and `smtp`, always send +multi-part messages with an HTML and a plain text part. As a result, both +the `-body.html.hbs` as well as the `-body.txt.hbs` template +will be used when rendering the email message. All other notification +target types only use the `-body.txt.hbs` template.