Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Notes

In the note editor, the formatting toolbar provides bold, italic, inline code, links, headings, lists, quotes, and code blocks. Heading, list, quote, and code block actions apply to the selected lines.

Browse gives the note list about a quarter of the available width by default. Drag the divider to resize the list and preview. This session-local size is independent of the editor’s source/preview divider.

Sidebar shortcuts can be reordered by dragging a note onto another shortcut.

Notes is experimental and hidden by default. Turn it on in Settings → Views.

Library

Choose an existing folder of Markdown files. Productivity indexes it locally; Refresh rescans it. The Markdown files remain the source of truth.

Browse

  • The row under the page title shows how many notes the folder holds and where it is, with Choose folder…, Refresh, Import…, Recovery, and Export all….
  • Search matches titles and file contents. Press Enter or Search to apply it.
  • Sort by title, created, modified, or journal date. Each card shows its journal date (or Undated) before its file name.
  • Filter by project (shared with the task views) and by linked task or unlinked notes.
  • Click a note for a read-only preview; the selected note is highlighted. ↑ / ↓ move through the list and update the preview. Links, images, and HTML are inert, and previews are limited to 1 MiB.
  • The preview’s header reads like an e-mail: the note’s title with its action buttons, then its file, journal date, and creation time, with the time the file last changed on disk (including edits made in other apps) on the right. Below, Linked shows each linked task as a mini card (type icon, title, status, due date) and each project with its task count; click a card to open its details, or × to unlink it. The picker beside them links another task or project. Write shows the same cards beside its formatting toolbar.
  • The preview is an embedded block editor: click a block to edit it right there, as in Blocks. Your changes go into the same draft as Write and are saved the same way. Click beside the blocks, or select another note, to stop editing.
  • Double-click a note in the list, or a shortcut’s full preview, to open it in Write.
  • The star adds the note to Shortcuts, the pen opens the editor, and the arrow opens a full preview. The same three actions appear in each card and in the preview’s toolbar. Back returns to where you were.

Editing

The current local day appears above the page title, just as in the other views. The editor offers Edit, Split, Preview, Live Edit, and Blocks layouts. Split and Preview show a live, inert preview. Edits autosave after a one-second pause; Save or Cmd+S / Ctrl+S saves immediately. The row under the page title holds the note’s name (click it to rename the note within its folder), its save state, Save, discard (↶), delete (trash), and the full-preview arrow. Below it, a compact icon toolbar formats the text: bold, italic, inline code, and link; heading 1, heading 2, list, task checkbox, quote, and code block; and insert image. Inline code and quote toggle off when applied again; a code block fences the selected lines, or puts the caret between new fences. Hover an icon for its name and shortcut.

  • Find: Cmd+F / Ctrl+F opens a search panel in the source. Undo and redo work as usual.
  • Format: Cmd+B / Ctrl+B and Cmd+I / Ctrl+I wrap the selection in bold or italic markers, or remove them again. Cmd+K / Ctrl+K turns the selection into a link and selects url so you can type the address.
  • Lists: Enter continues a list item (-, *, +, 1., 1)), a task item with a new open checkbox, or a quote. Enter on an empty item moves it out one level, or ends the list. Tab nests the selected items under the item above; Shift+Tab moves them out one level. Shift+Enter is a plain line break. In fenced code and ordinary text these keys keep their usual meaning.
  • Tasks: Cmd+Alt+X / Ctrl+Alt+X, or the task-checkbox icon, adds [ ] to the selected lines, turning plain lines into task items, and checks or unchecks existing ones. This only changes the note’s text; it never completes a task in Productivity’s task views.
  • Layout: Cmd+Alt+P / Ctrl+Alt+P cycles Edit, Split, Preview, Live Edit, and Blocks. In Split, Cmd+Alt+[ and ] (Ctrl+Alt+[ and ]) narrow or widen the source pane; dragging the divider works too.

Live Edit

Live Edit formats the Markdown you are writing in place: headings, bold, italic, strikethrough, inline code and code blocks, links, lists, quotes, and checked task items (dimmed and struck through). The syntax stays in the text. Markers such as #, **, and link addresses are dimmed, and show in full in the block around the caret so you can edit them.

It reads like a page: a centred column of slightly larger, more widely spaced text without a frame. List bullets, numbers, and task checkboxes stay visible in the accent color.

  • / menu: type / at the start of a line for Heading 1–3, Bulleted list, Numbered list, To-do, Quote, Code block, Link, or Divider. Code block puts the caret between its fences and Link where its text goes. Keep typing to filter (/todo), choose with the arrow keys and Enter or a click, or press Escape. The /word is replaced by the block’s Markdown. A / inside a sentence stays text, and Edit and Split have no menu.

  • Checkboxes: click a [ ] or [x] to check or uncheck the item; the caret stays put and the change is an ordinary, undoable edit of the draft.

  • It is the same text as Edit and Split. Switching layouts keeps the draft, selection, and undo history, and never saves or changes the note; copying copies Markdown.

  • Headings are bold and colored but keep the body text size, and syntax is dimmed rather than hidden.

  • Tables, raw HTML, images, and Mermaid blocks stay plain, editable source.

  • Clicking places the caret. Cmd+click (macOS) or Ctrl+click on a link opens it in the browser (http(s) and mailto only); clicking a checkbox is the only click that changes text.

  • Notes over 128 KiB are shown as plain Markdown while typing, because formatting them would trail behind the keyboard.

  • + New Note opens a blank draft with a name field. Create note saves it, even when empty; an existing name is rejected, and a blank name becomes a unique Untitled.md.

  • Linked beside the formatting toolbar in Write (on its own row in Preview) shows the tasks and projects the note is linked to as mini cards. Click one to open its details without losing unsaved task or note text; ← Back to note returns to Write. Links are many-to-many: a note can be linked to several tasks and projects, and a task or project to several notes. Add or remove links in Browse.

  • New note in a saved task’s or project’s details, beside Linked notes, starts the same draft named after the task or project. Create note creates it and links it to that task or project; your unsaved task or project draft stays open. Characters not allowed in a filename, such as /, become -. The button shows only while Notes is enabled.

  • New notes default to today’s journal date; the calendar picker can change or clear it.

  • Productivity stores its metadata as YAML front matter. Notes without metadata ask for consent before the first save adds it.

  • If the file changed on disk, Compare shows the external version, Save local copy writes a separate Recovered-<UUID>.md, and Reload external replaces the draft after a second confirmation.

  • Closing the window or quitting saves a dirty draft first and stops if that fails. Forced termination can still lose unsaved text.

Blocks (early)

Blocks, the layout after Live Edit, is the start of a Notion-style editor. It shows the note as formatted blocks in a centred column: headings, paragraphs, each list item, quotes, code, dividers, tables, and front matter.

  • Click a block to edit its Markdown in place; the field grows with the text. Press Escape or click beside the blocks to finish. Click the empty line below the last block, or press Enter at the end of it, to add a block at the end.
  • Enter starts a new block below, splitting the text at the caret. In a list the new block is the next item (the next number, or an open checkbox after a task); Enter on an empty item ends the list. At the very start of a block, Enter opens a new block above it. Inside a code block Enter is an ordinary line break.
  • Shift+Enter breaks the line inside the block.
  • Backspace in an empty block removes it and continues at the end of the block before.
  • The block being edited has its own formatting strip: bold, italic, inline code, link, quote, and code block. Cmd/Ctrl+B, I, K, and Alt+X work there too.
  • Type / at the start of a line in a block for the same menu as Live Edit, shown under the block: Up/Down choose, Enter inserts, Escape closes it.
  • Links are blue; Cmd+click (macOS) or Ctrl+click opens one in the browser, and a plain click edits the block. Only http(s) and mailto links open.
  • The note is drawn as a page, apart from the app around it.
  • Click a task’s checkbox to check or uncheck it without opening the block.
  • It edits the same draft as the other layouts: every change is in the draft at once, and autosave and Save work as usual. Only the edited block’s text is replaced; blank lines and everything else stay exactly as written.
  • If the block’s text changes elsewhere while you edit it, the block closes instead of overwriting that change. Notes over 128 KiB and notes with an unresolved conflict are edited in the other layouts.
  • Not yet: arrow keys between blocks, undo across blocks, and dragging blocks.

Images

The insert image icon in the formatting toolbar copies a PNG, JPEG, GIF, or WebP file (up to 20 MiB) into the folder’s assets/ directory, under a new name if one is taken, and inserts a relative link at the caret. Previews show relative images that stay inside the notes folder. Remote, absolute, SVG, and out-of-folder images stay inert placeholders. Other attachments are ordinary links; Productivity has no viewers for them.

Import and export

Both copy files and never replace existing ones.

  • Import… in Browse copies Markdown files or folders from outside the notes folder.
    • A folder becomes a new top-level folder with the same name (Name 2 if taken). It keeps its Markdown files and images at their relative paths. Other files and symbolic links are skipped.
    • A file goes into the notes folder’s root (name 2.md if taken), along with the images it links inside its own folder. If one of those image paths already holds a different file, the note is skipped. Import its folder instead.
    • Imported files are copied byte for byte. A file whose Productivity ID is already used in the library is the exception: its copy gets a new ID. Links and shortcuts are never copied, and metadata-free files stay metadata-free.
  • Export all… in Browse, or Export… in a note’s preview toolbar, copies notes and the local images they reference to a folder you choose. Paths stay relative to the notes folder, so image links keep working in other Markdown apps. If any target file already exists, nothing is written. The export holds only Markdown and images. Task and project links and shortcuts stay in the database (see Data, backups, and logs).

Recovery and deletion

Recovery in Browse lists copies kept outside the notes folder: drafts whose save failed, conflicting local edits, interrupted operations, and deleted notes. For each entry you can View its text, Save as new note (a Recovered-<UUID>.md file with a fresh ID), Restore a deleted note to its original path (only if that path is free), or discard it after a second confirming click. Entries stay until you discard them.

The delete (trash) icon in the editor works on a saved note with no unsaved changes, after Confirm delete. The file’s content moves to Recovery. Browse keeps listing the note as missing so its links and shortcuts survive a restore.

Supported Markdown

Previews follow CommonMark plus common GitHub extensions: tables, task lists (read-only), strikethrough, and fenced code. Raw HTML is never executed. Links in the preview are inert; safe http, https, and mailto links appear as separate Open buttons that need a click. Productivity does not render Obsidian wikilinks or plugin syntax, but keeps such text unchanged in the file.

Mermaid diagrams

A fenced code block whose language is mermaid appears as a diagram in every preview:

```mermaid
flowchart LR
  Idea --> Task --> Done
```
  • Rendering: diagrams are drawn by merman, a native Rust implementation of Mermaid. No JavaScript, browser, or network access is involved. They follow Day or Night appearance and re-render when it changes. Labels are sized with the fonts installed on your computer, so the first diagram after starting the app can take a moment longer while they are found.
  • Diagram types: flowcharts, sequence, class, state, ER, Gantt, pie, journey, timeline, mindmap, Git graph, quadrant, XY, sankey, C4, architecture, block, packet, requirement, kanban, radar, treemap, and others that merman supports.
  • Errors and limits: while a diagram renders, or if it is invalid, the preview shows its source, with a short error below an invalid block. Diagrams over 64 KiB, or that take more than 3 seconds, are not drawn. Errors never affect saving.
  • Differences from other apps: the file keeps the block unchanged, so other Markdown apps render it their own way. Output can differ slightly from mermaid.js, and the ELK layout is not included, so layout: elk uses the default layout. click links and callbacks are removed, and diagrams cannot load images or other files.

Editing outside Productivity

The notes folder is ordinary files. You can edit, add, rename, or delete notes in other apps, and Browse follows those changes. A clean editor reloads an external change automatically. A dirty editor reports a conflict instead (see Compare above). Productivity checks the file right before replacing it, but it cannot lock files against other editors. Saving in two apps within the same instant can still lose one of the edits. File interoperability is not sync, so do not point two running copies of Productivity at the same database.

Shortcuts

Star or unstar notes from Browse or a preview. Starred notes appear in the sidebar’s Shortcuts section: drag them to change their order, or click one to open it. The star next to the opened note’s edit button removes the shortcut without deleting the file. There is no separate shortcut-management screen. Legacy groups appear as one deduplicated list; unstarring removes a shortcut from every group, including when its note is unavailable.