mjml

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 24, 2026 License: AGPL-3.0 Imports: 12 Imported by: 0

Documentation

Overview

Package mjml works with MJML documents on the server: a tolerant parser for outlines, warnings and wireframes, the server-side compiler (gomjml, MJML 4.15) used when content arrives as MJML only (API and automation sends), and head helpers that keep <mj-title>/<mj-preview> in step with the subject and preheader.

The composer compiles in the browser with mjml-browser (grapesjs-mjml); both engines target MJML 4 and parity is checked by tests.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ChangedSections

func ChangedSections(base, next string) []string

ChangedSections compares two documents and returns the labels of the sections of `next` that differ from `base` (added, edited or moved), plus the labels of sections removed from base.

func HeadMeta

func HeadMeta(src string) (title, preview string)

HeadMeta reads the title and preview text of a document.

func SectionLabel

func SectionLabel(n *Node, index, total int) string

SectionLabel names a top-level body element: the ReputeCast marker when there is one, otherwise what it looks like.

func SetHeadMeta

func SetHeadMeta(src, title, preview string) string

SetHeadMeta writes <mj-title> (the subject) and <mj-preview> (the preheader) into a document so the compiled HTML's title and hidden preview text always match the fields. Empty values remove the element. A document that doesn't parse is returned unchanged.

Types

type Attr

type Attr struct {
	Name  string
	Value string
}

Attr is one attribute with its decoded value.

type MJMLProblem

type MJMLProblem struct {
	Line    int    `json:"line"`
	Message string `json:"message"`
	Tag     string `json:"tag,omitempty"`
}

MJMLProblem is a compile error or warning with its line (0 when unknown).

func Lint

func Lint(src string) []MJMLProblem

Lint returns layout warnings the MJML compiler doesn't report: images wider than their column (Outlook draws them at full width and breaks the layout) and columns adding up to more than their section.

type MJMLThumbItem

type MJMLThumbItem struct {
	H      int             `json:"h,omitempty"`
	W      int             `json:"w,omitempty"`
	Accent bool            `json:"accent,omitempty"`
	Row    []MJMLThumbItem `json:"row,omitempty"`
}

MJMLThumbItem is one bar of a template's wireframe thumbnail in the gallery: a grey block of height H (px) and width W (% of the thumbnail; 0 = full), an accent pill for buttons, or a row of blocks for columns.

func Thumb

func Thumb(src string) []MJMLThumbItem

Thumb derives the gallery wireframe from a document: a short bar for the header, a block for a hero image, a row of blocks for columns, lines for text and a pill for a button. It keeps at most five items and stops at the first one that doesn't fit the thumbnail, so no bar is cut off.

type Node

type Node struct {
	Tag      string
	Attrs    []Attr
	Children []*Node
	// Inner is the raw content of ending tags (mj-text, mj-button, mj-raw…),
	// which hold HTML rather than MJML elements.
	Inner string
	// Marker is the ReputeCast block a preceding <!-- rc:… --> comment names
	// ("footer", "header-logo"), empty otherwise.
	Marker string
	// Line is the 1-based line of the opening tag.
	Line int
	// Start and End are byte offsets of the element in the source.
	Start, End int
}

Node is one element of an MJML document.

func Body

func Body(root *Node) *Node

Body returns the <mj-body> of a document, or nil.

func Head(root *Node) *Node

Head returns the <mj-head> of a document, or nil.

func Parse

func Parse(src string) (*Node, error)

Parse reads an MJML document and returns its <mjml> root. It is lenient about whitespace, attribute quoting, comments and void tags, and reports tags that are never closed with their line.

func (*Node) Attr

func (n *Node) Attr(name string) string

Attr returns an attribute value or "".

func (*Node) Find

func (n *Node) Find(tag string) *Node

Find returns the first descendant (or n itself) with the tag.

func (*Node) Get

func (n *Node) Get(name string) (string, bool)

Get returns an attribute value and whether it is set.

func (*Node) Walk

func (n *Node) Walk(fn func(node *Node, path []int))

Walk calls fn for n and every descendant, depth first, with the path of element indices from n.

type ParseError

type ParseError struct {
	Line    int
	Message string
}

ParseError is a syntax problem with its line.

func (*ParseError) Error

func (e *ParseError) Error() string

type Result

type Result struct {
	HTML     string
	Errors   []MJMLProblem
	Duration time.Duration
}

Result is the outcome of a server-side compile.

func Compile

func Compile(src string) Result

Compile renders MJML to HTML with gomjml, the server-side twin of the composer's mjml-browser. It is used when content arrives as MJML only (the API, automations); the composer stores the HTML it compiled itself.

type Section

type Section struct {
	// Index is the position among mj-body's elements (comments excluded).
	Index int    `json:"index"`
	Tag   string `json:"tag"`
	// Label names the section the way the layer tree does: "header", "hero",
	// "2 columns", "text", "footer".
	Label string `json:"label"`
	// Marker is the ReputeCast block it was inserted from ("footer"), if any.
	Marker string `json:"marker,omitempty"`
	Line   int    `json:"line"`
	// Hash fingerprints the section's source, to tell which sections changed
	// between two versions.
	Hash string `json:"-"`
}

Section is one top-level block of <mj-body>.

func Outline

func Outline(src string) ([]Section, error)

Outline lists the sections of a document's body with readable labels.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL