# Writing and editing > The collaborative markdown editor, presence, version history, and locking a document. You write markdown documents in Filement itself. Open one and choose **Edit**; choose **Done** to go back to reading. Shift+⌘+E toggles between the two from the keyboard. Esc always returns to reading. Reading and writing share one layout on purpose. The text stays exactly where it was when you switch, so you never lose the line you were on. ## Finding your way around a document A document with headings gets an **Outline** in the panel beside it. It lists every heading down to three levels and follows you as you scroll. Clicking an entry jumps to that section, while writing as well as while reading. The bar above the document shows the word count and how long the document takes to read. The copy button in the corner of a code block copies the whole block. It appears when you hover the block, and always shows on a touch screen. ## Two documents side by side To read or write with another document in view, choose **Open beside…** from a document's **…** menu (or its right-click menu on the board) and pick the second one. The two sit side by side, and each scrolls and edits on its own. The outline and Insights move into the bar above each document to leave room for the text. The keyboard shortcuts act on whichever side you last clicked. **Close**, at the top of the right-hand document, goes back to one. The pair is part of the address, so a reload or a copied link opens both. On a narrow window the second document sits under the first, and on a phone the option is not offered. ## Writing together Several people can edit the same document at once. Changes merge as you type, and you see who else is in the document: their avatars at the top and their cursors in the text. Each person gets a colour of their own, and the ring round their avatar matches it. People who are only reading show as viewing, not editing. ### Pointing something out You don't have to be editing to show someone what you mean. Press the **share** button (the arrow) in the bar above the document. It appears once someone else has the document open. While it is on, everyone else on the document sees what you select, highlighted in your colour with your name beside it, and sees your mouse move over the text. That works whether they are reading or editing. When two people select the same words, both colours show. Click anywhere to clear a selection. Sharing stays on until you press the button again or everyone else leaves. Other people's selections and pointers show up without you turning anything on. On a touch screen you can share selections; there is no pointer to share. While you are editing, your cursor is always visible to the others, shared or not. Sharing connects your browser directly to the browsers of the other people on the document, so what you point at moves without delay. Like a video call, that lets each side see the other's network address. On networks that block direct connections everything still shows, a little behind. On an older browser you may see the name and the cursor of the person selecting, without the coloured highlight. The editor handles headings, lists, checklists, quotes, code, links, tables, images and video. Filement stores everything as markdown, so what you write is also what search, the assistant and agents read. There is no Save button and nothing to lose. Your writing goes to the server as you type. The bar above the document says **Saving…** while a change is on its way and **Saved** once it has arrived. If the document changes while you have the editor open but aren't typing, for example when an agent edits it or someone restores a version, the editor reloads with the latest text and tells you so. Everything you had written was already saved, and it's part of what reloads. A tab left open in the background can never save its old copy over newer changes. ## Adding a block Type / on an empty line to see everything a document can hold: headings, lists, a checklist, a quote, a code block, a table, a divider, an image, a clip. Keep typing to narrow it (`/tab`, `/todo`), use ↑ and ↓ to move, Enter to choose and Esc to leave it. Each entry shows its markdown shortcut beside it, which is faster once you know it: `#` for a heading, `-` for a bullet, `1.` for a numbered list, `[]` for a checklist, `>` for a quote, ` ``` ` for code, `---` for a divider. They work as you type. The **+** in the margin beside a block does the same thing. It opens a new block below that one with the menu already up. ## Formatting what you selected Select some text and a small bar appears above it with bold, italic, underline, strikethrough, inline code and links, plus a menu on its left for turning the whole block into something else. The toolbar above the document has the same controls if you'd rather go there. ## Links Put the cursor in a link and a card appears showing where it goes, with three actions: open it in a new tab, change the address, or remove the link and keep the words. Clicking a link while editing puts the cursor in it instead of following it. That's what the card is for. ## Code A code block can say what language it is. Choose one from the picker in its top-left corner, or write the language on the fence (` ```ts `). The block is then coloured as you write, and coloured the same way when you go back to reading. The **copy button** in its corner takes the whole block. ## Tables Put the cursor in a table and a bar appears above it. You can add a row above or below, add a column left or right, delete either one, turn the header row on or off, or delete the table. A wide table scrolls sideways instead of squeezing into the page. Markdown has no way to write down a column width, so Filement doesn't store one, and a table is as wide as its contents. ## Pasting Paste markdown and it arrives as a document, not a wall of hashes and asterisks. Headings, lists, quotes, code fences, tables and links all come through as you'd expect. Text with no markdown structure stays exactly as you pasted it. ## Find and replace Press ⌘+F while editing. It searches the whole document, not only the part on screen (which is all the browser's own find can reach), and it can replace one match at a time or all at once. Enter moves to the next match, ⇧+Enter to the previous one, and Esc closes it and hands ⌘+F back to the browser. Match case and whole words are the two toggles at the bottom. Whatever you had selected when you opened it becomes the search term. ## Moving blocks around Hover over any block while editing and two controls appear in the margin to its left: **+** to add a block below, and a **grip**. - **Drag the grip** to move that block. A line shows where it will land. - **Click the grip** for the block's own menu: turn it into something else, move it up or down, duplicate it, or delete it. From the keyboard, ⌘+D duplicates the block the cursor is in and ⌘+⇧+↑/↓ moves it past its neighbour. All of this works on a single checklist item or list row too, so you can reorder a list of tasks one at a time. ### On a phone or tablet The margin controls need a pointer and dragging needs a mouse, so on a touch screen the same menu lives on the **toolbar**. The grip button at its left end acts on the block the cursor is in. **Move up** and **Move down** there do what dragging does elsewhere, and the rest of the list is the same: turn into, insert below, duplicate, delete. The toolbar also has **Image** and **Video** buttons, so you can add a picture without a right-click. ## Checklists Type `[]` at the start of a line, or use `/todo`, to start a checklist. Ticking an item draws a line through it and dims it. Anything nested underneath stays as it is, because an unfinished task holding a finished one isn't finished itself. Ticks are read-only while you read. You change them in the editor. ## Images and video Paste an image or a video clip, or drag one from your desktop, and it lands at the cursor. It shows straight away and uploads in the background. You can also **right-click anywhere in the editor** and choose **Add image** or **Add video** to pick a file. It goes in after the line you clicked. The toolbar's Image and Video buttons and the `/image` and `/video` entries open the same picker and put the file at the cursor. Both show small in the document, about a third of the page, and open full size when you click one. A picture opens fitted to the screen, however tall it is. **Scroll to zoom in**, drag or scroll to move around it, scroll back out to fit it again, and press Esc to close. Double-clicking zooms in and out too. While editing, the **play button on a clip** still opens it on a single click. A single click anywhere else selects the image or clip so you can move or delete it, and a double click opens it. - **Every image is shrunk before Filement stores it**, to at most 2048 pixels on its long side, and converted to WebP. A photo straight off a phone usually ends up around a tenth of its original size and looks the same on screen. - **Camera metadata goes** in the same step, including the GPS coordinates most phones write into a photo. - **Animated GIFs and SVGs stay exactly as they are.** Re-encoding either one would damage it. - **The same image used twice is stored once**, however many documents it appears in. - **A model describes each image**: what it shows and any text legible in it. You can then find a diagram or screenshot by searching for what's in it, and the assistant can talk about it. If the deployment has no model configured, images still work; they just don't get a description. ### Video Your browser **compresses a clip before uploading it**, to at most 1280 pixels on its long side, as MP4. A phone or screen recording usually ends up a fraction of its original size, which decides whether a clip is something you can keep in a document or something that eats a workspace. Nothing uploads until that finishes, so a long clip shows a progress bar where it will appear. - **Up to 10 minutes and 500 MB** as it comes off your disk. Anything longer belongs in a folder as a file. - **Sound stays.** Only the picture is re-encoded. - **A clip that is already small and efficient is left alone**, not re-compressed into something larger. - **No model watches video.** You find a clip by the text around it and by its name. An image, by contrast, gets a description and is searchable by what it shows. - It needs a recent browser (Chrome, Edge or Safari 17+). If yours can't compress video, the paste is refused with a note saying why, and the original isn't uploaded. Images and clips live inside the document that holds them. They don't appear as separate files on the board or in All files, and deleting the document deletes them. If you remove one from a document, Filement keeps it for a week before clearing it, so an undo always finds it. ## Discarding what you wrote While you edit, **Discard** appears in the bar above the document as soon as there is something to discard. It puts the document back exactly as it was when you opened the editor and takes you back to reading. Nothing is kept, so it asks first. Discard covers the session you are in, not your last one. Once you leave the editor, that writing is a version, and the way back to an earlier one is **Restore**. Discard is refused while someone else is typing in the same document. Their paragraph isn't yours to throw away. ## Version history Every document keeps its history, uploaded files included. Open a document's insights to see **Version history**: each version, who made it, and when. - **One editing session is one version.** Filement writes it when the last person leaves the editor, not while you type, so a morning of writing is one entry, not a hundred. - **The same goes for an agent or the assistant.** An agent connected over MCP that makes a dozen small edits to a document in one sitting leaves one version, and so do several of the assistant's changes applied from one conversation. The entry says it came via an agent or the assistant and how many edits went into it. Anyone else saving in between, or a pause of half an hour, starts a new version. Undoing it (from Activity, or the assistant's card) puts the document back to how it was before the session. - **Opening the editor isn't an edit.** Look at a document, change nothing, close it again, and history stays as it was, and so does the file, down to how its markdown is written. The same goes for typing something and deleting it before you finish. - Your writing still saves continuously while you work. Saving and versioning are different things: the bar says _Saved_ long before there is a version. - **Open a version to read it.** Click any entry and the version opens as the document it was. Switch to **What changed** to compare it with the current text, with added and removed lines marked. Reading a version changes nothing, so you don't have to restore one to see what it said. - **Restore** brings an old version back as a new version. History is never rewritten. - **Versions are kept indefinitely.** Nothing removes one, so a document you have worked on for months still has every state it passed through. - **History costs almost nothing.** A version isn't a second copy of the document. Text that hasn't changed since the last version is stored once and shared, so saving a long document again after fixing a paragraph stores just the paragraph. History doesn't count towards your [storage](https://filement.app/docs/guide/limits.md) at all. Deleting the document is what clears it. ## Locking **Lock editing** on a document, or **Lock folder** on a folder, freezes it. While it's locked, only the person who locked it and workspace owners and admins can change it. Everyone else can still read it. A folder lock covers everything inside. Use **Unlock** to lift it. A lock means "please leave this alone". It doesn't hide anything. To hide a folder, use [access](https://filement.app/docs/guide/workspaces-and-access.md). ## Edits from AI tools An AI tool with write access can edit markdown documents over MCP. Each of its edits is a normal version you can restore. If someone has the document open in the editor at that moment, Filement refuses the edit and tells the tool who has it open, so the two never race. Everything a tool changes is also listed in **Activity**, grouped into one entry per working session. **Undo all** there takes the whole session back, newest change first, and an undone edit comes back as a new version.