# Writing notes

> The editor: editing and saving, markdown shortcuts, the insert menu, every kind of block, links between notes and pasting markdown

## Editing and saving

A note opens for reading. To change it, click **Edit** in the top bar. Kribble loads the latest saved version first, so you start from what everyone else sees.

While you edit, the top bar shows **Save** and **Discard**:

- **Save** (Ctrl+S, or ⌘+S on a Mac) saves your changes as a new version of the note and switches back to reading. Every save is kept in the note's history (see [Comments and reviews](../using-kribble/comments-and-reviews.md)).
- **Discard** throws your changes away and reloads the saved note. If you haven't changed anything, the button says **Cancel**.

:::callout{type="warning"}
Kribble doesn't save the note to the server on its own. Your changes reach other people only when you click **Save**.
:::

### Drafts

As you type, Kribble keeps a draft of your unsaved changes in your browser. If you close the tab, lose your connection or your browser crashes, open the note again: it opens in editing mode with your changes still there, ready to **Save** or **Discard**.

The draft lives only in that browser on that computer. Nobody else sees it, and you won't find it on another device.

### Title and description

Click the title at the top of the note to rename it, and the line under it (**Add a description...**) to give it a short description. Both save on their own a moment after you stop typing, whether or not you're in editing mode. Press Enter in the title to move to the description, and Enter in the description to move to the text.

The icon left of the title (**Add icon**) gives the note an icon; see [Organising notes](../using-kribble/organising-notes.md).

### When someone else saved first

If someone saves the note while you're editing it, Kribble tries to combine your changes with theirs when you save. When you changed different parts of the note, this happens without you noticing.

When you both changed the same part, the top bar shows **Conflict detected** and a banner appears above the text. Click **Resolve** to open **Resolve Conflict**: it shows the **Current saved version** next to **Your version (editable)**, with changed, added and removed blocks marked. Edit your version until it's right, then click **Save Resolution**.

### Notes you can't edit here

A note pushed from a git repository with the [kribble CLI](../using-kribble/the-kribble-cli.md) shows where it came from above the text, with "change it in the repository". It has no **Edit** button, because the next push would overwrite changes made here. Comments still work. **Detach…** stops syncing the folder with the repository and makes its notes editable here.

A single note can hold up to 5 MB. If you go over, a warning appears above the text and your changes may not save until you remove something, such as a very large table.

## Formatting text

Select some text and a toolbar appears above it. From left to right:

- **+** inserts an empty block below the current one. Hold Alt (Option on a Mac) while clicking to insert it above.
- The block type menu turns the current block into **Text**, **Heading 1**, **Heading 2**, **Heading 3**, **Bullet List**, **Ordered List**, **Quote** or **Code**.
- **Bold**, **Italic**, **Underline**, **Strikethrough** and **Code** (inline code).
- **Link**: paste or type an address and press Enter.
- **Align left**, **Align center** and **Align right**.

On a phone or tablet the same toolbar sits at the bottom of the screen while you edit.

While editing, put the cursor inside a link to see its address with buttons to **Open link**, **Open in new tab**, **Edit link** and **Remove link**.

### Markdown shortcuts

You can format as you type, the way you would in markdown.

| Type | To get |
| --- | --- |
| `#` `##` `###` and a space, at the start of a line | Heading 1, 2 or 3 |
| `-`, `*` or `+` and a space | Bullet list |
| `1.` and a space (any number) | Numbered list, starting at that number |
| `[ ]` or `[x]` and a space | Task list item, unchecked or checked |
| `>` and a space | Quote |
| ` ``` ` | Code block |
| `---` | Divider |
| `**text**` | **Bold** |
| `*text*` | *Italic* |
| `__text__` | <u>Underline</u> (not bold, as in some markdown editors) |
| `~~text~~` | ~~Strikethrough~~ |
| `` `text` `` | Inline `code` |
| `:note-link[[` | Link to another note (see below) |

## Inserting blocks

Type `/` at the start of an empty line to open the insert menu. Type to filter it (**Filter blocks...**), move with the arrow keys and press Enter, or click an item. Esc closes the menu. You can also hover to the left of any block and click **+** (**Add block below**; Alt-click for above) to start a new empty line.

The menu has:

| Item | What it inserts |
| --- | --- |
| **Text** | A plain paragraph |
| **Heading 1**, **Heading 2**, **Heading 3** | Headings |
| **Bullet List**, **Ordered List**, **Task List** | Lists |
| **Quote** | A block quote |
| **Code Block** | Code with syntax highlighting |
| **Divider** | A horizontal line |
| **Callout** | An info, warning or note box |
| **Table** | A table |
| **Tabs** | Content split into tabs |
| **Accordion** | A section that opens and closes |
| **Cards** | A grid of cards that can link somewhere |
| **Columns** | Content side by side |
| **Drawing** | A whiteboard with shapes, arrows and freehand drawing |
| **Diagram** | A diagram you write as text and Kribble draws (see \[Diagrams\]{noteId="01a134d9-9ea8-77d4-ad08-92209cd578e9"}) |
| **Embed** | A YouTube, Vimeo, Loom, CodeSandbox, StackBlitz or Figma frame |
| **Video** | An uploaded video |
| **File Attachment** | Any uploaded file |
| **Image** | An uploaded or pasted image |
| **Mermaid Diagram** | A diagram written in Mermaid |
| **File Tree** | A folder and file structure |
| **Steps** | A numbered walkthrough |

## The blocks

### Lists and task lists

Press Tab to indent a bullet or numbered list item under the one above it, and Shift+Tab to move it back out. Press Enter on an empty item to end the list.

In a task list, click the box to tick an item. Task items hold one line of text each and can't have lists nested inside them.

### Code blocks

Click the language name in the top-right corner of a code block to choose its language for highlighting; type in **Filter...** to find it quickly. Next to it are a **filename (optional)** field, which shows when you hover the block or once it has a name, and a **Copy code** button.

Inside a code block, Tab indents by two spaces and Shift+Tab removes indentation, for one line or every selected line. To leave the block, press Enter on an empty last line, or the down arrow at the very end of the block.

### Mermaid diagrams

A **Mermaid Diagram** block draws flowcharts, sequence diagrams and other diagrams from [Mermaid](https://mermaid.js.org) text. Type the source in the editor at the top; the diagram updates below it as you type, and says **Invalid diagram syntax** until the text is valid. **Toggle editor** hides or shows the source.

### File trees

A **File Tree** shows a project's structure. Click **Edit** and write one name per line, indenting children by two spaces. End a name with `/` to make it a folder:

```
src/
  components/
    App.vue
  main.ts
package.json
```

### Callouts

A callout is a coloured box for something readers shouldn't miss. Click its icon (**Change callout type**) to switch between **Info**, **Warning**, **Danger**, **Success** and **Note**. Callouts can hold any other blocks, including lists and code.

### Tabs

**Tabs** splits content into tabs, for example one per operating system. Double-click a tab's name to rename it, click **+** (**Add tab**) to add one, and the **×** on a tab (**Remove tab**) to remove it. **Delete tabs** removes the whole group.

When a page has several tab groups with the same tab names, choosing a tab in one switches the others to match. Tabs can't be placed inside other tabs.

### Steps

**Steps** is a numbered walkthrough. Each step has a title and a body that can hold any blocks. **Add step** adds one at the end, and **Remove steps** removes the whole walkthrough.

### Accordions

An **Accordion** has a title and content that readers open and close with the arrow beside the title. Use it for detail most readers can skip. **Delete accordion** removes it.

### Columns

**Columns** puts content side by side; it starts with two. Use **Add column** to add more (up to six) and **Remove column** to remove one. **Delete columns** removes the whole layout. On narrow screens the columns stack.

### Cards

**Cards** is a grid of cards, each with an optional cover image, a title and a short description.

- Click **Add cover** to upload a cover image.
- Press Enter in a card's title to move to its description, and Ctrl+Enter (⌘+Enter) to add a new card after it. **Add card** adds one at the end.
- Hover a card and click **Set link** to make it link to another note or to a web address. **Delete card** removes one card, and **Delete card group** removes the grid.

### Tables

A new **Table** has a header row and three columns. Press Tab and Shift+Tab to move between cells. While the cursor is in a table, its toolbar offers **Add row**, **Delete row**, **Add column left**, **Add column right**, **Delete column** and **Delete table**.

To change a column's width, drag the handle on the border between two columns. Double-click a handle to go back to automatic widths. Tables can't be placed inside tables.

### Images, videos, files and embeds

- **Image**: click the box to pick a file, or paste or drag an image anywhere into the note. JPEG, PNG, GIF, WebP and SVG are kept as they are; photos in HEIC format (from iPhones) are converted to JPEG. Add a description for screen readers in the **Alt text...** field under the image.
- **Video**: click the box or drop a video file on it.
- **File Attachment**: click the box or drop any file on it, such as a PDF or a spreadsheet. Readers get a **Download** button.
- **Embed**: paste a link into **Paste a URL**. YouTube, Vimeo, Loom, CodeSandbox, StackBlitz and Figma links show the content in the note. Other addresses are tried as they are; if the site doesn't allow embedding, the block shows a link instead. **Fullscreen** enlarges it.

Uploads can be up to 500 MB each (your server may set a lower limit). Programs and scripts, such as `.exe` or `.sh` files, can't be uploaded.

### Drawings

A **Drawing** is a whiteboard inside the note, with the feel of Excalidraw: shapes, arrows that stay attached, text, freehand, images, and a hand-drawn style if you want it. Click into it to start; the toolbar's tools also have keys:

| Key | Tool |
| --- | --- |
| V or 1 | Select |
| H | Hand (pan) |
| R or 2 | Rectangle |
| D or 3 | Diamond |
| O or 4 | Ellipse |
| A or 5 | Arrow |
| L or 6 | Line |
| P or 7 | Draw (freehand) |
| T or 8 | Text |
| I or 9 | Insert an image |
| E or 0 | Eraser |

After drawing a shape you're back on Select; press **Q** (or the lock at the toolbar's left) to keep the tool. While drawing, **Shift** keeps squares, circles and 15° angles, and **Alt** draws from the center. A click with a shape tool drops a default-sized shape.

- **Selecting**: click a shape's outline (or anywhere in a filled one), drag a box around things, Shift-click to add or remove. Drag to move, Alt-drag to copy. Shapes snap to the edges and centers of others, with guide lines; hold Ctrl (⌘ on a Mac) to place freely. Ctrl+' shows a grid to snap to.
- **Resizing and rotating**: drag a handle (Shift keeps the proportions, Alt resizes from the center) or the round handle above to rotate.
- **Arrows** attach to the shape you start or end on (it lights up) and follow it when it moves. Click, click, click draws a line through several points (Enter to finish); drag a point of a selected line to move it, or the dot between two points to bend it. Line type (straight, curved, elbow) and arrowheads are in the panel.
- **Text**: double-click empty space to write, double-click a shape or arrow (or press Enter) to give it a label. Labels wrap inside their shape.
- **Style**: the panel on the left changes the selection, and what you pick is used for the next things you draw: colours, fill (hatched, cross-hatched, solid), stroke, **Sloppiness** (clean, hand-drawn, sketchy), corners, font, alignment, opacity, layers.
- **More**: right-click for copy, paste, duplicate (Ctrl+D), group (Ctrl+G), lock, flip, layer order (Ctrl+\] and Ctrl+\[) and **Copy as PNG/SVG**. You can paste or drop images, and paste shapes copied from Excalidraw.
- **Moving around**: once you've clicked into the drawing, the mouse wheel pans it; Ctrl+wheel or a pinch zooms. Space+drag or middle-drag pans too. Shift+1 fits everything in view, Shift+2 the selection, Ctrl+0 goes back to 100%.

### Diagrams in drawings

The **Shapes** button in the toolbar opens a library of diagram elements, like draw.io's sidebar. It has five sections: General, UML class & structure, Use case, Activity and Sequence, and a search box at the top. To place a shape, click it to drop it in the middle of the view, or drag it to where you want it. To draw a connector, click it and then drag from one shape to another. Hovering a shape shows its connection points as small crosses. Drag outwards from one to start an arrow there.

- **Class diagrams**: a **Class** has name, attributes and methods compartments. Double-click a compartment to edit it, one member per line. The box grows to fit. Start the name with a stereotype line such as `«interface»` or `«abstract»`. With a class selected, the panel's **Abstract** button sets the name in italics, and **Methods** shows or hides the last compartment. The library also has an interface, an abstract class, an enumeration, a package, a note and a component. The relationship connectors are association, directed association, inheritance, realization, dependency, aggregation and composition. To change a drawn arrow's relationship, select it and pick another from **Relationship…** in the panel. Double-click near either end of an arrow to write a multiplicity or role there, such as `1` or `0..*`.
- **Use case diagrams**: actors, use cases and a **System boundary**. Anything inside the boundary moves with it. The «include» and «extend» connectors are dashed and labelled.
- **Activity diagrams**: start, end, flow end, action, decision, fork/join bars, object nodes and **Swimlanes**. Double-click a lane's header to rename it, use **+ Lane** and **− Lane** in the panel to add or remove lanes, and drag the line between two lanes to resize them. The lanes to the right shift over, and their shapes go with them. Moving the pool moves everything in it. To label a guard such as `[ok]`, double-click the flow.
- **Sequence diagrams**: lifelines (with a box or an actor head), activation bars and the messages: sync (filled head), async (open head), return (dashed), self message and create. A message attaches to a lifeline's dashed line at the height you draw it and stays there when the lifeline moves. All lifelines joined by messages share the same length, and resizing one resizes the others. Combined fragments (alt, opt, loop) have a tab with the operator. Double-click it to change the operator, or double-click an operand to write its guard. **+ Operand** adds a dashed separator.

Containers (packages, system boundaries, swimlanes and fragments) are placed behind other shapes. Shapes inside one move, copy and duplicate with it. Deleting a container leaves its contents where they are.

To write a diagram as text instead of drawing it, use a **Diagram** block (see [Diagrams](../using-kribble/diagrams.md)). **Convert to diagram** in a drawing's **⋯** menu turns boxes and arrows you drew into one.

Press **?** in a drawing for all its shortcuts. The drawing has its own undo and redo (Ctrl+Z and Ctrl+Shift+Z). Drag the bottom edge of the block to make it taller, or use **Fullscreen** (Esc leaves it). It's saved with the note when you click **Save**.

:::callout{type="info"}
A drawing's shapes are stored only in Kribble. When you export a note as markdown or read it with the CLI, the drawing is a placeholder. PDFs, HTML exports and published sites show the drawing as you drew it.
:::

## Linking to other notes

Type `:note-link[[` anywhere in the text. A picker opens with two tabs:

- **Note**: type part of a note's title (**Search notes...**), choose a note with the arrow keys and press Enter. Notes from the current organisation are listed.
- **URL**: type a web address and press Enter to insert an ordinary link.

A note link shows the note's name. Click it to open that note, or Ctrl-click (⌘-click) to open it in a new tab.

## Pasting markdown

When you paste text that looks like markdown (from a text editor, a documentation page or an AI chat), Kribble turns it into formatted blocks instead of plain text. This includes Kribble's own blocks, such as callouts, tabs and steps, written the way the \[kribble CLI\]{noteId="01a134d9-9ed7-709d-bc40-0e60ff9a6e21"} writes them. Links to `.md` files become links to the notes with matching names, when they exist. Footers that often come along when you copy a documentation page, such as "Was this page helpful?" or "Last updated", are left out.

To go the other way, open **Copy as** in the top bar while reading a note and choose **Markdown**, **LLM Markdown**, **Discord** or **Slack**. The note is copied to your clipboard in that format, ready to paste elsewhere. The **PDF** button next to it is covered in [Exporting PDFs](../using-kribble/exporting-pdfs.md). On a phone both are in the top bar's **⋯** menu.

## Editor keyboard shortcuts

On a Mac, use ⌘ where it says Ctrl.

| Shortcut | What it does |
| --- | --- |
| Ctrl+B | Bold |
| Ctrl+I | Italic |
| Ctrl+U | Underline |
| Ctrl+Shift+S | Strikethrough |
| Ctrl+\` | Inline code |
| Ctrl+Shift+1, 2, 3 | Heading 1, 2, 3 |
| Ctrl+Shift+0 | Plain text |
| Ctrl+Shift+8 | Bullet list |
| Ctrl+Shift+9 | Numbered list |
| Ctrl+Shift+B | Quote |
| Ctrl+Shift+C | Code block |
| Shift+Enter | Line break inside a block |
| Tab, Shift+Tab | Indent or outdent a list item, code, or move between table cells |
| Ctrl+Z | Undo |
| Ctrl+Shift+Z or Ctrl+Y | Redo |
| Ctrl+S | Save |