{
    "info": {
        "author": "Keepsafe",
        "author_email": "support@getkeepsafe.com",
        "bugtrack_url": null,
        "classifiers": [
            "Intended Audience :: Developers",
            "License :: OSI Approved :: BSD License",
            "Programming Language :: Python"
        ],
        "description": "# ks-email-parser [![Build Status](https://travis-ci.org/KeepSafe/ks-email-parser.svg?branch=master)](https://travis-ci.org/KeepSafe/ks-email-parser)\n\nA command line tool name `ks-email-parser` to render HTML and text emails of markdown content.\n\n## Goal\nThe 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.  \n\n## Requirements\n\n1. Python 3.+\n2. libxml - on OSX install with `xcode-select --install`\n\n## Installation\n\n`make install`\n\n## Usage\n\n`ks-email-parser` in root folder to generate all emails.\n\n\n### Options\n\nRun `ks-email-parser --help` to see available options.\n\n\n## Format\nEmails are defined as plain text or markdown for simple translation. The folder structure makes it easy to plug into an existing translation tool.  \nThe content of each email is stored in a XML file that contains all content, the subject and the assosiated HTML template.\n\n### Syntax\n\n```\n<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<resources template=\"html_template_name\" style=\"css_style_name\">\n    <string\n        name=\"template_placeholder_name\"\n        order=\"order_for text conversion\"\n        >text_string</string>\n</resources>\n```\n\n#### Inline text\n\nBy default any text simple text you put in a `<string>` tag will be wrapped in a `<p>` tag, so `simple text` would become `<p>simple text</p>`.\nThis 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,\nwrap the entire block in `[[text]]`, for example `<string name=\"link\">[[www.google.pl]]</string>` would become `www.google.pl`.\nThis is true only for entire blocks of text (paragraphs separated by blanck lines), `<string name=\"link\">[[www.google.pl]] hello</string>`\nwould be rendered as `[[www.google.pl]] hello`\n\n#### Base url for images\n\nThe parser will automatically add base_url to any image tag in markdown, so `![Alt text](/path/to/img.jpg)` and base url `base_url`\nwill produce `<img alt=\"Alt text\" src=\"base_url/path/to/img.jpg\" />`\n\n### Elements\n\n#### `resource`\nResource attributes:\n\n- **template** - the name of the corresponding HTML template to render\n- **style** - (optional) comma separated value of CSS to be used for HTML templates. Those will be applied in order of the list.\n\n#### `string`\nContent formatting\n\n- Plain text\n- Markdown wrapped in `![CDATA[`\n\nString attributes:\n\n- **name** - Name of the matching place holder `[name_value]` in the HTML template\n- **order** - (optional) in case of multiple string elements, they get rendered in the right order into text emails.\n\n#### Example\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<resources template=\"basic_template.html\" style=\"common.css,basic_template.css\">\n    <string name=\"subject\">Verify your email address with KeepSafe.</string>\n    <string name=\"content\"><![CDATA[Hello,\n\n    Please click the link below to verify your email address:\n\n    ##[Verify email]({{url}})\n\n    Thanks,\n    The KeepSafe Team]]></string>\n</resources>\n```\n\n## Templates\n\nHTML 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. You can find example of the templates in `templates_html` folder in this repo.\n\n\n## Folder structure\n\n```\nsrc/\n    en/\n        email_template.xml\ntarget/\ntemplates_html/\n    html_template.html\n    html_template.css\n```\n\n- `src/` - all email content by local. e.g. `src/en/` for english content\n- `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`\n- `templates_html/` - all HTML templates and CSS styles. A HTML template can have a corresponding CSS file with the same name.\n\nThis 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.\n\n## Rendering\n*ks-email-parser* renders email content into HTML in 2 steps.\n\n1. Render markdown files into simple HTML\n2. 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.\n\n### Strict mode\n\nYou can use `--strict` option to make sure all placeholders are filled. If there are leftover placeholders the parsing will fail with an error.\n\n### isText\n\nIn case you want to put some non-text values in emails, like colors, you can use placeholders which will be ignored in text emails:\n\n`<string name=\"color\" isText=\"false\">[[#C0D9D9]]</string>`\n\nThe only valid false value for isText is `false`, everything else counts as true including omitting the attribute.\n\n## Placeholders validation\n\nTo make sure the placeholders are consistent between languages and every language has all needed placeholders you can create configuration file to hold needed placeholders.\n\n### Config file\n\nThe 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:\n\n```\n{\n    \"email name\" : {\"placeholder1\":1, \"placeholder2\":2}\n}\n```\n\nYou can generate the file in the provided source directory from existing emails with \n\n```\n$ ks-email-parser config placeholders\n```\n\nIt will go through your email and extract placeholders.\n\n### Validation\n\nIf 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.\n\n## 3rd party support\nSome 3rd party services have custom formats to represent emails in multiple languages. This is a list of supported providers.\n\n### Customer.io\nCustomer.io defines their own multi language email format. More: [http://customer.io/docs/localization-i18n.html](http://customer.io/docs/localization-i18n.html)\n\n#### Usage\n`ks-email-parser customerio [email_name]`  \nGenerates a valid customer.io multi language email format into the `target/` folder.\n\nCHANGES\n=======\n\n0.2.6 (2016-04-09)\n------------------\n\n- Warn on extra placeholders.\n\n0.2.2 (2015-07-23)\n------------------\n\n- Log to stdout by default.\n\n0.2.1 (2015-07-23)\n------------------\n\n- Validate number of placeholders too.\n\n\n0.2.0 (2015-07-22)\n------------------\n\n- Placeholders validation.\n\n\n0.1.12 (2015-05-07)\n------------------\n\n- Add --version cmd option.\n\n\n0.1.11 (2015-04-14)\n------------------\n\n- Set dir attribute only when possible.\n\n0.1.10 (2015-04-14)\n------------------\n\n- Set dir attribute for entire content not for each placeholder.\n\n0.1.9 (2015-04-06)\n------------------\n\n- Use href for links only if available.\n\n0.1.8 (2015-04-06)\n------------------\n\n- Improve logging for strict mode.\n\n0.1.7 (2015-04-06)\n------------------\n\n- Improve logging for strict mode.\n\n0.1.6 (2015-04-06)\n------------------\n\n- Dependencies update.\n\n0.1.5 (2015-04-06)\n------------------\n\n- Adds default parser options.\n\n0.1.4 (2015-04-06)\n------------------\n\n- Log filename if parsing fails.\n\n0.1.3 (2015-04-06)\n------------------\n\n- Fixes missing dependency.\n\n0.1.2 (2015-04-06)\n------------------\n\n- Fixes requirements parsing.\n\n0.1.1 (2015-04-06)\n------------------\n\n- Use text and href for links in text files.\n\n0.1.0 (2015-04-06)\n------------------\n\n- Refactorings.\n\n\n0.0.1 (2014-09-30)\n------------------\n\n- Initial release.",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "UNKNOWN",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/KeepSafe/ks-email-parser",
        "keywords": null,
        "license": "Apache",
        "maintainer": null,
        "maintainer_email": null,
        "name": "ks-email-parser",
        "package_url": "https://pypi.org/project/ks-email-parser/",
        "platform": "UNKNOWN",
        "project_url": "https://pypi.org/project/ks-email-parser/",
        "project_urls": {
            "Download": "UNKNOWN",
            "Homepage": "https://github.com/KeepSafe/ks-email-parser"
        },
        "release_url": "https://pypi.org/project/ks-email-parser/0.2.7/",
        "requires_dist": null,
        "requires_python": null,
        "summary": "A command line tool to render HTML and text emails of markdown content.",
        "version": "0.2.7"
    },
    "last_serial": 2056352,
    "releases": {
        "0.2.7": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "15e5ea73cd9aeb52317606bf55b6e3f7",
                    "sha256": "062ae4158b8d892c08a363aad0942d2c3d607a98f68b30d490f9a9ea135ebf8a"
                },
                "downloads": -1,
                "filename": "ks-email-parser-0.2.7.tar.gz",
                "has_sig": false,
                "md5_digest": "15e5ea73cd9aeb52317606bf55b6e3f7",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 21678,
                "upload_time": "2016-04-10T16:18:07",
                "url": "https://files.pythonhosted.org/packages/c2/7f/7945fc98984253cd329ef208dc1ff4ccedb1b7ff9672f27a2a5d88cb2fe3/ks-email-parser-0.2.7.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "15e5ea73cd9aeb52317606bf55b6e3f7",
                "sha256": "062ae4158b8d892c08a363aad0942d2c3d607a98f68b30d490f9a9ea135ebf8a"
            },
            "downloads": -1,
            "filename": "ks-email-parser-0.2.7.tar.gz",
            "has_sig": false,
            "md5_digest": "15e5ea73cd9aeb52317606bf55b6e3f7",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 21678,
            "upload_time": "2016-04-10T16:18:07",
            "url": "https://files.pythonhosted.org/packages/c2/7f/7945fc98984253cd329ef208dc1ff4ccedb1b7ff9672f27a2a5d88cb2fe3/ks-email-parser-0.2.7.tar.gz"
        }
    ]
}