The editor

In Mahfouz’s editor you’re always editing plain Markdown text, but certain syntax renders visually as you type (checkboxes, bullets, highlights, tags, wikilinks, media) rather than showing raw symbols.

There are three view modes for how much raw syntax stays visible, switched with the bottom bar’s view button (an eye in Preview, code brackets in Source, a terminal prompt in Vim), or with ModShiftP (ModAltP on the web) Since 0.20.0 (remembered on this device, not per note). The button opens a menu of Preview, Source and Vim; the shortcut switches between Preview and Source, and from Vim goes to Preview. Since 0.20.0

• Source (default): most Markdown punctuation stays visible (# , **, _, [text](url), etc.) so it’s obvious what you’re editing, while checkboxes, bullets, and horizontal rules still render as real widgets.
• Preview: heading marks, emphasis marks, link brackets, == highlight marks, and ~/^ sub/superscript marks are all hidden in favor of the styled result, except on whatever line your cursor is currently on, which always reveals its raw syntax so you can edit it. Tables render as fully interactive editable tables in Preview mode regardless of cursor position (see Tables). An image, video or audio embed likewise replaces its ![alt](path) line in Preview mode, wherever the cursor is (see Images & attachments). Copying from Preview copies formatted text: pasted into Mail, Google Docs, Slack or Word, headings, emphasis, lists, links and tables keep their formatting. Apps that only take plain text, and Mahfouz itself, get the Markdown, and so does Paste and Match Style. Wikilinks and attached images paste as their text. Copying in Source copies Markdown only.
  • The copy holds the Markdown of what you selected. Formatting the selection only partly covers is closed and reopened around the part you copied, so no marker is left over: selecting old t in **bold** text copies **old** t, and selecting the whole bold word copies **bold**. Since 0.20.0
  • Pending suggestions and comments copy as the text you see, with no markup and no author line. Since 0.20.0
  • Cut and dragging text to move it carry the same text, and the note keeps the markers of the formatting that stays. Since 0.20.0
  • Code blocks, tables, a note in Suggesting mode, and a whole line copied with nothing selected copy the raw Markdown, as before.

Other editor behavior:

• Pasting formatted text keeps its formatting as Markdown: from a web page, Word, Outlook, Google Docs, Notion, Slack or Mail, headings, bold, italic, strikethrough, inline code, links, bullet, numbered and task lists, quotes, tables, code blocks (with their language) and horizontal rules all come through. Since 0.20.0
  • Images aren’t pasted, nor are buttons and other page controls; links keep their address only for web and email links.
  • Code pastes as its text: from a code editor such as VS Code, a selection that’s all code, and anything pasted into a code block.
  • Copying from Mahfouz and pasting back pastes the Markdown, wikilinks and comments included.
  • ModShiftV (Paste as Plain Text) pastes the text without formatting.
• An empty heading on the cursor’s line, such as a ## you’ve just typed, shows its level as a gray hint (Heading 2) until you type its text, in Source and Preview. The hint is never saved, and it goes when the cursor leaves the line. A new note’s first line shows New Note instead. Since 0.13.0
• Tab on a list item (bullet, numbered, or checklist) nests it under the item above, wherever your cursor is on the line, and its sub-items move with it. Shift+Tab moves it back out a level. On the first item of a list Tab does nothing, since there’s nothing above to nest under.
• In Preview, Backspace and Delete remove what you can see; hidden markup goes only with the thing it formats. Since 0.13.0
  • Next to a wikilink, a link, or bold, italic, strikethrough, code, highlighted, underlined, subscript or superscript text, they step over the hidden markup and remove the visible character: Backspace after [[Note]] leaves [[Not]].
  • Removing an element’s last character, or deleting a selection of all its text, removes the element with its markup, so no stray [[]] or **** is left behind.
  • At the start of a heading’s, list item’s, task’s, quote’s or callout’s text, Backspace removes the line’s markup and leaves a plain paragraph. A nested list item moves out a level instead, with its sub-items, the same as ShiftTab. Since 0.20.0
  • Delete at the end of a line joins the next line’s text without its markup.
  • Deleting a word (AltBackspace on a Mac, CtrlBackspace elsewhere) or to the start of the line (CmdBackspace on a Mac) follows the same rule. Since 0.20.0
  • Deleting a selection removes only the text you see. The markup of formatting that keeps some of its text stays, also when the selection spans several lines. With several cursors, each one works the same way. Since 0.20.0
  • A person mention, a task’s date or assignee chip, and a formula go whole in one press: Backspace after a formula or Delete before one removes it. Since 0.20.0
  • On a line with text right after a horizontal rule, a table, an image card, an embed or a table of contents, Backspace at the start of the line deletes the whole block in one press; CmdZ (CtrlZ elsewhere) brings it back. On an empty line after one, it deletes only that line. Since 0.20.0
  • Emptying a suggestion removes it, its author line included. Since 0.20.0
  • Typing or pasting over part of a formatted element’s text keeps the formatting around it. Since 0.20.0

  In Source, Backspace and Delete work as usual.

• In Preview, the cursor never sits in front of a list item’s bullet or checkbox. Clicking left of the bullet, pressing Home, or moving up or down onto the marker puts it at the start of the item’s text, and ← from there goes to the end of the line above.
• On any other line, outside code blocks and tables, Tab moves focus out of the editor to the next control, and ShiftTab to the one before it. Since 0.20.0 See Writing from the keyboard for moving between the editor and the panels around it.
• Alt↑ and Alt↓ on a heading move its whole section, and on a list item the item with its sub-items (see Moving sections and list items). Since 0.20.0
• Misspelled words are underlined by your system’s spell checker (see Spelling check). In the macOS desktop app, what you type stays as typed, except for your Text Replacements and spelling corrections: the other macOS substitutions (smart quotes, smart dashes and link detection) are off (see Text substitutions). Since 0.14.0
• In Preview, a click on a link, a tag or a person follows it, and a click on an image or a diagram opens it larger (see Clicking in Preview). Since 0.20.0 In Source, a click places the cursor and Cmd/Ctrl+click opens a link in the background. With the cursor on a link, ModEnter follows it in either mode, and Mod. opens its card (see Writing from the keyboard). Since 0.20.0
• Find and replace: Cmd/CtrlF (or toolbar) opens the Find and Replace bar.
• Find selection: Cmd/CtrlAltF jumps to the next occurrence of the selected text, or of the word under the cursor when nothing is selected, without opening the panel. Press Cmd/CtrlG to keep going, Cmd/CtrlShiftG to go back. Since 0.12.0
• Undo/redo: standard Cmd/CtrlZ / Cmd/CtrlShiftZ, also available as toolbar buttons.

Clicking in Preview Since 0.20.0

In Preview, what a click does depends on what’s under it:

• A reference, such as a link, a tag or a person, goes where it points.
• A block, such as an image or a diagram, opens larger.
• Anything else is text: a click places the cursor.

A reference’s other actions are on its card, a right-click away. A block’s are on the toolbar that shows when you point at it, and in its menu.

The first time a click follows a link, a notice says: “Links open on click. Right-click to edit.”

Clicking links, tags and people

References are wikilinks (in table cells too), Markdown links, bare URLs, paths to files on your computer, #tags, mentions and a task’s assignee chip.

The person chips in a note’s attributes open the same way: a click opens the person, and Cmd/Ctrl+click opens them in the background. Their right-click menu and hover card are the ones under Person chips.

From the keyboard, put the cursor on the reference: ModEnter follows it, and Mod., ShiftF10 or the Menu key opens its card.

The card shows the preview at the top, then the reference’s actions. Open shows its keys. ↑ and ↓ move between the actions, and Esc closes the card and puts you back in the note.

• A link: Open, Open in background (for a note), Edit link…, Edit text, Copy link and Remove link, which keeps the text. Edit link… opens the link editor. A bare URL has no Remove link.
• A tag: Search #tag, Rename tag…, Merge into…, Edit text and Copy tag.
• A person: their card (email, phone, GitHub and website), then Open person, Open in background, Change person…, Edit text and the person’s other actions, such as Change handle @handle… and Find mentions (see Person chips).
• A path: Reveal in Finder (Reveal in File Explorer on Windows, Open Containing Folder on Linux) and Copy path. On the web, only Copy path.
• A reference inside commented text adds Open thread: a click on the reference follows it, so the card is where you reach the comment.

To change a reference’s text, choose Edit text on its card, move the cursor into it with the arrow keys, or click just beside it.

In Source, a click places the cursor, and Cmd/Ctrl+click opens the reference in the background.

Clicking images and diagrams

Blocks are images on their own line, diagrams (Mermaid, draw.io and other plugin diagrams), math on its own lines, a [TOC] table of contents and database views.

• A click on an image on its own line, or a diagram, opens the viewer: the image or diagram at full size over the app. Drag to pan, and use Zoom out, Zoom in and Fit to zoom. Its bar has Edit, Copy, Delete, ⋯ (Replace… and Download, for an image file) and Close; at phone width, ⋯ and Close. Esc closes it. An image inside a link follows the link instead.
• Edit opens the plugin’s own editor in a tab for draw.io and Mermaid; for anything else, it shows the block’s source in the note. A diagram that’s empty or failed to draw opens its editor on a click.
• A click on a math block or a table of contents shows its source to edit. A click on a table of contents entry jumps to its heading.
• A click on a database view’s frame, such as its header or footer, opens the database. Its rows and buttons work as usual.
• Cmd/Ctrl+click on a block does the same as a click.
• Pointing at an image, a diagram, math or a table of contents shows its toolbar. A block 360 pixels wide or wider shows View, Edit, Copy and Delete, plus ⋯ (Replace… and Download) for a file. A narrower image or diagram shows View and ⋯. Only the actions that apply show. A database view has no toolbar.
• A right-click on an image, a diagram, math or a table of contents opens the block’s menu, with all of its actions. A database view keeps its own menus.
• A video or audio player keeps its own controls.

From the keyboard, select the block, with Shift and the arrow keys or by moving onto it: Enter opens it as a click would, ShiftF10 opens its menu, and Delete or Backspace removes it (not a database view).

Clicking in read-only notes

A revision, a note in Trash and a shared note you can only read work the same way, without the actions that change the note: no Edit link…, Edit text, Remove link, Edit, Delete or Replace…. A click or ModEnter on a wikilink to a note that doesn’t exist does nothing, since following it would create the note; the card’s Open and Cmd/Ctrl+click still follow it. A note shared with you isn’t in any of your vaults, so its wikilinks don’t open and its tags don’t search.

While you’re suggesting, Edit link…, Remove link and Delete are written as your suggestions, or refused where a suggestion can’t go, such as a change to a link’s URL. Replace… isn’t offered.

Clicking on a phone

• While you read a note, a tap follows a reference or opens a block in the viewer, as a click does.
• While you edit, a tap on a reference places the cursor in it, so you can change its text (a tap on a mention selects it), and a small button shows under it to follow it: Open and the name, Search #tag, or the reveal item for a path. A tap on an image or a diagram still opens the viewer.
• Touch and hold a reference to open its card, or a block for its menu, as a sheet from the bottom of the screen.

The first time a tap follows a link, the notice reads “Links open on tap. Touch and hold for more.”

Vim mode Since 0.20.0

Pick Vim from the bottom bar’s view menu to edit with vim keys. Vim shows the raw Markdown as Source does, with relative line numbers, and the bottom bar shows which vim mode you’re in: NORMAL, INSERT or VISUAL. The choice is remembered on this device, like Preview and Source. The command palette also has Switch to Vim mode, which has no default key; you can give it one (see Keyboard shortcuts).

Vim is for the note editor only. Revisions, Trash previews, shared notes, Markdown files opened from outside a vault and the phone layout don’t use it.

• :w saves and commits at once, like Manual save. It commits the vault’s waiting changes, not just this note’s. A disk-only note isn’t committed.
• :q closes the tab. A pinned tab has to be unpinned first.
• :wq does both.
• Esc first closes an open menu (wikilinks, @ mentions, the slash menu, emoji). A second Esc goes back to Normal mode.
• In Insert mode, CtrlP and CtrlN list words from the note (the nearest ones above the cursor first for CtrlP, below for CtrlN), and move through any list that’s open. CtrlY accepts the highlighted word and CtrlE closes the list. On the web on Windows and Linux the browser keeps CtrlN (new window), so use CtrlP there.
• In Suggesting mode, edits made with vim keys are tracked as suggestions, like any other edit.

Find and replace

Cmd/CtrlF, Edit → Find and Replace or the toolbar’s Find and replace opens the Find and Replace bar, with the selection, or the word at the cursor, already in the Find field. The bar sits across the top of the note, full width, and stays in place while the note scrolls. Since 0.13.0 It stays open, with its query, when you switch between Source and Preview.

• Match case (Aa), Match whole word (ab) and Use regular expression (.*) are toggles inside the Find field. From the field, AltC, AltW and AltR switch them.
• The count beside the field reads “12 results”, then “3 of 12” once you’re on a match. It counts the note’s text, so matches hidden inside markup in Preview count too. Past 1,000 matches it reads “1,000+”. With no match, the field turns red, the count reads “No results” and the buttons are dimmed; an invalid regular expression says so in place of the count.
• Enter and ShiftEnter (or the up and down arrows beside the count) go to the next and previous match.
• Select every match with Cmd/CtrlShiftL or AltEnter in the Find field, to edit them all at once.
• Replace is folded away at first. Click the chevron at the bar’s left, or press Cmd/CtrlF again in the Find field, to show the Replace field with the Replace and Replace all buttons. Enter in the Replace field replaces the current match, and Cmd/CtrlEnter replaces them all. Since 0.13.0 The bar remembers whether Replace was open until you quit. A read-only note has no Replace.
• Find in all notes: the scope button beside the Find field takes the query, with its Aa, ab and .* settings, to the Search tab, which searches every note. When Replace is open, the Search tab opens with its Replace field open too, holding the same text, to replace across notes. Cmd/CtrlShiftF does the same from the note. Since 0.13.0
• While Suggesting, Replace and Replace all write each replacement as a tracked substitution, and the bar says “Replacements are added as suggestions.” Matches a suggestion can’t change, such as text already suggested for deletion or someone else’s suggestion, are skipped.
• While Editing, Replace and Replace all skip the matches in suggestion and comment markup: a suggestion’s delimiters and its {>>@name · date<<} author, and a comment’s entries. A replace never changes who a suggestion or comment is credited to. The text a suggestion adds or removes is replaced like any other. While the note holds suggestions or comments, the bar says “Matches in suggestion and comment markup are left as they are.” Since 0.13.0
• Esc closes the bar and puts you back in the note.

Find selection (Cmd/CtrlAltF) never opens the bar.

Right-click menus

What a right-click in the editor opens depends on whether you click inside a selection.

Inside a selection, on the desktop and on the web, Mahfouz opens its own menu:

• Cut, Copy, Paste
• Comment (see Comments)
• the toolbar’s Style, Text, Insert and Paragraph groups, in the toolbar’s order and with its labels. Each toolbar dropdown (Heading, Subscript / Superscript, Embed, List, Callout) is a submenu.

A check mark shows the formatting the cursor is in. A row that can’t be used right now is dimmed and says why, such as “switch to Editing to insert” while Suggesting. In a read-only note, such as a revision preview, the menu has Copy only. On macOS, Paste from this menu works like CmdV.

From the keyboard, Mod., ShiftF10 or the Menu key opens this menu for the selection, or a menu for the link, task, suggestion, tag, table or image at the cursor (see The menu at the cursor). Since 0.20.0

On a link, a tag, a person or a path, a right-click opens its card, and on an image, a diagram, math or a table of contents, the block’s menu (see Clicking in Preview). Since 0.20.0

Anywhere else in the editor, a right-click opens the system’s menu:

• In the macOS desktop app, that menu (spelling suggestions, Look Up, Writing Tools) has a Format submenu with the same items, in place of the system’s Font submenu. Since 0.12.0
• On the web, and in the desktop app on Windows and Linux, it’s your browser’s or system’s usual menu.
• In an unlocked encrypted note, no menu opens.

Outside the editor, a right-click opens no system menu, except in text fields. The app’s own menus (on sidebar rows, tabs and breadcrumbs) open as before. On the web this means the browser’s menu, with items such as “Open link in new tab”, isn’t there outside text fields.

Outline, table of contents & page preview

Three ways to find your place in a long note, all driven by the editor’s current scroll position (“whichever section is at the top of the viewport is active”):

• Outline (floating over the editor’s right edge) shows one short dash per heading (levels 1–6), deeper levels shorter, with the current section’s dash darker. Hover over it, or move keyboard focus to it, to open the list of headings; click one to jump the editor there. It’s hidden when the note has fewer than two headings, in the phone layout (a window narrower than 700px) and for encrypted notes. On a phone, Outline in the note’s toolbar lists the headings instead (Reading and editing a note). Since 0.17.0 Turn it off in Settings → General → Note outline. In a note with numbered headings, the list shows each heading’s number. Since 0.14.0 Right-click a heading in the list and choose Copy link to heading to copy a link to it. Since 0.14.0 From the keyboard, F6 reaches the outline; ↑ and ↓ move between headings, Enter jumps to one, and Esc goes back to the note. Since 0.20.0
• Table of contents (right sidebar) lists every heading (levels 1–6, ignoring anything inside a code fence) in the note, indented by level; click one to jump to it.
• Page preview (collapsible column to the left of the editor) shows thumbnail cards for each “page”: the note split wherever a bare --- line appears (the same rule presenting uses for slide breaks). Click a thumbnail to jump there. Drag cards to reorder pages, or right-click one for Move up / Move down / Delete page. It’s off by default: turn it on in Settings → General → Page previews. Switched off, the column isn’t shown at all, its collapse bar included.