Skip to content

feature/mjml 7 documentation audit update #3021

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
totocap merged 2 commits into from
Dec 8, 2025
+1,386 −1,366
Merged

feature/mjml 7 documentation audit update #3021

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8b97136
feature(MJML docs): documentation audit MJML-7
dazgreer Nov 24, 2025
fe46e1e
feature(docs): updated content
dazgreer Dec 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
226 changes: 118 additions & 108 deletions doc/basic.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,26 +1,21 @@

# Basic layout example
## Basic layout example

In this section, you're going to learn how to code a basic email template using MJML.

Here is the final render we want to end with:
Here‘s what we’re building:

<p style="text-align: center;" >
<a href="https://mjml.io/try-it-live/templates/basic"><img width="350px" src="https://static.mailjet.com/mjml-website/documentation/basic-layout-example.png" alt="sexy"></a>
</p>
<figure>
<img width="350px" src="https://static.mailjet.com/mjml-website/documentation/basic-layout-example.png" alt="Basic email layout" />
</figure>

<p style="text-align: center;" >
<a href="https://mjml.io/try-it-live/templates/basic"><img width="100px" src="https://mjml.io/assets/img/svg/TRYITLIVE.svg" alt="try it live" /></a>
</p>
<p class="cta-container"><a class="cta" href="https://mjml.io/try-it-live/templates/basic">Try it live</a></p>

Looks cool, right?
### Sections

## Sections

``` html
```html
<mjml>
<mj-body>

<!-- Company Header -->
<mj-section background-color="#f0f0f0"></mj-section>

Expand All @@ -38,167 +33,182 @@ Looks cool, right?

<!-- Social icons -->
<mj-section background-color="#f0f0f0"></mj-section>

</mj-body>
</mjml>
```
First, we will implement the skeleton which are the sections. Here, our email is going to be divided into 6 sections.

## Company Header
First, we’ll create the basic structure, dividing the email into six sections.

``` html
#### Company Header

```html
<!-- Company Header -->
<mj-section background-color="#f0f0f0">
<mj-column>
<mj-text align="center"
font-style="italic"
font-size="20px"
color="#626262">
<mj-text
align="center"
font-style="italic"
font-size="20px"
color="#626262"
>
My Company
</mj-text>
</mj-column>
</mj-section>

```
The first section of the email consists in a centered banner, containing only the company name. The following markup is the MJML representation of the layout we want to obtain.

<aside class="notice">
Remember everything has to be contained in one column.
</aside>
The text padding represents the inner space around the content within the `mj-text` element.
The first section of the email consists in a centered banner, containing only the company name. The following markup is the MJML representation of the layout we want to obtain.

## Image Header
<div class="alert alert-important" role="alert">
<p>Important</p>
<p>Remember everything has to be contained within the column.</p>
</div>

``` html
#### Image Header

```html
<!-- Image Header -->
<mj-section background-url="https://1.bp.blogspot.com/-TPrfhxbYpDY/Uh3Refzk02I/AAAAAAAALw8/5sUJ0UUGYuw/s1600/New+York+in+The+1960's+-+70's+(2).jpg"
background-size="cover"
background-repeat="no-repeat">

<mj-column width="600px">
<mj-text align="center"
color="#fff"
font-size="40px"
font-family="Helvetica Neue">
Slogan here
</mj-text>

<mj-button background-color="#F63A4D"
href="#">
Promotion
</mj-button>
</mj-column>

</mj-section>
<mj-section
background-url="https://1.bp.blogspot.com/-TPrfhxbYpDY/Uh3Refzk02I/AAAAAAAALw8/5sUJ0UUGYuw/s1600/New+York+in+The+1960's+-+70's+(2).jpg"
background-size="cover"
background-repeat="no-repeat"
>
<mj-column width="600px">
<mj-text
align="center"
color="#fff"
font-size="40px"
font-family="Helvetica Neue"
>
Slogan here
</mj-text>

<mj-button background-color="#F63A4D" href="#"> Promotion </mj-button>
</mj-column>
</mj-section>
```

Next comes a section with a background image and a block of text (representing the company slogan) and a button pointing to a page listing all the company promotions.

To add the image header, you will have to replace the section's background-color by a background-url.
Similarly to the first header, you will have to center the text both vertically and horizontally.
The padding remains the same.
The button `href` sets the button location.
In order to have the background rendered full-width in the column, set the column width to 600px with `width="600px"`.
To add the image header, you will have to replace the section's `background-color` with a `background-url`.

## Introduction Text
Similarly to the first company header, you will have to center the text.

The button `href` sets where the button links to.

In order to have the background rendered full-width in the column, set the column width to 600px with `width="600px"`.

``` html
#### Introduction Text

```html
<!-- Intro text -->
<mj-section background-color="#fafafa">
<mj-column width="400px">
<mj-text font-style="italic"
font-size="20px"
font-family="Helvetica Neue"
color="#626262">
My Awesome Text
</mj-text>
<mj-text color="#525252">
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin rutrum enim eget magna efficitur, eu semper augue semper. Aliquam erat volutpat. Cras id dui lectus. Vestibulum sed finibus lectus, sit amet suscipit nibh. Proin nec commodo purus. Sed eget nulla elit. Nulla aliquet mollis faucibus.
</mj-text>

<mj-button background-color="#F45E43"
href="#">
Learn more
</mj-button>
</mj-column>
</mj-section>
<mj-section background-color="#fafafa">
<mj-column width="400px">
<mj-text
font-style="italic"
font-size="20px"
font-family="Helvetica Neue"
color="#626262"
>
My Awesome Text
</mj-text>

```
<mj-text color="#525252">
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin rutrum enim
eget magna efficitur, eu semper augue semper. Aliquam erat volutpat. Cras
id dui lectus. Vestibulum sed finibus lectus, sit amet suscipit nibh.
Proin nec commodo purus. Sed eget nulla elit. Nulla aliquet mollis
faucibus.
</mj-text>

The introduction text will consist of a title, a main text and a button.
The title is a regular `mj-text` that can be customized.
<mj-button background-color="#F45E43" href="#">Learn more</mj-button>
</mj-column>
</mj-section>
```

## 2 Columns Section
The introduction text will consist of a heading, the main text and a button.
The title is a regular `mj-text` tag that can be styled as a heading.

``` html
#### 2 Columns Section

```html
<!-- Side image -->
<mj-section background-color="white">

<!-- Left image -->
<mj-column>
<mj-image width="200px"
src="https://designspell.files.wordpress.com/2012/01/sciolino-paris-bw.jpg" />
<mj-image
width="200px"
src="https://designspell.files.wordpress.com/2012/01/sciolino-paris-bw.jpg"
/>
</mj-column>

<!-- right paragraph -->
<mj-column>
<mj-text font-style="italic"
font-size="20px"
font-family="Helvetica Neue"
color="#626262">
Find amazing places
</mj-text>

<mj-text color="#525252">
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin rutrum enim eget magna efficitur, eu semper augue semper. Aliquam erat volutpat. Cras id dui lectus. Vestibulum sed finibus lectus.
</mj-text>
<mj-text
font-style="italic"
font-size="20px"
font-family="Helvetica Neue"
color="#626262"
>
Find amazing places
</mj-text>

<mj-text color="#525252">
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin rutrum enim
eget magna efficitur, eu semper augue semper. Aliquam erat volutpat. Cras
id dui lectus. Vestibulum sed finibus lectus.</mj-text
>
</mj-column>
</mj-section>

```

This sections is made up of 2 columns. One containing an image, the other one containing a text.
For the image part, note that when a tag does not have any child, you can use the XML self-closing tag syntax:
`<mj-image />`
This section is made up of two columns. One containing an image, the other containing text.

For the image, note that when a tag does not have any children, you can use the XML self-closing tag syntax: `<mj-image />`

For the text part, you are going to need two `<mj-text>`s like above. One with a title format, and the other one as a regular text.
For the text, you are going to use two `mj-text` tags like, as previously; one with a heading style, and the other one styled as regular text.

## Icons
#### Icons

``` html
```html
<!-- Icons -->
<mj-section background-color="#fbfbfb">
<mj-column>
<mj-image width="100px" src="https://191n.mj.am/img/191n/3s/x0l.png" />
<mj-image
padding="10px"
width="100px"
src="https://191n.mj.am/img/191n/3s/x0l.png"
/>
</mj-column>
<mj-column>
<mj-image width="100px" src="https://191n.mj.am/img/191n/3s/x01.png" />
<mj-image
padding="10px"
width="100px"
src="https://191n.mj.am/img/191n/3s/x01.png"
/>
</mj-column>
<mj-column>
<mj-image width="100px" src="https://191n.mj.am/img/191n/3s/x0s.png" />
<mj-image
padding="10px"
width="100px"
src="https://191n.mj.am/img/191n/3s/x0s.png"
/>
</mj-column>
</mj-section>
```
This section is a 3-columns-based section. Please notice you can make the padding vary to change the space around the images.
This section uses a 3-column layout to display the 3 icons horizontally across the email.


## Social Icons

``` html
#### Social Icons

```html
<mj-section background-color="#e7e7e7">
<mj-column>
<mj-social>
<mj-social-element name="facebook">Share</mj-social-element>
</mj-social>
</mj-column>
</mj-section>

```
The MJML standard components library comes with a `mj-social` component.
Here, we're going to use `facebook` only.

MJML has an `mj-social` component as standard. Here, we're going to use `facebook` only, but there are several default social media sites to choose from, or you can add your own bespoke.
4 changes: 2 additions & 2 deletions doc/body_components.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
# Standard Body components
## Standard Body components

MJML comes out of the box with a set of standard components to help you build easily your first templates without having to reinvent the wheel.
Body components ease your development process by providing ready made responsive layouts that you can use to create your email template.
11 changes: 5 additions & 6 deletions doc/community-components.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,17 @@
# Community components
## Community components

In addition to the standard components available in MJML, our awesome community is contributing by creating their own components.

To use a community component, proceed as follows:

- Install MJML locally with `npm install mjml` in a folder
- Install the community component with `npm install {component-name}` in the same folder
- Create a `.mjmlconfig` file in the same folder with:
- Create a `.mjmlconfig` file in the same folder with this code:

```json
{
"packages": [
"component-name/path-to-js-file"
]
"packages": ["component-name/path-to-js-file"]
}
```

Finally, you can now use the component in a MJML file, for example `index.mjml`, and run MJML locally in your terminal (make sure to be in the folder where you installed MJML and the community component): `./node_modules/.bin/mjml index.mjml`.
You can now use the component in an MJML file, for example `index.mjml`, and run MJML locally in your terminal. Ensure that you’re in the folder where you installed MJML and the community component, e.g.: `./node_modules/.bin/mjml index.mjml`.
49 changes: 49 additions & 0 deletions doc/community-contributions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
## Community Contributions

The MJML ecosystem has a dedicated community that we count to help make it grow and provide it with even more awesome tools, always aiming to make development with MJML an efficient and fun process!

Getting involved is really easy. If you want to contribute, feel free to [open an issue](https://github.com/mjmlio/mjml/issues) or [submit a pull-request](https://github.com/mjmlio/mjml/pulls)!

Here are some tools that utilise MJML:

### Mailjet

[Mailjet](https://www.mailjet.com/demo/) offers an integrated MJML workspace designed for creating, previewing, and managing email templates. Its MJML editor supports syntax highlighting, live preview, and validation, helping you move quickly while keeping your markup in good shape.

The drag-and-drop editor in Mailjet is also built on MJML, so visually created templates share the same responsive structure as those coded by hand.

When your template is ready, you can export it in MJML or HTML, or send emails directly through Mailjet.

### Parcel

[Parcel](https://parcel.io) is the code editor built for email. This feature packed tool includes syntax highlighting, Emmet, inline documentation, autocomplete, live preview, screenshots, and full MJML, CSS, and HTML validation.

Use Focus Mode to keep the preview aligned with the code you're working on, or Inspect Element to easily find the code that produces specific elements in the preview.

Export MJML to HTML with a click.

### IntelliJ IDEA Plugin - MJML Support

[IntelliJ IDEA](https://www.jetbrains.com/idea/) is an IDE developed by JetBrains. The plugin provides you with a (near) realtime preview, auto complete, inline documentation and code analysis.

It is available on the [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/16418-mjml-support).

### Gradle Plugin - MJML Compilation

[Gradle](https://gradle.org/) is a build tool for a various set of languages and environments. The plugin provides an easy way to embed your MJML templates to your Java/Kotlin application in its resources in precompiled form (HTML).

It is available through the gradle plugin system [io.freefair.mjml.java](https://plugins.gradle.org/plugin/io.freefair.mjml.java) and documentation is available here [FreeFair User Guide](https://docs.freefair.io/gradle-plugins/current/reference/).

### Neos CMS

[Neos CMS](https://www.neos.io/) is a content management system that combines structured content with application. This package adds the helper for compiling MJML markup as well as some prototypes which allow you to use TailwindCSS like classes in your MJML markup.

It is available on [packagist](https://packagist.org/packages/garagist/mjml).

### Easy-email

[Easy-email](https://github.com/zalify/easy-email) drag-and-drop email editor based on MJML. Transform structured JSON data into HTML that’s compatible with major email clients.

### Email Love

The [Email Love Figma plugin](https://www.figma.com/community/plugin/1387891288648822744/email-love-html-email-builder) takes the headache out of the email development process by enabling you to export responsive, production-ready email HTML or MJML directly from Figma.
Loading
Loading