Markdown Rendering

Purpose and Scope

This document describes the Markdown rendering system in hypervel/mail, which converts Markdown-based email templates into styled HTML and plain text versions. The system handles theme application, CSS inlining, component path resolution, and integration with the Hyperf view engine.

For information about creating Mailables that use Markdown content, see Creating Mailable Classes. For details on the Blade component compilation system used by Markdown templates, see Blade Components and Compilation. For the structure of default email templates, see Email Template Structure.

Sources: Diagram 5 from high-level architecture

Core Components

The Markdown rendering system consists of two primary classes that work together to convert Markdown templates into email-ready HTML and text.

Markdown Class

The Markdown class src/Markdown.php16-158 is the core renderer responsible for processing Markdown templates. It manages theme selection, component path resolution, and the conversion of templates into both HTML (with inlined CSS) and plain text formats.

Property	Type	Purpose
$theme	string	Current theme name (default: 'default')
$componentPaths	array	Registered custom component paths
$view	FactoryInterface	Hyperf view engine instance

Key Methods:

• render(string $view, array $data = [], mixed $inliner = null): HtmlString src/Markdown.php42-65 - Renders Markdown template to HTML with inlined CSS
• renderText(string $view, array $data = []): HtmlString src/Markdown.php70-84 - Renders Markdown template to plain text
• parse(string $text): HtmlString src/Markdown.php89-101 - Static method to convert raw Markdown text to HTML
• theme(string $theme): static src/Markdown.php144-149 - Sets the theme to use for rendering

Sources: src/Markdown.php1-159

MarkdownFactory

The MarkdownFactory class src/MarkdownFactory.php10-25 creates configured Markdown instances using dependency injection. It resolves the view factory and configuration, then instantiates Markdown with settings from the mail.markdown configuration array.

The factory is invokable via the __invoke() method src/MarkdownFactory.php18-24 which:

1. Retrieves markdown configuration from mail.markdown
2. Passes the view factory and configuration to the Markdown constructor
3. Returns the configured Markdown instance

Sources: src/MarkdownFactory.php1-26

Configuration

Markdown rendering is configured in the mail.php configuration file under the markdown key publish/mail.php128-134

Configuration Key	Type	Description
theme	string	Theme name for styling HTML emails (default: 'default')
paths	array	Custom component paths to search for mail templates

The theme setting determines which CSS file is used for styling. Themes are resolved as view names in the format mail::themes.{theme} src/Markdown.php58 or as custom theme views starting with mail. src/Markdown.php53-54

Sources: publish/mail.php117-134 src/Markdown.php35-36

Markdown Rendering Pipeline

HTML Rendering Process

The HTML rendering pipeline converts Markdown templates into styled HTML with inlined CSS for maximum email client compatibility.

Process Steps:

1. Cache Flush src/Markdown.php44-46 - Clears the view finder cache if the method exists
2. Namespace Replacement src/Markdown.php48-51 - Replaces the mail namespace with HTML component paths (e.g., vendor/mail/html)
3. View Rendering src/Markdown.php51 - Renders the Markdown view using Blade templating
4. Theme Resolution src/Markdown.php53-59 - Resolves the theme view name using priority: custom mail.{theme} > namespaced theme > mail::themes.{theme}
5. CSS Inlining src/Markdown.php61-64 - Uses TijsVerkoyen\CssToInlineStyles to inline CSS styles into HTML elements

Sources: src/Markdown.php42-65

Text Rendering Process

The text rendering pipeline generates plain text versions of emails by rendering Markdown templates with text-specific components.

Process Steps:

1. Cache Flush src/Markdown.php72-74 - Clears the view finder cache
2. Namespace Replacement src/Markdown.php76-79 - Replaces the mail namespace with text component paths (e.g., vendor/mail/text)
3. View Rendering src/Markdown.php79 - Renders the view using text-specific Blade components
4. Whitespace Normalization src/Markdown.php82 - Removes excessive line breaks (2+ consecutive newlines become 2)
5. Entity Decoding src/Markdown.php82 - Converts HTML entities back to UTF-8 characters

Sources: src/Markdown.php70-84

Theme System and CSS Inlining

Theme Resolution Flow

The theme system provides CSS styling for HTML emails. Themes are Blade templates that output CSS, which is then inlined into HTML elements for compatibility with email clients.

Theme View Resolution Priority:

1. Custom Theme View src/Markdown.php53-54 - Checks if mail.{theme} exists (e.g., mail.default)
2. Namespaced Theme src/Markdown.php56-57 - If theme contains ::, uses it as-is
3. Default Package Theme src/Markdown.php58 - Constructs mail::themes.{theme} (e.g., mail::themes.default)

Sources: src/Markdown.php53-64

CSS Inlining with TijsVerkoyen

The CssToInlineStyles class from the tijsverkoyen/css-to-inline-styles package src/Markdown.php14 converts external CSS into inline style attributes on HTML elements src/Markdown.php61-64 This ensures consistent rendering across email clients that strip <style> tags.

Inlining Process:

The inliner parameter is optional src/Markdown.php42 defaulting to a new CssToInlineStyles instance src/Markdown.php61 allowing custom inliner injection for testing.

Sources: src/Markdown.php14 src/Markdown.php61-64

Component Path Management

The Markdown renderer manages separate component paths for HTML and text rendering modes, enabling different template layouts for each format.

Component Path Resolution

Path Methods

Method	Returns	Purpose
componentPaths()	array	Merges custom paths with package default src/Markdown.php126-131
htmlComponentPaths()	array	Appends /html to each component path src/Markdown.php106-111
textComponentPaths()	array	Appends /text to each component path src/Markdown.php116-121
loadComponentsFrom(array $paths)	void	Sets custom component paths src/Markdown.php136-139

The default package path is always included: dirname(__DIR__) . '/publish/resources/views' src/Markdown.php129 which resolves to the package's published view resources.

Namespace Replacement:

• HTML rendering: $this->view->replaceNamespace('mail', $this->htmlComponentPaths()) src/Markdown.php48-51
• Text rendering: $this->view->replaceNamespace('mail', $this->textComponentPaths()) src/Markdown.php76-79

This allows templates to reference components using the mail:: namespace (e.g., mail::button), which resolves to different paths depending on the rendering mode.

Sources: src/Markdown.php106-139

Static Markdown Parsing

The Markdown::parse() static method src/Markdown.php89-101 provides a standalone utility for converting raw Markdown text to HTML without the full rendering pipeline.

Parse Method Implementation

Implementation Details:

1. Environment Configuration src/Markdown.php91-93 - Creates a League CommonMark environment with unsafe links disabled
2. Extension Registration src/Markdown.php95-96 - Adds CommonMark core and table support extensions
3. Converter Creation src/Markdown.php98 - Instantiates a MarkdownConverter with the configured environment
4. Conversion src/Markdown.php100 - Converts Markdown text to HTML and wraps in HtmlString

Supported Markdown Features:

• CommonMark core syntax (headers, lists, emphasis, links, etc.)
• Tables (via TableExtension)
• HTML entities
• Unsafe links are blocked for security

Usage Example:

Sources: src/Markdown.php89-101

Integration with Mailable Lifecycle

The Markdown renderer is invoked during the Mailable preparation phase when the content definition specifies markdown content.

Mailable to Markdown Flow

When a Mailable specifies markdown content, the rendering pipeline:

1. Resolves MarkdownFactory from the container
2. Calls MarkdownFactory->__invoke() to create a configured Markdown instance
3. Invokes Markdown->render() for HTML version with theme and CSS inlining
4. Invokes Markdown->renderText() for plain text version
5. Returns both versions as HtmlString objects

This integration is handled automatically by the Mailable's buildMarkdownView() method during the preparation phase described in Mailable Lifecycle and Preparation.

Sources: Diagram 4 from high-level architecture, src/MarkdownFactory.php18-24