Content Rendering System

The content rendering system transforms various input formats (Blade views, Markdown templates, raw HTML) into email-ready HTML and text content. This system integrates multiple components including Markdown parsing via CommonMark, Blade template compilation, mail-specific component processing, and CSS inlining for email client compatibility.

The rendering system is primarily accessed through the Markdown class and integrates with the broader mail system via the Mailable lifecycle. For information on creating mailable classes, see Working with Mailables. For details on individual rendering components, see Markdown Rendering, Blade Components, and Email Template Structure.

System Architecture

The content rendering system consists of four primary layers that transform template inputs into email-compatible HTML output.

Content Rendering System Overview

Sources: src/Markdown.php1-158 src/MarkdownFactory.php1-26

Component Integration Map

Sources: src/Markdown.php1-33 src/MarkdownFactory.php10-25 publish/mail.php128-134

Rendering Pipeline

The content rendering system processes templates through a multi-stage pipeline that handles different input formats and applies transformations to produce email-compatible output.

Complete Rendering Flow

Sources: src/Markdown.php42-65 src/Markdown.php70-84

Pipeline Stage Breakdown

Stage	Input	Processing	Output	Key Method
Namespace Resolution	View name	Replace mail namespace with component paths	Resolved view paths	replaceNamespace() src/Markdown.php48-51
Template Compilation	Blade/Markdown template	Parse Markdown, compile Blade syntax	Compiled PHP	ViewFactory->make() src/Markdown.php51
Component Resolution	<x-mail::*> tags	Resolve to component views	Expanded HTML	Via ComponentTagCompiler
Theme Loading	Theme name	Load theme CSS file	CSS string	ViewFactory->make(theme) src/Markdown.php63
CSS Inlining	HTML + CSS	Inline styles for email clients	Inlined HTML	CssToInlineStyles->convert() src/Markdown.php61-64
Text Rendering	Text template	Process text-specific components	Plain text	renderText() src/Markdown.php70-84

Sources: src/Markdown.php42-84

Input Sources

The content rendering system accepts multiple input formats, each processed through appropriate parsers and compilers.

Supported Input Types

Input Type	Format	Processing	Use Case
Blade Views	.blade.php files	Blade compiler → HTML	Complex layouts with dynamic content
Markdown Templates	Markdown syntax	CommonMark parser → HTML	Content-focused emails with simple formatting
Raw HTML Strings	HTML strings	Direct rendering	Pre-formatted content
View Data	PHP arrays	Variable interpolation	Template data binding

Input Processing Methods

Sources: src/Markdown.php106-131

View Data Binding

Template data is passed as associative arrays and made available to all rendering stages:

• View variables accessible in Blade syntax: {{ $variable }}
• Passed to theme templates for consistent styling
• Available in component slots and attributes
• Preserved through the entire rendering pipeline

Sources: src/Markdown.php42-65

Core Components

The content rendering system consists of several specialized components that work together to transform templates into email content.

Markdown Renderer

The Markdown class is the central orchestrator of the content rendering system. It manages theme configuration, component path resolution, and coordinates the rendering pipeline.

Markdown Class Responsibilities

Responsibility	Method	Description
HTML Rendering	render()	Compile template with theme CSS and inline styles
Text Rendering	renderText()	Generate plain text version without styling
Static Parsing	Markdown::parse()	Convert raw Markdown strings to HTML
Path Management	htmlComponentPaths(), textComponentPaths()	Resolve component template paths
Theme Management	theme(), getTheme()	Configure and retrieve current theme
Component Loading	loadComponentsFrom()	Register custom component paths

Sources: src/Markdown.php16-158

Markdown Environment Configuration

Sources: src/Markdown.php21-37 src/Markdown.php126-131

View Factory Integration

The rendering system integrates with Hyperf's ViewEngine through the FactoryInterface, providing Blade template compilation and rendering capabilities.

View Factory Operations

Operation	Purpose	Method Call
Cache Flushing	Clear compiled view cache	flushFinderCache() src/Markdown.php44-46
Namespace Replacement	Redirect mail:: namespace to component paths	replaceNamespace('mail', paths) src/Markdown.php48-51
View Rendering	Compile and render template with data	make(view, data)->render() src/Markdown.php51
Theme Loading	Load CSS theme file	make(theme, data)->render() src/Markdown.php63

Sources: src/Markdown.php42-84

CSS Inlining System

The CSS inlining component uses tijsverkoyen/css-to-inline-styles to embed CSS rules directly into HTML element style attributes, ensuring consistent rendering across email clients.

Inlining Process

Supported CSS Features

The inliner processes standard CSS selectors and properties, converting them to inline styles:

• Class selectors (.class-name)
• ID selectors (#element-id)
• Element selectors (div, p, a)
• Descendant selectors (div p)
• Pseudo-classes (:hover - preserved as-is)

Sources: src/Markdown.php61-64

CommonMark Parser

The static Markdown::parse() method provides Markdown-to-HTML conversion using the league/commonmark library with table support.

Parser Configuration

Sources: src/Markdown.php89-101

Supported Markdown Features

Feature	Extension	Example
Headings	Core	# Heading
Bold/Italic	Core	**bold**, *italic*
Links	Core	<FileRef file-url="https://github.com/hypervel/mail/blob/74a6fc27/text" undefined file-path="text">Hii</FileRef>
Lists	Core	- item or 1. item
Code blocks	Core	```code```
Tables	Table Extension	| Col1 | Col2 |
Blockquotes	Core	> quote

Sources: src/Markdown.php89-101

Configuration

The content rendering system is configured through the markdown section of the mail.php configuration file.

Markdown Configuration Options

Configuration Key	Type	Default	Purpose
theme	string	'default'	Theme name for CSS styling
paths	array	[resource_path('views/vendor/mail')]	Custom component search paths

Sources: publish/mail.php128-134

Theme Resolution

The Markdown class resolves theme names through multiple strategies:

Sources: src/Markdown.php53-59

Component Path Resolution

Component paths are resolved hierarchically, with custom paths taking precedence over defaults:

1. Custom paths from configuration (paths array)
2. Default package path (publish/resources/views)
3. Subdirectories: html/ for HTML templates, text/ for plain text

The componentPaths() method merges these paths, ensuring custom components can override defaults.

Sources: src/Markdown.php126-131 src/Markdown.php136-139

Factory Configuration

The MarkdownFactory creates configured Markdown instances using dependency injection:

Sources: src/MarkdownFactory.php10-25

Theme System

The theme system provides CSS styling for email templates through a flexible, customizable architecture.

Default Theme Structure

The default theme is located at mail::themes.default and provides base styling for all email components:

• Typography: Font families, sizes, and line heights
• Layout: Spacing, widths, and responsive breakpoints
• Components: Styled elements (buttons, panels, headers)
• Colors: Brand colors and semantic colors (success, error, warning)

Custom Theme Creation

Custom themes can be created by:

1. Publishing the default theme: Copy to resources/views/vendor/mail/
2. Creating a custom view: Register as mail.{theme-name}
3. Using namespaced themes: Reference as package::theme-name

The theme file should output valid CSS that will be inlined into the HTML output.

Theme Configuration

Sources: src/Markdown.php53-59 src/Markdown.php144-149 publish/mail.php128-130

HTML and Text Output

The rendering system produces two types of output: HTML for rich email clients and plain text for fallback rendering.

Dual Output Generation

HTML Output Processing

The HTML rendering path produces fully-styled email content:

1. Component Resolution: Load HTML versions of mail components
2. Template Rendering: Compile Blade template with data
3. Theme Application: Load theme CSS
4. CSS Inlining: Convert CSS rules to inline styles
5. HtmlString Wrapping: Return safe HTML output

Sources: src/Markdown.php42-65

Text Output Processing

The text rendering path produces plain text versions:

1. Component Resolution: Load text versions of mail components
2. Template Rendering: Compile text-focused templates
3. Entity Decoding: Convert HTML entities to characters
4. Whitespace Normalization: Remove excessive line breaks
5. HtmlString Wrapping: Return formatted text

The text output undergoes post-processing to normalize whitespace:

• Multiple consecutive line breaks reduced to double line breaks
• HTML entities decoded: " → ", & → &
• Preserves formatting for plain text email clients

Sources: src/Markdown.php70-84

Output Format Comparison

Aspect	HTML Output	Text Output
Component Source	html/ subdirectory	text/ subdirectory
Styling	Inline CSS styles	No styling
Images	Full <img> tags	Text descriptions or omitted
Links	Clickable <a> tags	Plain URLs or text
Tables	HTML tables	ASCII-art or simplified text
Encoding	UTF-8 HTML entities	UTF-8 plain text

Sources: src/Markdown.php42-84 src/Markdown.php106-121

Integration with Mailable System

The content rendering system integrates with the Mailable lifecycle to provide templated email content.

Mailable Content Rendering

When a Mailable is processed, its content is rendered through the Markdown system:

Content Method Integration

The Mailable class defines content through the content() method, which can specify:

Content Option	Method	Description
Markdown Template	markdown	Markdown template with theme support
HTML View	view or html	Blade template for HTML version
Text View	text	Blade template for plain text version
View Data	with	Data passed to templates

When markdown is specified, the Markdown rendering system processes the template through the full pipeline including theme application and CSS inlining.

Rendering Context

The rendering system receives context from the Mailable:

• View Data: All public properties and with() data
• Attachments: Files to embed or attach
• Theme: Configured theme name
• Component Paths: Custom component directories

This integration allows Mailables to leverage the full power of the content rendering system while maintaining a clean, declarative API.

Symfony Integration

The Message class maintains full compatibility with Symfony's Email component through method forwarding and direct access.

Method Forwarding

The ForwardsCalls trait enables transparent delegation to the underlying Symfony Email instance:

• Unrecognized methods are forwarded to the Symfony object using __call()
• Return values are preserved or wrapped as appropriate
• Fluent interface is maintained when Symfony returns itself

Direct Access

The getSymfonyMessage() method provides direct access to the underlying Email instance for advanced operations or framework integration.

Sources: src/Message.php20 src/Message.php321-324 src/Message.php329-337

SentMessage Wrapper

The SentMessage class wraps Symfony's SentMessage to provide serialization support and maintain API consistency.

Serialization Handling

The wrapper implements custom serialization logic to handle email attachments:

Condition	Serialization Method	Purpose
Has attachments	Base64 encoded	Preserve binary attachment data
No attachments	Direct serialization	Optimize performance

Sources: src/SentMessage.php50-60 src/SentMessage.php65-70