Your map is a Markdown file
A Graphmark map is a Markdown list. Each branch is a list item and each child is an item indented below it, so the file reads as an ordinary outline in any text editor. Whatever Markdown has no way to express, such as where you placed a branch or which colour you gave it, goes in a separate companion file beside the map.
How a map is written
This map has a central topic with two branches, one of which has children:
- Product launch
- Goals
- Reach the first thousand readers #marketing
- [x] Write the announcement
- Timeline
Dates are still provisional.
- Branches are list items. A file with several top-level items has several main topics.
- Titles are the first line of an item. Bold, italics, code, strikethrough and links in a title appear as formatting in the map.
- Notes are any text indented under an item after its title, such as the line under “Timeline” above. You can read and edit notes in the document pane (⌥⌘E).
- Tags are words that start with
#at the end of a title. - Tasks are items that start with
[ ]or[x]. You can also type[ ]at the start of a title, or press ⇧⌘T. - Pictures are written as Markdown images,
, under the branch they belong to. See Pictures.
Text in the file that is not part of a list, such as an introduction or a table, stays where it is and is saved unchanged. A first-level heading at the top of the file becomes the map’s title.
If you choose a theme or a layout other than the defaults, Graphmark adds a short block at the top of the file that records them:
---
graphmark: 1
theme: signal
layout: down
---
Marks at the end of a line
When a branch needs to be referred to from the companion file, for example because it has a connection or a colour of its own, Graphmark adds a short mark to the end of its line, such as ^gm-a1b2. Obsidian reads this as a block reference, and other editors show it as plain text. Graphmark hides it in the map and in the document pane.
Leave these marks in place when you edit the file in another app. If one is removed, the branch keeps its text, but the settings stored for it in the companion file no longer reach it.
The companion file
A map saved as Markdown has a companion file in the same folder, named after the full name of the Markdown file:
| Map | Companion file |
|---|---|
Launch plan.md | Launch plan.md.graphmark.yaml |
notes.markdown | notes.markdown.graphmark.yaml |
Each map has its own companion file, so a folder with hundreds of notes never mixes up their settings. The companion file holds:
- the position of branches you placed by hand, and which side of the central topic a branch grows on
- branch widths, shapes, colours and borders that you set in the inspector
- connections between branches, with their labels
- which branches are folded, and where the view was
- a copy of the map’s theme, if you chose one (see Themes)
Graphmark writes the companion file only when there is something to put in it. A map you never styled has none.
If you rename or move a map in the Finder, rename or move its companion file with it. A map whose companion file is missing still opens with all its text, but with automatic layout and default styling.
If you delete the companion file, nothing in the Markdown is lost.
Graphmark packages
When you save, you can choose Graphmark Map instead of Markdown. That creates a .graphmark package: a folder that the Finder shows as one file. It contains the map as index.md, its settings as graphmark.yaml, and its pictures. Use a package when you want to send someone a single file with everything in it.
To see what is inside, Control-click the package in the Finder and choose Show Package Contents.