Advanced Text (Markdown & Code)

Relevant source files

The following files were used as context for generating this wiki page:

• skills/react-email/references/COMPONENTS.md
• skills/react-email/SKILL.md
• packages/react-email/src/components/markdown/markdown.spec.tsx
• packages/editor/src/core/serializer/compose-react-email.spec.tsx
• apps/web/src/app/api/markdown/components/markdown.spec.ts
• packages/react-email/src/components/markdown/markdown.tsx
• packages/react-email/src/components/code-block/code-block.tsx
• packages/react-email/src/components/code-inline/code-inline.tsx

Advanced Text components in React Email enable the rendering of complex text structures, specifically Markdown content and syntax-highlighted code blocks. These components automate the conversion of standard Markdown and raw code strings into email-safe HTML, handling the structural and styling inconsistencies typical of various email clients.

The system comprises three primary components: Markdown, CodeBlock, and CodeInline. These components are designed to work within the broader React Email ecosystem, integrating with the Tailwind system and the visual Editor to ensure consistent presentation across platforms.

Sources: SKILL.md, COMPONENTS.md:12-28

Markdown Component

The Markdown component converts a Markdown string into valid React Email template code. It parses standard Markdown syntax—including headings, lists, links, images, and blockquotes—and applies default or custom styles suitable for email clients.

Component Architecture

The component uses a parser to transform the children prop (a Markdown string) into a series of React elements. It allows for granular control over the output through two main styling props: markdownCustomStyles for individual element overrides and markdownContainerStyles for the wrapper div.

The diagram shows the data flow from a raw Markdown string to final email-safe HTML.
Sources: COMPONENTS.md:213-241, markdown.spec.tsx:5-50

Configuration and Props

Prop	Type	Description
children	string	The Markdown content to be rendered.
markdownCustomStyles	Record<string, CSSProperties>	Style overrides for specific tags like h1, bold, link, etc.
markdownContainerStyles	CSSProperties	Styles applied to the root container div.

Sources: COMPONENTS.md:243-247

Supported Elements and Defaults

• Headings: Renders h1 through h6 with default font weights and relative font sizes (e.g., h1 at 2.5rem).
• Lists: Supports ordered (ol) and unordered (ul) lists, including nested and loose list structures.
• Links & Images: Automatically handles URL escaping and applies target _blank to links.
• Blockquotes: Renders with a vertical border and background color to distinguish from body text.

Sources: markdown.spec.tsx:52-156

Code Components

React Email provides specialized components for displaying code, ensuring readability and consistent formatting in email environments.

CodeBlock

CodeBlock displays multi-line code with syntax highlighting. It utilizes Prism.js for regex-based highlighting and supports various pre-defined themes.

The diagram illustrates how CodeBlock combines raw text with language and theme configurations.
Sources: COMPONENTS.md:183-207

CodeBlock Implementation Requirements

1. Wrapper: Always wrap CodeBlock in a div with overflow-auto to prevent layout breaking due to long lines.
2. Theme: A theme prop (e.g., dracula, github, nord) is mandatory.
3. Language: A supported Prism language must be specified.

Sources: COMPONENTS.md:209-211

CodeInline

CodeInline provides a predictable element for small code snippets within body text. It is designed to render correctly across all major email clients without the overhead of full syntax highlighting.

Sources: COMPONENTS.md:15, COMPONENTS.md:212-212

Serializer Integration

The Advanced Text components are a key target for the @react-email/editor serialization process. The composeReactEmail function transforms internal editor states into these specific components.

Mark Ranking and Nesting

During serialization, the system preserves the hierarchy of text marks (formatting). For example, a link mark typically wraps a bold mark based on extension priority.

The sequence shows how text marks are prioritized during the conversion from editor state to components.
Sources: compose-react-email.spec.tsx:75-125

Serialization Rules

• Code Marks: The serializer applies specific inline styles to code marks to ensure they match the email's visual theme.
• Link Marks: Links are processed to include theme-resolved colors and decorations, while preserving specific attributes like href.

Sources: compose-react-email.spec.tsx:180-210

Implementation Example

The following example demonstrates integrating Markdown and themed Code components within a single email template.

import { Html, Markdown, CodeBlock, dracula } from 'react-email';

const codeSnippet = `const welcome = "Hello World";`;

export default function AdvancedTextEmail() {
  return (
    <Html lang="en">
      <Markdown
        markdownCustomStyles={{
          h1: { color: "#007bff", fontSize: "24px" },
          codeInline: { backgroundColor: "#f4f4f5", padding: "2px 4px" }
        }}
      >
        # API Documentation
        Use the following snippet to initialize the client:
      </Markdown>
      
      <div className="overflow-auto">
        <CodeBlock
          code={codeSnippet}
          language="javascript"
          theme={dracula}
        />
      </div>
    </Html>
  );
}

Sources: COMPONENTS.md:190-205, COMPONENTS.md:225-240

Summary

Advanced Text components provide a robust bridge between raw content formats (Markdown/Code) and the restrictive environment of email clients. By centralizing the parsing and styling logic in the Markdown and CodeBlock components, the project ensures that complex formatting remains accessible and visually consistent across inbox providers.