django-templated-email-md 2024.10.2

An extension for django-templated-email for creating emails with Markdown

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

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',
]

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 %}Welcome to Our Service{% endblock %}

{% block preheader %}Thanks for signing up!{% endblock %}

{% block content %}
# Welcome, {{ user.first_name }}!

We're thrilled to have you join our service. Here are a few things you can do to get started:

1. **Complete your profile**
2. **Explore our features**
3. **Connect with other users**

If you have any questions, don't hesitate to reach out to our support team.

Best regards,
The Team
{% 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='[e-mail]',
    recipient_list=['[e-mail]'],
    context={
        'user': user_instance,
        # Add other context variables as needed
    },
)

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.