Email Templates
Relevant source files
The following files were used as context for generating this wiki page:Introduction
The email templates are the presentation layer for all emails sent by the newsletter program. They are standard HTML files that use a simple {{variable}} substitution syntax to dynamically insert content. The system uses these templates for various purposes, including sending out the main newsletter and welcoming new subscribers.
All email templates are located in the newsletter-program/src/templates/ directory. The core logic for loading templates and substituting variables is handled by the NewsletterComposer class. This system allows for a clean separation of content, logic, and presentation.
Sources: newsletters/README.md:94-98, newsletter-program/src/core/newsletter-composer.js:8
Template Loading and Processing
The NewsletterComposer class is responsible for composing the final HTML for an email. It combines a markdown content file with an HTML template. The process involves parsing the markdown file for its frontmatter metadata and content, converting the markdown content to HTML, and then injecting all the data into the specified email template.
Sources: newsletter-program/src/core/newsletter-composer.js:69-93
Processing Flow
The following diagram illustrates how a newsletter is composed from a markdown file and an HTML template.
This diagram shows the key steps within the composeNewsletter method, highlighting the roles of parseNewsletterFile and loadTemplate.
Sources: newsletter-program/src/core/newsletter-composer.js:69-93
The loadTemplate Function
The loadTemplate function in NewsletterComposer is the core of the template processing. It reads the specified HTML template file from the templatesDir and iterates through a provided variables object, replacing all occurrences of {{key}} with the corresponding value.
// newsletter-program/src/core/newsletter-composer.js:51-66
async loadTemplate(templateName, variables = {}) {
try {
const templatePath = path.join(this.templatesDir, `${templateName}.html`);
let template = await fs.readFile(templatePath, 'utf-8');
// Replace template variables
for (const [key, value] of Object.entries(variables)) {
const regex = new RegExp(`{{${key}}}`, 'g');
template = template.replace(regex, value || '');
}
return template;
} catch (error) {
throw new Error(`Failed to load template ${templateName}: ${error.message}`);
}
}
Sources: newsletter-program/src/core/newsletter-composer.js:51-66
Variable Substitution
Templates support dynamic content through a variable substitution system. Variables are denoted by double curly braces, e.g., {{subject}}. These variables are populated from the newsletter's markdown frontmatter and other generated data.
Sources: newsletters/README.md:80-81
Standard Variables
The system provides a set of built-in variables available to the newsletter.html template.
| Variable | Description | Source |
|---|---|---|
{{subject}} | The subject of the newsletter, from the markdown frontmatter. | newsletter-program/src/core/newsletter-composer.js:77 |
{{date}} | The display date for the newsletter, from the markdown frontmatter. | newsletter-program/src/core/newsletter-composer.js:78 |
{{content}} | The main body of the newsletter, rendered from markdown content. | newsletter-program/src/core/newsletter-composer.js:79 |
{{website_url}} | A link to the main website. | newsletter-program/src/core/newsletter-composer.js:80 |
{{github_url}} | A link to the GitHub profile. | newsletter-program/src/core/newsletter-composer.js:81 |
{{preferences_url}} | A link for users to manage their subscription preferences. | newsletter-program/src/core/newsletter-composer.js:82 |
{{unsubscribe_url}} | A link for users to unsubscribe from the newsletter. | newsletter-program/src/core/newsletter-composer.js:83 |
Sources: newsletter-program/src/core/newsletter-composer.js:76-85, newsletters/README.md:82-90
Custom Variables
In addition to the standard variables, you can define custom variables in the variables section of a newsletter's markdown frontmatter. These are then available for use within the template.
Example Frontmatter:
variables:
author: John Doe
edition_number: 42
theme_color: "#3498db"
These can be used in the template as {{author}}, {{edition_number}}, etc. The NewsletterComposer merges these custom variables into the main variables object.
Sources: newsletters/README.md:91-93, newsletter-program/src/core/newsletter-composer.js:84-85
Available Templates
The project includes several HTML templates for different email types.
newsletter.html
This is the main template for sending out newsletters. It includes a header, a content area where the rendered markdown is injected, and a footer with social and management links.
Key Placeholders:
{{subject}}{{date}}{{content}}{{website_url}}{{github_url}}{{preferences_url}}{{unsubscribe_url}}
Example Snippet:
<!-- newsletter-program/src/templates/newsletter.html:70-74 -->
<div class="content">
<h1>{{title}}</h1>
<p>{{description}}</p>
<p><a href="{{link}}">Read more</a></p>
<p>Published: {{pubDate}}</p>
{{content}}
</div>
This template is also used for generating emails from RSS feed items, which explains placeholders like {{title}}, {{link}}, and {{pubDate}}.
Sources: newsletter-program/src/templates/newsletter.html, newsletter-program/src/core/content-processor.js:14-25
welcome.html
This template is used to send a welcome email to new subscribers. It confirms their subscription and provides details about what they can expect.
Key Placeholders:
{{email}}{{frequency}}{{format}}{{topics}}{{preferences_url}}{{unsubscribe_url}}
Example Snippet:
<!-- newsletter-program/src/templates/welcome.html:79-82 -->
<p>Your subscription is confirmed for: <strong>{{email}}</strong></p>
<p>Newsletter frequency: <strong>{{frequency}}</strong></p>
<p>Email format: <strong>{{format}}</strong></p>
<p>Topics of interest: <strong>{{topics}}</strong></p>
The usage of this template is demonstrated in the integration tests for the subscription flow, where it's loaded and processed with mock subscriber data.
Sources: newsletter-program/src/templates/welcome.html, newsletter-program/src/tests/integration/newsletter-subscription-flow.test.js:184-204
Summary
The email templates provide a flexible and maintainable way to generate HTML emails for the portfolio's newsletter system. By using a simple variable substitution mechanism, the NewsletterComposer can populate templates with data from various sources, including markdown files and RSS feeds. The separation of templates (.html), content (.md), and logic (.js) creates a robust and extensible email generation pipeline.
Sources: newsletter-program/src/core/newsletter-composer.js, newsletters/README.md