Developer documentation.

Template Hedgehog is an Artifexa implementation system for production email. Layout pages show complete message structure, and component pages let you inspect single blocks when needed.

The intended editing model is straightforward: treat MJML as the source of truth, compile to HTML when your ESP or review process needs final markup, and keep screenshots or previews as validation rather than the editable asset.

A safe working pattern for most teams looks like this:

1. Start from the closest layout, then move to component detail when needed.
2. Edit the MJML source rather than patching compiled HTML by hand.
3. Compile to HTML and test the result in your delivery workflow.
4. Run quick visual checks in Gmail, Outlook, and Apple Mail before final send.

Use the compiled HTML panels when you need a delivery-ready snapshot for QA, approval, or an ESP that only accepts raw HTML. If you expect the block to be reused, keep your real changes in the MJML source instead.

Component pages expose two copy modes when the sources differ. Use the snippet mode when you are stacking multiple blocks inside one existing mj-body. Use the standalone mode when you need a complete file that can compile on its own.

• MJML snippets are block-level source for composing several sections into the same email.
• Standalone MJML includes the wrapper, shared classes, and document structure required for independent compilation.
• HTML snippets are useful for inspection and controlled assembly, but most ESP handoff should use standalone compiled HTML.
• Compiled standalone HTML is the delivery-ready output for QA, import, and final review.

Desktop Outlook is still the main reason email markup becomes brittle. MJML helps, but it does not make Outlook behave like a modern browser.

• Keep complex nesting conservative. Deeply layered sections, unusual overlaps, and fancy spacing are more likely to break.
• Test button padding and border radius in Outlook desktop. Small visual differences are common even when the block is valid.
• Avoid relying on background-image tricks for essential content or CTA clarity.
• Expect typography to render slightly heavier or looser than in Gmail and Apple Mail.
• When in doubt, prefer simpler table-safe structure over a more ambitious visual treatment.

The safest customisation approach is to change tokens and content first, then structure only when required.

• Replace copy, links, imagery, and brand colours before altering block structure.
• Keep CTA labels short so buttons still read cleanly on narrow mobile clients.
• When swapping imagery, preserve the overall aspect ratio where possible to avoid uneven spacing.
• Reuse spacing values consistently instead of introducing one-off padding tweaks across multiple sections.
• If you need a recurring variant, duplicate the MJML block in your own codebase rather than repeatedly editing compiled HTML.

A good default is to maintain your own small token map for colours, spacing, and button styles, then interpolate those values into the MJML before compilation.

Email clients fetch images remotely, so image delivery matters as much as markup quality.

• Host production images on a stable HTTPS domain or CDN you control.
• Do not rely on temporary design-tool URLs or expiring preview links.
• Use meaningful alt text for content images and empty alt text only for decorative ones.
• Optimise file sizes before send. Heavy images slow down preview loading and can affect clipping in some clients.
• Keep critical message copy out of images so dark mode, blocking, or accessibility settings do not hide it.

Components are best when you are assembling or updating one block at a time. Layouts are best when you need a starting architecture for a complete send.

• Start with a component page when the job is small, such as swapping a hero, footer, CTA, or transactional panel.
• Start with a layout page when the whole email structure matters, including content order and message pacing.
• Use the component breakdown on layout pages to identify which blocks should become your editable source modules.
• Once a layout is close, refine its individual sections through the related component pages rather than editing blindly.

Some teams hand compiled HTML straight to an ESP. Others move through review, QA, or CRM tooling first. The important thing is to separate editable source from delivery output.

• Use MJML in version control if developers or marketers will iterate on the email again.
• Use compiled HTML for final import, QA snapshots, or platforms that do not understand MJML.
• Keep a record of the component or layout slug used so future edits start from the right source block.
• After importing into an ESP, verify that tracking links, merge tags, and unsubscribe logic did not alter structure unexpectedly.

Even solid MJML can be undermined by delivery context. These are the common issues worth checking before send.

• Long CTA labels that wrap awkwardly on mobile.
• Logo or hero images that are too small to survive high-density displays cleanly.
• Dark-mode inversions that reduce contrast on muted text or secondary links.
• Padding values that look balanced in webmail but become too tight in Outlook desktop.
• Edited compiled HTML drifting away from the MJML source, making the next revision harder than it should be.

If you hit one of these issues often, favour the simpler variant in the layout reference. Reliability is usually worth more than a slightly more decorative layout treatment.