hiroyaiizuka2k downloadsView and edit Markdown as linked, illustrated mind maps.
English | 日本語 | Documentation

Mappy lets you read and edit an Obsidian note as a mind map, without turning it into anything else. A plain note written with H2 headings and bullet lists is shown in one of four layouts (mind map, timeline, hierarchy, balanced), and adding, editing and moving nodes writes back to that note's Markdown. There is no special file format: without Mappy, the note is still headings and bullet lists.
0.x is a beta. It has been checked only with Obsidian on macOS desktop. Real typing with a Japanese IME, Windows and Linux have not been checked yet (see Compatibility and Known limitations). Mappy is desktop only and doesn't run on mobile. Before using it in your everyday vault, make sure you have a backup such as git or Obsidian Sync.
[[ / ![[<mark style="background: …;">, as the Highlightr plugin writes it, so the note shows the same color![[Map note]] in another note to embed the map read-only. A map note's card on a Canvas shows the map too, and a double click opens the map beside the CanvasThe Markdown is the single source of truth. Everything in a map is in the note's body and frontmatter; Mappy keeps none of it in files or a database of its own. Outside your notes, Mappy leaves its settings (data.json), the backups of notes taken before an input is written (exit-backups/; see "Quitting or reloading while typing" under Known limitations) and which branches are folded (how the maps are shown, folds.json), all in the plugin's folder .obsidian/plugins/mappy/, plus the inputs that could not be written on a reload or quit (in Obsidian's storage for this vault). Deleting folds.json changes no note (deleted with Obsidian closed, the maps open as they start, with nothing remembered, an inserted map's branches open down to its root's children at first; deleted while Obsidian runs, Obsidian keeps using what it remembers and writes the file again the next time it writes its memory, after a fold for example).
The root is an H2 heading, and list indentation below it makes the hierarchy. The first line of an item is the node's text; there is no separate title field.
---
mappy: true
---
## Trip plan
- Preparation
- Packing list
- Destinations
- Kyoto
- [[Kyoto notes]]
- ![[map.png]]
Mappy writes three frontmatter keys. It only handles notes with mappy: true and leaves every other note alone.
| Key | Value | Meaning |
|---|---|---|
mappy |
true (a YAML boolean) |
Open this note as a map. "Turn this note into a mind map" writes it and "Turn off mind map for this note" removes it |
mappy-layout |
timeline / hierarchy / balanced |
The layout. Not written for the mind map layout (leaving it out means mind map) |
mappy-topics |
heading text: { mindmap: [x, y], timeline: [x, y] } |
Free topic positions, keyed by the heading text and saved per layout. When several topics share a heading, the second and later ones are keyed heading text (2), heading text (3)… (in source order; when that string is another heading's text, the smallest unused number) |
=== / --- (a setext heading) is a heading only when the text is a single line (including a single line with <br>). === / --- under text of two or more lines is read as body paragraphs, not a heading, as Obsidian's reading view and outline do (with ---, a paragraph and a horizontal rule). Mappy 0.3.8 and earlier showed this form as a heading node too, so in such notes that node leaves the map and becomes body text of the node above, and the nodes below it may get a new parent. A note whose only heading besides H2 was this form of === now opens as the list format, and the list items that used to be body text appear as nodes. The note's text doesn't change. To keep the node, make the heading text a single line in Markdown (use <br> for line breaks), or rewrite it as ## Heading. %%…%% comments are also read as Obsidian reads them: inside one line they are part of that line's text, and across lines they count as a blank line (a Heading and === right below a line holding only %%note%% are two lines of text, so they are not a heading; with a blank line between them, they are).Mappy can be installed on the desktop version of Obsidian (1.8.7 or later; see Compatibility for what has been checked).
Mappy, and choose InstallWhen a new version comes out, check for updates on the Community plugins screen to bring it in.
To install by hand, put the three files main.js, manifest.json and styles.css attached to a version on Releases in your vault's .obsidian/plugins/mappy/, then enable Mappy in the community plugins list (with Restricted mode off; if Mappy isn't listed, reload the list or restart Obsidian). The repository's source code does not work as it is.
For a step-by-step guide to using Mappy, see the documentation.
Use the command palette, the ribbon icon on the left, or a file's context menu. No default hotkeys are registered; assign them in Obsidian's settings if you need them.
| Command | What it does |
|---|---|
| Create new mind map | Creates a note with mappy: true and an H2 root in the folder from the settings, and opens it. The file is named "Untitled mind map" and the root "Central topic" (written into the note as ## Central topic). Tab there adds a "Main topic", and Tab on that a "Subtopic" |
| Turn this note into a mind map | Writes mappy: true into the open note's frontmatter and opens it as a map (also in the file's context menu) |
| Open mind map | Opens a mappy: true note as a map. The ribbon icon on the left does the same, but when the open note is not a map (or no note is open) it creates and opens a new map, as "Create new mind map" does (the open note's content is not changed; pressed on a Markdown note, the new map opens in that note's tab). On an old-format note with mappy-layout alone it creates nothing and points to "Turn this note into a mind map" |
| Open mind map beside Markdown | Puts the map and the standard editor side by side. Run from a Markdown note, the map is on the left and the editor on the right. Run from a map, the Markdown opens on the left |
| Switch between map and Markdown | Flips the same pane between the two. The Markdown side scrolls to the selected node's line |
| Turn off mind map for this note | Removes mappy, mappy-layout and mappy-topics and goes back to Markdown, keeping the body |
| Change current map to list format | Converts a heading-hierarchy note to an H2 root and a list (undo reverts it) |
| Search and insert a map | Searches for another mappy: true note and adds it as an ![[Other map]] item at the end of the selected node's children. With nothing selected (after clicking empty space to clear the selection), places it near the main map as a ## ![[Other map]] free topic at the end of the note. Only while a map is active |
| Insert current map into Excalidraw drawing | See Adding to Excalidraw |
| Export current map as SVG or PNG | See Exporting to SVG or PNG |
| Rescue unsaved drafts | Lists the inputs that couldn't be written when Obsidian reloaded or quit, and the backups of notes taken before inputs were written ("Quitting or reloading while typing" under Known limitations); the one you choose is saved, after a confirmation, as a new note in the Mappy Recovery folder at the top of the vault. The original note, the kept input and the backups are not changed. An input or a backup you no longer need can be discarded from its line, after a confirmation (a backup goes to the system trash) |
A mappy: true note opened from a link or the file explorer also opens as a map. A pane switched to Markdown with "Switch between map and Markdown" stays Markdown when the same note is opened again. A map tab behaves like a Markdown tab: a note chosen from a link in the map or from the file explorer opens in that tab (Cmd/Ctrl+click for a new tab; pin the tab to keep it), and back/forward return to the map. [[#Heading]] and [[Note#^block]] select the node at that position, and when you move to another note while editing a node's text, what you typed is saved first. Escape on a node doesn't move focus to the neighboring tab. Hovering over an internal link in a node with Cmd/Ctrl held shows Obsidian's page preview of the linked note, as in the Markdown editor (in map tabs, embeds and called branches alike; links are resolved from the note they are written in). Whether Cmd/Ctrl is needed can be changed under Settings → Core plugins → Page preview → Mappy. No preview shows while you are typing in a node or dragging or panning the map. While a map is active, Obsidian's file commands such as "Copy current file path from vault folder" and "Delete current file" act on the map's note, not on the note next to it. Click the note name at the top of the map (the title) to rename the note there, as in Markdown (Enter or clicking elsewhere confirms it, Escape restores the old name; the command "Rename file" also starts editing the title; checked on Obsidian 1.14.4). Mappy 0.4.8 and earlier couldn't rename from the title, and the tab title ended in "· map" (now it is just the note name; the tab icon tells a map from Markdown).
The canvas fills the view, with floating buttons: the layouts in the bottom-left corner, the gear (a popover of three items) in the top-right corner, and zoom in the bottom-right corner.
| Action | How |
|---|---|
| Gear | The gear in the top-right corner opens a popover below it with just three items: Switch to Markdown (Open the note in this tab), Search and insert a map (Insert another map) and Export (Save as SVG or PNG). ↑↓ move, Enter runs, and Escape, a click outside or pressing the gear again closes it. Node actions are on the keys below and in the context menu; everything else is in the command palette |
| Right-click | Right-click a node to open Mappy's card: color circles at the top (No color and six colors), then Edit body and links and Add image, and below a line Delete (the same as Delete/Backspace). A heading note also offers Change to list format (a file name standing as the root offers no Delete). Delete/Backspace on the card also deletes. A node of an inserted map offers only Open original map and Collapse (Expand on a folded branch); empty space offers only Add topic. ↑↓ and Tab move, ←→ move along the color circles, Enter/Space run. Escape, a click outside, scrolling or zooming the map, or moving to another tab or window closes it. After Escape, a scroll or a zoom the focus is back on the node; after moving to another window it is on the node when you come back (a click outside or another tab keeps the focus where it went). The card is the same whatever Obsidian's native menus setting says. Editing text, adding a child or sibling, moving and undo/redo are not on the card: use the keys in this table, a double-click or a drag |
| Moving the selection | ↑/↓ in display order, ← to the parent, → to the first child. Clicking empty space clears the selection (dragging the background doesn't), and the arrow keys start again from the main root. Undo and redo work with nothing selected |
| Adding a sibling/child | Enter/Tab with a node selected. An input opens with a provisional name selected: "Main topic" for a node right under the root (of the map or of a topic), "Subtopic" further down. Typing replaces it (Enter without typing keeps the name, Escape right away cancels the addition, and Escape after typing cancels only the typing). A topic from double-clicking empty space or from the context menu (and a topic made with Enter on a topic's root) works the same way with "Topic". The provisional name is written into the note as it is, in Japanese (メイントピック, サブトピック, トピック) when Obsidian's language is Japanese |
| Editing text | Double-click or F2. Enter confirms, Shift+Enter breaks the line inside the node (saved on one line in Markdown, like Hot<br>springs), Escape cancels. The input widens with the text and wraps at the same width as the confirmed node (a line with link or emphasis syntax, a URL or runs of spaces may wrap at a different place than after confirming) |
| Adding children in a row | Tab while editing text confirms and adds a child |
| Link and attachment suggestions | [[ or ![[ while editing text. While suggestions are shown, Enter/Tab picks a suggestion first |
| Moving up/down | Alt (Option)+↑/↓, or drag the node (see Reordering and changing the parent) |
| Reordering and changing the parent | Drag the node. A placeholder node and line show the destination beforehand; Escape puts it back |
| Deleting | Delete/Backspace (with its branch). Afterwards the sibling above is selected, or else the sibling below, or else the parent (in source order, also in the balanced layout). Clearing a free topic's title selects the topic above or below, or else the main root. The items of a main map without an H2 and the topics are treated as separate sequences; when nothing is left in the same sequence, the nearest node is selected. Undo brings it back |
| Folding | Space, or the round − that appears at a branch's fork. A folded branch shows how many descendants are hidden. Branches folded and unfolded on a map tab are remembered per note: they stay as they were when you open another note in the same tab and come back, switch to Markdown and back, or restart Obsidian (and they follow the note when it is renamed or moved inside Obsidian). With one note open in two tabs, each tab keeps its own folds while open, and the next opening shows the tab changed last |
| Editing body and links / adding an image | Right-click the node (see Right-click above) |
| Coloring a node | Right-click the node and press a color circle at the top: No color or one of six colors (yellow, orange, red, green, blue, purple). Hover a circle for its name; the current one has a ring. The commands "Color selected node: …" and "Remove color from selected node" can take hotkeys. Markdown gets the node's whole text wrapped in <mark style="background: #FFF3A3A6;">…</mark> (Highlightr's inline style and its default colors), nothing else. The same written by hand in Markdown, or ==…== around the whole text, shows as a color too; a mark around part of the text stays a highlight inside the text. A block id at the end of the line ( ^id) stays outside the mark. The dark theme draws each color darker so the text stays readable. The text input does not show the mark, and renaming keeps the color. Undo takes it back in one step |
| Undo/redo | Cmd/Ctrl+Z / Cmd/Ctrl+Shift+Z. Right after adding a node (Enter/Tab, or a double-click on empty space), Cmd/Ctrl+Z in its input removes the node, as Escape does, and Cmd/Ctrl+Shift+Z brings it back (a topic from a double-click comes back without the position you clicked). Once you have typed in the input, Cmd/Ctrl+Z first undoes the typing |
| Panning and zooming | Drag the background, scroll or pinch, scroll with a modifier key, or the buttons in the bottom-right corner |
| Inserting another map | Make a node's text just ![[Map note]] (the same as "Search and insert a map"; ![[Note#Heading]] inserts only what is under that heading; a free topic heading ## ![[Map note]] works too, and that topic becomes the inserted map). The node becomes the inserted map's root, and the inserted map's branches line up to the right, looking the same as the current map's and in the same layout (down to the root's children when first opened). The inserted part is read-only (in a muted text color; an ![[…]] node has a link mark in front): you can select and fold it, and open the original map (double-click, or "Open original map" in the context menu). The ![[…]] node itself can be edited, moved and deleted as usual, and deleting it removes the inserted branches with it. Insertions of the map itself, and insertions inside an inserted map, stay links |
If you switch to another app or window while typing in a node's input (the one opened by double-click, F2 or Enter/Tab), the input stays open and what you had typed so far is saved to the note (if the save is refused, the input shows an error and nothing is written to the note. What happens when you leave in the middle of IME composition, and how it behaves when actually switching apps, have not been checked. The "Edit body and links" dialog does not save when you leave). Come back and press Enter to close it; anything you typed after coming back is saved then. Escape after coming back cancels only what you typed after leaving, and what was saved when you left can be undone with Cmd/Ctrl+Z.
If you close the map tab or another window, or disable Mappy, with the input still open (without pressing Enter or Escape), what you are typing is saved to the note too. It is the same as a Markdown tab not losing typed text, and the same as moving to another note (a link, the file explorer, back/forward). Text still being composed with an IME is saved as it appeared in the input (closing in the middle of real IME typing has not been checked yet). Even if the input shows an error, closing tries to save once more, and if it can't, tells you why with "Couldn't save the text being edited." (for example, when the node being edited itself changed on the Markdown side; the note then keeps the Markdown side's content). To discard what you typed, press Escape before closing. Quitting Obsidian or reloading the window saves it too (it is written after the reload or at the next launch; when it can't be, see Known limitations).
Hovering over a node's body shows no tooltip with its title or its source path (so as not to cover the input or the node right below). The fold buttons and the buttons at the edges of the view show tooltips as before. The source path stays in exported SVG as the node's tooltip. With the focus in the map, F2 is the map's key: it starts editing the selected node (it does nothing in a node's input or on the map's buttons). With the focus outside the map, for example in the map tab's title, F2 does what Obsidian's default hotkey ("Rename file") does and selects the note name in the title, as in Markdown (checked on Obsidian 1.14.4; in Mappy 0.4.8 and earlier, F2 outside the map did nothing while a map was active). The input in a node is Mappy's own, not Obsidian's standard editor. Besides note names, paths and aliases, the suggestions include attachments in the vault such as PNG, SVG and PDF.
Choose one in the bottom-left corner. Switching only writes mappy-layout; the body doesn't change.
mappy-layout is not writtentimeline): puts the first level along a horizontal axis and grows the branches below it alternately up and down. When consecutive first-level items are on the same side and the next item has branches, the next item is placed well apart from those of the previous item's branches that reach the height where its own branches go, and closer to branches farther from the axishierarchy): puts the root at the top and grows downwards, lining up children of the same parent on one row (for org charts and issue trees)balanced): puts the root in the middle and splits the first level right, left, right, left in Markdown order. There is no way to choose the side by handFree topic positions are saved per layout and kept when you switch (a topic without a name yet also stays where you put it). For switching while dragging, see Known limitations.
The note's first heading section is the main map, and each later top-level section (## ) is a free topic placed near it.
| Action | How |
|---|---|
| Adding | Double-click empty space, or "Add topic" in the empty space's context menu. A ## Topic section is created where you clicked, with "Topic" selected in an input to type over (Escape right away cancels). Running "Search and insert a map" with nothing selected places a ## ![[Other map]] topic near the main map (in a note with no content, either way that section becomes the main map) |
| Moving | Drag the topic's root. The position is saved in mappy-topics. Topics with the same heading (such as the same map inserted twice) move separately |
| Making it a branch of the main map | Carry the topic next to a node of the main map and drop it. The section becomes a list under that node |
| Detaching a branch | Drag a branch of the main map to empty space with no nodes and drop it. It becomes a new ## section at the end of the note |
| Moving the main map | Drag the main root. Topics keep their place on screen |
| Deleting | Delete, or "Delete topic" in the context menu |
All of these can be undone. A note with no headings gets a root showing the file name that holds everything together.
Obsidian's Settings → Mappy has four items. Changing them doesn't rewrite any note.
mappy-layout. Notes that already exist keep their layout/ is the vault rootmappy-layout is a hidden layout, that note still shows its button. This is a display setting, not a way to turn features off: saving and restoring mappy-layout, the commands, embeds and inserting into Excalidraw don't change. Up to 0.4.2 all four were shown by default. After updating to 0.4.3, if you haven't changed any Mappy setting since 0.2.0, the Balanced button leaves the bottom-left corner (turn it on in the settings to bring it back). If you have changed any setting since 0.2.0, your saved choice stays as it isWriting ![[Map note]] or ![[Map note#Heading]] shows a read-only map in reading view, Live Preview and hover previews. The layout is the original note's mappy-layout, the frame has a fixed height, and inside it you can only fold and unfold branches. Branches you unfold (or fold) in an embed stay that way when you edit the original note as a map, switch its layout or undo. When the original note is rewritten on the Markdown side or by an external tool (including when you keep working on the map right after), folding may reset on branches of nodes that share a name or have an empty title. "Open in map" in the top-right corner opens the original note as a map. A note without mappy: true, and a block reference (#^id), stay Obsidian's usual embeds.
When you put a note with mappy: true on a Canvas, its card (a file card) shows a read-only map filling the card too (a card with #Heading shows only what is under that heading; you can fold and unfold branches in it). Double-click the card, or press "Open in map" in its top-right corner, and the note opens as a map beside the Canvas; what you change there shows up on the card. If the note's map is already open somewhere other than the Canvas's own row of tabs (a split beside it, a sidebar or another window), that one comes to the front instead of a new one (a map tab in the Canvas's own row of tabs isn't used; a new one opens beside). A double click on a fold button or a link inside the card does only what that button or link does, and opens nothing beside. Clicking a link to a note inside the card turns the Canvas's tab into that note, as with Obsidian's usual cards. On a map's card, a double click doesn't start Canvas's Markdown editing (the "Edit" item in the Canvas menu that appears above a selected card still does). A card of a note without mappy: true stays Obsidian's usual card. A card with a block reference (#^id), and the cards of a Canvas embedded in a note or shown in a hover preview, are out of scope and are built to stay usual cards (not checked in the app). Checked with Obsidian 1.14.4. In Mappy 0.4.9 and earlier, a map note's card showed the note's text as it is, and a double click started Markdown editing.
With the Excalidraw plugin enabled, there are three ways.
| Method | Result |
|---|---|
Drop a mappy: true .md onto the canvas while holding Option (Alt) |
Inserts the map as native Excalidraw elements (rectangles, text, lines, images), in one group, with the root linking to the original note |
| The command "Insert current map into Excalidraw drawing" | Inserts into the drawing that was last active, with the current layout and folding |
| Excalidraw's "Insert Interactive-Frame" (by default, drop while holding Ctrl on a Mac or Shift+Ctrl on Windows, then choose "as Embeddable" in the dialog) | Shows the mappy: true note inside the frame as a live Mappy view you can edit |
A map inserted as native elements is a snapshot that doesn't sync with the original note. Dropping without a modifier key (which makes a link) works as Excalidraw normally does. When you drop a mappy: true note from Obsidian's file explorer onto a drawing with one of Excalidraw's own inserts, Mappy fits the result to the map. Which modifier key gives which insert is an Excalidraw setting, and Excalidraw shows a hint while you drag (by default, on a Mac: Shift for "Insert Image", Shift+Ctrl for "Insert Image @100%", Ctrl for "Insert Interactive-Frame"; on Windows: Shift for "Insert Image", Ctrl+Alt for "Insert Image @100%", Shift+Ctrl for "Insert Interactive-Frame"). For a single note, "Insert Image" and "Insert Interactive-Frame" open a dialog; choose "as Image" or "as Embeddable" there. Inserted as an image ("Insert Image @100%" and a drop of several notes included), the note becomes an SVG image of the map instead of an image of its text (<note name>.svg is created where the drawing's attachments go, with a number added if the name is taken, so each insert adds one file; the image links to the original note and is drawn in the light theme, which also reads on a dark drawing). This image is also a snapshot that doesn't sync with the note. An "Insert Interactive-Frame" frame (the table above) takes the map's proportions and loses its border. In 0.4.9 and earlier, with the same drawing also open in another pane, an image of the note's text could be left under the map's image. Checked on macOS with Obsidian 1.14.4 and Excalidraw 2.29.0.
With a map open, run "Export current map as SVG or PNG" and choose a format. The map is saved as <note name>.svg / .png in Obsidian's attachment folder, with the layout, folding and theme colors you are looking at (a number is added if the name is taken). The original note isn't rewritten.
foreignObject). Browsers and Obsidian show it, but some SVG editors and previews, such as Inkscape and Illustrator, may not show its content. Images from the vault are embedded in the SVG file (it doesn't refer to separate files). An image that can't be read becomes alternative text, keeping the node| Environment | Status |
|---|---|
| macOS desktop, Obsidian 1.14 | Checked (main actions, by automation and by eye; keeping inputs that couldn't be written, the rescue and the backups taken before a write were not checked with 1.14, see Known limitations) |
| Windows and Linux desktop | Not checked |
| iOS and Android | Not supported. Mappy is desktop only (isDesktopOnly in manifest.json), so Obsidian doesn't offer or load it on mobile. If your vault's .obsidian folder is synced between devices (Obsidian Sync with plugin sync on, iCloud and so on), the version your desktop installs reaches the phone as well, but from 0.4.1 Obsidian on mobile doesn't load Mappy (0.4.0 and earlier could be installed on mobile). Synced or not, map notes stay plain Markdown and nothing in them changes |
| Obsidian 1.8.7 to 1.13 | Can be installed on 1.8.7 and later, but not checked in this range (except what Known limitations says was checked with 1.13.7 under "Quitting or reloading while typing") |
| Interface language | Japanese when Obsidian's language is Japanese, English otherwise (command names, menus, settings and notices, and the provisional names Mappy writes into notes: Main topic / メイントピック, Subtopic / サブトピック, Topic / トピック, and the new map's root Central topic / 中心トピック; the new map's file name Untitled mind map / 無題のマインドマップ follows it too). English was checked on macOS only for command names, buttons, the gear popover, context menus, the settings tab, Subtopic, Main topic, Central topic and one refusal message; not every notice |
<mark …> into the heading's text, and Obsidian then no longer finds it with [[Note#Heading]] or ![[Note#Heading]] (in Markdown, the page preview, and embeds of notes that are not maps). Mappy's own embeds, inserted maps and links that open the map still find it by its text without the color. Removing the color brings Obsidian's links back.![[Map note]] node), after you unfold or fold the branch of a node that shares a name or has an empty title (such as a node with only an image), when the inserted note is rewritten on the Markdown side or with an external tool (as in the next item, "Folding after an external change"), that branch's folding may go back to how it was when the map was opened, and the node's selection may be cleared. Also, when one note has insert items written exactly the same way (such as two lines of - ![[Map note]]), temporarily editing one of them on the Markdown side and then restoring it may return the folding of that item's whole inserted branch to how it was when the map was opened, and clear the selection inside that branch.app:reload) may lose the ones not written down yet (the map opens as it was before them). A branch is known by the titles from the top of the note down to it (same-named siblings by their order from the top; an empty title counts as a name), so if titles, order or parents change on the Markdown side or in an external tool while the map is closed, the branch may open as it starts instead of as remembered, or a fold may land on another branch of the same name. Only folds made on map tabs are remembered; folding in an embed or a Canvas card is not (they start as usual each time). A note renamed or moved outside Obsidian (in Finder or by a sync tool, including while Obsidian is closed) may lose its remembered folds. A folds.json brought in from another device by a sync such as iCloud is not read again while Obsidian runs: the next time this Obsidian writes its memory (after a fold, after an edit on the Markdown side, and so on), it writes its own folds over it. Folds are remembered for up to 1,000 notes and 4 MiB; beyond that, the notes not folded in or shown as a map for the longest time are forgotten first (they open with nothing remembered).app:reload) with a node's input open, what you are typing is saved to the note too. It isn't written at that moment (a write cut off there can leave the note empty); it is written when Mappy loads next (after the reload, or at the next launch). If other lines changed in the meantime, only your edit is written. It isn't written when the node itself (or the text right next to it) changed on the Markdown side, when nodes with the same name make it unclear where the change was, when a note over 262,144 characters (counted in UTF-16 units: most emoji count as two or more) or a free topic's rename saw any change in the meantime, when the note can't be found, when the input is more than a day old (for example, Mappy was disabled meanwhile), or when the write is refused (for example, the note changed between reading it and writing). It also isn't written when the note got shorter than it was when you typed (other lines deleted or a title shortened included), because that can't be told apart from a write that stopped and lost the end of the note; for the same reason, nor when both the last line and the line before it were changed, a line was added higher up than right above the last line and the last line changed, the last node was moved up, or the last line was joined to the one before. Before an input is written, the whole note as it is then is saved as a backup in the plugin's folder, exit-backups (.obsidian/plugins/mappy/exit-backups/), and read back to check it; then the input is written (a notice says "Wrote … A backup of the note from just before the write is kept"). It isn't written when the backup can't be saved or checked, when the backup folder holds files that aren't Mappy's backups (half-written ones included), or when a record of an earlier write that didn't finish is there. The backup folder holds at most 10 MiB in all; once it is full, inputs stop being written (they can still be rescued). Discarding backups you don't need in the list of the command "Rescue unsaved drafts" makes room, and the inputs held back are written the next time Mappy loads (after a confirmation, Discard moves the backup file to the system trash, or to the vault's .trash folder when the system trash can't be used). A backup whose input is still kept is the record that keeps that input from being written again, so it can't be discarded until that input is. The notice for a full folder points to these steps too. Mappy never deletes backups by itself. Files in the backup folder that aren't Mappy's backups (half-written ones included) can't be discarded from the list; open exit-backups in Finder, for example, to look at them (Finder hides .obsidian by default). Backups don't guarantee nothing is lost: Obsidian Sync, deleted files, uninstalling the plugin (the backups go with the plugin's folder), OS failures, power loss, not waiting for writes to reach the disk, clearing the browser data and other devices are not covered. An original text that is already lost can't be brought back. For an input that kept no original text, the backup is the note as it was when the input was written, not a text lost before that. If you go back to an earlier version of Mappy, it doesn't read the backups and may write inputs that were held back by its own rules (to go back, disable Mappy, move exit-backups out of the vault and set aside the inputs not written yet first; there is no way to set them aside yet, though rescuing an input to a separate file and then discarding it takes it out with its content kept). An input that isn't written is kept, not dropped: each time Mappy loads it tries again (and once it can be written, for example after you put the note's earlier text back, it is written then, with a notice saying so), and while it can't, a notice that stays until you close it says "Couldn't write "(your text)" in (note), which was being edited when Obsidian reloaded or quit." and what is kept, at every load. What is kept is the title you typed and the planned change, and for a note of 262,144 characters or less the note's text as it was then too (not for a longer note, which keeps nothing to bring the whole note back from). For an input that couldn't be planned because the note had already changed, only the title you typed and the reason are kept (neither a planned change nor the note's text). The command "Rescue unsaved drafts" saves what is kept, or a backup, as a new note (<original note> <date time> <id>.md) in the Mappy Recovery folder at the top of the vault (from a backup, the whole note just before the write goes in; a backup file that can't be read is listed by its path alone). The note's text goes in a code block, so the rescued note is not a map and the original frontmatter has no effect. Rescuing doesn't change the original note, and nothing is put back into it automatically (copy from the rescued note by hand to put it back). The kept input stays after a rescue and the notice keeps showing at every load (rescuing again makes another file with the same content; the same input can be rescued up to 20 times, after which the old rescued files have to be deleted first). An input you no longer need can be discarded in the same list (after a confirmation, that input alone goes, and its notice stops from the next load; it can't be brought back; the original note and the other inputs and backups aren't changed). Why a note can be left empty when the page ends during a write is not fixed. When Obsidian's local storage is short of room, the input is kept without the note's text, so it isn't written if the note saw any change in the meantime, whatever its length (with the same notice). The note's text can then be taken, without notice, even from an input whose notice said it was kept. If there is room only for the newest input, inputs still waiting from an earlier reload or quit (kept ones that couldn't be written included) are dropped without notice. Items in the local storage that can't be read as inputs aren't deleted when Mappy loads, but the next quit or reload that keeps an input may overwrite them without notice (as before; not guaranteed). Kept inputs pile up unless you discard them, so several kept inputs of long notes make this more likely. Nothing is saved if the app crashes or is force-quit, or if the local storage has no room even for the newest input. Checked on macOS only. Writing after a quit or reload was checked with Obsidian 1.14.2 in a version from before the backups and the rescue were added, and with 1.13.7 in a version that has them. Keeping the inputs that couldn't be written, the rescue command, the backup taken before a write and discarding inputs and backups were checked only with 1.13.7 (not with 1.14, which Compatibility lists as checked), in cases that artificially empty the note, cut it to its first half or change it at a reload. An input that couldn't be written after a quit, and a real half-finished write, have not been seen.![[Map note]] embed and the map on a Canvas card are read-only (make changes in the original note's map), and native elements inserted into Excalidraw don't sync with the original note. When you disable Mappy and enable it again (updating included), the cards of a Canvas that is open stay Obsidian's usual cards (they are built to come back when you open the Canvas again or the note changes, but that hasn't been checked in the app). Cards of one note with different headings, stacked at nearly the same place and size, stay usual cards too.mappy: true note inserted through the insert dialog opened from Excalidraw's commands or tool panel, or dragged in from outside the app (Finder and so on), stays an image of the note's text (checked in Excalidraw's source, not in the app). In the map's image, a short node's text can wrap onto two lines ("b1" as "b" and "1", for example; it is one line in the map view). Within a minute after a drop of a map note that made nothing to replace (a drop without a modifier key, a cancelled insert dialog, and so on), inserting a map note as an image with another drop can make two map images and two attachments (not checked in the app).mappy-topics is a nested value, so it isn't meant to be edited from Obsidian's Properties panel. Mappy rewrites it only when it moves topics.Mappy doesn't bring its own format into your notes, so recovery happens entirely on the Markdown side.
| Situation | What to do |
|---|---|
| The map looks or behaves wrong | Open the Markdown with "Switch between map and Markdown", and check or fix the text there. The Markdown is the source of truth; the map only shows it |
| You want to stop using Mappy | Disable Mappy in Settings → Community plugins. Notes open as ordinary headings and bullet lists; frontmatter keys such as mappy stay but do no harm |
| You want just one note back as an ordinary note | Run "Turn off mind map for this note". It removes mappy, mappy-layout and mappy-topics from the frontmatter and leaves the body as it is. With Mappy disabled, remove the same keys by hand in Properties or in Markdown |
| Saving is refused with "The note changed in Markdown. Update the map and edit again." or a similar message | After the map updates to the latest content, press Enter again to confirm (for a drop or an added image, do it again). If it is still refused, copy what is in the input and write it on the Markdown side |
| You want to undo something | Cmd/Ctrl+Z on the map. If the history was cleared, for example by an external change, and the note is also open in a Markdown editor, pressing Cmd/Ctrl+Z repeatedly in the editor may bring it back (later changes, from outside or from switching the layout, are undone first, and map actions from before the editor was opened are not). Otherwise, restore from the core plugin "File recovery" or from a backup |
| You want to remove it completely | Uninstall the plugin. All it leaves in the vault are the frontmatter keys in your notes, the <mark style=…> around the text of colored nodes (it stays and shows as a Markdown highlight; remove it on the Markdown side if you don't want it) and the plugin settings in .obsidian/plugins/mappy/data.json (besides these, inputs that could not be written on a reload or quit, if any, stay in Obsidian's storage for this vault). The backups taken before inputs are written (.obsidian/plugins/mappy/exit-backups/) are in the plugin's folder too, so rescue what you need before uninstalling (the remembered folds in the same folder, folds.json, and the folds.next.json a cut write may leave need no rescue) |
Mappy has no server of its own, and sends no telemetry, update checks or note content. There are no accounts or payments. It reaches outside only when a note itself refers to an image at an external URL.
, it is loaded for display by the same rendering as Obsidian's reading viewTwo features read the list of files in your vault, on your device only: the suggestions after [[ / ![[ (file names and aliases) and the search for a map to call (the notes marked mappy: true). The list is not sent anywhere. Besides these, Mappy reads the list of files in its own backup folder in the plugin's folder (exit-backups) before writing an input and when rescuing (not the list of your notes).
MIT License (Copyright (c) 2026 Hiroya Iizuka).
The only bundled third-party code is the Markdown parser @lezer/markdown (MIT License, Copyright (C) 2020 by Marijn Haverbeke and others). Other plugins (MarkMind, Light Mindmap) served as references for features; none of their code is included.