The Markdown Editor

Where you'll see it

The same editor opens in every place you write more than a sentence in ResearchOS.

• The Lab Notes tab of any experiment popup (see Experiments & Notes).
• The Description field on the task detail popup, which you can open from the Gantt, the left sidebar, search results, or the calendar.
• The Results tab inside the Workbench project view (the old standalone Results page was retired; /results now redirects to Workbench).
• The body of every method in the Methods library.
• Free-form notes (running logs and standalone notes).

Everything you type is plain markdown. The toolbar buttons just insert the same characters you'd type by hand (e.g., **bold**, # heading), so opening any of these files in a normal text editor outside ResearchOS gets you the same content.

One surface, type markdown and watch it render

There's nothing to configure and no block to click into. The editor is a single, continuous writing surface, like a normal document. You type plain markdown and the editor renders it live around your cursor. Headings look like headings, bold looks bold, and images show as images, all in one flowing column.

The key is what happens at your cursor. Markdown markers (the ** around bold, the # on a heading, a link target) stay hidden while you read, so the line looks finished. Move your caret onto that line and the markers reveal themselves, ready to edit; move away and they tuck back behind the rendered output. You are always editing the real markdown, never a separate rich-text copy.

The toolbar

Every editor has a single toolbar along the top. From left to right it carries these controls.

• The Edit | Preview toggle (covered above).
• Focus mode. The expand glyph drops the editor into a full-screen distraction-free writing view (also Cmd+Shift+F).
• Add Image (or Add File on surfaces that accept any file type) to pick attachments from disk.
• Browse to insert an image already attached to this record without re-uploading.
• Attachments to show or hide the bottom attachment strip (see Attachments).
• On surfaces that own their own save (the experiment popup's Lab Notes / Results tabs, the task popup), the Version history button and the Save checkpoint button ride at the right end of this same bar (see Saving).

Keyboard shortcuts

Use Cmd on macOS and Ctrl on Windows and Linux anywhere this table says Cmd.

Attachments

Images and files live in one place, a single attachment strip along the bottom of the editor, toggled with the toolbar's Attachments button. A small Images / Files tab bar above the strip switches it between image thumbnails and file tiles. There's no separate Files panel and no top-of-editor Markdown / Files toggle anymore; everything funnels through this one strip.

Adding an image

There are four ways to get a new image in.

• Click the toolbar's Add Image button to pick one or more files from disk.
• Drag image files into the editor body. While you're dragging from Finder, a blue ring lights up around the popup or editor card so you know the drop will be caught. Release inside text and the image inserts at that position. Release outside text and it appends to the bottom of the document. You can drop straight onto a rendered image too, and the new file slots in beside it. Chrome's default replace-image behavior is intercepted, so nothing else happens.
• Paste from the clipboard. Copy a screenshot (e.g., macOS Cmd+Shift+4, then Cmd+V in the editor) and it lands inline.
• Click Browse to pick from images already attached to this record (the gallery picker). Useful when the image is already on disk and you just want to insert a reference without re-uploading.

Every image lands in an Images/ folder adjacent to the document on disk (e.g., users/<you>/results/task-12/Images/gel-2026-05-10.png), and the markdown body references it with ![caption](Images/gel-2026-05-10.png). Filenames with spaces render inline just fine. The reference looks like ![](Images/Emile ID card-1.jpg) and the editor resolves it to the right file without any extra escaping.

The Images tab

The Images tab in the bottom strip lists every image in the document's Images/ folder as a row of thumbnails, whether or not the body references the image yet. Images already referenced look normal. Images that exist on disk but aren't referenced yet (e.g., a fresh arrival from the companion app) show a small blue dot in the corner so you can spot them. Here's what you can do from the tab.

• Click a thumbnail to open the image metadata popup. The popup shows a larger preview and lets you edit the caption, rename the file, delete it from disk, or jump to where it's used in the body. If the image isn't referenced anywhere yet, the jump button is disabled. The popup also has an Annotate button that opens the non-destructive image annotation editor, where you can circle a band or label lanes without ever modifying the raw photo.
• Drag a thumbnail into the editor to insert that image at the cursor position. The thumbnail stays in the strip so the same image can appear twice in the document.
• Drag a thumbnail to the trash zone at the bottom of the editor. ResearchOS deletes the file from disk and removes every reference in the body. The trash zone only appears while you are actively dragging a thumbnail.

Resizing an image

Click any rendered image and a size popover appears inline with 25%, 50%, 75%, and 100% options. The choice writes a width attribute into the markdown so the size persists.

Broken image references

If an image reference points at a file that no longer exists (e.g., you renamed the file outside the app, or the relink hasn't synced from a teammate yet), a small red "Image Not Found" popup appears in the bottom-right corner of the editor. It lists similar-named files in the document's Images/folder. Click one and the reference rewrites in place. If nothing looks right, the same popup offers a Remove reference from note button to strip the dead snippet entirely, and a Dismiss all button at the bottom to silence the queue. Multiple broken refs queue up one at a time, with a Skip link so you can step past one without touching it.

The Files tab

Anything that isn't an image (PDFs, CSVs, sequence files, protocols, archives) drops into a sibling Files/ folder and shows up as a clickable hyperlink in the prose, not as an inline preview. Switch the bottom strip to its Files tab to manage them. The add flow mirrors images, so you drag from Finder, paste, or use the toolbar's Add File button (which replaces Add Image on surfaces that accept any file type, namely experiment Lab Notes, Results, and Notes). The chosen file copies into Files/ and a markdown link inserts at the cursor.

• Each tile shows an icon for the file type and the filename. Files already linked in the body look normal. Files that exist on disk but aren't referenced yet show a small blue dot and an "unlinked" count in the tab header.
• Drag a tile into the editor to insert a link to it at the cursor.
• Drag a file tile to the red trash zone at the bottom-right of the editor. ResearchOS asks for confirmation, then deletes the file from disk and strips every link to it from the markdown body, including links that stored the filename URL-encoded (so Files/READ%20ME.md gets cleaned up when the underlying READ ME.md is dragged out).

Clicking a file link

Click any [name](Files/…) link in Edit or Preview mode and a small View / Download popup appears centered on screen.

• Text-like files (markdown, txt, csv, json, code, sequence files like fasta and gbk) get a popup with Cancel, Download, and View buttons. Click View and the contents render in an inline monospace viewer with its own Download button up top. Click Download from either spot and the file saves locally.
• PDFs get the same popup. Click View and ResearchOS opens the PDF in a new browser tab so you can use the browser's built-in PDF viewer. Click Download and a copy lands on disk.
• Everything else (zips, office docs, audio, video, binaries) downloads immediately without a popup. There's nothing meaningful to render inline.

Broken file references

When a [name](Files/…) link points at a file that isn't in the document's Files/ folder, the same red corner popup that handles broken images opens with a File Not Found heading. There's no similar-name search for files (the recovery is usually to remove the dead link), so the popup goes straight to a Remove reference from note button. Dismiss all closes the queue without touching the markdown, and Skip moves to the next broken reference if there's more than one.

What a real ResearchOS note looks like

A typical note in a working lab is mostly tables, measurements, and small annotations. The four examples below are the shape to aim for.

PCR reaction setup

## PCR reaction (25 uL, Q5)

| Reagent              | Stock     | Final     | Volume (uL) |
|----------------------|-----------|-----------|-------------|
| Q5 master mix (2x)   | 2x        | 1x        | 12.5        |
| Forward primer F1    | 10 uM     | 0.5 uM    | 1.25        |
| Reverse primer R1    | 10 uM     | 0.5 uM    | 1.25        |
| Template (gDNA)      | 50 ng/uL  | 1 ng/uL   | 0.5         |
| Nuclease-free water  |           |           | 9.5         |
| **Total**            |           |           | **25.0**    |

Program: pcr_program_id = 142  (Tm = 62 C, 30 cycles, 35 s elongation)
Variation: dropped extension to 30 s, single template lot.

Plasmid metadata

## pGN-027  (parent: pGN-012)

- Resistance: Kan (50 ug/mL)
- Size: 5.4 kb
- Source: Gibson assembly of pGN-012 backbone + amplicon FN-1
- Sequence: Files/pGN-027.gbk
- Glycerol stock: -80 B, box 4, position B3
- Verified by: Sanger seqs SP1/SP2 (Files/pGN-027-seq.zip)

Sample measurement record

## OD600 readings, 2026-05-22 08:14 CT

Instrument: BioTek Synergy H1 (SN 19F-3204)

| Sample  | Strain        | Media | OD600  | QC  |
|---------|---------------|-------|--------|-----|
| A1      | WT            | YPD   | 0.412  | ok  |
| A2      | dADE2         | YPD   | 0.398  | ok  |
| A3      | dADE2-comp    | YPD   | 0.087  | low |
| A4      | media blank   | YPD   | 0.041  | ok  |

Subtracted media blank (0.041) from A1-A3 before plotting.
A3 looks suspect, repeat tomorrow morning.

Equipment log

## Centrifuge 5424R service log

- Serial: 5424R-7831
- Location: lab room 314, bench 4
- Last service: 2025-11-09 (annual calibration, certified)
- Belt replaced: 2024-04-02
- Rotor: FA-45-24-11 (max 21,130 x g)
- Notes: unbalanced load alarm fixed 2026-03-15, gasket reseated.

Tables, lists, and other markdown

Standard GitHub-flavored markdown all works.

• Tables with the |-and-- syntax.
• Bulleted (-) and numbered (1.) lists.
• Task lists with - [ ] and - [x]. Boxes are clickable in Edit and Preview.
• Blockquotes (> text).
• Horizontal rules (---).
• Inline code with single backticks and code blocks with triple backticks.

The helper panel

The editor includes a collapsible helper panel on the left side with two tabs at the top, Shortcuts and Style Guide. Click the arrow in the panel header to collapse or expand it.

• Shortcuts lists every keyboard shortcut the editor responds to, with the key combo on the right. Read-only.
• Style Guide shows example syntax for every markdown feature (headings, lists, tables, code blocks, callouts). Click any example to insert it at the cursor. Handy when you've forgotten the table syntax or want to see what callout markdown looks like.

Saving is a checkpoint

The editor doesn't autosave. You save explicitly, and every save is a checkpoint, a permanent, revertible version of the document. Click Save checkpoint in the toolbar (or press Cmd+S) to write your edits to disk and record a version you can come back to.

Version history and revert

Next to the save button, the Version history button opens a docked sidebar listing every checkpoint, newest first, grouped by day. Select a version and the editor body flips to a read-only diff view showing exactly what changed between that checkpoint and the one before it (additions and removals highlighted in place). The live document is never altered while you browse.

If you have write access, the sidebar footer offers a Restore action. Restoring writes the chosen version back as the current content and records it as a fresh checkpoint, so the restore is itself revertible. You can always roll forward again to the pre-restore state. The timeline labels these entries so a restored note reads clearly in its own history.

On save, the editor also runs a quick cleanup pass over the document's Images/ and Files/ folders: anything sitting on disk that nothing in the markdown points at gets deleted, so deleted snippets don't leave dangling files behind. The sweep matches links the way the body writes them, so URL-encoded file links (Files/READ%20ME.md) protect their on-disk counterparts correctly.

See Version History for the full picture of how checkpoints, diffs, and restore work across ResearchOS.

Object embeds

A lone [name](ros://<type>/<id>) link on its own line renders as a live card instead of a plain hyperlink. Trees, sequences, molecules, and notes each have their own card style. The card pulls from the same source the full viewer does, so a tree embed is the same rendering engine as the Tree Studio, not a screenshot.

You get an embed link whenever you insert a reference from the @mention picker and it resolves to a block-embed type. The link is still valid markdown outside ResearchOS, it just opens as a normal link in a text editor. Inside ResearchOS, the renderer at RenderedMarkdown.tsx detects the ros:// scheme and mounts the live card in place of the raw link text.

Things people miss

• Undo / redo across the whole document. The editor maintains its own undo stack. Cmd+Z steps back through edits, including image drops and deletions. Cmd+Shift+Z (or Ctrl+Y on Windows) steps forward.
• Promote/demote a heading in place with Cmd+Alt++ or Cmd+Alt+-. You don't need to retype the # marks.
• Focus mode (Cmd+Shift+F or the toolbar expand glyph) gives you a full-screen, distraction-free writing view with a compact top bar. That top bar carries a width control with four presets (Narrow, Comfortable, Wide, Full-bleed) so you can set how wide the text column runs, from a tight ~60-character measure up to the full available width. Your choice is remembered. Exit returns you to the popup.
• The Attachments button in the toolbar toggles the bottom attachment strip (its Images and Files tabs) on and off. Click it again to bring the strip back.
• Drag a thumbnail back into the editor to insert the same image a second time. The file isn't duplicated, only the reference is.
• Spell-check your prose by turning on Settings › Behavior › Spell-check in the editor (off by default). When on, the editor underlines likely misspellings and offers click-to-fix suggestions, and its dictionary already knows common lab terms so science words aren't flagged. Anything it does flag can be added to your own dictionary. Code spans, link URLs, and numbers stay quiet.