Description

VS Code/Sublime text style overlay panel to navigate through headings (toc/table of contents) in the markdown editor

Additional Information

[!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.

[!important] 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.

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.

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

On desktop, selecting a heading with the keyboard previews it by immediately scrolling the editor to that heading. Hitting enter in the panel (or clicking somewhere else) will close the panel. Hitting escape will close the panel & return to your original scroll/cursor position. Previewing is disabled on mobile and can be disabled in the plugin settings on desktop.

[!note] When the panel is pinned, clicking outside of the panel will not close the panel, and hitting escape will move focus to the editor without closing the panel or restoring previous scroll position.

Features

• Navigate through headings with the keyboard
• Search filter to filter list of headings
• Copy link to heading: right-click a heading on desktop, long-press on mobile
• Panel adapts to your Joplin theme
• Adjustable panel size (desktop only)
• Ability to pin panel so it stays open until you unpin it (desktop only)

Settings

The plugin can be customized via Tools | Options | 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
• Panel top offset: 0-200px distance from the top of the editor (default: 12px)
  • Push the panel down to avoid overlapping other top-right editor decorations, such as a backlinks indicator (desktop only)
• Heading metadata display: What each heading row shows alongside its text (default: Full)
  • Full: the H# - line # metadata row
  • Compact: an H# level badge instead of the metadata row
  • None: no level indicator at all
  • Compact and None also reduce heading row height on desktop, so more headings fit in the panel. Mobile keeps its larger touch targets.
• Preview headings while navigating: Scroll the editor to the highlighted heading while filtering or using keyboard navigation (default: on, desktop only)
• Copy internal anchor links: Copy [Heading](#heading-anchor) instead of [Heading @ Note](:/noteId#heading-anchor) (default: off)

Panel appearance settings take effect the next time the panel is opened. The copy link setting applies to the next copied link.

Mobile Support

• The plugin can be accessed via the toolbar icon in the editing toolbar in the markdown editor.

• On mobile, the panel has a responsive design and appears centered with faded background.

• Long-press a heading to copy its link.

• Filtering and keyboard navigation highlight headings in the panel without scrolling the note behind the modal. Selecting a heading still navigates to it.