Skip to content

Commit ef1505a

Browse files
jacklinkejacklinke
committed
Add a page documenting all settings
1 parent 89bdfd0 commit ef1505a

File tree

2 files changed

+204
-0
lines changed

2 files changed

+204
-0
lines changed

‎docs/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ maxdepth: 1
1212
---
1313
1414
usage
15+
settings
1516
terminology
1617
reference
1718
contributing

‎docs/settings.md‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
2+
# Settings Guide
3+
4+
There are several settings available to ensure `django-templated-email-md` can be configured for your needs.
5+
6+
The only one that is **required** is `TEMPLATED_EMAIL_BACKEND`.
7+
8+
## Core Settings
9+
10+
### `TEMPLATED_EMAIL_BACKEND`
11+
- **Default:** None
12+
- **Required:** Yes
13+
- **Type:** String
14+
- **Description:** The backend class to use for processing Markdown email templates.
15+
- **Example:**
16+
```python
17+
TEMPLATED_EMAIL_BACKEND = 'templated_email_md.backend.MarkdownTemplateBackend'
18+
```
19+
20+
### `TEMPLATED_EMAIL_TEMPLATE_DIR`
21+
- **Default:** 'templated_email/'
22+
- **Required:** No
23+
- **Type:** String
24+
- **Description:** Directory where email templates are stored. Must include a trailing slash. This is set by default in the `django-templated-email` package.
25+
- **Example:**
26+
```python
27+
TEMPLATED_EMAIL_TEMPLATE_DIR = 'templated_email/'
28+
```
29+
- **Further Reading:** [Django Template Loading Documentation](https://docs.djangoproject.com/en/stable/topics/templates/#template-loading)
30+
31+
### `TEMPLATED_EMAIL_FILE_EXTENSION`
32+
- **Default:** 'md'
33+
- **Required:** No
34+
- **Type:** String
35+
- **Description:** File extension for Markdown template files.
36+
- **Example:**
37+
```python
38+
TEMPLATED_EMAIL_FILE_EXTENSION = 'md'
39+
```
40+
41+
### `TEMPLATED_EMAIL_BASE_HTML_TEMPLATE`
42+
- **Default:** 'templated_email/markdown_base.html'
43+
- **Required:** No
44+
- **Type:** String
45+
- **Description:** Path to the base HTML template that wraps the Markdown content. See the [usage guide](https://django-templated-email-md.readthedocs.io/en/latest/usage.html) for more information on available approaches to overriding the default template.
46+
- **Example:**
47+
```python
48+
TEMPLATED_EMAIL_BASE_HTML_TEMPLATE = 'my_app/markdown_base.html'
49+
```
50+
- **Further Reading:** [Django Template Inheritance](https://docs.djangoproject.com/en/stable/ref/templates/language/#template-inheritance)
51+
52+
## Markdown Settings
53+
54+
### `TEMPLATED_EMAIL_MARKDOWN_EXTENSIONS`
55+
- **Default:** ['markdown.extensions.extra', 'markdown.extensions.meta', 'markdown.extensions.tables']
56+
- **Required:** No
57+
- **Type:** List
58+
- **Description:** List of Markdown extensions to enable when processing templates.
59+
- **Example:**
60+
```python
61+
TEMPLATED_EMAIL_MARKDOWN_EXTENSIONS = [
62+
'markdown.extensions.extra',
63+
'markdown.extensions.meta',
64+
'markdown.extensions.tables',
65+
'markdown.extensions.codehilite',
66+
]
67+
```
68+
- **Further Reading:**
69+
- [Python-Markdown Extensions Documentation](https://python-markdown.github.io/extensions/)
70+
- Popular extensions:
71+
- [Extra Extension](https://python-markdown.github.io/extensions/extra/)
72+
- [Meta Extension](https://python-markdown.github.io/extensions/meta_data/)
73+
- [Tables Extension](https://python-markdown.github.io/extensions/tables/)
74+
75+
## URL Settings
76+
77+
### `TEMPLATED_EMAIL_BASE_URL`
78+
- **Default:** None
79+
- **Required:** No
80+
- **Type:** String
81+
- **Description:** Base URL to prepend to relative URLs in email templates.
82+
- **Example:**
83+
```python
84+
TEMPLATED_EMAIL_BASE_URL = 'https://example.com'
85+
```
86+
- **Further Reading:**
87+
- [django-templated-email-md Usage Guide](https://django-templated-email-md.readthedocs.io/en/latest/usage.html)
88+
- [Django URL Configuration](https://docs.djangoproject.com/en/stable/topics/http/urls/)
89+
90+
## Default Content Settings
91+
92+
### `TEMPLATED_EMAIL_DEFAULT_SUBJECT`
93+
- **Default:** 'Hello!'
94+
- **Required:** No
95+
- **Type:** String
96+
- **Description:** Default subject line used when no subject is provided in the template or context.
97+
- **Example:**
98+
```python
99+
TEMPLATED_EMAIL_DEFAULT_SUBJECT = 'Message from Our Company'
100+
```
101+
102+
### `TEMPLATED_EMAIL_DEFAULT_PREHEADER`
103+
- **Default:** ''
104+
- **Required:** No
105+
- **Type:** String
106+
- **Description:** Default preheader text used when no preheader is provided in the template or context.
107+
- **Example:**
108+
```python
109+
TEMPLATED_EMAIL_DEFAULT_PREHEADER = 'Important information from Our Company'
110+
```
111+
- **Further Reading:** [Email Preheader Best Practices](https://www.litmus.com/blog/the-ultimate-guide-to-preview-text-support/) (refered to in this blocg as 'preview text')
112+
113+
## Plain Text Generation Settings
114+
115+
### `TEMPLATED_EMAIL_HTML2TEXT_SETTINGS`
116+
- **Default:** {}
117+
- **Required:** No
118+
- **Type:** Dictionary
119+
- **Description:** Configuration options for html2text when generating plain text versions of emails.
120+
- **Some of the Available Options:**
121+
- `ignore_links`: Exclude links from plain text output
122+
- `ignore_images`: Exclude image descriptions
123+
- `body_width`: Maximum line width before wrapping
124+
- `ignore_emphasis`: Exclude emphasis markers
125+
- `mark_code`: Wrap code blocks with backticks
126+
- `wrap_links`: Wrap URLs in angle brackets
127+
- **Example:**
128+
```python
129+
TEMPLATED_EMAIL_HTML2TEXT_SETTINGS = {
130+
'ignore_links': False,
131+
'ignore_images': True,
132+
'body_width': 0,
133+
'ignore_emphasis': True,
134+
'mark_code': False,
135+
'wrap_links': False,
136+
}
137+
```
138+
- **Further Reading:** [Available html2text Options](https://github.com/Alir3z4/html2text/blob/master/docs/usage.md#available-options)
139+
140+
## Error Handling Settings
141+
142+
### `TEMPLATED_EMAIL_FAIL_SILENTLY`
143+
- **Default:** False
144+
- **Required:** No
145+
- **Type:** Boolean
146+
- **Description:** If True, suppresses exceptions during email rendering and sends fallback email instead.
147+
- **Example:**
148+
```python
149+
TEMPLATED_EMAIL_FAIL_SILENTLY = True
150+
```
151+
152+
## Complete Configuration Example
153+
154+
Here's a complete example showing all settings with their default values:
155+
156+
```python
157+
# Email Backend Configuration
158+
TEMPLATED_EMAIL_BACKEND = 'templated_email_md.backend.MarkdownTemplateBackend'
159+
TEMPLATED_EMAIL_TEMPLATE_DIR = 'templated_email/'
160+
TEMPLATED_EMAIL_FILE_EXTENSION = 'md'
161+
TEMPLATED_EMAIL_BASE_HTML_TEMPLATE = 'templated_email/markdown_base.html'
162+
163+
# Markdown Extensions
164+
TEMPLATED_EMAIL_MARKDOWN_EXTENSIONS = [
165+
'markdown.extensions.extra',
166+
'markdown.extensions.meta',
167+
'markdown.extensions.tables',
168+
]
169+
170+
# URL Configuration
171+
TEMPLATED_EMAIL_BASE_URL = ''
172+
173+
# Default Content
174+
TEMPLATED_EMAIL_DEFAULT_SUBJECT = 'Hello!'
175+
TEMPLATED_EMAIL_DEFAULT_PREHEADER = ''
176+
177+
# Plain Text Generation
178+
TEMPLATED_EMAIL_HTML2TEXT_SETTINGS = {
179+
'ignore_links': False,
180+
'ignore_images': True,
181+
'body_width': 0,
182+
'ignore_emphasis': True,
183+
'mark_code': False,
184+
'wrap_links': False,
185+
}
186+
187+
# Error Handling
188+
TEMPLATED_EMAIL_FAIL_SILENTLY = False
189+
```
190+
191+
## Notes
192+
193+
1. To implement any of the above settings, the setting should be added to your Django project's `settings.py` file.
194+
2. Many settings have sensible defaults and are optional.
195+
3. The TEMPLATED_EMAIL_BACKEND setting is required and must be set explicitly.
196+
4. When using relative URLs in templates (either explicitly in the template or when using Django's [url template tags](https://docs.djangoproject.com/en/stable/ref/templates/builtins/#url)), either TEMPLATED_EMAIL_BASE_URL should be set in settings, or base_url should be provided when calling send_templated_mail.
197+
198+
## Additional Resources
199+
200+
- [django-templated-email Documentation](https://github.com/vintasoftware/django-templated-email/)
201+
- [Django Email Documentation](https://docs.djangoproject.com/en/stable/topics/email/)
202+
- [Django Templates Documentation](https://docs.djangoproject.com/en/stable/topics/templates/)
203+
- [Python-Markdown Documentation](https://python-markdown.github.io/)

0 commit comments

Comments
 (0)