Notes, links & search

Notes & organization

Every note is a single Markdown file, <note-id>.md, at the vault root. The moment a note gets its first child it becomes a folder of the same name holding its own file (<note-id>/<note-id>.md) and its children (<note-id>/<child-id>.md, nesting the same way). Once a note has a folder it keeps it. You never see these paths day to day — the Sidebar presents them as a normal expandable tree. Vaults created before this layout are offered a one-time migration on open; declining keeps the older one-folder-per-note shape, which still works.

• New note: Cmd/Ctrl+N creates a sibling of whatever’s selected; Cmd/Ctrl+Shift+N creates a child of it; Cmd/Ctrl+Alt+N creates a note at the parent level. Each vault section also has a + button in the Sidebar for “new note here.”
• Title: there’s no separate title field — a note’s title is always the first non-empty line of its body (with a leading # stripped if present). Rename a note by editing its first line.
• Reordering / nesting: drag a note in the Sidebar to reorder it or drop it onto another note to make it a child.
• Moving to another vault: drag a note onto a note, a folder or the name of another vault in the Sidebar. The note moves, along with every note under it. Hold Option (Alt on Windows and Linux) when you release to copy it instead. The original stays where it is, and the copy gets new ids.
  • Images and other attachments the note links to are copied into the other vault’s files/ folder, and the links are updated. Linked files that no longer exist are skipped; the message after the move says how many.
  • The move is committed in both vaults: Moved from <vault>: <title> in the new one, and Deleted: <title> in the old one. You can bring the note back from Trash in its old vault.
  • Links to the note from notes in its old vault stop working. If any exist, or the note has notes under it, Mahfouz asks before it moves anything.
  • Files in the note’s folder that it doesn’t link to stay in the old vault.
  • A note whose auto-commit is off (disk only) can’t be moved or copied to another vault. Turn auto-commit back on first.
• Folders: a folder doesn’t have to belong to a note. Right-click a plain folder in the Sidebar for New note, New folder, Rename folder (edit the name in place: Enter saves, Esc cancels), Reveal in Finder, and Delete folder.
• Breadcrumb: the bar above the editor shows where the open note lives: the vault, then every folder it’s nested in. Click a folder that belongs to a note to open that note; click a plain folder to show it in the Sidebar.
• Sidebar menu: right-click empty space in the Sidebar for New note and New folder (in the active vault), New vault…, Open vault…, and the grouping, sort and filename-display options.
• Reveal in Finder is called Reveal in File Explorer on Windows and Open Containing Folder on Linux.
• Bookmarks: click the ribbon icon on a Sidebar row, or use the toolbar’s ⋯ menu → Bookmark, to pin a note. Cmd/Ctrl+2 jumps to the Bookmarks view (a flat list across all vaults).
• Unimported files: if you drop a plain .md file into the vault folder outside Mahfouz (no id: in its frontmatter), it shows up right away in the Sidebar as a clickable “pending” row, in the folder (or under the note) it was added to. Mahfouz doesn’t touch the file until you edit it there: the first edit imports it — Mahfouz adds the id it needs and leaves everything else alone.
• Edits from other apps: Mahfouz watches the vault folder. When another app changes the note you have open, the editor updates in place within a second, keeping your cursor where it was (Cmd/Ctrl+Z undoes the reload). If you were typing at the same moment, a banner offers to reload or resolve the conflict instead, so your unsaved typing is never overwritten.
• Status dots: each Sidebar row shows a small dot indicating whether the note has uncommitted changes, is synced to a remote, or is local-only. A note with auto-commit off also shows a drive glyph (see Auto-commit and disk-only notes).
• Sort order: toggle alphabetical vs. chronological (by last-updated) ordering from the Sidebar header in Trash/Bookmarks views, or globally via Settings.

Links, wikilinks & backlinks

• [[Note Title]] links to another note by its exact title (case insensitive). Type [[ to trigger autocomplete of existing titles. A wikilink to a title that doesn’t exist yet still renders, just styled as “broken” until a matching note is created.
• Pasting a bare URL over an empty cursor wraps it as <url>; pasting over a text selection turns the selection into [selected text](url).
• Backlinks: the right sidebar’s “Linked from N notes” section lists every note that links to the one you’re viewing (via [[wikilink]] or a regular link to its title). The backlinks pill above the note shows the count and opens it (see Note pills).

Tags

Any # immediately followed by a letter (and not inside code) is a tag — #project, #ideas, etc. Tags are indexed automatically:

• The Sidebar’s Tags view (Cmd/Ctrl+3) lists every tag with its note count; click one or more to AND-filter notes, “Clear” to reset.
• The lighter-weight Tag filter chip row offers the same picker in contexts that don’t want the full Sidebar view.

Search

Cmd/Ctrl+K opens the search overlay — searches across all open vaults as you type (debounced), matching title and body text with multi-term AND matching, ranked roughly: exact title match, then title-starts-with, then title contains all terms, then title contains the whole phrase, then body-only matches. Matched terms are highlighted in the title and a generated snippet. With an empty query it shows your 8 most recently edited notes instead. Navigate results with ↑/↓ (or Ctrl+P/Ctrl+N), Home/End, and open with Enter.