Skip to content
Permalink
Browse files

feat: free content with markdown + new flat theme + minor fixes (matc…

…ornic#9)


* feat: possibility to use markdown as content of email + use pretty table when generating fallback plain text e-mails
* feat: new flat theme
* fix: add a break word policy in actions troubleshooting section, in order to have a better responsive display when using really long Link URL on action
* feat: better layout of dt and dl in HTML template
* feat: pretty tables in plain text
  • Loading branch information...
matcornic committed May 31, 2017
1 parent 6bf6103 commit be1f57b7ab39cdb58e2f2de1f4c4bc23cbecc74b
@@ -334,3 +334,14 @@ In order to support generating RTL e-mails, inject the `textDirection` variable
<body dir="{{.Hermes.TextDirection}}">
```

## FreeMarkdown Injection

In order to support Markdown free content, inject the following code:

````html
{{ if (ne .Email.Body.FreeMarkdown "") }}
{{ .Email.Body.FreeMarkdown.ToHTML }}
{{ else }}
[... Here is the templating for dictionary, table and actions]
{{ end }}
```
111 README.md
@@ -6,7 +6,7 @@
[![Godoc](https://godoc.org/github.com/matcornic/hermes?status.svg)](https://godoc.org/github.com/matcornic/hermes)

Hermes is the Go port of the great [mailgen](https://github.com/eladnava/mailgen) engine for Node.js. Check their work, it's awesome!
It's a package that generates clean, responsive HTML e-mails for sending transactional e-mails (welcome e-mails, reset password e-mails, receipt e-mails and so on).
It's a package that generates clean, responsive HTML e-mails for sending transactional e-mails (welcome e-mails, reset password e-mails, receipt e-mails and so on), and associated plain text fallback.

# Demo

@@ -85,15 +85,35 @@ This code would output the following HTML template:

<img src="screens/demo.png" height="400" />

And the following plain text:

```
------------
Hi Jon Snow,
------------
Welcome to Hermes! We're very excited to have you on board.
To get started with Hermes, please click here: https://hermes-example.com/confirm?token=d9729feb74992cc3482b350163a1a010
Need help, or have questions? Just reply to this email, we'd love to help.
Yours truly,
Hermes - https://example-hermes.com/
Copyright © 2017 Hermes. All rights reserved.
```

> Theme templates will be embedded in your application binary. If you want to use external templates (for configuration), use your own theme by implementing `hermes.Theme` interface with code searching for your files.
## More Examples

* [Welcome](examples/default/welcome.go)
* [Receipt](examples/default/receipt.go)
* [Password Reset](examples/default/reset.go)
* [Welcome](examples/welcome.go)
* [Receipt](examples/receipt.go)
* [Password Reset](examples/reset.go)
* [Maintenance](examples/maintenance.go)

To run the examples, go to `examples/<theme>/`, then run `go run *.go`. HTML and Plaintext example should be created in the folder.
To run the examples, go to `examples` folder, then run `go run *.go`. HTML and Plaintext example should be created in given theme folders.

## Plaintext E-mails

@@ -115,6 +135,10 @@ The following open-source themes are bundled with this package:

<img src="screens/default/welcome.png" height="200" /> <img src="screens/default/reset.png" height="200" /> <img src="screens/default/receipt.png" height="200" />

* `flat`, slightly modified from [Postmark Transactional Email Templates](https://github.com/wildbit/postmark-templates)

<img src="screens/flat/welcome.png" height="200" /> <img src="screens/flat/reset.png" height="200" /> <img src="screens/flat/receipt.png" height="200" />

## RTL Support

To change the default text direction (left-to-right), simply override it as follows:
@@ -247,13 +271,11 @@ email := hermes.Email{
}
```

> Note: Tables are currently not supported in plaintext versions of e-mails.
### Dictionary

To inject key-value pairs of data into the e-mail, supply the `dictionary` object as follows:
To inject key-value pairs of data into the e-mail, supply the `Dictionary` object as follows:

```go
```go
email := hermes.Email{
Body: hermes.Body{
Dictionary: []hermes.Entry{
@@ -264,6 +286,77 @@ email := hermes.Email{
}
```

### Free Markdown

If you need more flexibility in the content of your generated e-mail, while keeping the same format than any other e-mail, use Markdown content. Supply the `FreeMarkdown` object as follows:

```go
email := hermes.Email{
Body: hermes.Body{
FreeMarkdown: `
> _Hermes_ service will shutdown the **1st August 2017** for maintenance operations.
Services will be unavailable based on the following schedule:
| Services | Downtime |
| :------:| :-----------: |
| Service A | 2AM to 3AM |
| Service B | 4AM to 5AM |
| Service C | 5AM to 6AM |
---
Feel free to contact us for any question regarding this matter at [support@hermes-example.com](mailto:support@hermes-example.com) or in our [Gitter](https://gitter.im/)
`,
},
}
}
```

This code would output the following HTML template:

<img src="screens/free-markdown.png" height="400" />

And the following plaintext:

```
------------
Hi Jon Snow,
------------
>
>
>
> Hermes service will shutdown the *1st August 2017* for maintenance
> operations.
>
>
Services will be unavailable based on the following schedule:
+-----------+------------+
| SERVICES | DOWNTIME |
+-----------+------------+
| Service A | 2AM to 3AM |
| Service B | 4AM to 5AM |
| Service C | 5AM to 6AM |
+-----------+------------+
Feel free to contact us for any question regarding this matter at support@hermes-example.com ( support@hermes-example.com ) or in our Gitter ( https://gitter.im/ )
Yours truly,
Hermes - https://example-hermes.com/
Copyright © 2017 Hermes. All rights reserved.
```

Be aware that this content will replace existing tables, dictionnary and actions. Only intros, outros, header and footer will be kept.

This is helpful when your application needs sending e-mails, wrote on-the-fly by adminstrators.

> Markdown is rendered with [Blackfriday](https://github.com/russross/blackfriday), so every thing Blackfriday can do, Hermes can do it as well.
## Troubleshooting

1. After sending multiple e-mails to the same Gmail / Inbox address, they become grouped and truncated since they contain similar text, breaking the responsive e-mail layout.

0 comments on commit be1f57b

Please sign in to comment.
You can’t perform that action at this time.