feature(html/mjml): updates/reduction to underlying html

[dazgreer]

Highlights

• mj-title throws an error if missing or empty
• optional Outlook and dark mode support
• add space to preview text
• comprehensive tidy of HTML to reduce code bloat
• updated tests and docs

Details

Features

• mj-title throws an error if missing or empty (added test, updated doc)
• added support-outlook-classic option to mjml tag to remove support for Outlook (removes ghost tables and other Outlook specific code. Set to `true by default) (updated doc)
• added option to mj-preview to add blank space after preview text (updated doc) [Fixes Create automatically white space after <mj-preview> text #1829]

HTML changes

General

• auto removes any empty attribute instance of class=“” or style=“”
• removed | IE from all conditional comments
• updated docs for all attribute changes

html

• removed namepsacexmlns attribute as no longer needed
• only shows namepsace xmlns:o attribute when support-outlook-classic=“true"
• only shows namepsace xmlns:v if background-url is present on mj-hero or mj-section

meta

• updated charset tag
• removed X-UA-Compatible tag as no longer useful
• updated viewport tag to include user-scalable=yes
• added format detection tags to prevent clients from creating links from dates, contact details etc
• added dark mode tags behind support-dark-mode option (on <mjml> tag) to allow dark mode support

head (skeleton)

• removed .mj-outlook-group-fix CSS as only applies to older unsupported Outlook versions (2003 and less)
• removed -ms prefixed reset styles when support-outlook-classic="false"
• changed -webkit-text-size-adjust to text-size-adjust
• changed default margin from 13px to 1em
• removed <link> font import, now uses just @import CSS
• added dark mode :root CSS behind support-dark-mode option (on <mjml> tag) to allow dark mode support

style (skeleton)

• removed type=“text/css” as no longer required
• removed some spacing between CSS rules
• concatenates <style> blocks where possible
• removed width declaration for mj-column-per-100 as it’s declared by default in the tag
• added format detection CSS to prevent clients from creating links from dates, contact details etc

table

• updated all instances of role=“presentation” to role=“none”
• removed all <tbody> tags [breaking change for any user added CSS that relies on it in a selector]

font-family declarations

• removed Helvetica and Arial as fallbacks [small breaking change as fonts will change to system default sans-serif font]

mj-body

• added xml:lang=“” (populated from globalData language, declared on mjml tag)
• removed word-spacing as declared on the child div

mj-accordion

• concatenated CSS selectors with identical declarations
• changed border-bottom declaration to 0 and now only outputs when border is not already set to 0 or none
• removed vertical-align as it’s default to the tag
• fixed Gmail specific CSS (broken by Prettier) and broken out accordion CSS into its own <style> block as it broke other things in Gmail

mj-accordion-element

• removed padding attribute as it’s default to the tag

mj-accordion-title

• moved background-color attribute to parent table tag rather than both td tags

mj-button

• removed text-transform, font-weight attributes as default to the tag
• removed target attribute as not necessary in email
• set display to block and removed mso-padding-alt declaration to solve issue where the full button is not clickable when the width is set
  • added multiline option to allow users to negate issues with the above in Outlook classic when button text wraps
• removed default cursor: auto set on <td> and margin: 0 set on <a>
• added function to remove 1px padding to compensate for the added border

mj-carousel

• added prettier-ignore comment to fallback image as Prettier was breaking it
• concatenated CSS selectors for identical declarations, where possible
• changed carousel unique ID from 16 characters to 6
• removed mso-hide-all attributes as the carousel is not displayed in Outlook
• removed border-radius from Outlook fallback image as Outlook does not display it
• created shared CSS for multiple carousel instances as previously it was duplicated
• removed default target on links and height on image as not needed.
• removed [owa] class as no longer used

mj-carousel-image

• now respects target attribute
• checkbox set to just checked for first input rather than checked="checked"

mj-column

• removed direction attribute as default to the tag
• removed vertical-align declaration from table as set in children
• removed mj-outlook-group-fix class as only applies to older unsupported Outlook versions (2003 and less)

mj-divider

• now uses either table or p (based on support-outlook-classic) and only outputs one
• removed px units for html table width as they don’t work
• added max-width to both table and p to better handle width

mj-group

• removed direction attribute as default to the tag
• removed 'text-align': 'left' from div as default
• removed mj-outlook-group-fix class as only applies to older unsupported Outlook versions (2003 and less)

mj-hero

• removed unnecessary background-url and padding defaults
• removed duplication of background-repeat declaration in background shorthand value
• reduced value of background-position declaration to single center
• added closing </td> tags for fluid height hero as self-closing tag is not valid
• removed vertical-align declaration from <tr> tag
• fixed issue where left padding disappeared in Outlook when background-url (VML) added

mj-image

• removed fluid-on-mobile CSS when not set
• removed unnecessary class on td and changed CSS selector to accommodate
• removed text-decoration, outline and font-size as attributes as default to the tag
• removed target attribute as not necessary in email

mj-navbar

• hamburger now takes set font-family / font-size / line-height when declaring in mj-attributes > mj-all. Previously it was using its own
• removed hamburger CSS when hamburger is not set [Fixes Navbar without hamburger unnecessary css #2848]
• removed ico-text-decoration attribute as default to the tag
• concatenated CSS selectors with same rules
• removed 'mso-hide': 'all' and '-moz-user-select': 'none' as not required
• changed navbar unique ID from 16 characters to 6

mj-navbar-link

• removed font-weight as attribute as default to the tag
• removed target attribute as not necessary in email

mj-section

• removed direction, background-repeat and background-size as attributes as default to the tag
• removed multiple declarations of background-color or color reference in background as unnecessarily declared multiple times
• changed text-align option to column-align as it was poorly named. Aliased the deprecated option for backwards compatibility [updated docs]
• fixed issue where left padding disappeared in Outlook when background-url (VML) added

mj-social

• removed target attribute as not necessary in email
• updated sharer URLs
• removed icon width declarations [Fixes MJ-SOCIAL - Outlook app android/iOS interpret wrong the icon-padding. #3043]

mj-social-element

• removed text-align and vertical-align as attributes as default to the tag

mj-table

• removed width declaration when user sets to auto as default to tag
• removed table-layout attribute as default to the tag. If the user adds, it will also not be be written out
• updated associated test

mj-wrapper

• removed text-align from docs as it doesn't do anything

[guigui64]

Code looks good to me.

Just one remark on this:

removed all tags [potential small breaking change for any user added CSS that relies on it in a selector]

I think it is a breaking change (not a small one) and you should list it in the release notes.

[Copilot]

Pull request overview

This PR reduces generated email HTML, introduces configurable Outlook/dark-mode support, and updates component rendering, documentation, and regression coverage.

Changes:

• Simplifies generated markup, styles, conditional comments, and table structures.
• Adds Outlook-classic, dark-mode, preview-spacing, alignment, and button options.
• Updates component defaults, compatibility fixes, documentation, and tests.

Reviewed changes

Copilot reviewed 61 out of 61 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
packages/mjml/test/utils.js	Safely extracts CSS properties.
packages/mjml/test/template-syntax-sanitization.test.js	Tests mixed template syntax.
packages/mjml/test/tableWidth.test.js	Updates table-width expectations.
packages/mjml/test/support-outlook-classic.test.js	Tests Outlook option parsing.
packages/mjml/test/section-gutter.test.js	Updates reduced column markup expectations.
packages/mjml/test/section-button-outlook-margin.test.js	Tests VML button alignment.
packages/mjml/test/section-background-url-no-background-size.test.js	Tests section background defaults.
packages/mjml/test/button-inner-padding-border.test.js	Tests button border compensation.
packages/mjml/test/beautify-output.test.js	Updates beautification fixtures.
packages/mjml-wrapper/src/index.js	Uses shared MSO helpers.
packages/mjml-wrapper/README.md	Updates wrapper defaults.
packages/mjml-validator/src/rules/validTag.js	Permits root mjml validation.
packages/mjml-validator/src/index.js	Validates formerly skipped roots.
packages/mjml-text/src/index.js	Simplifies text and Outlook markup.
packages/mjml-text/README.md	Updates text defaults.
packages/mjml-table/src/index.js	Omits redundant table widths/layouts.
packages/mjml-table/README.md	Updates table defaults.
packages/mjml-social/src/SocialElement.js	Reduces social-element markup.
packages/mjml-social/src/Social.js	Simplifies social tables and conditionals.
packages/mjml-social/README.md	Updates social defaults.
packages/mjml-section/src/index.js	Adds alignment and VML handling changes.
packages/mjml-section/README.md	Documents section API changes.
packages/mjml-parser-xml/test/preprocessors.test.js	Adds a title to preprocessing coverage.
packages/mjml-navbar/src/NavbarLink.js	Simplifies Outlook link rendering.
packages/mjml-navbar/src/Navbar.js	Reduces and deduplicates hamburger output.
packages/mjml-navbar/README.md	Updates navbar defaults.
packages/mjml-image/src/index.js	Reduces image markup and conditional CSS.
packages/mjml-image/README.md	Updates image target defaults.
packages/mjml-hero/src/index.js	Simplifies hero and VML markup.
packages/mjml-hero/README.md	Updates hero defaults.
packages/mjml-head-title/README.md	Adds title-validation documentation.
packages/mjml-head-preview/src/index.js	Adds preview filler options.
packages/mjml-head-preview/README.md	Documents preview filler attributes.
packages/mjml-group/src/index.js	Simplifies group markup and classes.
packages/mjml-group/README.md	Updates group defaults.
packages/mjml-divider/src/index.js	Selects table or paragraph rendering.
packages/mjml-core/tests/mergeHeadStyleBlocks.test.js	Tests style-block merging.
packages/mjml-core/src/index.js	Initializes options and post-processes styles.
packages/mjml-core/src/helpers/styles.js	Consolidates generated style blocks.
packages/mjml-core/src/helpers/skeleton.js	Reduces skeleton and adds feature flags.
packages/mjml-core/src/helpers/mergeOutlookConditionnals.js	Supports updated MSO conditionals.
packages/mjml-core/src/helpers/mergeHeadStyleBlocks.js	Merges adjacent head styles.
packages/mjml-core/src/helpers/mediaQueries.js	Consolidates media-query CSS.
packages/mjml-core/src/helpers/fonts.js	Uses CSS-only font imports.
packages/mjml-core/src/helpers/conditionalTag.js	Adds configurable Outlook conditionals.
packages/mjml-core/src/createComponent.js	Omits empty and false attributes.
packages/mjml-column/src/index.js	Reduces columns and adds VML corrections.
packages/mjml-column/README.md	Updates column defaults.
packages/mjml-carousel/src/CarouselImage.js	Simplifies carousel images and targets.
packages/mjml-carousel/src/Carousel.js	Deduplicates carousel CSS and markup.
packages/mjml-carousel/README.md	Updates carousel target defaults.
packages/mjml-button/src/index.js	Changes button sizing and multiline behavior.
packages/mjml-button/README.md	Documents button API changes.
packages/mjml-body/src/index.js	Simplifies body markup and language output.
packages/mjml-body/src/helpers/preview.js	Updates hidden preview sizing.
packages/mjml-accordion/src/AccordionTitle.js	Consolidates title styles.
packages/mjml-accordion/src/AccordionText.js	Reduces accordion text markup.
packages/mjml-accordion/src/AccordionElement.js	Removes redundant element styles.
packages/mjml-accordion/src/Accordion.js	Consolidates accordion CSS and markup.
packages/mjml-accordion/README.md	Updates accordion defaults.
doc/components_1.md	Updates generated HTML and root options.

Suppressed comments (3)

packages/mjml-section/src/index.js:459

• Section padding accepts percentages, but getShorthandAttrValue parses away the unit and this rebuilds every value as pixels. For example, padding="10%" becomes a VML inset of 10px while Outlook's normal padding is disabled, producing substantially different spacing. Preserve the declared units or calculate the percentage against the relevant dimensions.
  packages/mjml-column/src/index.js:534
• The same unit loss affects button outer padding: padding-left="25%" is emitted in the VML correction rule as 25px. Since % is allowed for button padding, left-aligned buttons in background sections receive the wrong Outlook margin. Preserve the unit or resolve the percentage against the button container.

            if (isLeftAlignedButton && hasSectionBackground) {
              const buttonClassName = `vml-button-${genRandomHexString(6)}`
              const buttonLeftPadding = `${component.getShorthandAttrValue('padding', 'left')}px`

packages/mjml-button/src/index.js:122

• This second mso-padding-alt declaration also survives support-outlook-classic="false". Apply the same global support check here so the option consistently removes Outlook-only CSS.

        ...(this.getAttribute('multiline') === true && { 'mso-padding-alt': '0px' }),

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[dazgreer]

I've updated so that scanner emits malformed remaining input and sets pos = headInner.length for:

• Unterminated <!-- comments
• Unterminated plain <style>
• Attributed <style> without a closing tag
• Attributed <style ... without a closing >

Also added regression testing for these cases

[dazgreer]

I've updated to detect a later plain <style> block whose CSS begins with @import or @charset and keeps it separate instead of concatenating it after earlier CSS.

Added regression tests for both cases

[dazgreer]

I've updated to check length and returns before setting globalData.carouselSharedStylesEmitted = true.

Added regression test for this case

[dazgreer]

Updated to preserve resolved global and class attributes in rawAttrs.

Added regression testing for both cases to demonstrate inheritance

[dazgreer]

I've updated to add a unit-preserving getPaddingLeft() function and applied it in two instances

• the column gutter preserves % instead of appending px.
• the left aligned button VML margin

Added test verifying both of these

[dazgreer]

I've removed this from the docs. I initially added validation but removed it as overreach.

[dazgreer]

I haven't added space by default (to prevent a breaking change) but this does gives the user control over adding it.

I have normalised negative values to 0, added regression testing and updated documentation for clarity

[dazgreer]

I've updated to include supportOutlookClassic from the global context and emit mso-padding-alt:0 only when it's not set to false.

line 459 doesn't contain an mso-padding-alt declaration.

[dazgreer]

I've updated to gate the mso-padding-alt declaration on both multiline="true" AND supportOutlookClassic in two instances.

Added regression testing for this case