# Editing Documents

> Edit HTML and Markdown notes in place — click and type, the slash menu, the formatting toolbar, keyboard shortcuts and moving blocks.

Source: https://docs.docgraph.app/editing/documents/

DocGraph documents are real HTML files, and the editor works directly on them — click into any paragraph, heading, or list and type. The experience is designed to feel like a native notes app.

## The basics [!both]

- **Click and type.** The caret goes where you click; edits commit automatically.
- **Enter** continues lists, splits paragraphs, and exits a list when pressed on an empty item — the way you'd expect from apps like Notion or Obsidian.
- **Shift+Enter** starts a new line inside the same paragraph or list item, without splitting it. In a `.md` note this works in paragraphs; in a list item or heading it just leaves the block.
- **Backspace** at the start of a block merges it with the previous one; **Delete** at the end of a block pulls the next one up.
- **Slash menu.** Type `/` to insert lists, code blocks, dividers, tables, diagrams and more — see [Diagrams, Callouts & Code](https://docs.docgraph.app/editing/blocks/). Headings come from typing `# `, not from this menu.

## Formatting [!partial]

Select text and a toolbar appears — bold, italic, inline code, strikethrough, underline, text colour, highlight, links, and an [AI menu](https://docs.docgraph.app/ai/in-your-documents/#rewrite-a-selection). The usual shortcuts work too (`⌘B`, `⌘I`, `` ⌘` ``, `⌘⇧X` for strikethrough, `⌘⇧H` for highlight). Typing `~~text~~` also strikes it through.

In a `.md` note the toolbar keeps bold, italic, inline code, strikethrough (written `~~text~~`), highlight (written `==text==`, one colour), links and the AI menu; underline and text colour are HTML-only, because Markdown has no syntax for them.

In an HTML note, when the selection is a single run of text, the toolbar also has **Encrypt this passage** (the key icon), which replaces it on disk with an encrypted marker — see [Encryption](https://docs.docgraph.app/privacy/encryption/#encrypt-one-passage).

Paste a URL over selected words and they become a link to it, in either kind of note. `⌥↑` / `⌥↓` move the block your cursor is in up or down — a heading takes its section with it.

### Colours [!html]

**Text color** and **Highlight** each open a palette of eight swatches. A **Default** chip in the same popover clears the colour again.

| Text color | Highlight |
|---|---|
| Red, Orange, Amber, Green, Teal, Blue, Violet, Pink | Yellow, Green, Blue, Pink, Orange, Violet, Teal, Gray |

Text colours are saturated so they read on a light or dark page; highlights are pastels so body text stays legible on top. Once a run is underlined, an **Underline color** control appears beside them, with the same eight text colours. The same three palettes are in the right-click menu (below).

### Keyboard shortcuts [!partial]

With text selected:

| Shortcut | Action |
|---|---|
| `⌘B` / `⌘I` | Bold / italic |
| `⌘U` | Underline (HTML notes) |
| `` ⌘` `` | Inline code |
| `⌘⇧X` | Strikethrough |
| `⌘⇧H` | Highlight (toggles the default colour) |
| `⌘L` | Add or edit a link — opens the link prompt (with an optional **Link type** field, in HTML and Markdown notes). On an existing link the prompt has **Apply** and **Remove**; **Remove** unlinks the text and keeps the words |
| `⌘\` | Clear formatting on the selection (HTML notes) |

With nothing selected, `⌘B`, `⌘I` and `` ⌘` `` insert the Markdown delimiters at the cursor, and `⌘L` inserts `[]()` with the cursor inside, ready to type.

With the cursor anywhere in a block:

| Shortcut | Action |
|---|---|
| `⌘⌥0` | Turn the block into a paragraph |
| `⌘⌥1` to `⌘⌥6` | Turn the block into a heading of that level |
| `⌘⌥7` / `⌘⌥8` | Turn a paragraph or heading into a bulleted / numbered list |
| `⌥↑` / `⌥↓` | Move the block up or down |
| `Tab` / `⇧Tab` | Indent / outdent a list item |
| `⌘Enter` | Tick or untick the to-do the cursor is in |
| `⌘⇧P` | Open the [properties window](https://docs.docgraph.app/editing/block-properties/) for the line (HTML notes) |
| `⌘F` | Find in the note — see [below](#find-in-a-note) |
| `⌘A` | Select progressively: the block's text, then the enclosing container, then the whole page |
| `⌘Z` / `⌘⇧Z` | Undo / redo |
| `⌘S` | Save now (see [Autosave](#autosave-and-undo)) |

## Changing a block's type [!both]

Select some text and the leftmost control in the selection toolbar is a block picker: **Paragraph** and **Heading 1** to **Heading 6**, each labelled with its `⌘⌥0`–`⌘⌥6` shortcut. The right-click menu has the same list under **Turn into**. With nothing selected, the shortcuts act on the block the cursor is in. Headings come from typing `# ` as well — the slash menu doesn't list them.

## Moving and deleting blocks [!html]

Hover a block and a small handle appears in the left margin. **Drag** it to reorder — a heading carries its whole section with it, and a line marks where the block will land. Hovering the handle shows **Added** and the time when the line was [time-stamped](https://docs.docgraph.app/editing/block-properties/#recording-when-a-line-was-written). **Click** it (without dragging) for a menu:

- **Properties…** opens the block's [properties](https://docs.docgraph.app/editing/block-properties/).
- **Move to note…** files the line into another note — see [below](#move-a-line-to-another-note).
- **Delete** removes the block, or the whole section when the block is a heading.

### Move a line to another note [!html]

Click a line's handle and choose **Move to note…**. A picker lists the notes you've recently filed or captured into; type to search other note names. Pick one and the line moves to the **end** of that note, marked `filed: true`, and the note joins your recent targets. The search lists HTML notes only, never the page you're on. Table, chart and query blocks don't have the entry. If the page changed underneath you, nothing is written and a message says why. Two pages change, so undoing it takes one ⌘Z in each.

## Pasting [!partial]

In an HTML note:

- **Web content** — copied from a page, an email or a Google Doc — keeps its structure. Headings, lists, quotes, code, tables, images and links arrive as the matching blocks, not as one styled blob.
- **Plain text** is inserted as written. If it looks like Markdown (it starts a line with `#`, `-`, `1.`, `>`, a fence or a `|` table) it is converted to blocks. Otherwise each line break is kept as a line break inside one paragraph, and blank lines separate paragraphs.
- **Inside a code block**, the text goes in verbatim — no conversion.
- **A URL pasted over selected words** turns them into a link.
- **An image** is saved into the vault — see [Images](https://docs.docgraph.app/editing/images/).

In a Markdown note:

- **Web content** with links, images, tables or several blocks is converted to Markdown as it lands — headings, lists and quotes become their Markdown forms, and links are kept as `[label](url)`. A one-line paste keeps its bold, italic, code, strikethrough and links the same way.
- **A URL pasted over selected words** turns them into a `[label](url)` link.
- **An image** is saved into the vault and written as ``.

### Copying and dragging text [!partial]

Copying from a note keeps its formatting, so it pastes as formatted text into other apps and as plain text where formatting isn't accepted; a whole heading copied and pasted back stays a heading. Pasted text that carries a text, highlight or underline colour keeps it in an HTML note.

Drag selected text to move it within the page; hold `⌥` while dropping to copy it instead.

## Right-click menu [!partial]

Right-click in the page for a menu that adapts to what's under the pointer:

- Over a selection, a row of **bold**, *italic*, underline, strikethrough, code and link buttons, then **Turn into**, **Text color**, **Highlight**, **Underline color** (only on underlined text) and, on HTML notes, **Encrypt this passage**. On a `.md` note the colour and underline entries are left out.
- **Cut** (when the selection can be cut), **Copy** (when there is one) and **Paste**.
- **Dictate here**, when [voice](https://docs.docgraph.app/voice/overview/) is set up.
- Over a selection, with [AI](https://docs.docgraph.app/ai/setup/) on: **Ask about this**, **Explain this**, **Rewrite this** and **Make tasks from this**.
- **Copy link to block**, which gives the block an id and copies a [link to it](https://docs.docgraph.app/editing/links-and-tags/#linking-to-one-block); hold `⌥` to copy it as a Markdown link.
- **Remove chart**, **Remove table**, **Remove callout**, **Remove divider**, **Remove code block**, **Remove list** or **Remove blank line**, when you right-clicked one of those.

## Markdown shortcuts while typing [!both]

Markdown shorthand converts as you type. In a `.md` note what you type already *is* the Markdown, so the line simply renders in place. The line-start triggers work at the start of a paragraph or heading, and fire when you type the space after them. A line holding only `---` or `***` becomes a divider:

| Type | You get |
|---|---|
| `# ` to `###### ` | A heading of that level |
| `> ` | A quote |
| `- ` or `* ` | A bulleted list |
| `1. `, `3. ` (any number) | A numbered list |
| `[ ] `, `[] `, `[x] ` (optionally after `- ` or `* `) | A to-do item, unchecked or checked |
| ` ``` ` then a space | A code block |
| `---` or `***` | A [divider](https://docs.docgraph.app/editing/blocks/#dividers) |

Inline spans convert when you type the closing delimiter: `**bold**` or `__bold__`, `*italic*` or `_italic_`, `~~strike~~`, `` `code` ``, `==highlight==`, and `[label](url)` for a link (`www.example.com` as the target becomes `https://www.example.com`). The underscore forms don't fire in the middle of a word, so `snake_case_name` stays as typed, and a backslash before the opening delimiter cancels the conversion. A bare `https://…` or `www.…` address is drawn as a link; ⌘-click opens it.

**Auto-pair.** When you type an opening `` ` ``, `*`, `**`, `==` or `~~`, a faint closing mark appears after the cursor. Type your text, then the closer, and it formats. Press **Esc** to keep the mark as plain text. It's on by default; turn it off in **Settings → General → Editor → Typing → Auto-pair markdown syntax**.

**Changed your mind? Press Backspace.** Right after a conversion, **Backspace** gives you back what you typed. In an HTML note that works for a mark (`` `npm` `` becomes a code chip; Backspace turns it back into `` `npm` ``), for a prefix typed on a new line (`- `, `1. `, `[ ] `, `> `), and for a prefix typed at the start of an existing paragraph that turned it into a heading, list item, to-do or quote. The text you got back stays text when you keep typing or leave the line. In a `.md` note, Backspace at the start of a new line that just became a quote, bullet, number, heading or checkbox removes that and keeps your words.

**Wrap a selection.** Select some text and type `` ` ``, `*`, `=` or `~` to wrap it in code, italic, highlight or strikethrough. It works in HTML and Markdown notes, follows the Auto-pair setting, and does nothing inside code.

## Lists: indent, outdent and exit [!both]

**Enter** at the end of a list item starts the next one; on an empty item it ends the list. Pressing **Tab** in a list item indents it under the item above, and **Shift+Tab** moves it back out — at the top level it turns the item into a plain paragraph. **Backspace** at the start of an item outdents it, or removes its bullet at the top level.

## Live Preview: seeing the syntax at the caret [!both]

**Live Preview** shows formatted text as formatted — until your cursor enters it, when that span reveals its raw syntax so you can edit the markup directly — `**bold**`, or `[label](href)` for a link; a heading or quote shows its `#` / `>` prefix while the cursor is in it. Move away and it renders again; delete a delimiter and the span goes back to plain text. To keep formatted text as it is at the caret, turn off **Reveal syntax at the caret** in **Settings → General → Editor → Live Preview**, then reopen the file.

## Spelling [!both]

The editor uses the Mac's own spell checker: misspelled words get a red underline as you type, and right-clicking one offers suggestions. **Edit → Check Spelling While Typing** in the menu bar turns it off for the whole app. Autocorrect never changes text in a note; it only fixes typos in plain fields such as the AI chat box (**Edit → Correct Spelling Automatically** turns it off). For an AI spelling pass over a whole page, see [AI in Your Documents](https://docs.docgraph.app/ai/in-your-documents/).

## Find in a note [!both]

Outside `<>Source`, `⌘F` opens a find bar over the page and highlights every match. **Enter** and **Shift+Enter** step to the next and previous match; **Esc** closes the bar. In `<>Source`, `⌘F` opens the source editor's own find / replace instead (below). To search every note, use `⌘K`.

## Inserting things [!partial]

Type `/` for the block menu: [diagrams, callouts, code blocks and tasks](https://docs.docgraph.app/editing/blocks/), [tables and charts](https://docs.docgraph.app/tables-charts/overview/), [whiteboards](https://docs.docgraph.app/whiteboards/basics/), and [AI blocks](https://docs.docgraph.app/ai/in-your-documents/). Type `[[` to [link to another note](https://docs.docgraph.app/editing/links-and-tags/), `#` for a [tag](https://docs.docgraph.app/editing/links-and-tags/#tags), or `@@` for a [date](https://docs.docgraph.app/editing/links-and-tags/#dates). Paste or drag in [an image](https://docs.docgraph.app/editing/images/).

## Typing suggestions [!html]

With AI on and **Suggest completions while editing** switched on in **Settings → AI → Chat & index** (it's off by default, and needs a chat model), pausing at the end of a paragraph or heading shows a grey continuation after the cursor. **Tab** accepts it; **Esc** or typing on dismisses it, and nothing is written unless you accept. See [Suggestions while you type](https://docs.docgraph.app/ai/in-your-documents/#suggestions-while-you-type).

## The two editing surfaces [!both]

Most of the time you edit the rendered page directly — that's everything above. The toolbar's **`<>Source`** button (`⌘⇧E`) switches to the raw file in a full code editor with syntax highlighting, which is the escape hatch for anything the inline editor won't touch: a stray wrapper, hand-written HTML, a marker you want to delete outright.

Two tools live in that source view:

- **Find / replace** (`⌘F`) — search and replace within the open file; `⌘G` / `⌘⇧G` jump to the next / previous match. This is *in-document* search; `⌘K` searches the whole vault.
- **Format document** (`⇧⌥F`) — tidies the file's indentation and structure. It's a plain reformat with no AI involved, unlike [Beautify](https://docs.docgraph.app/ai/in-your-documents/#restyle-a-page), which rewrites styling with a model.

`<>Source` is available for HTML and Markdown. Other formats are [read-only](https://docs.docgraph.app/formats/overview/) and the button is disabled.

## The document toolbar

The bar above the document holds everything that acts on the open file, in one row: back and forward at the far left, then the file's path, then the actions, with the Edit / `<>Source` toggle pinned to the end. Which buttons appear depends on the file's format, the mode you're in, and whether [AI](https://docs.docgraph.app/ai/setup/) and [voice](https://docs.docgraph.app/voice/overview/) are set up — a `.pdf` has no Source button, and the AI button is absent when AI is off.

*[Screenshot: DocGraph with a project note open. One page bar runs across the top of the page: back and forward arrows, the path (projects › Atlas — Offline Sync), then the reading options, focus mode, the ⋯ menu and the Edit / Source switch at the right.]*

### In the editing view

| Control | Shown when | Covered in |
|---|---|---|
| **‹ ›** back / forward | Always — walks the links you followed (`⌘[` / `⌘]`) | [Finding Your Way Around](https://docs.docgraph.app/getting-around/overview/) |
| Path (vault › folder › file) | Always — click a folder or the file to reveal it in the sidebar | [Finding Your Way Around](https://docs.docgraph.app/getting-around/overview/) |
| **Lock / Unlock** | The file is encrypted | [Encryption](https://docs.docgraph.app/privacy/encryption/) |
| **Unlock *n*** / **Lock** passages | The page contains [encrypted passages](https://docs.docgraph.app/privacy/encryption/) | [Encryption](https://docs.docgraph.app/privacy/encryption/) |
| **Scripts on / off** | The page contains `<script>` | [Privacy & Security](https://docs.docgraph.app/privacy/overview/) |
| **Aa** **Display & reading** | Outside Source | [Reading & Presenting](https://docs.docgraph.app/editing/reading/#reading-preferences) |
| **✦ AI** menu — **Summarize this file**, **Check spelling**, **Beautify this page** (HTML only) | AI enabled | [AI in Your Documents](https://docs.docgraph.app/ai/in-your-documents/) |
| **Voice** (mic icon) — **Dictate here**, **Listen to page**; with voice off, **Turn on voice…** | Always, except on boards | [Voice](https://docs.docgraph.app/voice/overview/) |
| **Focus mode** (`⌘.`) | Always | [Reading & Presenting](https://docs.docgraph.app/editing/reading/#focus-and-presentation) |
| **⋯** more actions | Outside Source — see below | |
| **Edit / `<>Source`** (`⌘E` / `⌘⇧E`) | Always (Source is disabled on read-only formats and on a locked encrypted file) | Above |

The **⋯** menu always holds the actions you reach for less often:

| Item | Covered in |
|---|---|
| **Export to PDF** | [Reading & Presenting](https://docs.docgraph.app/editing/reading/#export-to-pdf) |
| **Encrypt this file** | [Encryption](https://docs.docgraph.app/privacy/encryption/) |
| **Collapse all sections** / **Expand all sections** (with [collapsible headings](https://docs.docgraph.app/editing/blocks/#collapsible-sections) on) | [Diagrams, Callouts & Code](https://docs.docgraph.app/editing/blocks/#collapsible-sections) |
| **Full width** / **Center content** | [Reading & Presenting](https://docs.docgraph.app/editing/reading/) |

**Collapse all sections** and **Full width** are also rows in **Display & reading**.

### In `<>Source`

Switching to the source editor adds the two tools that act on raw markup, and drops the ones that need a rendered page — no export, no reading controls, no Beautify.

| Control | Covered in |
|---|---|
| **Find / replace** (`⌘F`) | Above |
| **Format document** (`⇧⌥F`) | Above |
| **• modified** | Below — shown while there are unsaved edits |

### When the window is narrow

Buttons fold into the `⋯` menu rather than being dropped, by priority — Full width and the reading controls go first, Find and focus mode hold on longest. Everything in the menu keeps the state and behaviour it had in the bar. Back / forward, the Edit / Source pill, the security controls and the Voice button never collapse.

## Autosave and undo [!both]

Everything autosaves — after a short idle pause, and on demand with <kbd>⌘S</kbd> (which simply flushes any pending edit). Autosave is silent: there is no "Saving…" or "Saved" indicator. The one state that ever shows in the title bar is a red **Not saved**, when the last change couldn't be written. Source mode also marks unsaved edits with a **• modified** note in the toolbar. Undo (<kbd>⌘Z</kbd>) works across your editing session.

### When a save fails

If an inline edit can't be saved — for example because the file changed on disk underneath you — DocGraph doesn't discard what you typed. A toast appears at the bottom right, **This edit wasn't saved — your text is safe here**, showing the reason and a preview of your text, with three buttons:

- **Reapply** tries the write again against the file as it is now.
- **Copy text** puts your text on the clipboard so you can paste it anywhere.
- **Open source** switches to `<>Source` so you can merge it by hand.

The toast dims after a while but stays until you dismiss it with **×**.

### Saving in `<>Source`

In `<>Source` your edits stay in the editor until you press `⌘S`. If the file changed on disk since you opened it there, `⌘S` first asks: *&lt;name&gt; has been modified outside DocGraph*.

- **Cancel** does nothing; your edits stay unsaved. **Esc** picks this.
- **Reload from disk** throws your edits away and loads the file as it is now.
- **Overwrite** writes your version over the one on disk.

**Enter** picks none of them, so you can't overwrite by accident. If a save fails, a **Save failed** notice with the reason shows at the bottom right for a few seconds; your edits stay unsaved, so you can press `⌘S` again.

Closing the window while `<>Source` edits are unsaved asks *You have unsaved changes in N file(s)* and lists them. **Keep editing** (the default; **Enter** and **Esc** pick it) leaves the window open; **Discard** closes it and the edits are lost. With **Keep running in the menu bar** on, closing only hides the window, so nothing is lost and nothing is asked.

### Save as…

In `<>Source`, `⌘⇧S` asks for a new vault-relative path and writes the current contents there as a new page, then opens it. The original file is left as it was on disk. An extension you type (`.html`, `.md`, `.markdown`, `.json`) is kept as typed; a bare name gets the same extension as the original file.

## Reading preferences

Text size, line spacing, font, focus mode and PDF export are all covered in [Reading & Presenting](https://docs.docgraph.app/editing/reading/).