Using Ferret
Editor and preview
Open and edit project files, and preview Markdown and Mermaid. A preview opened in the built-in browser can be recorded and reviewed like any web page.
#Open and edit files
- Files (the file tree): ⌘⇧E / CtrlShiftE, with Filter by file name, Refresh, and Collapse All.
- Go to File…: ⌘P / CtrlP.
- Drag a file from Finder (File Explorer on Windows, your file manager on Linux) onto the tab bar or the editor to open it. Files in the project open in the editor or a viewer. To bring a file from outside the project in, drop it on Files, which copies it into the project. A folder dropped here opens as a project. Files dragged from Files open the same way. Images and videos dropped on an open Markdown file are embedded in it instead (see Embed images and videos in Markdown).
- Save with ⌘S / CtrlS. Closing a modified file asks
Save changes to <name>?
with Save, Don't Save, and Cancel. - If the file changes on disk while you have unsaved edits, choose Reload from Disk or Keep My Changes.
The editor is Monaco. Files that aren't text open in a viewer instead: images (zoom in and out; SVG can also be shown as code), video and audio with a seek bar, PDF, and, for any other binary file, its size and a hex view of the first bytes. Viewers are read-only, and files outside the project folder or reached through a symbolic link that leaves it are not shown.
#Work with files in the file tree
Work on files right in Files, the way you would in VS Code. Right-click an item, or the empty space below the tree to work at the top of the project. Names are typed in place in the tree.
- New File / New Folder: the buttons above the tree, or right-click. A new item goes into the selected folder, next to the selected file, or at the top of the project. Type a name with slashes, such as
src/routes/index.ts, to create the folders along the way. A new file opens in the editor. In an empty folder, Files shows This folder is empty with New File and New Folder buttons. - Cut, Copy, and Paste: ⌘X / CtrlX, ⌘C / CtrlC, ⌘V / CtrlV, or right-click. Folders are copied with everything inside. Duplicate makes a copy next to the original. If the name is taken, the copy is named
name copy, thenname copy 2. - Drag items onto a folder (or the empty space for the top of the project) to move them. Hold ⌥ / Ctrl while dropping to copy instead. Files and folders dragged in from Finder (File Explorer on Windows) are copied into the project; the originals stay where they were.
- Rename: F2 / Enter / F2, or right-click.
- Delete: ⌘⌫ / Delete / Delete, or right-click. Ferret asks first, then moves the item to the Trash (the Recycle Bin on Windows), so you can restore it. Tabs of deleted files close; if any had unsaved edits, the confirmation says so.
- Undo: ⌘Z / CtrlZ reverses the last new item, rename, move, paste, or duplicate. Deleted items are restored from the Trash.
- Copy Path (⌥⌘C / ShiftAltC) and Copy Relative Path (⌥⇧⌘C / CtrlShiftAltC) put the path on the clipboard.
- Reveal in Finder (Reveal in File Explorer on Windows, Open Containing Folder on Linux): ⌥⌘R / ShiftAltR. Open in Terminal opens a new terminal tab in that folder (for a file, its folder).
- For a file, Open opens it in the editor and Open in Default App opens it in the app your OS uses for that type.
- Select several items with ⌘ / Ctrl-click or ⇧ / Shift-click to cut, copy, move, or delete them together.
- Esc cancels a name you are typing.
Open tabs follow a renamed or moved file and keep unsaved edits. Ferret won't overwrite an existing file or folder with the same name, and it keeps everything inside the project folder: it refuses .., absolute paths, symbolic links that point outside, anything inside .git, moving a folder into itself, and names that some OS can't use: / \ < > : " | ? *, control characters, a trailing space or dot, and Windows reserved names such as CON or NUL. One copy or drop can hold up to 10,000 items and 1 GB.
#Markdown and Mermaid preview
Preview works for .md, .markdown, .mdx, .mmd, and .mermaid. Mermaid is bundled with the app, so diagrams render offline.
A Markdown file has two views at the top of the editor: Source and Preview. The preview is always editable, so you can type straight into it; click Source to go back to the text. Both show the same content, and saving, the unsaved mark, and the close confirmation work the same way.
- Type straight into headings, paragraphs, lists, checkboxes, tables, links, and bold, italic, or inline code. Typing
#,-,1., or>and a space at the start of a line starts a heading, list, or quote. - Type
/at the start of a line (or after a space) to pick a block from a list: headings, bulleted, numbered, or check lists, a table, a code block, a quote, or a divider. Each entry says what it makes and how it is written in Markdown. Keep typing to filter, use ↑ ↓ and Enter to choose, or Esc to keep the/as text. A table starts as 3 × 3 with a header row; Tab moves to the next cell and adds a row at the end. Typing/inside a table adds or deletes rows and columns, or deletes the table. - Code blocks are edited as their source, with the language shown in the corner. A Mermaid code block (
mermaidormmd) shows the diagram by default. Click Code at its top right, or double-click the diagram, to edit the source; moving the cursor out of the block shows the diagram again. If the source has an error, the message is shown with Fix the code. Diagrams are drawn inside a sandboxed frame, and the saved Markdown stays as written. - Front matter (the
---block at the top) is shown as text above the document and can be edited there. - Parts you don't change are saved exactly as written, including heading style, list markers, blank lines, table alignment, and line endings. A block you edit keeps its style where possible; otherwise that block is written in a standard Markdown form, with
-for lists and#for headings. - Images and videos in the project are shown. Images from other sites are not loaded; their host name is shown instead. Other HTML in the file is shown as text.
.mdx files (edited as source only), .mmd, and .mermaid files have a read-only preview instead:
- Open Preview to the Side: next to the editor
- Open Preview: in the built-in browser (
ade-preview://), so you can record and review it
#Embed images and videos in Markdown
Drag images (PNG, JPEG, GIF, WebP, SVG, AVIF) or videos (MP4, WebM, MOV) onto a Markdown file, in Source or Preview, to embed them where you drop them.
- Files already in the project, including ones dragged from Files, are linked with a path relative to the Markdown file. Nothing is copied.
- Files from outside the project (Finder, the desktop, File Explorer on Windows) are first copied into a folder next to the Markdown file:
assets,images,media, orimgif one is already there, otherwise a newassetsfolder. Spaces in the name become-, and if the name is taken the copy is namedname-2. The originals stay where they were. - Images are written as
and videos as<video src="assets/name.mp4" controls></video>, which GitHub also plays. Both are shown in Preview. - An image can be up to 50 MB and a video up to 500 MB, and one drop copies up to 50 files and 1 GB. Other files dropped with them open in the editor as usual.
#Review docs by recording
- In the Review targets panel, open the Markdown file from Files. It opens as a preview in the built-in browser.
- Record as usual. Talk through the spec or design doc and circle what's wrong.
- Stop. Findings reference the file's project-relative path instead of a URL.
- Send to Agent to have the doc fixed.
