Markdown Here — User Guide

1. Quick Start

Markdown Here is a browser extension for Chrome and Firefox that lets you write emails and web forms in Markdown, then render them to styled HTML in-place with a single keystroke. Type Markdown in Gmail, Fastmail, or any contenteditable field, hit Alt+Shift+M, and your formatting appears instantly. Hit the same shortcut again to revert to raw Markdown and keep editing.

Key features:

• Toggle Markdown rendering in any rich-text compose field
• Keyboard shortcut (Alt+Shift+M), toolbar button, and right-click context menu
• Partial-selection rendering — render only highlighted text
• Syntax-highlighted fenced code blocks via highlight.js (100+ themes)
• Optional LaTeX math rendering (requires internet; uses codecogs.com API)
• Auto-excludes email signatures (-- separator)
• "Forgot to render" safety prompt on Gmail and Fastmail
• Fully customizable CSS for rendered output and syntax themes
• Settings synced across devices via browser sync

Prerequisites: Chrome or Firefox desktop browser.

Install from your browser's extension store, then open Gmail, type some Markdown in the compose body, and press Alt+Shift+M.

Tip

You can also click the Markdown Here toolbar button or right-click the compose area and choose Markdown Here Toggle from the context menu.

2. Installation

System requirements

Warning

Safari support was discontinued and the extension was removed from the Mac App Store. There is no current Safari-compatible version.

Install from browser store

Chrome

1. Visit the Markdown Here listing on the Chrome Web Store.
2. Click Add to Chrome.
3. Confirm permissions when prompted.

Firefox

1. Visit the Markdown Here listing on Firefox Add-ons (AMO).
2. Click Add to Firefox.
3. Confirm permissions when prompted.

Post-install verification

After installation the Markdown Here icon appears in your toolbar. Open Gmail, compose a new message, type **bold**, and press Alt+Shift+M. The text should become bold.

Important

On first install the extension automatically opens the Options page. On version upgrades a small popup appears in the toolbar — click it to see what changed.

3. Configuration

Open the Options page by:

• Clicking the Markdown Here toolbar icon → gear/options link, or
• Right-clicking the toolbar icon → Options.

Available options

Note

The Options page includes a live preview pane on the right. Edit CSS and watch the preview update in real time before saving.

Customizing rendered output

The Main CSS field contains the full stylesheet applied at render time. Change fonts, colors, spacing, or heading sizes — anything CSS can express. The reset button under the field restores the built-in default.

Choosing a code theme

The Syntax CSS field controls the highlight.js theme for code blocks. The extension ships with the full highlight.js theme library. Replace the field contents with any theme's CSS to change the appearance.

Tip

Settings are stored in chrome.storage.sync and sync automatically across all signed-in browser profiles on multiple devices.

4. Core Usage

Rendering Markdown

1. Open a rich-text field (Gmail compose, Fastmail compose, etc.).
2. Write content using Markdown syntax.
3. Click inside the field — or select a specific region to render only that part.
4. Trigger rendering:
   • Keyboard: Alt+Shift+M
   • Toolbar button: click the Markdown Here icon
   • Context menu: right-click → Markdown Here Toggle

Rendering converts Markdown to styled HTML in-place. The original Markdown is saved invisibly in the DOM for revert.

Reverting to Markdown

Press Alt+Shift+M (or use toolbar/context menu) while the cursor is inside a rendered block. The HTML is replaced with your original Markdown text.

Note

Revert works on the current rendered block. Place your cursor inside the block you want to revert. Content inside <blockquote> elements (quoted replies) cannot be reverted — this is intentional so you don't accidentally modify received email.

Partial-selection rendering

Highlight a specific portion of text before triggering Markdown Here. Only that selection renders, leaving the rest untouched. Useful for mixing a Markdown table or code block with plain surrounding text.

Email signature exclusion

The extension automatically excludes email signatures from rendering. A signature is identified as content starting with -- (two hyphens then a space, or a non-breaking space) on its own line. Everything from that line onward is left as-is.

Forgot-to-render prompt

When enabled in Options, Markdown Here intercepts send attempts in Gmail and Fastmail. If it detects unrendered Markdown patterns (backticks, bold markers, bullet lists, or LaTeX), a prompt appears asking whether to go back and render or send anyway.

Important

The forgot-to-render check requires host permission for mail.google.com and fastmail.com. The extension requests this permission when you enable the option. You can revoke it by disabling the option.

Supported Markdown elements

Tip

Links with no URL scheme (e.g., [example](example.com)) automatically get https:// prepended during rendering so they are clickable in the rendered email.

5. Common Tasks

Send a formatted email in Gmail

1. Open Gmail, click Compose.
2. Write the email body in Markdown:

   Hi team,
   
   Here's the **weekly summary**:
   
   - Task A: done
   - Task B: in progress
   
   See the [dashboard](example.com) for details.
   

3. Press Alt+Shift+M to render.
4. Review the output; press Alt+Shift+M again to revert and edit if needed.
5. Send.

Tip

Write the full email first, then render at the very end. You can revert and re-render multiple times without data loss.

Insert a syntax-highlighted code block

In the compose field, write:

```python
def greet(name):
    return f"Hello, {name}!"

After rendering the block displays with syntax highlighting according to the active Syntax CSS theme.

> [!NOTE]
> Code blocks without a language tag render as unstyled monospace blocks without syntax coloring.

### Render only a portion of a message

1. Select the specific lines you want to render.
2. Press **Alt+Shift+M**.

Only the highlighted region renders. Non-selected content stays as plain text.

### Enable and use LaTeX math

1. Open Options, check **Enable math rendering**, save.
2. Use `$x^2 + y^2 = r^2$` for inline math or:
   ```text
   $$\frac{a}{b} = c$$

for a block equation. 3. Press Alt+Shift+M to render.

Warning

Math rendering sends LaTeX expressions to latex.codecogs.com to generate PNG images. An internet connection is required at render time. Offline math rendering is not supported (see #874).

Customize rendered appearance

1. Open Options.
2. Edit the Main CSS field (the preview updates live).
3. Click Save when satisfied.

Example — change heading color:

h1, h2 {
  color: #2c5282;
  border-bottom: 2px solid #e2e8f0;
}

6. Troubleshooting

Error: Alert says the field can't be rendered

Cause: The focused element is a plain-text <textarea> or non-editable element, not a rich-text (contenteditable) field.

Solution:

1. Ensure Gmail (or whichever app) is in rich-text / HTML compose mode.
2. In Gmail look for a formatting toolbar at the bottom of compose — if it's absent, switch from plain-text mode.

Prevention: Use rich-text mode in your email client.

Rendered output loses formatting when the email is sent

Cause: Some web clients strip HTML attributes on send (reported in #972 for Gmail's HTML/DIV handling).

Solution:

1. Render as the very last step before clicking Send.
2. Do not click inside the rendered area after rendering — editing can corrupt the internal state.

LaTeX math blocks are not rendering

Cause: Math rendering is disabled by default, or the codecogs.com service is unreachable.

Solution:

1. Open Options and confirm Enable math rendering is checked.
2. Verify internet connectivity.
3. Check LaTeX syntax — wrap inline math in $...$ and block math in $$...$$.

Single newlines are creating unwanted line breaks

Cause: GFM line breaks is enabled by default, treating every newline as a <br>.

Solution: Open Options and uncheck GFM line breaks. After disabling, a blank line is required between paragraphs (standard Markdown behavior). See #338.

"Forgot to render" prompt never appears

Cause: The feature is disabled by default, or the required host permission was not granted.

Solution:

1. Open Options → enable Forgot-to-render check.
2. Grant the mail.google.com / fastmail.com host permission when prompted.
3. Note: this prompt only appears in Gmail and Fastmail; other clients are not supported.

Signature content is being rendered

Cause: The auto-exclude logic looks for -- (dash dash space) on its own line. If your signature uses a different separator it is not recognized.

Solution: Ensure your signature starts with exactly -- (two hyphens, a space) on its own line above the signature text.

7. FAQ

Q: Does Markdown Here work outside of Gmail?

Yes. Any web page with a contenteditable rich-text field works — Fastmail, Outlook.com (web), forum editors, project management tools, etc.

Q: Does it work in Google Docs?

No. Google Docs uses a proprietary editing model that is not based on standard contenteditable. Integration has been requested (#28) but is not implemented.

Q: Can I change the keyboard shortcut?

Yes. In Chrome: go to chrome://extensions/shortcuts and reassign the Markdown Here shortcut. In Firefox: Add-ons Manager → Manage Extension Shortcuts.

Q: How can I preview how my CSS will look before saving?

The Options page includes a live preview pane. Edit the Main CSS field and the preview updates immediately.

Q: Can I undo a render with Ctrl+Z?

Pressing Alt+Shift+M again is the reliable way to revert. Browser undo (Ctrl+Z / Cmd+Z) may work in some clients but is not guaranteed.

Q: Is my Markdown sent to any external server?

Only if math rendering is enabled. LaTeX expressions are sent to latex.codecogs.com to generate images. All other rendering happens entirely in your browser — no Markdown text leaves your machine.

Q: Settings are not syncing to my other browser

Settings sync via chrome.storage.sync. Confirm you are signed into the same browser profile on both machines and that browser sync is enabled for extension data.

Q: Is Safari supported?

No. Safari support was removed due to browser API incompatibilities. See #534 and #686 for history.