# Images

> Add images to your pages by dragging, pasting, or using the slash command.

Images you add in the editor go into the `images/` folder of your project's Git repo, so they travel with your docs.

## Adding images

There are three ways to add an image in visual mode:

<Steps>
  <Step title="Drag and drop">
    Drag an image file from your computer into the editor.
  </Step>
  <Step title="Paste">
    Copy an image or take a screenshot, then paste it into the editor with `Cmd+V`.
  </Step>
  <Step title="Slash command">
    Type `/image` and press `Enter` to pick an image from your computer.
  </Step>
</Steps>

Typemark uploads the file and adds the image to the page. If an upload fails, a message tells you why, for example when the file type isn't supported.

## Supported formats

| Format | Extension | Good for |
|--------|-----------|----------|
| PNG | `.png` | Screenshots and diagrams |
| JPEG | `.jpg`, `.jpeg` | Photos |
| GIF | `.gif` | Short animations |
| SVG | `.svg` | Logos and vector graphics |
| WebP | `.webp` | Smaller files at similar quality |

## Size and alt text

Click an image to bring up its toolbar:

- **S**, **M**, and **L** set the width to 320, 480, or 720 pixels. **Original** removes the width.
- Drag the handle on the image's edge to set any other width.
- The alt text field describes the image for screen readers and search engines.
- The delete button removes the image from the page. The file stays in your repo.

<Callout type="tip">
  Always add alt text. It makes your docs accessible and helps search engines understand your images.
</Callout>

An image without a width is saved as Markdown. An image with a width is saved as an `<img>` tag:

```mdx
![Dashboard overview](/images/dashboard-overview.png)

<img src="/images/dashboard-overview.png" alt="Dashboard overview" width="480" />
```

## How images are stored

When you add an image, Typemark:

1. Saves the file to `images/` in your repo, with a lowercase file name
2. Commits it, and pushes it to GitHub if your project is connected
3. Adds the image to your page

<Callout type="warning">
  Uploading a file with the same name as an existing image replaces that image everywhere it's used.
</Callout>

In source mode, images you uploaded in the editor point at the editor's copy of the file, a path that starts with `/projects/`. Typemark rewrites that path on your published site, so you don't need to change it.

## Referencing images by hand

When you write image paths yourself, use the path from the root of your docs. If the file is at `images/setup-wizard.png`, reference it as `/images/setup-wizard.png` from any page, however deep the page is.

<Accordion title="Directory structure example">
  ```
  my-docs/
  ├── typemark.json
  ├── introduction.mdx
  ├── guides/
  │   └── getting-started.mdx
  └── images/
      ├── logo-light.svg
      ├── logo-dark.svg
      ├── setup-wizard.png
      └── dashboard-overview.png
  ```

  From `guides/getting-started.mdx`, the setup screenshot is still `/images/setup-wizard.png`.
</Accordion>
