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
- func ChangedSections(base, next string) []string
- func ConditionalID(n *Node) string
- func ExpectedMarkers(src string) []string
- func HeadMeta(src string) (title, preview string)
- func MarkSynced(block, kind string) (string, bool)
- func PrepareCompile(src string) string
- func RemoveAttr(src string, n *Node, name string) (string, bool)
- func ReplaceSynced(src, kind, block string) (string, bool)
- func SectionLabel(n *Node, index, total int) string
- func SectionWord(l i18n.Lang, label string) string
- func SetAttr(src string, n *Node, name, value string) (string, bool)
- func SetAttrRaw(src string, n *Node, name, value string) (string, bool)
- func SetHeadMeta(src, title, preview string) string
- func StripMarkers(html string) string
- func SyncedKinds(src string) []string
- func UnmarkSynced(src, kind string) (string, bool)
- func UnwrapFragment(doc string) string
- func WrapFragment(block string) string
- type Attr
- type Fingerprint
- type MJMLProblem
- type MJMLThumbItem
- type Merge
- type MergedSection
- type Node
- type ParseError
- type Result
- type Section
- type Verdict
Constants ¶
const ( AttrVisible = "rc-visible" AttrName = "rc-name" AttrPoll = "rc-poll" AttrOmit = "rc-omit" AttrShowOn = "rc-show-on" // ShowOnWeb is a Web only block: it isn't part of the email. ShowOnWeb = "web" )
AttrVisible, AttrName, AttrPoll and AttrOmit are ReputeCast's own attributes; AttrShowOn is a block's "Show on" (the publication website, design expansion phase 7): "email", "web", or absent for both.
const ( MarkerIf = "<!--rc:if " MarkerFi = "<!--rc:fi " )
Marker comments around a conditional block in compiled HTML.
const AttrSynced = "rc-synced"
AttrSynced marks a synced block in an email (review 2026-10, CO-11): the element, a section or a wrapper, is the workspace's synced block of that kind ("header", "footer", or a named block's key such as "b-0123456789ab", R4.A3), and is replaced whenever the block changes (internal/brandkit). Like every rc-* attribute it is left out of the compiled HTML.
Variables ¶
This section is empty.
Functions ¶
func ChangedSections ¶
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 ConditionalID ¶
ConditionalID returns the id of a conditional element: one with a Visibility rule that doesn't show it to everyone. "" otherwise.
func ExpectedMarkers ¶
ExpectedMarkers lists the markers compiled HTML of src must carry, in order: one pair per conditional block PrepareCompile wraps.
func MarkSynced ¶
MarkSynced makes block, one MJML element, the synced block of a kind: it sets rc-synced on its outermost element. ok is false when block isn't a single section or wrapper.
func PrepareCompile ¶
PrepareCompile turns a document into what the compilers get: rc-* attributes removed, Web only blocks (the post's, not the email's) and blocks marked rc-omit (shown in the editor only) left out, and conditional blocks wrapped in their markers. A document that doesn't parse is returned unchanged (the compiler reports its error). A block whose id appears twice is marked once, the first time: the composer gives a copied block an id of its own.
func RemoveAttr ¶
RemoveAttr removes an attribute of an element in the source.
func ReplaceSynced ¶
ReplaceSynced puts block in place of every element marked rc-synced="kind" (not inside another such element). block is the synced block's MJML, one element. It returns the document unchanged, and false, when nothing is marked, nothing changes or the document doesn't parse.
func SectionLabel ¶
SectionLabel names a top-level body element: the ReputeCast marker when there is one, otherwise what it looks like.
func SectionWord ¶
SectionWord names a section label (Outline, SectionLabel) in a reader's language, in lower case as it reads inside a sentence: "chân thư" for "footer", "2 cột" for "2 columns". Labels it doesn't know, such as a block's own name, stay as they are.
func SetAttr ¶
SetAttr sets an attribute of an element in the source: it replaces the value or adds the attribute after the tag's name. Values are written double-quoted, escaped as html.EscapeString escapes them (spelled out, so that quotes visibly can't end the value: settings are JSON).
func SetAttrRaw ¶
SetAttrRaw is SetAttr for values that hold single quotes on purpose (font stacks): only &, <, > and double quotes are escaped.
func SetHeadMeta ¶
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.
func StripMarkers ¶
StripMarkers removes the conditional markers from compiled HTML: the email every recipient would get if no block were conditional.
func SyncedKinds ¶
SyncedKinds lists the kinds of synced blocks a document holds, in the order they first appear.
func UnmarkSynced ¶
UnmarkSynced unlinks the elements marked rc-synced="kind": they keep their content as ordinary sections and no longer follow the block (it was deleted, R4.A3). It returns the document unchanged, and false, when nothing is marked or the document doesn't parse.
func UnwrapFragment ¶
UnwrapFragment is the body elements of a document made by WrapFragment.
func WrapFragment ¶
WrapFragment puts body elements in a document so Parse reads them; UnwrapFragment takes them back out.
Types ¶
type Fingerprint ¶
type Fingerprint struct {
// Links are the href of every <a>, in document order.
Links []string
// Images are the src of every <img>, in document order.
Images []string
// Words are the visible words of the body, in document order.
Words []string
// Markers are the conditional blocks' markers, in document order
// ("if a1b2c3", "fi a1b2c3").
Markers []string
}
Fingerprint is what an email shows and does, read from its HTML: its links, its images, its words and its conditional markers. The HTML of one MJML document from two compilers has one fingerprint even where the markup differs (gomjml and mjml-browser, checked by the parity tests).
func HTMLFingerprint ¶
func HTMLFingerprint(src string) Fingerprint
HTMLFingerprint reads the fingerprint of compiled HTML. The head, styles, scripts and comments (Outlook's conditional comments included) carry no words; markers are comments of their own.
func (Fingerprint) Mismatch ¶
func (a Fingerprint) Mismatch(b Fingerprint) string
Mismatch says how two fingerprints differ ("links", "images", "text", "conditional markers"), or "" when they agree.
func (Fingerprint) String ¶
func (a Fingerprint) String() string
String writes a fingerprint for test failures.
type MJMLProblem ¶
type MJMLProblem struct {
Line int `json:"line"`
Message string `json:"message"`
Tag string `json:"tag,omitempty"`
// contains filtered or unexported fields
}
MJMLProblem is a compile error or warning with its line (0 when unknown). Message is in English; In writes it in a reader's language.
func Checked ¶
func Checked(src, htmlSrc string) (out, mismatch string, errs []MJMLProblem)
Checked returns the HTML to store for an MJML document and the HTML a client compiled from it: the client's when it shows and does what the MJML says, the server's own compile otherwise (mismatch names what differed: links, images, text or conditional markers). Without HTML the server compiles; without MJML (an HTML-only email) the HTML is the source. errs is set when nothing trustworthy can be stored: the MJML doesn't compile and there is no HTML, or the HTML lacks the markers.
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. They are in English; LintIn writes them in a reader's language.
type MJMLThumbItem ¶
type MJMLThumbItem struct {
Kind string `` /* 140-byte string literal not displayed */
H int `json:"h,omitempty"`
W int `json:"w,omitempty"`
Accent bool `json:"accent,omitempty"`
Row []MJMLThumbItem `json:"row,omitempty"`
}
MJMLThumbItem is one part of a template's thumbnail in the gallery, a miniature email (Composer and ComposerEmpty boards): a 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. Kind says what it stands for.
func Thumb ¶
func Thumb(src string) []MJMLThumbItem
Thumb derives the gallery's miniature email from a document: the header (logo and links), a block for a hero image, a row of blocks for columns, lines for headings and text, a pill for a button, and the footer. The header and the footer frame it; between them it keeps at most five parts and stops at the first one that doesn't fit, so no part is cut off.
type Merge ¶
type Merge struct {
// MJML is mine with their sections (and head) put in. Its head has no
// <mj-title> or <mj-preview>: they follow the subject and preheader,
// which are merged on their own (SetHeadMeta puts them back).
MJML string
// Theirs are the sections taken from theirs, in mine's positions.
Theirs []MergedSection
// Head is the inner MJML of their mj-head (styles, fonts, attributes)
// when theirs changed it and mine didn't.
Head string
}
Merge is a three-way merge of two edits of the same version, section by section (review 2026-10, CO-10): when two people changed different sections, each keeps theirs.
func MergeSections ¶
MergeSections merges theirs and mine, both edited from base, when they changed different sections. ok is false when they changed the same section (or the head) differently, or added, removed or moved sections: a person then chooses.
type MergedSection ¶
type MergedSection struct {
Index int `json:"index"`
Label string `json:"label"`
MJML string `json:"mjml"`
}
MergedSection is a section a merge took from the other side.
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 Parse ¶
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.
type ParseError ¶
ParseError is a syntax problem with its line. Message is in English; In writes it in a reader's language.
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.
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>.
type Verdict ¶
type Verdict struct {
// OK is true when the HTML shows and does what the MJML says.
OK bool
// Mismatch names what differs ("links", "text", "conditional markers").
Mismatch string
// HTML is the server's own compile of the MJML, to store instead when
// the HTML doesn't match; empty when the server couldn't compile it.
HTML string
// Errors are the server compile's errors, if any.
Errors []MJMLProblem
}
Verdict is the outcome of checking a client's HTML against its MJML.