CLI: Newsletter Composition
Relevant source files
The following files were used as context for generating this wiki page:The Newsletter Composition system provides a command-line interface (CLI) for creating, managing, previewing, and sending newsletters. It is designed around a repository-based workflow where newsletters are authored as Markdown files with YAML frontmatter. The system processes these files, combines them with HTML templates, and handles distribution to subscribers.
This system is a core part of the newsletter-program module, providing the tools for content creators to manage the entire newsletter lifecycle from their local development environment. It integrates with other modules for subscriber management and email sending. Other related systems include Subscriber Management and Analytics & Reporting.
Sources: newsletters/README.md, newsletter-program/src/cli/newsletter-cli.js
Architecture Overview
The CLI tool (newsletter-cli.js) serves as the entry point, using the commander library to define and handle user commands. The core logic is encapsulated within the NewsletterComposer class, which is responsible for file parsing, template rendering, and file system operations like creating, previewing, and archiving newsletters. For sending, the CLI interacts with a SubscriberManager to fetch recipients and a NewsletterSender to dispatch the emails.
Sources: newsletter-program/src/cli/newsletter-cli.js:16-18, newsletter-program/src/core/newsletter-composer.js
Component Interaction Diagram
This diagram shows the high-level interaction between the user, the CLI, and the core modules during the newsletter sending process.
Newsletter File Format
Newsletters are Markdown files (.md) located in the newsletters/ directory. Each file must contain a YAML frontmatter block at the beginning, which defines metadata and configuration for the newsletter. The content of the newsletter is written in Markdown below the frontmatter.
Sources: newsletters/README.md:12-14, newsletter-program/src/core/newsletter-composer.js:19-32
Frontmatter Fields
The following fields are supported in the YAML frontmatter:
| Field | Type | Description |
|---|---|---|
subject | string | The subject line of the email. |
date | string | The display date for the newsletter. |
status | string | The current status: draft, scheduled, or sent. |
scheduled_at | string | An ISO 8601 datetime string for scheduled sending. |
website_url | string | A link to the main website. |
github_url | string | A link to a GitHub profile or repository. |
preferences_url | string | A link for users to manage their subscription preferences. |
unsubscribe_url | string | A link for users to unsubscribe. |
variables | object | A key-value map for custom variables to be used in the template. |
Sources: newsletters/README.md:28-37, newsletter-program/src/core/newsletter-composer.js:80-88
Example Template
The newsletters/newsletter-template.md file provides a starting point for new newsletters.
---
subject: Weekly Newsletter - {{date}}
date: {{current_date}}
status: draft
scheduled_at:
website_url: https://example.com
github_url: https://github.com/username
preferences_url: https://example.com/preferences
unsubscribe_url: https://example.com/unsubscribe
variables:
author: Newsletter Team
edition_number: 1
theme_color: "#3498db"
---
# Weekly Newsletter - Edition {{edition_number}}
Welcome to this week's newsletter! Here's what's been happening.
...
Sources: newsletters/newsletter-template.md
Core Component: NewsletterComposer
The NewsletterComposer class is the engine of the composition system. It handles all file interactions, parsing, and HTML generation.
Sources: newsletter-program/src/core/newsletter-composer.js:6-10
Class Diagram
This diagram illustrates the structure and key methods of the NewsletterComposer class.
Key Methods
| Method | Description |
|---|---|
parseNewsletterFile() | Reads a .md file, separates YAML frontmatter from Markdown content, and converts the Markdown to HTML using the marked library. |
loadTemplate() | Reads an HTML template (e.g., newsletter.html) and substitutes placeholders like {{variable}} with provided values. |
composeNewsletter() | Orchestrates the parsing of a newsletter file and the loading of the template to produce the final HTML content and metadata. |
generatePreview() | Composes a newsletter and saves the resulting HTML to a file in the newsletters/output/ directory for local review. |
createNewsletterTemplate() | Generates a new newsletter .md file from a predefined template, populating it with provided options. |
archiveNewsletter() | Copies a sent newsletter file to the newsletters/archive/ directory, prepending the date and adding archive metadata. |
listNewsletters() | Reads the newsletters/ directory and returns a list of all available newsletters with their metadata. |
Sources: newsletter-program/src/core/newsletter-composer.js
CLI Commands
The newsletter-cli.js script provides several commands to manage the newsletter lifecycle.
Sources: newsletter-program/src/cli/newsletter-cli.js:22-24
create
Creates a new newsletter file from a template.
Usage: npm run newsletter create <name> [options]
| Option | Alias | Description |
|---|---|---|
--subject <subject> | -s | Sets the newsletter subject in the frontmatter. |
--date <date> | -d | Sets the newsletter date. |
--schedule <datetime> | Sets the scheduled time for the newsletter. | |
--author <author> | Sets the author variable. |
Sources: newsletter-program/src/cli/newsletter-cli.js:27-36
preview
Generates an HTML preview of a newsletter.
Usage: npm run newsletter preview <file> [options]
| Option | Alias | Description |
|---|---|---|
--output <path> | -o | Specifies a custom output path for the preview file. |
--open | Automatically opens the generated preview file in the default browser. |
Sources: newsletter-program/src/cli/newsletter-cli.js:53-58
list
Lists all available newsletters.
Usage: npm run newsletter list [options]
| Option | Description |
|---|---|
--status <status> | Filters newsletters by status (draft, scheduled, sent). |
--json | Outputs the list in JSON format. |
Sources: newsletter-program/src/cli/newsletter-cli.js:79-83
schedule
Updates a newsletter file to set its status to scheduled and adds the scheduled_at date.
Usage: npm run newsletter schedule <file> <datetime>
The <datetime> argument can be an ISO 8601 string or a natural language date string that new Date() can parse.
Sources: newsletter-program/src/cli/newsletter-cli.js:182-187
send
Sends a newsletter to subscribers.
Usage: npm run newsletter send <file> [options]
| Option | Description |
|---|---|
--force | Sends the newsletter immediately, ignoring any scheduled time. |
--test <email> | Sends a test email to a single specified address. The subject will be prefixed with [TEST]. |
--scheduled | A flag used by automation to indicate the send is part of a scheduled job. |
Sources: newsletter-program/src/cli/newsletter-cli.js:132-137
archive
Provides commands for managing the newsletter archive. The only subcommand is list.
Usage: npm run newsletter archive list
This command lists all files in the newsletters/archive directory.
Sources: newsletter-program/src/cli/newsletter-cli.js:213-225
Process Flows
Newsletter Creation Flow
This diagram shows the process of creating a new newsletter using the CLI.
Newsletter Sending and Archiving Flow
This diagram details the steps taken when the send command is executed.
Templating System
The system uses a simple string replacement mechanism for templating. Placeholders in the format {{variable_name}} are replaced with corresponding values.
Sources: newsletter-program/src/core/newsletter-composer.js:60-63
Template Variables
The newsletter.html template can access both built-in and custom variables.
Built-in Variables
These are automatically populated from the newsletter's frontmatter.
{{subject}}{{date}}{{content}}(The rendered HTML from the Markdown body){{website_url}}{{github_url}}{{preferences_url}}{{unsubscribe_url}}
Sources: newsletter-program/src/core/newsletter-composer.js:80-87, newsletter-program/src/templates/newsletter.html
Custom Variables
Any key-value pairs defined under the variables section in the frontmatter are also available. For example, {{author}} and {{edition_number}} from the default template.
Sources: newsletter-program/src/core/newsletter-composer.js:88, newsletters/newsletter-template.md:9-11
Dependencies
The newsletter composition feature relies on several key third-party libraries.
| Package | Version | Usage |
|---|---|---|
commander | ^11.1.0 | Used for building the command-line interface. |
marked | ^9.1.6 | Converts newsletter Markdown content into HTML. |
js-yaml | ^4.1.1 | Parses the YAML frontmatter from newsletter files. |