# Formatting Methods

This page covers the `MDEditor` methods that insert Markdown formatting: where they insert, how selections are handled, and when they emit HTML tags instead of Markdown markers.

## Insert Position

| Editor state | Behavior |
|---|---|
| Caret is inside the editor (with or without a selection) | Inserts at the caret; a selection is wrapped, and newlines inside it are removed |
| Caret was never placed | Appends to the last row; if the last row is empty, that row is rewritten |

Afterwards the caret moves inside the markers and an undo entry is recorded; with `autosave` truthy the preview is updated too.

## Markdown or HTML

The first argument of the inline methods is an event object, used to detect a held modifier key:

| `event.metaKey` or `event.ctrlKey` | Output |
|---|---|
| False (toolbar click, or `{}` passed) | Markdown markers, e.g. `**text**` |
| True (triggered by a shortcut) | HTML tags, e.g. `<b>text</b>` |

So `Cmd/Ctrl+B` inserts `<b></b>` while the toolbar button inserts `****`. These methods read `event.metaKey`, so calling them without an argument throws a `TypeError`; pass `{}` from code.

## Inline Formatting

| Method | Markdown | HTML (modifier) |
|---|---|---|
| `bold(event)` | `**text**` | `<b>text</b>` |
| `italic(event)` | `*text*` | `<i>text</i>` |
| `strikethrough(event)` | `~~text~~` | `<s>text</s>` |
| `underline(event)` | `<u>text</u>` | `<u>text</u>` |
| `marker(event)` | `==text==` | `<mark>text</mark>` |
| `sup(event)` | `^text^` | `<sup>text</sup>` |
| `sub(event)` | `~text~` | `<sub>text</sub>` |
| `code(event)` | `` `text` `` | `<code>text</code>` |

`underline()` has no Markdown form and always emits `<u>`. When the selection spans several rows, `code()` instead inserts a ` ``` ` row above and below it to form a code block.

## Headings

```javascript
editor.heading({}, 2);
```

| Parameter | Description |
|---|---|
| `event` | As above; with a modifier the output is `<h2></h2>` |
| `num` | `1`-`6` map to `#`-`######`; `0` removes an existing `#` prefix |

With a selection, the row's existing leading `#` and whitespace are stripped before the new level is applied.

## Block Formatting

| Method | Prefix per row | Without a caret |
|---|---|---|
| `blockquote()` | `> ` | Appends a `> ` row |
| `ul()` | `- ` | Appends a `-` row |
| `ol()` | `1. ` | Appends a `1.` row |

With several rows selected, every row gets the prefix; `ol()` does not increment numbers, so every row is `1.` and the rendered `<ol>` numbers them.

## Links and Images

| Method | Output | Ignored when |
|---|---|---|
| `link(title, href)` | `[title](href)` | Both `title` and `href` are empty |
| `image(src, alt, title)` | `![title or alt](src)` | `src` is empty |

`image()` puts `title` inside the brackets and falls back to `alt` when it is empty; it never writes a Markdown `"title"` attribute. When inserting at the caret, a trailing space is added.