Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/KeepSafe/ks-email-parser
A command line tool to render HTML and text emails of markdown content.
https://github.com/KeepSafe/ks-email-parser
Last synced: 3 months ago
JSON representation
A command line tool to render HTML and text emails of markdown content.
- Host: GitHub
- URL: https://github.com/KeepSafe/ks-email-parser
- Owner: KeepSafe
- License: apache-2.0
- Created: 2014-08-15T01:03:25.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2022-07-06T19:31:45.000Z (over 2 years ago)
- Last Synced: 2024-08-07T14:41:05.932Z (3 months ago)
- Language: Python
- Size: 349 KB
- Stars: 35
- Watchers: 19
- Forks: 3
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG
- License: LICENSE
Awesome Lists containing this project
README
# ks-email-parser [](https://travis-ci.org/KeepSafe/ks-email-parser)
A command line tool name `ks-email-parser` to render HTML and text emails of markdown content.
## Goal
The goal is to store emails in a unified format that is easy to translate and to generate HTML and text emails off. It should be easy for translators to maintain content formatting accords different languages.
## Requirements
1. Python 3.+
2. libxml - on OSX install with `xcode-select --install`
## Installation
`make install`
## Usage
`ks-email-parser` in root folder to generate all emails.
### Options
Run `ks-email-parser --help` to see available options.
## Format
Emails are defined as plain text or markdown for simple translation. The folder structure makes it easy to plug into an existing translation tool.
The content of each email is stored in a XML file that contains all content, the subject and the assosiated HTML template.
### Syntax
```
text_string
```
#### Inline text
By default any text simple text you put in a `` tag will be wrapped in a `
` tag, so `simple text` would become `
simple text
`.
This is standard markdown behaviour. In case you want to get raw text output, for example if you want to use it in a link tag,
wrap the entire block in `[[text]]`, for example `[[www.google.pl]]` would become `www.google.pl`.
This is true only for entire blocks of text (paragraphs separated by blanck lines), `[[www.google.pl]] hello`
would be rendered as `[[www.google.pl]] hello`
#### Link locale
`{link_locale}` is special placeholder, which is resolved by mapping located in `src/link_locale_mappings.json` during rendering.
If email locale couldn't be mapped to link locale, it's `en` by default.
```
{
"email locale": "link locale",
"zh-TW-Hant": "zh"
}
```
If email locale will be `zh-TW-Hant`, then `[something](https://getkeepsafe.com/?locale={link_locale})` will be rendered as `[something](https://getkeepsafe.com/?locale=zh)`.
#### Base url for images
The parser will automatically add base_url to any image tag in markdown, so `` and base url `base_url`
will produce `
`
#### No tracking for links in Sendgrid
Click tracking interferes with our deep links by augmenting the link. To disable click tracking for specific links add `!` in front of a link like so `[Alt text](!keepsafe://)`
### Elements
#### `resource`
Resource attributes:
- **template** - the name of the corresponding HTML template to render
- **style** - (optional) comma separated value of CSS to be used for HTML templates. Those will be applied in order of the list.
#### `string`
Content formatting
- Plain text
- Markdown wrapped in `![CDATA[`
String attributes:
- **name** - Name of the matching place holder `[name_value]` in the HTML template
- **order** - (optional) in case of multiple string elements, they get rendered in the right order into text emails.
#### Example
```
Verify your email address with KeepSafe.
```
## Templates
HTML templates use [Mustache](http://mustache.github.io/) to parse the template. You can use `{{name}}` inside a template and it will be replace by `name` string element from the email XML or you can use `{{global_name}}` and it will be replaced by `name` string elemenet from `/global.xml` (this file has exactly the same structure as usual email XML and behaviour, except it won't be parsed). You can find example of the templates in `templates_html` folder in this repo.
## Folder structure
```
src/
en/
email_template.xml
global.xml
target/
templates_html/
html_template.html
html_template.css
```
- `src/` - all email content by local. e.g. `src/en/` for english content
- `target/` - Output folder generated. Contains the same local subfolders as `src/`. Each email generates 3 files with the self explained file extensions `.txt`, `.html` and `.subject`
- `templates_html/` - all HTML templates and CSS styles. A HTML template can have a corresponding CSS file with the same name.
This structure is configurable. By changing `source`, `destination`, `templates` and `pattern` you can use a structure you like. The `pattern` parameter is especially useful as it controls directory layout and email names. the default is `{locale}/{name}.xml` but you can use `{name}.{locale}.xml` if you don't want to have nested directories. Keep in mind both `name` and `locale` are required in the pattern.
## Rendering
*ks-email-parser* renders email content into HTML in 2 steps.
1. Render markdown files into simple HTML
2. Inserting CSS style definitions from `html_template.css` inline into the HTML. The goal is to support email clients that don't support inline CSS formatting.
### Strict mode
You can use `--strict` option to make sure all placeholders are filled. If there are leftover placeholders the parsing will fail with an error.
### isText
In case you want to put some non-text values in emails, like colors, you can use placeholders which will be ignored in text emails:
`[[#C0D9D9]]`
The only valid false value for isText is `false`, everything else counts as true including omitting the attribute.
## Placeholders validation
To make sure the placeholders are consistent between languages and every language has all needed placeholders you can create configuration file to hold needed placeholders.
### Config file
The file is a mapping of name to required placeholders and the number of times they appear. It's a json file with structure as below:
```
{
"email name" : {"placeholder1":1, "placeholder2":2}
}
```
You can generate the file in the provided source directory from existing emails with
```
$ ks-email-parser config placeholders
```
It will go through your email and extract placeholders.
### Validation
If the config file is present in the source directory each email will be validated for having placeholders specified in the file. The parsing will fail with an error if any email is missing one of required placeholders.
## 3rd party support
Some 3rd party services have custom formats to represent emails in multiple languages. This is a list of supported providers.
### Customer.io
Customer.io defines their own multi language email format. More: [http://customer.io/docs/localization-i18n.html](http://customer.io/docs/localization-i18n.html)
#### Usage
`ks-email-parser customerio [email_name]`
Generates a valid customer.io multi language email format into the `target/` folder.