A tour of the dd_emailforge app
dd_emailforge runs inside your terminal. You'll mostly use the keyboard, but you can also click in the tree and the email outline. If you forget a key, press F1 for Help at any time.
Keys, screens, and commands may differ in other versions.
Image not captured yet. Full app window with the header, Structure tree, Details panel and footer bar labelled 1 to 4
Planned file: source/images/emailforge/tour-of-the-tui/tour-of-the-tui-01-layout-labelled.png
Alt text: The dd_emailforge window with four labelled areas: header, Structure tree, Details panel, and footer shortcut bar
- Header. Three rows at the top with the app name and a rotating tagline.
- Structure (left). A tree of your whole email. The top three rows are always there:
- [HEAD]: the email's details: name, subject, preheader, language, title, base URL for local images, web fonts, and custom CSS.
- [BRAND]: your email's font, text and background colors, content width, and button colors. These apply across the whole email.
- [BODY]: everything readers see. Below it are your blocks: sections, columns, and the content inside them.
- Details (right). A summary of the selected block's settings, plus a blueprint: a simple text outline of the whole email. Click any box in the blueprint to select that block.
- Footer bar. One line of shortcuts, starting with
F1:Help. It changes depending on what you're doing.
Give the app a wide terminal window. Below 48 columns, only the Structure panel shows, and narrow windows drop keys from the footer bar.
| Window | Open it with | What it's for |
|---|---|---|
| Help | F1 | Every shortcut, at a glance. |
| Theme | F2 | The app's own colors. This changes how the app looks, not your email. Your email's look lives in [BRAND]. |
| Validation | F3 | A list of problems in your template. Press Enter on one to jump to the block or field to fix. If there are no problems, you just see a "✓ Validation passed" message. |
| Insert picker | / | Add a block. Type to filter, pick with ↑/↓, then press Enter. The list is split into "blocks" (email-header, email-hero, …) and "primitives" (mj-section, mj-text, …). |
| FormEdit | Enter (or double-click) | Edit the selected block's fields. |
| Image picker | Ctrl+P (in FormEdit) | Choose an image from the template's images/ folder. |
| New / Open | n / o | Start a new template or open another one. |
| Messages | (automatic) | Short pop-up notes for success, info, warnings, and errors. |
Keys are case-sensitive: J means Shift+J.
| Key | What it does |
|---|---|
F1 | Help |
F2 | App theme (colors of the app, not your email) |
F3 | Validate. In the list, Enter jumps to the problem. |
n | New template |
o | Open a template |
p | Preview in your browser |
Shift+E | Export (template.mjml and template.html) |
s | Save now (also keeps a .backup copy) |
/ | Insert a block |
Enter or double-click | Edit the selected block (FormEdit) |
j / k | Move down / up the tree |
g / G | Jump to the top / bottom of the tree |
h / l | Collapse / expand the selected item |
Space | Toggle collapse/expand |
Tab | Switch between the Structure and Details panels |
J / K | Move the selected block down / up |
y | Duplicate the selected block |
d | Delete the selected block right away, with no confirmation (not [HEAD], [BRAND], or [BODY]). Undo with u. |
u | Undo (up to 20 steps) |
U or Ctrl+R | Redo |
C / V | Add / remove a column in the selected section. Every press resets all columns to equal widths. |
c / v | Select the previous / next column |
Ctrl+Q | Quit (q on its own does nothing) |
| Key | What it does |
|---|---|
Tab | Move to the next field |
← / → | Cycle through the choices for a field that has a fixed list (for example, alignment) |
Ctrl+S | Save the block (also updates template.mjml) |
Esc | Cancel without saving |
Ctrl+P | Open the image picker (shows files in images/ only) |
Ctrl+E | Expand a multi-line box (such as text Content) while you type |
A / X | In a list field (such as social Icons or Fonts): add / remove a row |
Enter | In a list field: edit the selected row (Ctrl+S returns to the parent form) |
You can paste text straight into fields. Your terminal's paste works as usual.
To clear a field, press End and then Backspace (in a multi-line box, Ctrl+End first). Ctrl+U doesn't clear fields.
Ctrl+S saves even if a required field is empty. F3 catches missing required fields later.
You rarely need to think about saving. dd_emailforge autosaves template.json about two seconds after each change. Press s to save right away. A manual save also keeps a template.json.backup copy. Ctrl+S in FormEdit also rewrites template.mjml, which keeps the browser preview up to date.
- Email blocks (body level only): email-header (logo), email-hero, email-article, email-cta, and email-footer (company details, unsubscribe link, social links, copyright). These go directly under [BODY], not inside sections.
- Layout: section, column, group, wrapper, hero.
- Content: text, image, button, divider, spacer, social, table, navbar, accordion, carousel.
Where things can go:
- A section holds columns (or groups). A new section starts with no columns: press
Conce for one full-width column, twice for two half-width columns. - Columns and heroes hold content blocks. You can't put a section inside a hero.
- A wrapper holds sections and heroes.
Where a new block lands depends on what's selected when you press /:
| Selected | New block goes… |
|---|---|
| A top-level block (email-header, a section, …) | Right after it |
| [BODY] | At the very end, below the footer |
| A column or hero | Inside it, at the end (content blocks only) |
| A content block (text, image, …) | Right after it |
A content block added while [BODY] or an email block is selected is wrapped in a new section with one full-width column. The easy rule: select the block you want the new one to follow.
- The tree mirrors
template.json(head,brand,body.nodes[]). Block names in the Insert picker match the node types in the file, such asemail-header,mj-section,mj-text. - [BRAND] values become
mj-attributesin the MJML. Ctrl+Sin FormEdit saves and regeneratestemplate.mjml. Autosave writestemplate.jsontwo seconds after a change.- Mouse clicks work in the tree and blueprint. Bracketed paste is supported.
Previous: Install and set up · Next: Build your first email