The editor
How to write in Jotura: formatting, the slash menu, lists and checkboxes, links between notes, images, tables, callouts, saving, exporting, and the Markdown view, with technical details at the end.
Every note opens in an editor that looks like a formatted document. Headings, lists, and bold text appear as you type, and Jotura saves your work for you. Behind the scenes each note is a plain Markdown file, a simple text format that any other app can open.
If you have not opened a vault yet, start with Getting started. Every keyboard shortcut is listed on Keyboard shortcuts, and every setting mentioned here is in the Settings reference.
Writing and formatting
Type the way you would in a chat app or a plain text file, and Jotura turns common patterns into formatting. Starting a line with # makes it a heading, and wrapping a word in ** turns it bold. The symbols disappear once the formatting appears.
| You type | You get |
|---|---|
# through ###### |
Heading levels 1 to 6 |
- , + , or * |
Bullet list |
1. with any number |
Numbered list, starting at that number |
> |
Quote |
``` |
Code block |
--- |
Divider line |
**bold** |
Bold |
*italic* |
Italic |
~~strike~~ |
Strikethrough |
`code` |
Inline code |
Web addresses turn into links by themselves. Text you paste in keeps its formatting, and text you copy out carries it into other apps.
Formatting with the keyboard
Mod means Command on macOS and Control on Windows and Linux.
| Action | Shortcut |
|---|---|
| Bold | Mod+B |
| Italic | Mod+I |
| Strikethrough | Mod+Shift+S |
| Inline code | Mod+E |
| Highlight | Mod+Shift+H |
| Heading 1 to 6 | Mod+Alt+1 through Mod+Alt+6 |
| Plain paragraph | Mod+Alt+0 |
| Quote | Mod+Shift+B |
| Code block | Mod+Alt+C |
| Bullet list | Mod+Shift+8 |
| Numbered list | Mod+Shift+7 |
| Checkbox list | Mod+Shift+9 |
| Line break inside a paragraph | Shift+Enter or Mod+Enter |
| Undo | Mod+Z |
| Redo | Mod+Y or Mod+Shift+Z |
Markdown has no underline, so Jotura has no underline either.
The selection toolbar
Select some text and a small toolbar pops up with Bold, Italic, Strikethrough, Inline code, Highlight, Link, and Insert image. It stays hidden in source mode and in notes you can only view.
Clicking the empty space below the last line puts the cursor at the end of the note, which saves a scroll on a long page.
The slash menu
Type / on an empty line and a menu of things to insert appears. Keep typing to narrow it down, for example /tab for a table, then press Enter. Arrow Up and Arrow Down move through the list, and Escape closes it.
| Item | What it inserts |
|---|---|
| Heading 1, 2, 3 | A heading at that level |
| Bullet list | A bullet list |
| Ordered list | A numbered list |
| Task list | A checkbox list |
| Blockquote | A quote |
| Code block | A block for code |
| Horizontal rule | A divider line |
| Table | A table with three rows and three columns |
| Image | Pick an image file and add it to the note |
| Callout | A highlighted box with a title, see Callouts |
| Math block | A block for an equation, see Math |
| Comment | A private note to yourself, see Comments |
| Footnote | A numbered footnote, see Footnotes |
A / typed in the middle of a sentence leaves the menu closed, so you can write “and/or” freely.
Lists and checkboxes
Enter starts the next item, and Enter on an empty item takes you out of the list, however deeply it was nested. Tab indents an item and Shift+Tab moves it back out.
Checkboxes
A checkbox list is a to-do list inside a note. Start one with /task, with Mod+Shift+9, or by typing - [ ] at the start of a line. Click a box to tick it.
- [ ] Draft the release notes
- [x] Book the meeting room
You can mix plain bullets and checkboxes in one list. Every checkbox in your vault also shows up in the Tasks pane in the right sidebar, covered in Daily notes, tasks, and templates.
Task states
A task can be more than open or done. Right-click a checkbox to choose Todo, Done, In progress, Cancelled, Forwarded, or Question. Each state is saved as one character between the brackets:
- [ ] Todo
- [x] Done
- [/] In progress
- [-] Cancelled
- [>] Forwarded
- [?] Question
A plain click still toggles between todo and done. You can also type the marker directly, such as - [/] . The Tasks pane lists only todo and done items, so a task in any other state stays in its note.
Links between notes
Type [[ and start typing a note’s name. A list of matching notes appears, and Enter inserts a link to the one you pick, written as [[Note name]]. Mod+L opens the same list. If you select some words first, they become the link text.
When nothing matches, the Create row makes a new note with that name at the top of the vault and links to it straight away.
Click a link to open that note. A link to a note that does not exist yet looks different, and clicking it offers to create the note.
To link to a web page, select the words, press Mod+K (or click Link in the selection toolbar), and paste the address. Leave the address empty to remove a link. Web links are not opened from inside the editor, so copy the address into your browser to visit it.
Renaming or moving a note in Jotura’s file tree rewrites the links that point to it, keeping each link’s form. A rename made outside the app, in your file manager for example, leaves links unchanged. To keep old links working then, give the note its old name as an alias, described in Wikilinks and aliases.
Tags
A word starting with #, such as #project or #work/admin, is a tag. Click one to search for every note that carries it. Tags also appear in the sidebar’s Tags pane.
Images
There are four ways to add an image:
- The Image item in the slash menu.
- The image button in the selection toolbar.
- Paste an image from the clipboard.
- Drag a file onto the note. It lands where you drop it and keeps its file name.
Images are copied into an assets folder in your vault. Dropping a file that is not an image adds a link to it, and the file goes into the document folder described in Documents.
Right-click an image to copy it, copy its file path, show it in your file manager, or delete it.
Images from the web stay hidden until you turn on Load remote images in Settings. It starts off because fetching an image tells the site hosting it your IP address and that you opened the note.
Embeds
An embed shows a file inside the note. Write a link with ! in front of it, or press Mod+Shift+L to pick the file from a list.
![[diagram.png]]
![[diagram.png|300]]
![[contract.pdf]]
![[Roadmap]]
| Embed | What you see |
|---|---|
| An image | The picture. Add |300 to set its width in pixels, or |300x200 for width and height |
| A PDF or other file | A chip with the file name |
| Another note | A chip with the note name |
Tables
Pick Table from the slash menu to insert one with three rows and three columns. Markdown tables explains the syntax underneath.
| Key | In a table |
|---|---|
| Tab | Next cell. In the last cell it adds a new row |
| Shift+Tab | Previous cell |
| Enter | New line inside the cell |
| Mod+Enter | Add a row below |
| Mod+Shift+Backspace | Delete the row |
A + button below the table adds a row, and one to its right adds a column. The thin strip above each column and beside each row is a handle. Click it to select the column or row, and right-click it to insert, delete, or align. Drag the strip between two columns to resize them.
Selecting every cell and pressing Backspace deletes the whole table. Mod+Z brings it back.
Callouts
A callout is a box that stands out from the text, with an icon and a title. Pick Callout from the slash menu, or type it:
> [!note] Title
> Body text, with **formatting** and [[links]].
> [!warning]- Collapsed by default
> This body is hidden until the box is expanded.
Click the label on a callout to change its kind, such as note, tip, or warning. The arrow on its title folds it closed, and the note remembers that it is folded.
Highlights
Wrap text in == to highlight it, or select it and press Mod+Shift+H.
This ==matters== more than the rest.
Comments
A comment is a note to yourself inside a note. Wrap it in %%, press Mod+Shift+/, or pick Comment from the slash menu. Comments show in a muted colour and are left out when you export the note.
Shipping on Friday. %% check with legal first %%
Footnotes
Pick Footnote from the slash menu. It adds a marker at the cursor and a matching line at the bottom for the footnote text.
The figure comes from the annual report.[^1]
[^1]: Annual report, page 12.
Math
Write equations in TeX between dollar signs. Press Mod+Shift+M for an inline pair, or pick Math block from the slash menu.
The area is $\pi r^2$ for a circle.
The equation appears typeset as soon as you type the closing dollar sign. Click it to edit the TeX, and it redraws when you click away. A math block works the same way: its TeX shows while the cursor is inside it, with the drawn equation below. The mobile app shows the TeX as written.
Saving
You never need to save. Jotura saves one second after you stop typing, and straight away when you switch to another tab, another app, or hide the window. The dot on the tab clears once the save lands, and screen readers announce Saved. Mod+S does nothing.
Notes shared with you as view only never save, because you cannot change them. See Sync and sharing.
If a note changes while you have it open, for example because sync brought in an edit from another device, Jotura combines both versions without asking, and screen readers announce Merged changes from disk. The only time it asks is when the note was deleted or moved outside the app. A banner then offers Close tab or Recreate with my version.
Exporting and printing
To send a note to someone who does not use Jotura, click the export button at the top right of the editor, the page icon with a down arrow, and choose where to save it. Hovering over it shows Export as HTML, and the same command is in the command palette as Export as HTML…. You get one web page file that opens in any browser and looks like the note does in Jotura. Comments stay out of it.
To make a PDF, open the command palette and run Print / Save as PDF. Your computer’s print dialog opens, and you pick its PDF option there.
Source mode
Source mode shows the note as the plain Markdown text saved on disk, with every symbol visible. Switch with the button at the top of the editor or Mod+Shift+E. The button names the view it takes you to, so it reads Source in the normal view and Preview in source mode.
To start every new tab in source mode, turn on Open in source mode in Settings.
Source mode is a plain text editor with line numbers and matching bracket highlighting. There is no find and replace, Tab moves focus out of the editor, and typing a bracket adds only that one character.
Mod+Shift+E only works from the normal view. To get back from source mode, click Preview or run Editor: Toggle Source Mode from the command palette.
Diagrams
A code block that starts with ```mermaid draws a Mermaid diagram. Click Edit in source mode on the diagram to change it. When the diagram text has a mistake, the block shows your text with Mermaid syntax error: and the reason.
Technical details
The rest of this page is for people who want to know exactly how the editor behaves.
Wikilinks and aliases
A wikilink is the note’s name in double brackets. Five forms are recognised, and each stays as literal text in the file.
| Form | What it points at |
|---|---|
[[Roadmap]] |
The note named Roadmap.md, wherever it sits |
[[Roadmap|the plan]] |
The same note, shown as the plan |
[[Roadmap#Q3]] |
The same note. The heading is kept in the file and ignored when resolving |
[[Roadmap#^abc123]] |
The same note. Block references work the same way |
[[#Q3]] |
The note you are reading |
One resolver decides what a link points at. The editor uses it, and so do the jotura links and jotura backlinks commands in the CLI. Its rules:
| Rule | Example |
|---|---|
| Matching is case-insensitive | [[roadmap]] opens Roadmap.md |
| A bare name matches the shortest path that ends in it | [[today]] opens inbox/today.md when no today.md sits higher up |
| A name with a slash matches that path | [[inbox/today]] opens inbox/today.md, with or without .md |
| Heading and block anchors are stripped | [[Roadmap#Q3]] and [[Roadmap#^abc123]] both open Roadmap.md |
| An empty target is the current note | [[#Q3]] stays where you are |
Frontmatter aliases resolve |
[[The Plan]] opens a note whose frontmatter lists aliases: [The Plan] |
| Encoded Markdown links are decoded | [text](My%20Note.md) opens My Note.md, tried relative to the note first and then to the vault root |
An alias is an extra name a note answers to. Declare one or more under aliases in the frontmatter, as a list, an inline array, or a single value:
---
aliases:
- The Plan
- Q3 plan
---
---
aliases: [The Plan, Q3 plan]
---
A wikilink to an alias opens the note. The link picker matches aliases as you type and shows the alias beside the file name, and picking one inserts [[Note name|Alias]]. Quick open (Mod+P) matches aliases too. When two notes declare the same alias, the first by path wins.
The link picker
The picker searches file names and frontmatter aliases, shows at most 20 results, and strips .md from the inserted name. Arrow keys wrap at both ends. The Create row appears when the query is not empty and matches no result exactly, and it creates the note in the vault root. From outside the editor, Insert Link to Note… in the command palette opens the picker for the active note. Mod+L, Mod+Shift+L, and Mod+K are editor shortcuts, so they need the editor to have focus.
Mod+K opens a prompt reading Link URL (leave empty to remove):, filled with the existing address when the selection already has a link. Cancelling leaves the text untouched.
How clicking a link resolves
| Link | Click behavior |
|---|---|
Wikilink such as [[Roadmap]] |
Opens the target note in the active tab |
| Wikilink to a missing note | Asks No note named "{name}". Create it?, then creates and opens it |
| Wikilink to a missing text or HTML file | Alerts No file named "{name}" in this vault |
Relative path such as [spec](specs/api.md) |
Resolves against the current note, then against the vault root, and opens it |
Hashtag such as #project |
Switches the sidebar to the search pane and searches for that tag |
External URL such as [docs](https://example.com) |
Nothing. The rich view does not open links carrying a URL scheme |
Relative-path resolution is skipped in four cases, each of which silently does nothing:
| Case | Why |
|---|---|
The link starts with a scheme such as http: or mailto: |
Treated as external |
The link starts with # |
Treated as an in-page anchor |
| The click is not a plain left-click | Middle-click and modified clicks are left alone |
| Text is selected at the time | The click counts as a selection gesture |
Paths that try to escape the vault with .. are rejected.
A hashtag must start a line or follow a space, and the first character after # must be a letter, digit, or underscore. So #work/admin is a tag and #-todo is not. Later characters may include hyphens and slashes, which is how nested tags work. Body tags count in the Tags pane alongside frontmatter tags:, except inside code.
Embed resolution
An embed of a file that is not a note resolves by file name. Jotura looks for the name anywhere in the vault, then in the attachment folder named in .obsidian/app.json when the vault has one, then in the note’s own folder. The size suffix is kept exactly as typed. An embedded note shows as a chip, and its content is not pulled into the page.
Typing and paste rules
The full set of patterns the editor converts:
| You type | You get |
|---|---|
```lang or ~~~ / ~~~lang |
Code block with that language |
___ or *** |
Divider line (these two need a trailing space, --- does not) |
__bold__ |
Bold |
_italic_ |
Italic |
[ ] or [x] at the start of a line |
Checkbox item |
- The code fence records a lowercase language only.
```JScreates the block without a language, and```Mermaiddoes not draw a diagram. - An em dash followed by a hyphen also makes a divider line, because some systems autocorrect three hyphens into that pair.
- Checkbox input accepts a lowercase
xonly. A[X]pasted from GitHub-flavored Markdown does not convert, though the file still reads correctly everywhere. - Bold, italic, strikethrough, and inline code each have a matching paste rule, so they apply to pasted text as well.
- URLs are linked both as you type and inside pasted or parsed Markdown.
- Plain text pasted into the editor is parsed as Markdown, and copied text is serialized back to Markdown.
- Raw HTML is shown as ordinary text. The Markdown layer has HTML disabled, so a pasted snippet never becomes markup.
Slash menu rules
The menu opens only when all of these hold: the editor has focus, nothing is selected, the cursor is in a paragraph, only whitespace sits before the /, and the text after it contains no spaces. Filtering is a plain substring match on the item label, and the typed /query is deleted before the block is inserted. Arrow keys wrap at both ends and Tab does nothing.
When the filter matches nothing, such as /xyz, the menu hides and stops handling keys, so Escape falls through to the app. Deleting a character brings it back.
Only headings 1 to 3 are in the menu. Use Mod+Alt+4 to Mod+Alt+6 or type #### for the rest. The Image item accepts png, jpg, jpeg, gif, webp, svg, bmp, and avif. The Callout item inserts > [!note], Math block inserts a $$ block with the cursor inside, and Footnote inserts the next free reference plus its [^n]: definition.
Keys and precedence
Holding Mod suppresses Tab everywhere in the editor. Mod+Tab and Mod+Shift+Tab are claimed application-wide for tab switching, so Mod+Tab neither indents a list item nor moves to the next table cell. On macOS the system app switcher usually takes Cmd+Tab first anyway.
Inside a quote, Backspace at the start of the text lifts you out of it. In lists, Backspace, Delete, Mod+Backspace, and Mod+Delete join items with awareness of the list structure.
Enter passes through several handlers, and the first to claim it wins: the table override, then the empty-list-item exit, then the ordinary task-item and list-item split. So inside a table cell, Enter on an empty nested list item gives a line break in the cell and keeps you in the list. The empty-item exit also requires the item to hold nothing at all, so an empty item with a nested sublist beneath it splits as usual.
In tables, Enter and Mod+Enter are Jotura overrides: Enter inserts a line break in the cell, and Mod+Enter adds a row, so it no longer gives a hard break there. Shift+Enter keeps its usual hard break. Backspace, Delete, Mod+Backspace, and Mod+Delete remove the whole table once every cell is selected.
The table handle menus hold Insert row above, Insert row below, and Delete row for rows, and Insert column left, Insert column right, Align left, Align center, Align right, Default align, Fit to content, Reset column width, Reset all widths, and Delete column for columns. Alignment applies to every cell in the column. The resize grips live on the handle strip above the table, with the tooltip Drag to resize, double-click to fit.
The image context menu disables Copy file path and Reveal in Finder for an image with no file behind it, such as a remote one. Its Reveal in Finder label is the same on every platform. Pasted images get a generated file name.
Callout, math, and comment syntax
Callouts nest, and any word works as a kind. A - after the kind means collapsed and a + means expanded, and folding in the editor writes that character into the file.
> [!tip]+ Expanded by default
> Nested callouts work too:
> > [!info] Inner
> > Text
Block math uses $$ on its own lines:
$$
\int_0^1 x^2 \, dx = \frac{1}{3}
$$
A whole block becomes a comment when %% sits alone on its opening and closing lines. Footnote labels can be words, such as [^source], as long as they contain no spaces or brackets.
Block ids and Obsidian compatibility
A block id is ^id at the end of a line. It stays in the file, and [[Note#^id]] links to the note holding it. An .excalidraw.md note opens in source mode, and the drawing is not rendered.
All of this syntax matches Obsidian’s, so a vault moves between the two apps in either direction with every construct intact. Jotura keeps each one byte-for-byte through an edit, and a round-trip test suite enforces it.
How saving and merging work
The editor owns the document while it is open, which is why the cursor never jumps during a save. Every save goes through a queue, so the autosave timer and a flush on blur cannot collide.
When the file changes on disk, Jotura runs a three-way merge. The base is the tab’s last clean content, “ours” is the editor, and “theirs” is the file on disk. It retries up to three times if the file changes again mid-merge, which can happen during a fast sync pull.
Because saves run on a one second timer, a note you are editing can be a moment behind on disk. Two actions check for this and refuse to run until the note is saved:
| Action | Message |
|---|---|
| Restoring an older version while the tab has unsaved edits | Save the note before restoring. |
| Ticking a task from the sidebar while its note has unsaved edits | Save the open note before toggling this task from the sidebar. |
Clicking into another tab or app flushes the save and clears both. Older versions are covered in Version history.
Editing the same notes from the CLI
The jotura command-line tool edits the same files with hash-checked writes, so a concurrent change in the app is never silently overwritten. Read the note with its hash, then write back with that hash as a precondition:
HASH=$(jotura read "Projects/Roadmap.md" --json | jq -r .hash)
jotura edit "Projects/Roadmap.md" --replace "old text" --with "new text" --if-hash "$HASH"
Exit code 2 means the file changed since you read it. Exit code 14 means it was deleted or moved between the read and the write, and the CLI does not recreate it. See Editing notes and Exit codes and JSON output.