Update docs

OmenApps · Oct 22, 2024 · aebecf5 · aebecf5
1 parent 1d6ce47
commit aebecf5
Show file tree

Hide file tree

Showing 2 changed files with 296 additions and 87 deletions.
diff --git a/README.md b/README.md
@@ -21,121 +21,134 @@
 
 ## Features
 
-- Write email templates using Markdown syntax
-- Automatically converts Markdown to HTML
-- Generates plain text version of emails
-- Inlines CSS styles for better email client compatibility
-- Seamless integration with django-templated-email
-- Supports Django template inheritance and tags
+- **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.
 
-## Dependencies
+## Installation
 
-- Django (>=4.2)
-- django-templated-email (~=3.0)
-- markdown (~=3.7)
-- premailer (~=3.10)
-- html2text (~=2024.2)
+You can install `django-templated-email-md` via [pip] from [PyPI]:
 
-## Installation
+```bash
+pip install django-templated-email-md
+```
 
-You can install _django-templated-email-md_ via [pip] from [PyPI]:
+### Add to `INSTALLED_APPS`
 
-```console
-$ pip install templated_email_md
+Add `templated_email_md` to your `INSTALLED_APPS` in `settings.py`:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    'templated_email_md',
+    # ...
+]
 ```
 
-## Usage
+## Configuration
+
+Assuming you have already installed and configured [django-templated-email](https://github.com/vintasoftware/django-templated-email/), update your Django settings as follows:
 
-**Usage Instructions:**
+```python
+# settings.py
 
-1. **Update Your Settings:**
+# Configure the templated email backend
+TEMPLATED_EMAIL_BACKEND = 'templated_email_md.backend.MarkdownTemplateBackend'
 
-   *Assumes you have already installed and configured [django-templated-email](https://github.com/vintasoftware/django-templated-email/).*
+# 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'
 
-   Add or update the following in your Django `settings.py`:
+# Set the directory where your email templates are stored
+TEMPLATED_EMAIL_TEMPLATE_DIR = 'templated_email/'  # Ensure there's a trailing slash
 
-   ```python
-   TEMPLATED_EMAIL_BACKEND = 'templated_email_md.backend.MarkdownTemplateBackend'
-   TEMPLATED_EMAIL_BASE_HTML_TEMPLATE = 'templated_email/markdown_base.html'
-   TEMPLATED_EMAIL_TEMPLATE_DIR = 'templated_email/'  # Ensure there's a trailing slash
-   TEMPLATED_EMAIL_FILE_EXTENSION = 'md'
-   ```
+# Define the file extension for your Markdown templates
+TEMPLATED_EMAIL_FILE_EXTENSION = 'md'
 
-2. **Create Your Markdown Email Templates:**
+# Optional: Specify Markdown extensions if needed
+TEMPLATED_EMAIL_MARKDOWN_EXTENSIONS = [
+    'markdown.extensions.extra',
+    'markdown.extensions.meta',
+    'markdown.extensions.tables',
+]
+```
+
+## Usage
 
-   Place your Markdown email templates in the `templated_email/` directory. For example, create a file `templated_email/welcome.md`:
+### Creating Markdown Templates
 
-   ```markdown
-   {% block subject %}Welcome to Our Service{% endblock %}
+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 preheader %}Thanks for signing up!{% endblock %}
+```markdown
+{% block subject %}Welcome to Our Service{% endblock %}
 
-   Hi {{ user.first_name }},
+{% block preheader %}Thanks for signing up!{% endblock %}
 
-   Welcome to our service! We're glad to have you.
+{% block content %}
+# Welcome, {{ user.first_name }}!
 
-   **Enjoy your stay!**
+We're thrilled to have you join our service. Here are a few things you can do to get started:
 
-   Best regards,
-   The Team
-   ```
+1. **Complete your profile**
+2. **Explore our features**
+3. **Connect with other users**
 
-3. **Send Templated Emails:**
+If you have any questions, don't hesitate to reach out to our support team.
 
-   Use the `send_templated_mail` function to send emails:
+Best regards,
+The Team
+{% endblock %}
+```
+
+### Sending Emails
 
-   ```python
-   from templated_email import send_templated_mail
+Use the `send_templated_mail` function to send emails using your Markdown templates, just as you would with the base django-templated-email package:
 
-   send_templated_mail(
-       template_name='welcome',
-       from_email='[email protected]',
-       recipient_list=['[email protected]'],
-       context={
-           'user': user_instance,
-           # Add other context variables if needed
-       },
-   )
-   ```
+```python
+from templated_email import send_templated_mail
 
-   Ensure that you provide the necessary context variables used in your templates.
+send_templated_mail(
+    template_name='welcome',
+    from_email='[email protected]',
+    recipient_list=['[email protected]'],
+    context={
+        'user': user_instance,
+        # Add other context variables as needed
+    },
+)
+```
 
 ## Documentation
 
 For more detailed information, please refer to the [full documentation][read the docs].
 
 ## Contributing
 
-Contributions are very welcome.
-To learn more, see the [Contributor Guide].
+Contributions are very welcome. To learn more, see the [Contributor Guide].
 
 ## License
 
-Distributed under the terms of the [MIT license][license],
-_django-templated-email-md_ is free and open source software.
+Distributed under the terms of the [MIT license][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.
+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
+We are grateful to the maintainers of the following projects:
+
 - [django-templated-email](https://github.com/vintasoftware/django-templated-email/)
 - [emark](https://github.com/voiio/emark)
 
-
 This project was generated from [@OmenApps]'s [Cookiecutter Django Package] template.
 
 [@omenapps]: https://github.com/OmenApps
 [pypi]: https://pypi.org/
-[cookiecutter django package]: https://github.com/OmenApps/cookiecutter-django-package
-[file an issue]: https://github.com/OmenApps/django-templated-email-md/issues
-[pip]: https://pip.pypa.io/
-
-<!-- github-only -->
-
 [license]: https://github.com/OmenApps/django-templated-email-md/blob/main/LICENSE
+[read the docs]: https://django-templated-email-md.readthedocs.io/
 [contributor guide]: https://github.com/OmenApps/django-templated-email-md/blob/main/CONTRIBUTING.md
-[command-line reference]: https://django-templated-email-md.readthedocs.io/en/latest/usage.html
+[file an issue]: https://github.com/OmenApps/django-templated-email-md/issues
+[cookiecutter django package]: https://github.com/OmenApps/cookiecutter-django-package
+[pip]: https://pip.pypa.io/