User guide

1What is MesoNotes?

MesoNotes is a free, open-source desktop program for Linux and Windows. It keeps your notes, tasks, Kanban boards, calendar, canvases and longer pieces of writing in one place.

The most important thing to know: your data is on your own computer. There is no account, no sign-up, no MesoNotes server. The program works fully without the internet. Anything goes out to the network only if you set it up (backup to a NAS or to S3 storage, sync, Google Calendar, weather, saving a web article, looking for a new version) – the chapter Privacy and security has the exact list.

This guide was written for version 1.0.

2Installation and first start

Linux

MesoNotes comes in several packages, in the Download section of the website; pick the one for your system. The files are downloaded from the releases of the program's GitLab page, where the source code and the earlier releases are found too.

An installed package adds a menu entry, and the program can be started with the mesonotes command as well. The AppImage is a single file: put it wherever you like. To update, install the new package over the old one the same way; your data stays where it is. Whether a newer release is out, the program tells you in the status bar – if you let it: see A new version.

Checking the download

On the website every package has its SHA-256 checksum beside it. It is the file's "fingerprint": if the checksum of the file you downloaded is the same, the file is intact and is exactly what was released.

• On Linux: sha256sum MesoNotes-*.AppImage (or the name of the package you downloaded) – compare the long string it prints with the one on the website.
• On Windows, in PowerShell: Get-FileHash .\MesoNotes-*-portable.exe -Algorithm SHA256 (for the installer give the *-setup.exe name)

If the checksums differ, do not start the file: download it again.

Windows

On Windows you get it in two forms: with an installer (MesoNotes-<version>-setup.exe) or as a portable program (MesoNotes-<version>-portable.exe, a single file).

• The installer installs for your user only; no administrator rights are needed. The folder can be chosen (%LOCALAPPDATA%\Programs\MesoNotes by default), a Start menu and a desktop shortcut are made, and the uninstaller is in the list of programs of Windows. The installed program keeps its data in the %APPDATA%\MesoNotes folder, and its workspaces go into Documents\MesoNotes. A new version is installed over the old one; your data stays. When you uninstall, the uninstaller asks whether your data should go too (by default no, and it asks once more). Uninstalling never deletes the backups and the synced data on the NAS, S3 or Google Drive.
• The portable version runs without installing. It keeps its data in the MesoNotes-data folder beside the program, so together with that folder it can be carried on a USB stick or moved to another computer. Put it somewhere it can write to (not under Program Files).

The installed program can take over the data of the portable version: it asks at the first start, and later you can do it with Settings → Backup → Restore → Take over the portable version…. The takeover brings over the settings, the sign-ins and the workspaces; the portable folder is only read. (Note: the current settings and workspace list of the installed copy are replaced by those of the portable one; the program restarts.)

Backup to a NAS works on Windows too (you give the share by its network path, \\NAS\data\MesoNotes or smb://…; it uses the SMB client of Windows, no smbclient is needed), and so does starting at login (Settings → General → Tray; for the installed and for the portable version alike).

The first start

At the first start MesoNotes creates a workspace called Personal (Személyes with the Hungarian interface) in your Documents folder, in the MesoNotes subfolder, and opens it.

Before that, a setup wizard takes you through what is set only once – and easily forgotten: language and theme, what opens at the start, looking for new versions, the tray and starting at login, backup and sync (and, if you already use MesoNotes on another computer, downloading your workspace), email notifications, the weather, and at the end how the calendars can be connected. Any step – or all of it – can be skipped, and the wizard can be run again: Settings → General → Setup wizard.

• The program starts in the language of your system: in Hungarian on a Hungarian system, in English everywhere else. You can switch later with the HU / EN button at the right end of the status bar (or: Settings → Appearance → Language and fonts). On a system in another language the program offers to look for a community translation of it.
• The first backup is made by itself a few minutes later, into the Documents/MesoNotes/Backups folder. More on this in the Backup chapter.
• Coming from another computer? If the backup and sync places you set up (NAS, S3, Google Drive, rclone, a backup folder) already hold a workspace of yours, the program offers to download it – the one changed most recently recommended.
• If you skipped the wizard, a card in the bottom right corner asks whether the program should look for new versions. Until you answer, nothing goes out to the network for this.

A new version

MesoNotes does not update itself, and it does not look for updates unasked either. If you answer yes to the question of the first start (or switch it on later: Settings → General → Start → Look for a new version daily), the program looks at the list of releases on the website once a day. If there is a newer one, the New version: … label appears at the right end of the status bar; a click opens the download part of the website in your browser.

• The program reads nothing but the version number from that list. It sends nothing about you or your notes, and it downloads and installs nothing by itself – you install the new package, as described above.
• If you answer no, the program never goes out to the network for this. You can change your mind with the switch at any time.

3The interface

1. Title bar and search. Click the field in the middle (or press Ctrl+K) to search your notes and to run commands.

2. Left rail – the modules. From top to bottom: Start page (if it is turned on), Notes, Tasks, Boards, Canvases, Graph, Today's note, Calendar, Writing, Timers, Games, News, Vault. At the bottom: collapsing the sidebar, Trash and Settings. The modules can be reordered by dragging; Alt+1 … Alt+9 always follow the current order. The icon of a module you do not use can be hidden (Settings → Appearance → Left rail).

3. Sidebar. At the top the workspace switcher and a row of buttons: New note, new folder, new note from a template, new section. Below it the tree of Folders – split into sections of your own, if you like –, the Special group (Favourites, Journal, Boards, Canvases, Writing and the others), the Vault, and at the bottom the Tags.

4. Tabs. Every open note can have its own tab. New tab: Ctrl+T, close: Ctrl+W, switch: Ctrl+Tab or Ctrl+1 … Ctrl+9.

   Two notes side by side: right-click a text note in the tree, on its tab or on a link to it → Open beside (on a link Shift+click too) puts it on the right. Both sides can be written in; the main toolbar works on the side you are using. In the right side's header: swap the two sides, open as a tab, close. The divider can be dragged, a double click makes it half and half. F8: off / on (with the note that was beside last). The same note is never on both sides; it is kept and comes back after a restart.

5. Toolbar. Formatting and inserting. The groups of the toolbar can be reordered (right-click the toolbar → Rearrange toolbar).

6. The note's header. Icon, title, dates, and below them the buttons: Favourite, Lock, History, Info, Tasks and the tags.

7. Status bar. From the left: whether the note is saved, the size of the workspace, the last backup and the state of the sync (a click opens their settings), the running timers. From the right: word count, language switch, version number – and, when a newer release is out, the New version label.

The size of the whole interface is set with Ctrl+= and Ctrl+-, or with Ctrl + the mouse wheel; Ctrl+0 is the original size.

Search and the command palette

Ctrl+K is the most important key of the program.

• Search: start typing; MesoNotes searches the titles and the text of your notes. Enter opens the result, Ctrl+Enter opens it in a new tab.
• Commands: type > (or press Ctrl+Shift+P) and every command of the program can be searched: change the theme, switch the language, switch workspace, Markdown import and export, back up now, new canvas, save an article from a web address, and so on.
• A timer in words: "timer 25 min pasta" or "remind me at 11:10" – Enter starts it.

4Notes and folders

Creating, renaming, moving

• New note: the New note button or Ctrl+N. The note goes into the folder that is selected at the moment (with a note selected: beside that note). If the selected row is not on screen just then – it is in a collapsed folder or section –, the new note goes to the top level, into the Folders part, so that it is in sight.
• New folder: Ctrl+Shift+N, by the same rule. Folders can be nested to any depth.
• Rename: F2, or simply rewrite the title at the top of the note.
• Move: drag it into another folder with the mouse, or right-click → Move › To a folder… (with a folder search).
• Several items at once: Ctrl + click selects them one by one, Shift + click selects a range; the selected items can be dragged, deleted and exported together, and tagged in one go.
• Copy: right-click → Make a copy.
• Delete: Delete, right-click → Delete, or the bin that appears at the right end of the row under the mouse. (A locked note and the folders of the Special group have no bin.)

The right-click menu has everything that can be done with a note or a folder, in submenus: New › (note, canvas, drawing, mind map, folder), Templates › (a note from a template, the folder's default template, save as a template), Properties › (pin, favourite, lock, task tracking, icon, colour, journal folder), on a folder Sort by ›, Move › (to a folder, and the sections), Export / import › (Markdown, copy as Markdown, PDF, print, import here). Rename, Make a copy and Delete stay at hand, and so do the own commands of a special folder (Today's note, Save a web page…). A submenu opens with the mouse or with →, ← goes back.

The middle always shows what is selected in the tree: a click on a note shows the note, a click on a folder shows the folder's page. A right-click does not move the selection – it only outlines the row the menu belongs to.

The page of a folder

A click on a folder opens the folder's own page. It has two parts:

• Contents (on the left, in a narrow column): the sub-folders and notes of the folder, in the order of the tree. A click opens them (Ctrl + click or the middle button: in a new tab); the two buttons in the column's header make a new note or sub-folder here.
• Description (on the right): this is where you write what the folder is for – with text, pictures, tables, links. It is the same editor as in the notes, with its whole toolbar; an inserted picture can be aligned left, centre or right. So the page of a folder serves as a cover for everything in it.

The Lock description button in the header makes the description read-only, so that a stray click cannot spoil it. It guards the description only: the folder can still be renamed, moved and deleted.

The description belongs to the folder: it is in the backups and in the sync, and the search finds the folder by its words. It does not make the folder a note – it has no word count, and its checkboxes do not go among the Tasks. In a narrow window the contents stand above the description.

Sections in the sidebar

If you have many folders at the top level, you can sort them into sections: named, collapsible groups in the sidebar, for example Work, Personal, Archive. A section only groups – your folders and notes stay where they are, nothing is moved.

• New section: the New section button in the row of buttons at the top of the sidebar; you type its name at once.
• Putting things in: drag a top-level folder or note onto the header of the section (or before or after a row that is in it), or right-click the row → Move ›, and pick the section under To a section:. Taking it out is in the same place: Take out of the section.
• The header: a click collapses it (it then says how many rows it holds), a double-click renames it. With the mouse on the header, four buttons appear at the right end: rename, icon, colour and the bin. A right-click: a new note or folder in the section, an icon and a colour, up / down, remove.
• Sorting: right-click the section's header → Sort by ›: by name, modified, created, rating or by hand, ascending or descending – one click, and the menu closes; the current choice is ticked. Each section keeps its own; the Folders and Special blocks' headers do the same.
• Removing: deletes nothing – the rows of the section go back to the Folders part. The bin (or the right-click menu) asks for confirmation first.

Every section has a faint frame, in its own colour if you gave it one; what is in no section stays in the Folders part. The sections belong to the workspace and are synced; which ones are collapsed is remembered on each computer separately.

Folders, Special, the Vault and the Tags are framed blocks like these too: they collapse the same way and can have an icon and a colour (the header's buttons, or right-click). A block can also be removed – nothing is lost: the folders stay in the list without a frame, and Special and the Vault are reached from the rail. To bring a block back, right-click the empty part of the sidebar → Removed blocks.

Every special folder is in the Special block even while it is empty: one not made yet (Web clips, say) is shown faint – point at it to see what it is for, click it to start it (the Journal with today's note, Web clips with the clipper, and so on). One you do not use can be hidden with the crossed-out eye at the right end of its row; the eye button of the header (or right-click → Hidden items) lists the hidden ones, a click brings them back. These belong to the workspace too, and are synced.

Icons, colours, sorting

• Icon: right-click → Change icon…, or click the icon beside the note's title. There are four kinds of icon to choose from: an emoji (searched by name); an icon from the Font Awesome, Lucide or Tabler set (chosen on the Icons tab); Apps – the logos of nearly three thousand programs and services (Nextcloud, Jellyfin, Home Assistant…), searched by name; or a picture of your own (PNG, ICO, SVG, JPG or WebP, 1 MB at most – picked from a file or dropped in). The logos come with the program, they need no internet.
• Colour: folders and notes can both be coloured: right-click → Properties ›, on a folder Colour and filter…, on a note Colour…. The picker has the eight basic colours, a colour of your own (with the system's colour picker, or typed in as a #rrggbb code) and the colours of your own used last. The colour tints the icon in the tree, among the favourites and in the note's header, and the note's point in the Graph.
• Sorting a folder: right-click → Sort by ›. The contents of a folder can be sorted by hand (by dragging), by name, by when they were changed or created, or by rating, ascending or descending. You can also filter by rating (for example "at least 4 stars"): Properties › Colour and filter….

Favourites and locking

• Favourite (Ctrl+D): the note appears in the Favourites part of the sidebar and on the start page.
• Lock (Ctrl+L): the note becomes read-only – it cannot be edited, moved or deleted until you unlock it. Good for final texts and for templates.

Trash

A deleted note or folder goes to the Trash (left rail, at the bottom), from where it can be restored – a folder with everything that was in it. Right after deleting, the notice at the bottom of the screen has an Undo too.

By default the contents of the Trash are deleted for good after 30 days. This can be changed in the Trash view: never, 7, 30 or 90 days. By hand it is emptied with the button of the Trash view, or with a click of the middle mouse button on the Trash icon of the left rail (it asks first).

5The editor

You do not have to take care of saving: MesoNotes saves all the time as you type. The green dot and the word Saved at the left end of the status bar tell you so.

Three ways to the same thing

Anything can be inserted or formatted in three ways; use the one that suits you.

1. The toolbar above the note.
2. The / menu: type / at the start of a line, then the name of the block (for example /tab → Table), and press Enter.
3. Shorthand while typing – the marks known from Markdown:

The floating menu

Select a piece of text: a small menu appears above it with the most common formatting (bold, italic, link, colour, highlight, block type, brush). Which buttons it has is set on the Settings → Editor → Floating menu tab.

The brush (copy formatting) works as in word processors: put the cursor in the text you want to copy the formatting from, click the brush, then select the text it should go to.

Moving blocks

Every paragraph, heading, list and table is a block. Move the mouse over one and a handle appears at its left edge:

• drag it to move the block;
• click it for a menu: turn the block into another type, duplicate it, move it up / down / to the top / to the bottom, delete it.

With the keyboard: Alt+↑ and Alt+↓ move the block, Ctrl+Shift+D duplicates it. Headings can be folded: the part below a heading is hidden with one click.

Selecting lines from the margin

In the empty strip left of the text the mouse pointer turns into an arrow leaning to the right – here you select whole lines, as in a word processor:

• a click: the line beside it (one row of the screen, not the whole paragraph);
• dragging up or down: the lines you pass;
• Shift + click: extends the selection to that line.

It works beside paragraphs, headings, lists, quotes and code; not beside tables and columns. The handle of the block keeps its place: a click on it still opens its menu.

What you can insert

• Table: choose a size, with or without a header row. Right-click in the table to insert rows and columns, merge cells, choose a header colour; the columns can be made wider or narrower by dragging. Sorting: the small arrow at the right of a header cell puts the rows in Ascending or Descending order — numbers by their value (1,234.5, %, currencies too), dates by time, text alphabetically; the header row stays in place, Ctrl+Z puts the rows back. Summary row: switched on on the table's bar (Σ) or in its menu; the last row counts live, and for each cell (at its top left corner) you can choose: sum, average, count, minimum or maximum. In exports and prints it is an ordinary row.
• Callout: a coloured box with a title and an icon – Note, Info, Tip, Warning, Error, Bug, Question and so on, thirteen built-in types in all. The box can be folded. You can make your own types too, with a name, a colour and an icon: Settings → Editor → Callouts.
• Code block: with a language picker and highlighting, and a Copy button; the Discord button copies it as a Markdown code block (for chats, GitHub).
• Toggle block: a title with content below it that can be hidden.
• Columns: 2 or 3 columns side by side.
• Table of contents: from the headings of the note; it updates by itself.
• Image or file: see the next section.
• YouTube video: by pasting its address.
• Footnote (Ctrl+Alt+F): a numbered mark in the text; the footnotes gather at the bottom of the note.
• Special character (Ctrl+Alt+X): °C, ½, →, € and the like, from a panel you can search.
• Rating: stars (for a book or a recipe, say); folders can be sorted and filtered by it.
• Today's date, timer, divider, icon.

Images and attachments

There are three ways to put an image or a file into a note: drag it in from the file manager, paste it from the clipboard (a screenshot too), or use the paperclip button of the toolbar (Ctrl+Shift+A).

• An image is shown in the note: it can be resized by its corner, aligned left, centre or right, or have the text wrap around it, and it can have a caption. A click opens it in full size; for a photo, Photo info shows the camera, the lens and the exposure.
• Audio, video and PDF can be played or viewed in the note.
• Every other file appears as a card; a double-click opens it with the system's default program. Right-click: show in the file manager, save as, replace the file.

Attachments are stored in the workspace's folder, and they are part of the backups and of the sync too. The same file takes up space only once, however many notes it is in.

Attachments that are no longer used anywhere can be deleted at Settings → Workspaces → Unused attachments.

Find and replace in a note

Ctrl+F finds, Ctrl+H replaces in the note that is open. Matching the case and Whole word can be turned on.

Spelling and typography

• Spell checking works in English and in Hungarian at the same time; right-click an underlined word for suggestions, or add the word to your own dictionary. The dictionaries come with the program, no internet is needed for them.
• Smart typography corrects as you type: "…" → “…”, -- → –, ... → …, -> → →. It does not touch anything in code.
• Block numbers (Ctrl+Alt+B) number the blocks in the left margin – useful when you discuss a text with someone.
• Indenting the content under headings makes a long note easier to take in; it is only for the display and does not change the export. If you do not want a paragraph (a table, a picture…) indented under its heading: put the cursor at the very start of the block, and Shift+Tab takes it out, Tab puts it back – or choose Out of the heading (no indent) in the menu of the block's handle. (In a list Shift+Tab moves the list item out instead; use the menu there.)

Each of them is switched on the Settings → Editor → Editing tab.

Details and contents

Ctrl+Alt+D (or the Info button of the header) opens the note's details on the right: a clickable table of contents, statistics (words, characters, reading time), the attachments, and the incoming and outgoing links.

History

While you edit, MesoNotes puts away a version of the note every 10 minutes. With the History button (Ctrl+Alt+H):

• you can look at any earlier version, and at what changed compared with the current text or with another version;
• you can restore a version – the current state goes into the history too, so this can be undone as well;
• Save version now makes a marked point. A version that you give a name is never deleted by the program (of the unnamed ones the newest 200 are kept for each note).

Printing, PDF, copying

• Print: Ctrl+P. Export to PDF: Ctrl+Alt+P.
• Copy as Markdown: Ctrl+Shift+C – the note goes to the clipboard as Markdown text and can be pasted anywhere.
• Export to Markdown: right-click the note or the folder; see the Import and export chapter.

6Links, tags, dates

Linking to another note

Type [[ (or press Ctrl+J) and start writing the name of the note. If there is no such note yet, you can create it right there. A click on the link opens the note it points to; when a note is renamed, the links to it change with it.

What links to a note is shown by the Incoming links part of the Details panel, and the whole web is seen in the Graph view.

A link to a web address: Ctrl+Shift+K. Ctrl + click opens a link in the browser.

Tags

There are two ways to add a tag:

• in the text: #something – it may contain letters, digits, _, - and / (no dot and no space), for example #mesonotes/dev;
• in the note's header with the Tag button (three at most here; the tags written in the text come on top of these).

The Tags block at the bottom of the sidebar lists every tag; click one to see all the notes that have it. Like the other blocks it collapses (closed, it says how many tags there are), can have an icon and a colour, and the right-click menu of its header sorts the tags by count (the default) or by name.

Several notes at once: select several notes in the tree (Ctrl or Shift + click), then right-click → Add a tag… or Take a tag off…. If the open note is among the selected ones, the Tag button of the header works for all of them too – its label says for how many notes. Only the selected notes get the tag (selected folders, and the notes in them that are not selected themselves, do not); a locked note and one that has three tags already are skipped.

Dates and reminders

A date typed after @ becomes a live date in the text: @today, @tomorrow, @friday, @next friday, @dec 24, with a time @tomorrow 16:45.

Click a date to set:

• the day and the time;
• whether it repeats (daily, weekly, monthly, yearly);
• up to three reminders: minutes, hours or days before, as a desktop notification (bell) or by email (envelope). For a date without a time the reminder counts from 9:00.

The day's journal opens from here too, and this is where the date can be removed from the text.

Lines with a date appear in the Calendar, and if the line has a checkbox as well, among the Tasks too. Ctrl + click on a date opens the journal of that day.

7News

News (its own icon on the left rail, with the number of unread items) gathers what is new on your favourite sites, to read inside the program, without a browser. The icon's right-click menu: fetch all, all read, new source, new category, settings.

It has three columns: the sources on the left, the list of items in the middle, the reader on the right.

• New source: an RSS / Atom address, or just the site's address — the program finds its feed. Beside each source its site's little icon (without one, its first letters in a colour of its own) and the number of unread items.
• Categories: the sources can be sorted into categories (by dragging, or from the source's menu), a category can have a colour and an icon. On a category's header the arrow or the name opens / closes it, the empty rest of the row shows all its items.
• On top All items, Starred (the item is kept as it was, even when the feed drops it – synced) and Saved (the items saved into notes; a click opens the note), under them a search in the news.
• The look of the list is chosen in its header and kept on this computer: Magazine (the default: cards with a picture), Compact list (one item a line, by day, a dot before the unread ones) or Picture grid (a big first item and tiles; the reader slides in from the right, Esc or a click beside it closes it). The preview picture comes from the item; when it cannot be fetched from there, the article page's own preview picture.
• The reader's header has a slim row of icons: whole article (when the feed gives only a summary, it takes the article out of the page – the settings can make it do so by itself), star, save into a note (the whole article, with its pictures; into the News folder by default), open in the browser, read / unread, text size, previous / next; beside them the reading time. Keys: J / K (or ↑ / ↓) step, M read / unread, S star.
• A source's right-click menu: refresh, all read, number of items (the default, or 1–50 for that source only), rename, move to a category, delete.
• OPML (the ⋯ menu): the sources of another feed reader (Feedly, Inoreader, NetNewsWire, Thunderbird…) come in with their categories, and yours can be saved; the ones already here are left out, a summary says what came.
• Settings (the gear): how often to fetch (15 minutes – 6 hours, or only by hand), how many items per source (1–50), the whole article at once, pictures in the reader, the folder to save into.
• Only text, links and pictures stay in the reader — no code of the news sites runs. The sources, the categories, the starred items and what you have read sync with the workspace.

8The start page

The start page is a pinned tab (Alt+0) that shows your day at a glance. Its boxes: greeting with a clock and a search field, weather, today's tasks, favourites, journal (with a calendar), journal entries, recent notes, tags, timers, statistics, today's focus (the one to three things that matter most today, with a tick; what you leave unticked is offered the next day: bring it over or drop it) and backup and sync (for each place the last backup, the state of the sync and the free space; red when something failed, Retry now runs the backup and the sync again).

• Customizing: with the pencil in its corner. The boxes are reordered by dragging, the eye hides a box, the other button switches it between wide and narrow. You can set a background picture too, with adjustable dimming and blur.
• What opens when the program starts is set on the Settings → General → Start tab: the start page, the note you opened last, the first note, or a note or folder of your choice.

Weather

On the Settings → General → Weather tab, search for the place (Budapest, for example) and choose what to show: feels-like temperature, wind, humidity, pressure, precipitation, UV index, sunrise and sunset, the hourly strip, and how many days of forecast.

The forecast comes from Open-Meteo – it is free and needs no account. Only the coordinates of the chosen place are sent to the service. Without the internet the last known data is shown.

9Journal

The Today's note button on the left rail (Ctrl+Alt+J) opens – or, if there is none yet, creates – the day's journal note in the Journal folder (its own icon on the left rail, with the number of unread items). A journal folder is special: it holds daily notes only, the newest first.

• Click a day in the calendar of the start page and that day's note opens; this way you can write ahead for a day in the future.
• In the header of a future journal note, the Reminder button sets a time: you are notified on that day, at that time.
• If the Templates folder has a template called Journal, every new daily note starts from it.
• Any folder can be turned into a journal: right-click → Make it a journal folder.

10Templates

A template is simply a note in the Templates folder. The first time, the Create the starter templates button makes the folder with a few ready-to-use templates (meeting, journal, project plan and others), which you can rewrite or delete.

• New note from a template: Ctrl+Alt+S, or the button beside New note. The picker shows a preview as well.
• Your own template: right-click any note → Save as template.
• A folder's default template: right-click the folder → Default template…. From then on every new note in the folder (and in its subfolders) starts from that template – in a "Meetings" folder, for example.

A template can hold placeholders, which are filled in when the note is created:

11Tasks

The Tasks view (Alt+2) is not a separate list that you have to keep up: the program gathers the things to do from where they are.

From three sources:

1. Checkboxes with a date in any note: a line of a task list that has a date in it (@friday, or in the form 2026-10-15).
2. Cards with a due date from the boards.
3. Every checkbox of the notes tracked as tasks, without a date too.

The list is grouped by day: Overdue, Today, Tomorrow, Next 7 days, Later, No date. Tick something here and it is done in the note or on the board too; a click on the line jumps there.

Quick add

Type the task into the field at the top of the list and press Enter. The line goes into the note called To-do. While typing you can give:

• the date: @today, @tomorrow, @friday, @10.15 (month.day);
• the priority: !! (or !high), and !low;
• the repeat: *weekly (and likewise *daily, *monthly, *yearly) – together with a date.

For example: Pay the invoice @friday !!

The priority can also be changed in the list by clicking the flag of the line (high → low → normal). A repeating task, when ticked, moves on to its next date.

You do not have to keep any of this in your head: F1 (or the keyboard icon at the right end of the header) lists the marks – see Help with F1.

Track as tasks

The ingredients of a recipe or the checkboxes of a packing list are not things to do, so checkboxes without a date do not appear among the Tasks by default. If you do want to see the checkboxes of a note there: right-click the note → Track as tasks, or the Tasks button in the note's header. Tracking is set note by note, not on folders.

12Boards

Boards (Alt+3) are Kanban boards: columns with cards in them, which you drag along as the work moves on.

New board

The New board button offers three layouts to start from:

• Simple: To do → In progress → Done
• Project: Idea → Plan → Work → Done
• Weekly: Monday … Sunday and a Done column

The columns can be renamed, moved (by their header) and deleted later, and new ones can be added.

On the list of boards the tiles stand in the order they were made in – none jumps to the front by itself –, and they can be reordered by dragging. With the mouse over a tile two buttons appear: one gives the board an icon, the other sends it to the Trash with its cards (it asks first).

Cards

Every card is a full note. A new card: the Card button at the bottom of the column, a title, Enter (or click elsewhere; Esc throws it away). A click opens the card – you can write into it anything you can write into a note: a list, a picture, a table.

At the top of the open card:

• Column – moving it without dragging;
• Due – date and time; with it the card appears in the Calendar and among the Tasks too;
• Repeats and Priority;
• Reminders – three at most, before the due date (without a time: counted from 9:00);
• Labels – the board's own, coloured labels;
• Card colour – sets the card's tile off with a colour of its own; without one it wears the colour of its first label;
• Cover image – the first image in the card shows as a band on the board; it can be hidden here.

How many of the card's checkboxes are ticked shows on the board too (1/3, for example), and so does the number of its attachments (a paper clip). The buttons in the top right corner: open in Notes, archive, delete. On the board, the tile of a card has three small buttons under the mouse: a palette (colour), a pencil (rename in place, without opening the card) and a bin.

Columns and order

• A column's ⋯ button: rename, colour (the eight colours or Automatic), At most this many cards (with more in it the count turns red – nothing is refused) and Make this the Done column. What gets into the Done column counts as a finished task; its header says so.
• Auto-archive: in the board's settings you can set after how many days the cards of the Done column go to the Archive. They can be restored from there at any time.
• Filtering: search the cards, filter by label and by due date (overdue, today, within 7 days, no due date).

The look and settings of a board

The gear in the board's header opens the board's own settings (they are kept with the board and synced):

• Look: the style – Classic (the default), Pastel (tinted columns, soft shadowed cards, a dragged card lifted at a slant), Clean (no column boxes, a coloured line on top, the labels as dots) or Coloured header (a filled header, a coloured edge on the cards, the due date coloured by how near it is) –, the density (compact: more cards fit) and the column width (narrow, normal, wide). The styles follow the theme, the light ones too.
• Colours: Automatic (the default) – the columns without a colour of their own get the next of a row in the coloured styles, the Done column green –, or By hand: every column's header and background (the eight colours, one of your own, or automatic), the colour of a card's edge and background.
• A card shows: text preview, cover, labels, due date, task progress, the number of attachments (a paper clip) – each can be turned off.
• How it works: which column is Done, a new card to the top or the bottom of its column, auto-archive.
• Labels: the board's own coloured labels.

F1 sums up in brief how a board is handled (clicking, dragging, renaming) – see Help with F1.

13Calendar

The Calendar (Alt+7) shows in one place everything that has a date: journal notes, cards with a due date, tasks with a date, the dates written into the text, and the alarms. It has a month view and a week view; the switches on top choose which kinds are shown.

• Dragging: drag an item to another day and its date changes – in the note and on the card too.
• Click an item: day, time, repeat, priority, reminders.
• Double-click a day: the day's journal opens.
• The + button of a day: a new task for that day, for example 16:45 Dentist. It goes into the To-do note.
• Deleting: the bin in the window of an entry of your own deletes after a confirmation: a dated checkbox line is removed from its note, an @date written in the text loses its date (the text stays), a card goes to the Trash, a timer or alarm is deleted. A journal page and an external (iCal) event cannot be deleted.

Two outside connections, independent of each other, can be set up for the Calendar. Neither is required.

Google Calendar

MesoNotes's notes with a date, cards with a due date and reminders go into a separate calendar called "MesoNotes" in your Google account. The program does not touch your existing calendars. This way Google notifies you – on your phone, by email – even when MesoNotes is not running on any of your computers.

1. Open Settings → General → Calendar.
2. Click Connect Google account. The browser opens.
3. Sign in and allow the access. The browser window can be closed afterwards.
4. MesoNotes creates the calendar and runs the first sync.

Good to know:

• One calendar per workspace is created. If you have a single workspace, it is called "MesoNotes"; if you have more, "MesoNotes – name of the workspace".
• If you drag or delete a MesoNotes event in Google Calendar, the change comes back into MesoNotes at the next sync.
• In the events: you can choose whether only the title goes to Google, or the first lines of the note too.
• The sign-in is for this computer. You have to connect separately on your other computer – it will write into the same calendar.
• While you are connected, the email reminders are sent by Google.
• Disconnect: in the same place. You can ask for the calendar to be deleted from your Google account as well. When you remove a workspace from the list, the program asks whether to delete its calendar.

Showing your own calendars (iCal)

If you would like to see the events you keep in Google Calendar, Outlook, iCloud or Nextcloud in MesoNotes's Calendar too, give MesoNotes the iCal address of the calendar.

1. Find the iCal address of your calendar.

Google Calendar (in a browser, on a computer):

1. On the left, move the mouse over the name of the calendar, click the ⋮ button → Settings and sharing.
2. Scroll to the bottom of the page, to Integrate calendar.
3. Copy the contents of the Secret address in iCal format field (the eye icon shows it, the copy button copies it).

Outlook.com / Microsoft 365 (in a browser; the labels may differ a little):

1. Cogwheel → Calendar → Shared calendars.
2. At Publish a calendar, choose the calendar and the "Can view all details" permission, then Publish.
3. Copy the ICS link.

iCloud:

1. In the Calendar of iCloud.com (or in the Calendar program of a Mac), click the share icon beside the name of the calendar.
2. Turn on Public Calendar.
3. Copy the address that appears, starting with webcal://.

Nextcloud: in the share menu beside the name of the calendar, Share link, then Copy subscription link.

2. Enter it in MesoNotes.

1. Settings → General → Calendar → Show your own calendars (iCal).
2. Give it a name (Family, for example), choose a colour, and paste the address. It has to start with https:// or webcal://.
3. Add. MesoNotes downloads the calendar once to check it, and the events appear in the Calendar.

At the top of the Calendar view every outside calendar has a button that hides it and shows it again.

14Canvases, drawings, mind maps

The Canvases module (Alt+4) brings together three freer kinds of note. All three are notes like any other: they can be put in folders, tagged and linked. On the home page of the module the tiles of the pages stand in the order they were made in, and can be reordered by dragging.

Canvas

Text boxes placed freely on a large page, as in OneNote. Click anywhere and type; the boxes can be dragged and resized, and all the formatting of the editor works inside them. There is snapping to a grid and zooming (Ctrl + wheel).

Drawing (hand-drawn diagram)

The drawing page (earlier: flowchart) is the Excalidraw editor inside the program, offline: shapes, arrows, lines, free drawing, text and pictures, in a hand-drawn (or plain) style.

• The toolbar at the top: select, hand (move), rectangle, diamond, ellipse, arrow, line, pencil, text, picture, eraser — by the number keys too (1–0).
• With an element selected, the style panel on the left: stroke and background colour, fill pattern (hatched, cross-hatched, solid), stroke width, dashed / dotted, "sloppiness", rounded edges, opacity.
• An arrow sticks to the shape you draw it to and moves with it; double-click a shape or an arrow to write into it.
• Note link: select an element and pick a note with the chain icon at the top right of the page — a click on the link shown on the element opens the note. A web address opens in the browser.
• Library (the button at the top right): selected elements can be saved there and dragged into any drawing; the library syncs with the workspace. Ready-made sets of the community are on libraries.excalidraw.com: the library panel's button opens it in the browser, and a downloaded .excalidrawlib file can be imported from the panel's menu or simply dropped onto the drawing.
• Pictures become attachments of the note (backup, sync). Export: the export button at the top right (PDF, PNG, SVG), or Save as image in the menu at the top left.
• All the keys: ? or the ? button at the bottom right.

An older flowchart is turned into a drawing the first time it is opened (shapes, labels, arrows).

Mind map

The topic in the middle, the branches around it. It is quickest from the keyboard:

Branches can be coloured (their child branches follow), can have an icon, and can be linked to a note: one click on the branch opens its note. The layout can have branches on both sides or only to the right.

15Graph

The Graph (Alt+5) draws the notes and the links between them as a web.

• Pointing at a note highlights it and its neighbours. A click keeps the highlight. A double-click opens the note (Ctrl: in a new tab).
• Filters: only one folder; the unlinked notes, the Journal, the Templates, the tags, the character relations and the writing projects can be turned on and off.
• Writing projects: every project is a point of its own – a rounded square with the project's icon –, and its notes are tied to it by faint dotted lines, so the scenes and sheets of a project stand together. A double-click opens the project's folder.
• Colours: a point wears the note's own colour, or failing that the colour of the coloured folder above it.
• Type into the search field and Enter jumps to the first result.

16Writing

The Writing module (Alt+8) is for longer works: a short story, a novel, a book of poems.

Project

At the New project button you give the title, the type and – if you like – the word count goal, the daily goal and the deadline.

• Short story: a manuscript with scenes; Characters, Places and Notes folders.
• Novel: a manuscript with chapters and scenes; the same folders.
• Poems: every poem is a note; a Notes folder.

On the list of projects the tiles stand in the order they were made in, and can be reordered by dragging. With the mouse over a tile four buttons appear: colour, icon, rename (the pencil, in place) and delete (the project goes to the Trash with its notes; it asks first). The Import button of the list brings a project exported to Markdown back as a project – see Markdown.

The pages of a project: Overview (word count, daily goal, the last 14 days, the deadline – and how many words a day the goal needs), Write, Corkboard, Timeline and Manuscript (the whole text in one piece, for reading).

The writing editor

• On the left the list of chapters and scenes (F9). It is reordered by dragging, between chapters too; a double-click renames. Every scene has a status: Draft → Revise → Done.
• In the middle the text. Alt+PageUp and Alt+PageDown step to the previous and the next scene.
• On the right the scene's data (F10): point of view, word count goal, synopsis, the time in the story, a note for the scene (this does not go into the manuscript), and which characters, places and items appear in the scene – the program recognizes these from the text.

Help for writing:

• Focus mode (F11): full screen, only the text.
• Typewriter scrolling (Shift+F11): the line of the cursor always stays in the middle of the screen.
• Comments (Ctrl+Alt+M): a note in the margin for the selected text.
• Versions: a named snapshot of the scene, which can be compared and restored later.
• Dialogue: paragraphs that start with a dash can be highlighted; Fix hyphens turns the hyphens used as dialogue dashes into en dashes (it makes a snapshot first).
• For poems: line numbers and the syllable count of each line in the margin.

Characters, places, items

Each has a sheet. A character's, for example: role, age, looks, personality, motivation (what they want, what they need, what stands in the way), backstory, arc (starting state – change – end state) and relations with other characters. A sheet can have a picture, and you can add your own fields, which appear on every sheet of the same kind in the project. At the bottom of the sheet you see which scenes it appears in.

Corkboard and timeline

• The Corkboard shows the scenes on cards, with their synopsis. They can be reordered by dragging (between chapters too), marked with a colour, and filtered by status, point of view, character and colour. You can give the colours a meaning ("timeline B" or "to rewrite", for example).
• The Timeline orders the scenes by the time of the story, and marks a flashback and how many days pass between two scenes. The time is set in the right column of the Write tab.

Exporting as a book

A manuscript can be exported in four formats:

• DOCX – for publishers and editors; the margin comments can go along as Word comments;
• ODT – LibreOffice Writer;
• PDF – for printing and reading;
• EPUB – for e-book readers (to a Kindle with the Send to Kindle service), with a cover image.

You can set the title page, the chapter numbering, whether chapters start on a new page, the separator between scenes, the font and its size, the line spacing, the first-line indent, justification, the margins and the page numbers. Scenes with Draft status can be left out.

17Timers and reminders

Two kinds of thing run in the Timers view (Alt+9):

• Countdown: "tell me in 25 minutes". It can be paused, extended (+1, +5 minutes) and restarted.
• Alarm / reminder: for a given time. It can be once, every day, on weekdays, or for a given day.

Both can have a name and can be linked to a note: a click on the notification opens that note. The quickest way to start one is Ctrl+K: "timer 25 min pasta".

On the Settings → General → Timers tab you choose the sound (chime, bell, digital, soft or silent), the volume, and whether there is a desktop notification.

Email notifications

On the Settings → General → Email section you can enter the details of an SMTP account, and MesoNotes sends an email about timers that run out and about the due dates of cards.

• Gmail and other accounts with 2-step verification need an app password, not the normal password.
• Check the settings with the Test e-mail button.
• Use a connection without encryption (port 25) only with your own, local mail server.

Reminder emails are sent only by a computer where MesoNotes is running (with Reminder emails from this computer on). If two computers have it on and run at the same time, a mail may come twice.

18Quick note and tray

The quick note is a small window where you can write down at once what came to your mind – even while you are working in another program.

• Ctrl+Enter saves, Ctrl+Shift+Enter saves and opens the note, Esc closes.
• Markdown works in it: - list, **bold**, - [ ] task.
• The note goes into the Special → Quick notes folder; if you leave the title empty, the first line becomes the title.

It opens from the right-click menu of the tray icon, from the command palette (Quick note…), or with a global shortcut.

Tray and running in the background

Settings → General → Tray:

• Tray icon: a click brings up or hides the window; right-click: quick note, today's journal, timers, quit.
• When the window is closed: Quit or Go to the tray. In the tray the program keeps running: timers ring, backups run.
• Start at login: MesoNotes starts hidden in the tray after you log in. (On Linux and on Windows; on Windows for the installed and the portable version alike.)

• Quick note shortcut: a global key that opens the quick note from any program. On Wayland the system may ask for permission the first time. If the system does not allow it, the same place has a command that you can bind to a key in the system's own shortcut settings.
• Tray icon look: it follows the light or dark colour scheme of the system by itself; if your panel differs, you can choose by hand.
• Centre the window (KDE Plasma, Wayland): on Wayland a program cannot say where its window opens: the window manager decides. This switch (on by default) hands KWin a small script at start that centres the windows of MesoNotes; nothing goes into the KDE settings, and the program takes the script off when it quits. The page says whether it runs, and if not, why.
• XWayland mode (Linux, off by default, takes effect after a restart): the program draws through X11, places its window itself and opens where it was last closed.

Other desktop environments

MesoNotes was made on KDE Plasma, but it runs on other desktops too. Some features depend on the desktop, though: the tray icon, the global shortcut, the keyring, starting at login, desktop notifications and the helper program of the NAS backup. Which of these work on your computer is shown by the This computer list on the Settings → About page: each line says whether the feature works, is off, does not work or cannot be told – and, if it does not work, what you can do about it.

If a feature that is turned on does not work on your computer, the program says so once after it starts, and a red dot stays beside About until you have looked at the list. The most common cases:

• GNOME: the tray icon needs the "AppIndicator and KStatusNotifierItem Support" extension. Without it the icon is not shown, so when the window is closed MesoNotes quits instead of going to the tray.
• Hyprland, Sway and other window managers: the tray icon needs a bar that shows a tray (Waybar, for example), notifications need a notification service (mako or dunst, for example). Starting at login and the quick note shortcut each need a line in your own config file; the list prints the exact line.
• No keyring: passwords and keys are stored only obfuscated, not encrypted. Install and start a keyring (KWallet or GNOME Keyring).
• The system does not allow the global shortcut: bind the command on the Tray tab to a key in the system's own shortcut settings; the list shows where to find that on your desktop.

19Saving a web article

On the command palette (Ctrl+K) choose Save article from web address… and paste the address. MesoNotes downloads the page, takes out the article itself – without the menu, the ads and the comments – and shows a preview. Save as note puts it into the Special → Web clips folder, with a link to the source.

The images are your decision:

• downloaded, they become attachments of the workspace: they show without the internet, but the workspace grows by that much (and so do the backups and the sync). You see their size beforehand;
• not downloaded, only a link to the original page stays in their place.

MesoNotes cannot read pages that load only with JavaScript, or that need a sign-in.

20Import and export

Markdown

• Import: command palette → Import Markdown files… or Import folder (e.g. Obsidian vault)…; or right-click a folder → Import … here…. The folder structure, the images and the [[links]] are kept.
• Export: right-click a note, a folder or several selected items → Export to Markdown…; the whole workspace from the command palette (Export workspace to Markdown…). The attachments are placed beside the notes.

In two things the Markdown export is more than a plain copy:

• A writing project, there and back: the export of a writing project writes the project's data beside the text (type, goals, the order of the chapters and scenes, statuses, synopses, the fields and picture of the sheets, the relations of the characters). On the home page of the Writing module the Import button – or dropping the project's folder on the page – makes a writing project of it again. With an older export, or a folder made by hand, the program tells what it can by the names of the folders (Manuscript, Characters, Places…). An import always makes a new project, it never overwrites one.
• The description of a folder: the description written on the folder's page appears in the folder as _index.md, and on import it comes back as the folder's description – it does not become a note of its own.

A Markdown export is a readable copy: it opens in any text editor and can be taken to another note-taking program. So your data is never locked into MesoNotes.

PDF and printing

Any note: Ctrl+Alt+P (PDF) and Ctrl+P (print). A drawing and a mind map export to PDF, PNG and SVG, a writing project to DOCX, ODT, PDF and EPUB.

21Workspaces

A workspace is a folder on your computer with the database of your notes and the attachments in it – much like a vault in Obsidian. You can have several workspaces (Personal and Work, for example); they are fully independent: separate notes, separate backup, separate sync.

With the switcher at the top of the sidebar (Ctrl+Shift+O) you:

• switch between workspaces;
• create a new one (New workspace…) – you give its name and its place;
• open an existing folder as a workspace (one copied over from another computer, for example);
• rename it, show it in the file manager, or remove it from the list. Removing does not delete the folder or the data – only the list gets shorter.

Exporting and importing a workspace

The menu of the workspace switcher and Settings → Backup → Restore have Export… and Import…. With them you can carry one workspace – or several – with their settings to another computer, or put them aside.

• Export: you choose the workspaces (the open one by default) and what goes with them: the data always; the settings; the calendars (iCal subscriptions); the sign-ins and passwords (NAS, S3, email, the S3 passphrase and the Google sign-in). The result is one zip file, or the same unpacked into a new folder. The calendars and the sign-ins go in only encrypted with a password of the export (at least 8 characters, typed twice); the window warns what they open.
• Import: you can give a zip file, an export folder or a plain workspace folder (workspace.json and its database). The original is not touched; the program copies it to its own place. The workspace keeps its id (so the sync goes on with it), unless this computer has it already: then it comes in as a copy named "(imported …)". The window shows what is in the file and asks what to take. The backup targets (NAS, S3, email) arrive switched off unless you tick that they should be switched on (it warns: do that only with your own export).

Restore from file… uses the same window when you give it an export zip.

22Vault

The Vault (the last module of the left rail, and the Vault part of the sidebar) is a password-protected, encrypted part of the workspace. Its notes, folders, attachments and history are stored encrypted on the disk (AES-256), and open only with the password or the recovery key. A workspace has one vault.

Creating it

1. Click the Vault icon of the left rail, type the password twice (at least 8 characters; a coloured bar shows its strength), then Create vault. The eye button of a password field shows what you typed; the password generator makes a strong one (length 10–128, small and capital letters, digits, special characters, without the easily confused ones), and one click puts it into both fields – copied, it is cleared from the clipboard after 30 seconds.
2. The recovery key is shown – now, once only. Copy it or save it to a file, and keep it somewhere safe (a password manager, say). With it you can open the vault even if you forget the password.

Until you tick that you have saved it, the key stays: if you click somewhere else meanwhile, coming back to the vault shows the key again first. If it went before you saved it (the program was closed, the computer locked), a bar at the top of the opened vault says so, and a button makes a new key.

Using it

• Inside you work as outside: folders and sections, notes, Kanban boards, canvases, drawings, mind maps, attachments, history. The field above the tree searches the vault; the items can be ordered by dragging. The keyboard icon of the header (or F1) sums up how it is used.
• A closed world: what is in the vault does not show outside – not in search, the graph, Tasks, the Calendar, the start page or the tag cloud, and it is not exported. Nothing can be moved or copied in from outside or out from inside (the clipboard works).
• A deleted item goes to the vault's own bin (the bin button of the header shows how many items are in it; a middle click on it empties it, after a question); it keeps them as long as the main Trash does.
• Locking: with the Lock button of the header at any time. Hovering over it tells you when it locks by itself. A locked vault opens with the password (or the recovery key) again; after many wrong tries the program waits longer and longer.

Folders with their own password

Inside the vault any folder can have its own password (right-click the folder → Folder password; the password generator is here too). Its content is encrypted with a key of its own: the vault's password alone does not open it. If the folder's password is lost, the vault's recovery key opens it. The folder locks with the vault and can be locked by hand; its password can be changed or removed in the same menu.

Settings

Settings → Vault (or the gear of the vault's header):

• Locking by itself: when idle; on screen lock and sleep; when leaving the vault (at once or after a few seconds); when the window goes to the background or the tray; open at most this many hours. The vault always locks on exit.
• Privacy: text copied from the vault is cleared from the clipboard after 30 seconds; the screenshot shield – while the vault is open, the window shows black on screenshots and when sharing the screen (on Windows; Linux does not support it).
• Password and recovery key: changing the password; a new recovery key (the old one opens nothing afterwards).
• Folders with their own password: locking when unused, or when leaving the folder.
• Dangerous actions: deleting the vault with everything in it, on every synced computer.

Sync and backup

The vault is backed up and synced with the workspace, but it leaves the computer only encrypted: the storage sees unreadable data. On the other computer the same password opens it.

23Backup

Settings → Backup has four tabs: Overview, Storage, Settings, Restore.

Backup and sync

They are two separate things, and it is best to use both:

• a backup takes a snapshot of the workspace that you can go back to – it keeps the earlier states too;
• the sync keeps the same workspace up to date on several computers – it keeps only the latest state.

The Storage tab is a table: one place per row, each with its own switches for whether to back up there, whether to sync through it (for the open workspace) and whether to encrypt:

On the Overview tab one line per place shows how the backup and the sync stand ("Backup: 10 minutes ago ✓ · Sync: 43 sec ago ✓"); if a place has an error, it shows in red with its cause. One button, Back up and sync now, starts the backup and the sync that are turned on.

How does the backup work?

A backup is a snapshot of the open workspace: notes, attachments, settings. Every attachment is stored only once, however many backups there are, so backups take up little space.

By default MesoNotes backs up by itself: shortly after it starts, every hour while you work, and when you quit or switch workspace – but only if something changed. When only the sync brought changes (from the other computer) since the last backup, it does not back up on quitting: those are on the other computers and the storage already; the next backup takes them. An empty workspace is not backed up (the Overview says: "Empty workspace — nothing to back up yet."); after its first note it is. On the Settings tab you can set:

• Interval: on change (about a minute after editing), every 30 minutes, every hour, every 3, 6 or 12 hours, or daily.
• Retry a failed target: if a backup location (NAS, S3, Google Drive, rclone) could not be reached, the program tries again by itself after 5, 10, 30 or 60 minutes – also when you have edited nothing meanwhile. 10 minutes by default.
• Keep: the newest 5, 10, 20 or 50 backups – and on top of these, one per day for a week and one per week for a month.
• Waiting for the backup when quitting: how long the program waits for the backup when you quit. Once one place has it, it waits only a few more seconds for the others; what is not finished is made up at the next start.
• Encryption: see below.

It can back up to several places at once; it starts with the nearest (local folder, S3, NAS, Google Drive, rclone), so a slow place does not hold up the others.

A backup by hand at any time: the Back up and sync now button of the Overview tab, or the Back up now command on the command palette (Ctrl+K). A click on the backup indicator of the status bar brings you here.

When the remote backup cannot be reached

If at a backup no remote location (NAS, S3, Google Drive, rclone) can be reached, your changes are not left without a backup: MesoNotes saves into the local backup folder – even if you have not turned the local folder on as a backup location. The Overview tab then shows a "Local folder (fallback)" line, and this backup can be restored like any other.

Meanwhile the status bar shows a yellow warning: "No remote backup can be reached — you only have a local backup". Move the mouse over it and it tells you the reason and what to check:

• whether the computer has a network (Wi-Fi, cable);
• whether the router and the NAS or the server are switched on;
• if you reach it from afar (VPN, Tailscale), whether the connection is up;
• whether the address, the password or the key has changed.

The Got it button hides the warning, and it does not come back until the remote backup has worked again (the backup indicator stays red until then). If it fails again later, it warns again. Meanwhile the program retries the remote locations by itself at the interval you set; as soon as it succeeds, the backup goes there too.

Storage

The Storage tab (1.0.21) is a table of five rows: Local folder, NAS, S3, Google Drive and rclone. Each has its own colour and icon (local: a green drive, NAS: an orange server, S3: a purple database, Google Drive: a yellow cloud, rclone: a teal cable), and the same marking comes back in the rest of the program. Under the name of the place you see where it points (path, share, bucket, account, connection), beside it its switches – Backup, Sync (for the open workspace; switched per workspace), Encryption –, the State ("Backup: 10 min ago ✓ · Sync: now ✓", or why it failed) and the Settings button. That opens a panel on the right with the connection (address, sign-in, Test connection) and the place's state in detail; Esc, ✕ or a click beside the panel closes it. Until a place is set up, its switches cannot be turned on. Under the table is the Back up and sync now button.

Local folder. Turned on by default; the backups go into the Documents/MesoNotes/Backups folder. You can give another folder, on an external or mounted drive, for example.

NAS (SMB share). It copies to a network share. The simplest way is to paste the address of the share into the top field as your file manager shows it – smb://user@192.168.1.20/data/MesoNotes, for example (on Windows \\192.168.1.20\data\MesoNotes works too) – and the program fills in the fields:

• Server: IP address or name (nas.local);
• Share: the name of the folder shared on the NAS;
• Folder on the share: optional; created if missing;
• User name and password: left empty, it connects as a guest on Linux, and uses the own sign-in of Windows on Windows.

The Test connection button tells you whether all is well. (On Linux the smbclient program is needed; on Windows it is not, the SMB client of Windows does the work.) The NAS can be used for sync too: the synced copy is in the folder you gave, under sync – see Sync through a NAS.

S3 storage. Any S3-compatible storage: RustFS, MinIO or Garage on your own server; Backblaze B2, Cloudflare R2, Wasabi or Amazon S3 in the cloud. Choosing the Provider fills in the usual settings; you have to give the endpoint, the bucket, the access key and the secret key. Test connection checks it, Create the bucket creates the bucket if there is none yet.

Google Drive. Here are the sign-in (Connect Google Drive), the switch of the sync and Back up to Google Drive: the backups go into the MesoNotes/backup folder of your Drive, with the same sign-in – see Sync through Google Drive.

rclone (1.0.15). Any storage rclone reaches: WebDAV / Nextcloud, SFTP, OneDrive, Dropbox, pCloud, Mega, Box, FTP, SMB, S3 and many more. rclone is installed separately (Arch: sudo pacman -S rclone; on Windows you download it, unpack it and point to rclone.exe with Browse) – when it is missing, the page tells you what to do. The connection is made with New connection…: you choose the service, and the program asks rclone's questions one by one (address, user name, password …); a sign-in in the browser (OneDrive, Dropbox, Google Drive) opens the browser, and the program waits meanwhile. No config file to edit by hand: the connections are in the program's own rclone settings (the passwords hidden), and they are edited, renamed and deleted here. Connections you made earlier with rclone config are offered to be taken over. The backups go into the backup folder under the folder you give, the sync (1.0.16) into its sync folder; the sync is started with the table's Sync switch, and how often it looks is the same as at the other places. The wizard asks only what is really needed: the fields meant for developers (an own OAuth app's id and secret) come back with Advanced settings too; an optional field can be passed with Skip. One connection works at a time (Connection in use): the backups and the sync always go to the chosen one; switching to another leaves the data on the old storage as it is, but it is not updated from then on. When you delete a connection, a tick asks for MesoNotes's data on the storage (its backup and sync folders) to go too – nothing else there is touched; when the storage cannot be reached, nothing changes, and only deleting the connection is offered. A sign-in in the browser opens the default browser, and the program shows the link with a copy button beside it – so you can sign in in another browser (or a private window) too.

Encryption

In the Encryption column of the Storage table it is switched place by place: S3, NAS, Google Drive and rclone; the common passphrase is in the Encryption passphrase part of the Settings tab. When it is on, the data that goes there – the backups and the sync alike – leaves your computer encrypted with your passphrase, notes, attachments and even the file names. The storage – and anyone who has access to it – sees only unreadable data.

One passphrase is used for every encrypted place (each has a key file of its own). The encrypted backups go into a folder of their own (…/encrypted); the earlier, unencrypted backups stay where they are. The content of the Vault always leaves your computer encrypted, whatever this is set to.

Passwords

The NAS, the S3 and the email password go into the system keyring (KDE Wallet, GNOME Keyring; on Windows the system's own protection). The Storage tab shows where the password is kept; if the system has no keyring, the program warns you.

Restore

The Restore tab has two parts.

The backups of the workspace. On top are the backups of the open workspace, each with a coloured tag of its place. A restore always goes into a new workspace: it overwrites nothing, and your current state stays beside it. If all is well, you carry on with the new workspace; if you were only looking for one note, copy it out and remove the new workspace. You can restore from a file too (Restore from file…): from a backup (.tar.gz) or from an export (.zip); the Export… and Import… buttons are here as well (see Exporting and importing a workspace).

Restore from a remote backup. Below it a table shows every workspace that has a backup or a synced copy – of this computer, of another one, or of an earlier install. One workspace is one row:

• Workspace: its name, and under it the coloured tags of the places where it has a copy (if it is in the local folder and on the NAS too, there are two tags);
• Contents: how many notes and folders it holds – or, in italics, "empty — no notes in it"; for an older backup "contents not shown";
• Size;
• Newest copy: the exact date, how long ago, from which computer, and the end of the id;
• the Restore button brings back the newest copy. The workspace stays the same one as on the other computer (same id), so it can sync with it; the synced ones stay in sync right away.

Of workspaces with the same name only the fullest is on top; the empty and older look-alikes (left by an earlier install, for example) are under the table, in Older and empty copies, closed. A row that is not on this computer has a bin as well: after a question it deletes every copy of that workspace (backup folders, the synced copy) from that place. The same table can be opened from the menu of the workspace switcher too.

On Windows, in the installed version, this page also has the Take over the portable version… button.

24Sync

Sync keeps the same workspace alike on two (or more) of your computers: what changes on one appears on the other, and the other way round. It can go through four kinds of storage, even through more than one at once:

Backup and sync are different things (see the beginning of the Backup chapter): backup keeps snapshots you can go back to; sync keeps the current state alike on your computers. It is best to use both.

How does sync decide?

• Note by note, the version that was changed later wins.
• What sync overwrites is kept for 7 days in the note's History – if something came across wrong, it can be brought back from there.
• Deleting and restoring are synced too.
• An empty workspace does not report to the sync (and is not backed up either): from its first note on it does.
• Your own changes go to every sync place within 30 seconds; the program looks for news from the other computer at the interval you set (1–30 minutes).
• Sync after the start: if at the start notes would be updated from the other computer that you changed here too and have not sent yet, the program asks, and you decide note by note which version stays (the other goes into the history).
• When you quit the program waits for your changes to go across; if there is no connection (no network, the NAS cannot be reached), it tells you and you decide: quit (they go at the next start) or try again.
• How often to check (1.0.21) is one value for every sync place (1–30 minutes); beside it the Sync now button syncs every place that is on.
• The Sync log (also on the Settings tab) shows what happened in the last 7 days: what arrived, what this computer sent, what was merged. You also see the name under which this computer shows on the other one.

The status bar shows the state of the sync in a single indicator (if the computer's clock is far off, it warns about that too – the sync keeps the version changed later, so the clock must be right); when there is an error, a click on it takes you to the Storage tab.

Sync through Google Drive

On the first computer:

1. Open Settings → Backup → Storage, and click Settings in the Google Drive row.
2. Click Connect Google Drive. The browser opens.
3. Sign in to your Google account and allow the access. If Google shows a checkbox for the access to Drive, tick it. The browser window can be closed afterwards.
4. The name of your account appears in MesoNotes. Close the panel and turn sync on for this workspace with the table's Sync switch; the first sync uploads everything.

On the second computer:

1. Install MesoNotes, and connect in the same place with the same Google account.
2. Open Settings → Backup → Restore (or Restore from a remote backup… in the menu of the workspace switcher). The workspace synced from the first computer appears in the table (with a Drive tag).
3. Restore. The workspace opens and stays in sync from then on.

Good to know:

• MesoNotes sees only the files it created itself on your Drive; it has no access to your other files.
• The files go into the MesoNotes / sync folder of your Drive – encrypted, if you turned on encryption for the Drive. Do not edit this folder by hand.
• You sign in on each computer separately, and the sign-in is not part of the backups.
• Disconnect: in the same place. Your notes stay on the computer, and the files on Drive are not deleted either.

Sync through S3 storage

1. Set up the S3 storage: Storage, Settings in the S3 row (endpoint, bucket, keys).
2. In the table turn on the row's Sync switch for this workspace (and its Encryption, if you like).
3. On the second computer enter the same S3 storage (with encryption, the same passphrase), then restore the workspace from the table of the Restore tab.

Sync through a NAS

1. Set up the NAS: Storage, Settings in the NAS row (address, share, sign-in).
2. In the table turn on the row's Sync switch for this workspace (and its Encryption, if you like). The synced copy is in the NAS folder, under sync.
3. On the second computer enter the same NAS (with encryption, the same passphrase), then restore the workspace on the Restore tab.

Sync through rclone

1. Make the connection: Storage, Settings in the rclone row, then New connection… (in detail: Storage).
2. In the table turn on the row's Sync switch for this workspace (and its Encryption, if you like). The synced copy is in the sync subfolder of the folder you gave.
3. On the second computer make the same connection to the same storage and folder (with encryption, the same passphrase), then restore the workspace on the Restore tab.

One rclone connection works at a time: if you switch to another, the copy on the old storage stays, but it is no longer updated.

If more than one sync place is turned on (NAS, S3, Google Drive, rclone), the program reconciles with all of them in one round, so the storages stay alike too.

25Appearance

Settings → Appearance:

• Theme: twenty-one built-in dark and light themes. It can be changed from the command palette too.
• Your own theme: starting from any theme you can change the colours (the editor's background, the sidebar, the text, the accent colour and the rest). Your own themes go over to your other computer with the sync, and they are part of the backups too.
• Language and fonts: the language of the interface (English or Hungarian), the size of the interface, the fonts of the interface and of the notes, the font size of the notes.
• Left rail: the icon of any module but Notes can be switched off. Only the icon goes: the module still opens from the command palette and with its key, and Alt+1 … Alt+9 follow the icons that are shown.

26Shortcuts

Nearly every shortcut can be changed: Settings → Shortcuts. Click a command and press the new combination; if it is already taken, the program tells you.

Help with F1

You do not have to keep the keys in your head: F1 shows on the spot what does what – always what belongs to the view that is open, with the keys that are valid for you (changed ones too). The keyboard icon brings up the same. Pressing F1 again hides the help.

In a note the Shortcuts panel opens beside the editor. On top is what you can type as you write (/ command menu, @ date, # tag, [[ link, [ ] task list…), below it the keys of the editor and every key of the program that is set (with the mouse actions of the margin), and at the bottom the buttons of the guide and of the bug report. The same panel comes up when you edit a card of a board or a scene in the Writing module.

In the Tasks view a small sheet opens under the keyboard icon at the right end of the header: what the quick add field understands (date, priority, repeat), and what a click and Esc do.

In the Boards view it is in the same place: clicking, dragging, renaming with a double-click, a new card with Enter.

The Start page, the Calendar, the Timers, News, the Trash, the Vault, the Settings, the Games (in the level editor with the editor's own keys), the list of Canvases and the pages of the Writing module (the project list, Overview, Corkboard, Timeline, Manuscript) have a sheet like this too: each lists its own clicks, drags and the marks you can type. While you write in the Writing module, it is the Shortcuts panel of the editor that comes up. On a canvas page the top of the panel shows the canvas's own handling (a new box with a click, moving, width, zoom, the grid).

On a mind map and in the graph the sheet is in the top right corner of the canvas (on a drawing the ? key shows the keys) and is open by default; the × button or F1 hides it, and the keyboard icon left in its place brings it back.

The default keys:

General

The open note

Editor

Writing editor

Some commands have no key by default, but you can give them one: new canvas, new drawing, new mind map, save an article from a web address, new timer, Trash, back up now, spell check on / off, duplicate the note.

27Games

For a short break there are eight games in the program (the last module of the left rail): 2048 (from 4×4 to 8×8), Numbers merge (with the arrow keys the column wraps around at the edges), Sudoku (four levels of difficulty, pencil marks), Minesweeper (three classic boards; the first click is always safe) and Tetris (a 10×20 well, the next three pieces shown, faster on every level; ← → move, ↑ rotate, ↓ faster, Space hard drop, P pause; the landing outline can be switched on the game's bar), Snake (after the old Nibbles: the edges wrap round, but every level has its own walls; 10 levels, the apples bring the next one, now and then a bonus apple blinks; three lives), Breakout (the paddle by mouse or arrows, 10 levels, three difficulties, bricks that take several hits and steel ones, good and bad capsules; beside the three red hearts up to three golden extra lives; while you play the mouse stays in the field, Esc lets it go and pauses the game) and Battleship (against the computer on three levels; six ships, the smallest a one-cell patrol boat; place the ships by hand or at random). Tetris, Snake and Breakout have a Tempo (Calm / Medium / Classic), Tetris a starting level too. Snake and Breakout have a level editor of their own (the game's Levels button): own levels come after the 10th level, in the order of the list; the left button draws, the right one erases, Mirror, Try it; the program checks that a level can be played, and levels can be saved to a file (.mnlevels).

F1 (or the keyboard button at the top right) shows the keys of every game.

A game you leave unfinished is kept on the computer and can be continued. The records are backed up and synced together with the workspace. No internet is needed for them.

28Delete everything

At the bottom of Settings → Workspaces, in the Danger zone, is the Delete everything button. You choose between two options:

• Only the current workspace: its notes and its attachments are deleted. Afterwards an empty workspace with the same name opens; the settings stay.
• Everything — factory reset: every workspace, the settings, the passwords and keys, the Google sign-ins and the program's own rclone connections (the computer's own rclone settings are left alone). The program restarts as it did the first time.

Whether the backups go too is yours to choose, with separate switches:

• deleting the local backups (on by default);
• deleting the remote backups: those on the NAS, on S3, on the Google Drive and on the rclone storage, together with the synced copies (off by default; the program warns when you turn it on). Deleting the synced copies is a step of its own for each place, run before anything on this computer goes: when a place cannot be reached, the run stops, and that place can be skipped – as with the backups. On an rclone storage the MesoNotes folders left empty go too.

So you can wipe a workspace here and keep it on the NAS or on S3, and restore it from there later – on another computer too. The list and the last warning follow your choice.

Before deleting, the program surveys and lists what will be deleted, and offers a last export (zip): it holds a readable Markdown copy, a backup that can be restored, and every setting. The passwords and keys are either left out of it, or put in encrypted with a password you give. To delete for good you have to type the word DELETE.

From the export you can restore later with Settings → Backup → Restore → Restore from file…, together with the settings. The remote backup targets and the email notifications come back turned off: look them over and turn them on.

29Privacy and security

Where is your data?

The exact places are shown by Settings → About, which opens them in the file manager too.

When does anything go out to the network?

Only when you set it up or start it:

The author of MesoNotes receives nothing about you: there are no statistics and no automatic bug reports. The program looks for a new version only if you allowed it (see A new version) – and even then it only downloads the list of releases from the website, and sends nothing. The error log (the program's error messages) is on your computer only; only you can send a bug report, and you see beforehand what goes. The spelling dictionaries are in the program too, they are not downloaded from anywhere. The details are in the privacy policy.

Good to know

• The notes are stored unencrypted on your computer, like your other documents – except the Vault. If someone else uses your computer too, or it may get lost, use the vault or the disk encryption of the system.
• MesoNotes does not start attached programs and scripts.
• Links pasted into a note open in the browser only, and only http, https and mailto addresses.

30Troubleshooting

The status bar says "Backup failed" or "Sync error". Click it: the settings tell the exact reason (wrong password, a server that cannot be reached, full storage). The program retries by itself (see When the remote backup cannot be reached).

The NAS backup does not work: "smbclient is not installed". Install it with the package manager of your system (Arch: sudo pacman -S smbclient, Debian / Ubuntu: sudo apt install smbclient, Fedora: sudo dnf install samba-client).

"No system keyring available." Install and start a keyring (KDE Wallet or GNOME Keyring). Without one, passwords are stored only obfuscated, not encrypted.

The global quick note shortcut does not work. On Wayland it needs the system's permission. If it does not work, use the command on the Settings → General → Tray tab in the system's own shortcut settings.

The tray icon is not shown. On some desktops (GNOME, for example) tray icons need an extension (AppIndicator). While there is no tray icon, do not set the program to go to the tray when the window is closed.

Google says the access was revoked. Disconnect the account in MesoNotes and connect again.

The workspace does not appear for download on the second computer. Check that you connected with the same Google account (or with the same S3 storage and passphrase), and that a sync has already run on the first computer.

I forgot the vault's password. Open it with the recovery key (Use the recovery key when opening), then give it a new password in Settings → Vault → Change password – proved by the recovery key too.

The content of a note is lost or came across wrong. Open its History: the earlier versions are there. If you deleted the note, look in the Trash; if it is gone from there too, it can be restored from a backup.

Have a question? Write to contact.mesonotes@gmail.com.

Reporting a bug

If you have found a bug, it is easiest to report it from the program: Settings → About → Report a bug (or Ctrl+K → "Report a bug", or at the bottom of the F1 panel).

1. The program opens a note to fill in, in the Special → Bug reports folder. Its questions: what happened, what you expected, which steps bring it up, how often, where, since when. You do not have to answer them all, but the more there is, the sooner the bug is found.
2. Simply paste a screenshot into the note (Ctrl+V) or drag it in.
3. At the end of the note the program writes in the details of your computer: the version and the package of MesoNotes, the system, the desktop environment, the displays, and whether the backup, the sync and the other connections are turned on and have reported an error. There is no name, note, path or address in it; you can delete what you would rather not send.
4. In the note's header click Send bug report.

Before sending, the window shows what goes: this one note with its pictures, the computer's details, and – if you leave it ticked – the end of the error log (the program's starts and error messages; you can look at it before you send it). No other note, setting or password of yours goes. The program makes a zip of all this in the Downloads folder, and:

• Write a message in my mail program: it opens the folder and your mail program with the address filled in – you attach the zip to the message;
• Only make the zip: if you use webmail, you send the zip from there to contact.mesonotes@gmail.com;
• Send now: shown only if you have set up an email account – then the program sends it itself.

The report stays with you as a note; you can add to it and send it again later.

If the program does not start or cannot be used, you can write with the form on the Report a bug page of the website. In that case attach the program's error log to the message too: on Linux ~/.config/MesoNotes/mesonotes.log, on Windows MesoNotes-data\mesonotes.log beside the program.