# Visual mode

> Write in an editor that looks like your published page, with slash commands, a floating toolbar, and editable components.

Visual mode is where the editor opens. You edit the page with the same typography and spacing your readers see, and Typemark writes clean MDX underneath.

<Callout type="info">
  Visual and source mode edit the same file. Switch at any time from the top bar. Typemark keeps every part of the page you didn't touch exactly as it was.
</Callout>

## The top bar

Everything about the page you're on lives in one bar at the top:

| Control | What it does |
|---------|--------------|
| Branch | Shows the branch you're editing, and switches to another or creates one. See [Branches in the editor](https://docs.typemark.dev/editor/branches). |
| **Visual / Source** | Switches between visual and [source mode](https://docs.typemark.dev/editor/source-mode) |
| Language | On a site in [several languages](https://docs.typemark.dev/configuration/languages), opens this page in another one, with each [AI translation's](https://docs.typemark.dev/ai/ai-translations) status |
| Undo and redo | Steps back and forward through your edits (visual mode) |
| Avatars | Shows who else has this page open |
| Save state | Tells you whether your work is saved |
| **Preview** | Opens this page on your live site |
| **Save** | Saves right away. Appears when you have unsaved changes. |
| **Publish** | Puts your saved changes live. Appears when the project uses manual deploy. |

Below the bar, a single banner tells you anything that needs your attention, such as a site that's still offline, a project you can only view, or the branch you're working on.

## Saving

Typemark saves three seconds after you stop typing. Press `Cmd+S` to save right away. The save state shows one of:

- **Saved**: everything is committed to your repo
- **Saving…**: a save is in progress
- **Unsaved changes**: you have edits that haven't been saved yet
- **Couldn't save**: the save didn't go through. Your changes are still in the editor. Try again.

After a save, the page builds in the background. You'll see **Building** while it runs and **Build failed** if something goes wrong. If you try to leave with unsaved changes, Typemark asks first.

## Title and description

The page title and description sit at the top of the page, where readers see them. Click either one to edit it. Typemark stores both in the page's frontmatter and leaves your other frontmatter fields as you wrote them. To edit fields like `icon`, use [source mode](https://docs.typemark.dev/editor/source-mode).

## Slash commands

Type `/` to open the command menu. Keep typing to filter by name: `/call` finds Callout, `/code` finds Code block and Code group.

| Command | Inserts |
|---------|---------|
| Heading 1, 2, 3 | Section headings |
| Bullet list | Unordered list |
| Numbered list | Ordered list |
| Task list | Checklist |
| Code block | Code with syntax highlighting and a language picker |
| Blockquote | Quote block |
| Callout | Info, warning, danger, or tip box |
| Accordion | Collapsible section |
| Steps | Numbered step-by-step guide |
| Tabs | Tabbed content |
| Code group | Tabbed code blocks |
| Card | Card with title, icon, and link |
| Card group | Grid of cards |
| Image | Uploads an image from your computer |
| Video | A YouTube, Vimeo, Loom, or Wistia video, or a video file, from its link |
| Table | Three-by-three table with a header row |
| Divider | Horizontal rule |

The AI commands sit at the bottom of the menu: **Ask AI**, **Continue writing**, **Draft with AI**, **Improve writing**, and **Auto-structure**. You can also press `Space` on an empty line, or `Cmd+J` anywhere, to ask AI. See [AI writing](https://docs.typemark.dev/editor/ai-writing).

## The block handle

Hover over any block to see its handle in the left margin.

- **+** adds a block below and opens the slash menu
- Drag the grip to move the block, including into and out of components
- Click the grip for the block menu: **Turn into**, **Insert block above**, **Insert block below**, **Move up**, **Move down**, **Duplicate**, and **Delete**

Press `Cmd+.` to open the block menu for the block your cursor is in. Deleting a block doesn't ask for confirmation. `Cmd+Z` brings it back.

## Floating toolbar

Select text to bring up the floating toolbar:

- **Bold**, *italic*, and ~~strikethrough~~
- `Inline code`
- Link, with a field for the URL
- **Ask AI** comes first when your project's plan includes [AI writing](https://docs.typemark.dev/editor/ai-writing)

## Editing components

Components render as blocks you edit in place, not as raw code:

- **Callout**: pick the type from the dropdown and add an optional title.
- **Tabs** and **Code group**: add, rename, reorder, and remove tabs from the tab bar.
- **Steps** and **Accordion**: edit the title at the top of each block.
- **Card**: pick an icon, set a title and an optional link.
- **Card group**: choose the number of columns and click **Add card**.
- **Code block**: choose a language from the picker. A **Mermaid** block shows the [diagram](https://docs.typemark.dev/components/diagrams) under the code.
- **Video**: paste a link, or click **Change link** to swap it. See [Videos](https://docs.typemark.dev/components/videos).
- **Table**: select a cell to add or delete rows and columns, or delete the table.

Images get their own toolbar for size and alt text. See [Images](https://docs.typemark.dev/editor/images).

<Callout type="warning">
  If a page uses a component the visual editor doesn't know, it shows as a read-only block and its source is saved exactly as written. Edit it in source mode.
</Callout>

### Pages that won't open visually

If the visual editor can't open a page safely, it opens in source mode instead, with a banner that says why. Fix the MDX there and switch back to **Visual**. The visual editor never saves over a page it couldn't load.

## The sidebar

The sidebar has two views:

- **Navigation** shows your site's tabs, groups, and pages, the way readers see them. Drag pages to reorder them or move them between groups. Hover over a group and click **+** to add a page. Use **Add group** and **Add tab** to grow the structure, and the **…** menus to rename or delete groups and tabs.
- **Files** shows every file in your repo. Click an `.mdx` or `.md` file to open it.

Changes in the Navigation view save to `typemark.json`. See [Navigation](https://docs.typemark.dev/configuration/navigation).

## Working together

When teammates have the same page open, their avatars appear in the top bar. If someone saves the page while you're on it, you'll see a note saying so.

Typemark doesn't merge simultaneous edits. If you save after someone else, it stops and asks you to reload instead of overwriting their work. Reloading shows their version and drops your unsaved changes, so copy anything you want to keep first.

## Read-only

Viewers and projects that are locked on the Free plan open in read-only mode. The save state shows **Read-only** and the banner explains why.
