Plugin: Heading Navigator [v0.4.2, 2025-11-06]

Plugins
1

NOTE: This plugin was created entirely with AI tools

Heading Navigator

A Joplin plugin that provides a simple overlay panel allowing you to navigate and filter headings in the markdown editor, inspired by sublime text's "go to symbol" function.

heading-navigator-demo

NOTE:
This plugin only works in the markdown editor (editor view or split view). It does not work in the reading view or in the rich text editor.

Codemirror 6 only, legacy editor is not supported.

How to use

In the markdown editor, click the Heading Navigator toolbar button, or use the assigned keyboard shortcut.

NOTE:
There isn't a default keyboard shortcut, you can assign one under Tools | Options | Keyboard Shortcuts | "Go to Heading" command.

You can navigate through headings using tab key (goes to next heading), shift tab key (goes to previous heading), arrow keys, or by scrolling and selecting a heading.

When selecting a heading with the keyboard, the editor will immediately scroll to the selected heading. Hitting enter in the dialogue (or clicking somewhere else) will close the dialogue. Hitting escape will close the dialogue & return to your original scroll position.

You can filter the list of headings using the search filter at the top of the panel.

Features

  • Navigate through headings with the keyboard
  • Search filter to filter list of headings
  • Copy link to heading
  • Panel adapts to your Joplin theme
  • Adjustable panel size

Settings

The panel appearance can be customized via Settings | Heading Navigator:

  • Panel width: 240-640px (default: 320px)
    • Useful for longer heading text or smaller screens
  • Panel max height: 40-90% of editor viewport (default: 75%)
    • Prevents the panel from obscuring too much content

Settings take effect the next time the panel is opened.

4 Likes
2

v0.2.0

  • Feature: Adjustable panel size (in plugin settings). Width can be adjusted between 240px-640px, and height between 40% and 90% (of the editor viewport)
  • Improvement: Make search filter close button adapt to Joplin theme
  • Improvement: Better behavior when no headings are found (the panel opens displaying "no headings found" instead of nothing happening)

v0.2.1

Fix issues where scrolling could be unreliable:

  • Debounce heading previews and deferred editor to prevent race condition with scrolling editor to headings 4555897
  • Fix issue where editor sometimes didn't scroll to heading when navigating headings with keyboard 849dcee
  • Fix issue where left clicking heading sometimes didn't scroll editor to selected heading 33b6c38

v0.2.2

  • Reverted previous scrolling logic from 0.2.1 because it didn't play nicely when rich markdown plugin is rendering images in a note
  • Implemented new logic that fixes the occasional missed scrolls when tabbing through headings and doesn't cause issues with rich markdown
  • You might occasionally see a small jump when it needs to re-center a heading on a missed scroll

v0.2.3

  • Feature: Restore original scroll position when closing panel with escape key
3

v0.3.0

  • Massively simplified the scrolling logic.
  • Significantly improved reliability and responsiveness when scrolling through headings, less jumpiness while scrolling.
  • Remove inline markdown from headings, so heading panel only displays heading text.

NOTE: Selected headings will no longer be centered (or highlighted). The selected heading will now be at the top of the viewport (like with the Outline and DDDot plugins). This allowed me to significantly simplify the code (and I think it also feels better this way when scrolling through the headings).

Also, recent Joplin versions have an option to highlight the selected line in the markdown editor (so if you enable that you can still get the gray highlight on headings as you scroll)

v0.3.1

  • Slight tweak to fix rare case where it could scroll slightly too far, leaving the heading text cut off at the top of viewport

v0.4.0 - v0.4.1

  • Feature: Added button to copy link to heading
  • Fix: Issue with overly aggressive regex removing underscores between words in heading links

v0.4.2

  • Improve panel rendering performance