django-templated-email-md

Features

• Markdown Templates: Write email templates using Markdown syntax for cleaner and more readable templates.
• Automatic Conversion: Automatically converts Markdown to HTML and generates a plain text version of emails.
• CSS Inlining: Inlines CSS styles for better email client compatibility using Premailer.
• Seamless Integration: Works as an extension of django-templated-email, allowing for easy integration into existing projects.
• Template Inheritance: Supports Django template inheritance and template tags in your Markdown templates.

Installation

You can install django-templated-email-md via pip from PyPI:

pip install django-templated-email-md

Requirements

• Python 3.11+
• Django 4.2+
• django-templated-email 3.0+

Add to INSTALLED_APPS

Add templated_email_md to your INSTALLED_APPS in settings.py:

INSTALLED_APPS = [
    # ...
    'templated_email_md',
    # ...
]

Configuration

Assuming you have already installed and configured django-templated-email, update your Django settings as follows:

# settings.py

# Configure the templated email backend
TEMPLATED_EMAIL_BACKEND = 'templated_email_md.backend.MarkdownTemplateBackend'

# Optional: Specify the base HTML template for wrapping your content. See the Usage guide for details.
TEMPLATED_EMAIL_BASE_HTML_TEMPLATE = 'templated_email/markdown_base.html'

# Set the directory where your email templates are stored
TEMPLATED_EMAIL_TEMPLATE_DIR = 'templated_email/'  # Ensure there's a trailing slash

# Define the file extension for your Markdown templates
TEMPLATED_EMAIL_FILE_EXTENSION = 'md'

# Optional: Specify Markdown extensions if needed
TEMPLATED_EMAIL_MARKDOWN_EXTENSIONS = [
    'markdown.extensions.extra',
    'markdown.extensions.meta',
    'markdown.extensions.tables',
]

# Optional: Base URL for resolving relative URLs in CSS/images
TEMPLATED_EMAIL_BASE_URL = 'https://example.com'

# Optional: Customize plain text generation
TEMPLATED_EMAIL_HTML2TEXT_SETTINGS = {
    'ignore_emphasis': True,
    'body_width': 0,
}

# Optional: Fail silently on errors (default: False)
TEMPLATED_EMAIL_FAIL_SILENTLY = False

For a complete list of available settings, see the settings documentation.

Usage

Creating Markdown Templates

Place your Markdown email templates in the templated_email/ directory within your project's templates directory. For example, create a file templated_email/welcome.md:

{% block subject %}Test Email{% endblock %}
{% block preheader %}Thanks for signing up!{% endblock %}

{% block content %}
# {{ user.first_name }}, you're in!

![Gorgeous, golden potato, Spedona, CC BY-SA 3.0 https://creativecommons.org/licenses/by-sa/3.0, via Wikimedia Commons](https://upload.wikimedia.org/wikipedia/commons/a/a4/Icone_pdt.png)

## Welcome to The Potato Shop

### Hello {{ user.first_name }}! 👋

> You have been invited to set up an account at the Potato shop on behalf of  **{{ inviter.name }}**.

Please click [this link]({% url 'invitations:accept-invite' key=invitation.key %}) to establish your account.

{% blocktranslate %}You will be directed to the 'set password' tool, where you can establish your account password.{% endblocktranslate %}

---

Best regards,

*Jack Linke*
Potato Shop, LLC - Managing Director

*Semi-round, Starchy Veggies for All*
{% endblock %}

Sending Emails

Use the send_templated_mail function to send emails using your Markdown templates, just as you would with the base django-templated-email package:

from templated_email import send_templated_mail

send_templated_mail(
    template_name='welcome',
    from_email='Potato Shop Support <support@mashedupyum.com>',
    recipient_list=['terrence3725fries@wannamashitup.com'],
    context={
        'user': request.user,
        'inviter': inviter,
    },
)

You can also pass a base_url parameter for resolving relative URLs in CSS and images:

send_templated_mail(
    template_name='welcome',
    from_email='support@example.com',
    recipient_list=['user@example.com'],
    context={
        'user': request.user,
    },
    base_url='https://example.com',  # Optional: for CSS/image URLs
)

The Result

Inbox Preview

Email Preview

More detailed information can be found in the usage guide.

Documentation

For more detailed information, please refer to the full documentation.

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the MIT license, django-templated-email-md is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Credits

We are grateful to the maintainers of the following projects:

• django-templated-email
• emark

This project was generated from @OmenApps's Cookiecutter Django Package template.