Skip to main content

Waypoint (Obsidian Plugin)

· 3 min read

The Waypoint plugin automatically generates an index listing for a Folder Note.

It's useful for folks who prefer to organize their vaults with folders. If you prefer a flat folder structure you won't get as much out of it.

Unlike many Obsidian plugins, it makes permanent changes to the content (contrast e.g. DataView) so the listing will continue to work event if you uninstall the plugin.

How it works​

You add a special Obsidian comment to a folder note, which the plugin will expand into an index listing, and keep up to date.

By default, the flag word is "Waypoint" but this is customizable. In this example, I will use the word "Flag" instead, so that the plugin doesn't try to expand the example.

If you have these files:

$ tree /path/to/folder-note/
folder-note
├── folder-note.md
├── note1.md
├── note2
│   ├── note2.md
│   └── note2-1.md
└── note3.md

And folder-note.md has the following content:

# Folder Note
## Index
%% Flag %%

And note2.md has the following content:

# Note 2
## Index
%% Flag %%

The plugin will expand the comment in folder-note into the following listing, and bold any child waypoints it finds:

# Folder Note
## Index
%% Begin Flag %%
- [[note1]]
- **[[note2]]**
- [[note3]]
%% End Flag %%

Waypoints and Landmarks​

In addition to standard Waypoints, the plugin also understands a variant they call "Landmarks".

When it encounters a Waypoint, it links to that note, and stops. You can see this in the example above, with note2. (The example assumes that note2.md also contains a waypoint.)

When it encounters a Landmark, it links to that folder note but continues listing that notes sub-notes as well.

The "Landmark" behavior is used by default for child folder-notes which do not specify either type of flag.

So, if note2 contained a landmark instead of a waypoint, then folder-note.md would have expanded to this instead:

# Folder Note
## Index
%% Begin Flag %%
- [[note1]]
- **[[note2]]**
	- [[note2-1]]
- [[note3]]
%% End Flag %%

Quirks​

I've noticed a few quirks related to the "Use Title Property" setting:

  • leaf nodes (regular notes) will use the title property as the display text for the link (e.g. [[note1|Display Text]]), but parent nodes (folder notes) will not.
  • This one is a maybe: There is some churn in the index when working on mobile, where it will flip between using or not setting the display text.
    • I am not certain this is real churn. This setting wasn't always available, and it seems to happen randomly with files I wasn't actually working on, plus I have better automation on desktop. So it's entirely possible that this is happening all the time and I only notice it on mobile.

Synergy with other plugins​

  • Supports the title front matter property, so it works well with [[2024-07-26-front-matter-title-plugin]]