# 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

| Browser | Support status |
|---------|---------------|
| Chrome (desktop) | Supported — Manifest V3 |
| Firefox (desktop) | Supported — Manifest V3 / MV2 hybrid |
| Safari | Not supported (see [#534](https://github.com/adam-p/markdown-here/issues/534), [#686](https://github.com/adam-p/markdown-here/issues/686)) |
| Firefox for Android | Not supported (see [#883](https://github.com/adam-p/markdown-here/issues/883)) |

> [!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

| Option | Default | Description |
|--------|---------|-------------|
| **Main CSS** | Built-in `default.css` | CSS applied to all rendered Markdown output. |
| **Syntax Highlighting CSS** | `github.css` | CSS theme for fenced code block highlighting. |
| **Math rendering** | Off | Renders `$inline$` and `$$block$$` LaTeX via codecogs.com. |
| **Forgot-to-render check** | Off | Prompts before sending if unrendered Markdown is detected in Gmail or Fastmail. Requires host permission. |
| **GFM line breaks** | On | Single newlines become `<br>`. Disable for standard paragraph behavior. |
| **Header anchors** | Off | Adds named anchors to headings so fragment links like `#heading-name` work. |

> [!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

| Element | Syntax |
|---------|--------|
| Headings | `# H1` through `###### H6` |
| Bold | `**text**` or `__text__` |
| Italic | `*text*` or `_text_` |
| Strikethrough | `~~text~~` |
| Inline code | `` `code` `` |
| Fenced code block | ```` ```lang ```` … ```` ``` ```` (syntax-highlighted) |
| Indented code block | 4-space indent |
| Blockquote | `> text` |
| Ordered list | `1. item` |
| Unordered list | `- item`, `* item`, `+ item` |
| Horizontal rule | `---` or `***` |
| Link | `[text](url)` — bare URLs get `https://` prepended |
| Image | `![alt](url)` |
| Table | GFM pipe syntax |
| Math (LaTeX) | `$inline$` and `$$block$$` — requires math option enabled |

> [!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:
   ```text
   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:

```text
```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](https://github.com/adam-p/markdown-here/issues/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:

```css
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](https://github.com/adam-p/markdown-here/issues/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](https://github.com/adam-p/markdown-here/issues/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](https://github.com/adam-p/markdown-here/issues/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](https://github.com/adam-p/markdown-here/issues/534) and [#686](https://github.com/adam-p/markdown-here/issues/686) for history.

---

_Generated May 2026 from adam-p/markdown-here at e00d005. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._