✅ Heading Navigation

Navigate between headings in org-mode, markdown, and LaTeX documents:

Note: These keybindings work consistently across org-mode, markdown, and LaTeX files. In LaTeX, headings correspond to \section{}, \subsection{}, etc.

,* First Heading
Content here...

,** Subheading A        <- Current position
Content...

,** Subheading B        <- Next heading
More content...

,* Second Heading       <- Another next heading

,* Parent Heading       <- Jump here
,** Child Heading
,*** Current Position   <- From here

✅ Source Block Navigation

Navigate between source blocks in org documents:

There are also speed-commands if you are the beginning of a block to navigate with n (next) and p (previous.)

Some text...

,#+BEGIN_SRC python      <- Current position
print("Hello")
,#+END_SRC

More text...

,#+BEGIN_SRC python      <- Next block
print("World")
,#+END_SRC

✅ Sibling Navigation (Speed Commands)

Speed commands provide efficient navigation between sibling headings (headings at the same level):

These commands only work when:

1. Speed commands are enabled

2. Cursor is at the beginning of a heading line

Example:

,* Parent
,** Sibling 1
,** Sibling 2          <- Press 'f' to jump to Sibling 3
,** Sibling 3          <- Press 'b' to jump back to Sibling 2
,** Sibling 4

Sibling navigation skips over child headings:

,** Sibling 1           <- Current position
,*** Child of Sibling 1
,*** Another child
,** Sibling 2           <- Press 'f' jumps here (skips children)

✅ Search Current File

Opens a quick pick showing all non-empty lines in the current file. Features:

• Live preview - cursor moves to selected line as you browse

• Fuzzy matching - type space-separated terms, all must match

• Match highlighting - matching terms are highlighted in results

• Cancel restores position - press Escape to return to original location

Example workflow:

1. Press C-c s to open fuzzy search

2. Type "function calculate" to find lines with both words

3. Use arrow keys or continue typing to narrow results

4. Press Enter to jump to selected line

5. Press Escape to cancel and return to original position

✅ Search Open Files

Like fuzzy search but searches across all open buffers/files. Results are grouped by file with file separators.

Use this to:

• Find text across multiple open files

• Navigate between related files quickly

• Review related code across different modules

✅ Search Outline (Headings/Symbols)

Searches only structural elements:

• Org files - Headlines (lines starting with *)

• Markdown files - Headings (lines starting with #)

• Code files - Function/class definitions

This provides a fast way to navigate document structure without seeing every line.

Icons indicate heading level:

• $(symbol-class) - Top-level or class

• $(symbol-class) $(symbol-class) - Second level

• $(symbol-method) - Functions/methods

⚠️ How a Jump Works

There is no prompt or picker: while a jump is running, your keystrokes are read straight from the editor, exactly as in Avy. The cursor never leaves the buffer and the status bar shows what the jump is waiting for.

Every jump command follows the same two steps. First you say what you are looking for, which for most commands is a single keystroke: C-c j c takes one character, C-c j j takes two, C-c j w takes the first character of a word, and C-c j l takes nothing at all. Second, each match is overlaid with a short label drawn on top of the text at its screen position, and typing the label jumps there. Nothing on the line shifts to make room.

If the query matches exactly one place, the jump happens immediately with no label to type.

Two-character labels narrow as you type. After the first character, only the matching targets stay lit and they redraw showing just the character that remains, so you always see exactly what to press next. Backspace undoes the last character you typed, and Escape cancels.

Labels are handed out nearest-first from the cursor, so the closest targets get the single-character labels and the far ones get pairs. When scimax.jump.allVisibleEditors is on (the default), every visible editor is labeled, so a jump can cross a split.

⚠️ Jump to Text (Timer)

This is the avy-goto-char-timer equivalent and the most flexible of the jump commands. Instead of a fixed number of characters, you type as much of the target text as you like and the matches highlight as you go. When you stop typing for a moment (300 ms by default, see scimax.jump.timeoutMs), the labels appear over whatever still matches.

Use it when one or two characters would leave too many candidates on screen. Backspacing past the labels returns you to editing the query.

👀 Jump to Character

👀 Jump to Word

Jumps to the start of a word, filtered by its first character:

1. Invoke scimax.jump.gotoWord

2. Type the character the word starts with, e.g. "f"

3. Every visible word starting with "f" is labeled (function, for, first, …)

4. Type the label to jump

The starting character is required rather than optional. Labeling every word on screen at once buries the text under labels, and the first character of the word you want is nearly always known.

⚠️ Jump to Heading

Labels every visible heading at once, with no character to type first. In a folded buffer that is most of the outline, which is where the overlay beats the fuzzy picker in scimax.org.jumpToHeading (C-c C-j): you can see the whole structure and pick from it directly rather than describing what you want.

The label is drawn over the leading stars rather than over the title, so the headings stay readable while you choose, and the cursor lands at the start of the heading line where the speed commands are active.

Headings are recognized per language, so org files use * headings, markdown files use # headings, and LaTeX files use \section and friends. A # comment inside an org source block is not mistaken for a heading.

✅ Jump to Line

Labels every visible line for quick vertical navigation:

1. Invoke scimax.jump.gotoLine

2. Every visible line gets a label (a, s, d, etc.)

3. Type the label to jump to that line

The cursor is placed at the first non-whitespace character of the selected line.

✅ Jump to Symbol

Jumps to structural elements in the visible area:

• Function/class definitions

• Org headings (* Heading)

• Markdown headings (# Heading)

• Comment markers (TODO, FIXME, NOTE, etc.)

Only visible symbols are labeled, making it very fast for navigating code structure.

👀 Jump to Subword

Like Jump to Word, but the boundaries inside an identifier count too. Type the character the part starts with, in either case: "v" labels the V in myVariableName as well as the v in my_variable_name. Useful for landing inside a long identifier rather than at its start.

⚠️ Listing the Jump Commands

If you cannot remember which letter follows C-c j, press ? instead. A picker lists every jump command with its keybinding and a one-line description, and choosing one runs it. The keybindings shown are read from the extension manifest, so they always reflect what is actually bound.

✅ Jump Actions

Beyond navigation, jump commands can perform actions:

These commands use the same labeling system but perform actions instead of just moving the cursor.

👀 Label Characters

Jump labels use home row keys for efficiency, ordered by ease of typing:

a s d f j k l g h q w e r u i o p z x c v b n m t y

Small numbers of matches use single characters. When there are more matches than characters, only as many prefixes as necessary are reserved for two-character labels, so most targets still get a single keystroke. Since labels are assigned nearest-first, the two-character labels land on the targets furthest from the cursor.

⚠️ Jump Settings

Raise scimax.jump.timeoutMs if the labels appear while you are still typing a longer query; lower it toward 0 to get labels immediately.

✅ Outline View

The Outline panel (View -> Outline) shows document structure:

For org files:

• Document title (from #+TITLE:)

• All headings in hierarchical structure

• TODO state indicators (box for TODO, check for DONE)

• Tags and priorities shown as details

• Source blocks (labeled with language)

• Tables

• Drawers

Symbols use semantic icons:

• $(symbol-class) - Level 1 headings

• $(symbol-method) - Level 2 headings

• $(symbol-function) - Level 3 headings

• $(symbol-key) - TODO items

• $(symbol-event) - DONE items

✅ Breadcrumb Navigation

The breadcrumb bar at the top of the editor shows your location in the document hierarchy:

Document Title > Level 1 Heading > Level 2 Heading > Current Position

Click any breadcrumb to see siblings and navigate quickly.

✅ Quick Outline

Press C-S-O (or s-S-O on Mac) to open VS Code's quick outline:

• Shows all document symbols

• Type to filter

• Press Enter to jump to symbol

This works similar to fuzzySearchOutline but uses VS Code's native UI.

✅ Global (All Modes)

✅ Org/Markdown Mode

✅ Speed Commands (at heading start)

✅ Quick Heading Navigation

Combine speed commands and fuzzy search:

1. Use j speed command for fuzzy heading search (when at heading start)

2. Use C-c C-j for heading search (from anywhere)

3. Use f/b speed commands to move between siblings

4. Use n/p speed commands to scan all headings

✅ Finding Code in Large Files

For code files:

1. C-c M-s - Search outline to find function/class

2. scimax.jump.gotoSymbol - Jump to visible function

3. C-S-O - VS Code quick outline for all symbols

✅ Cross-File Navigation

When working across multiple files:

1. C-c S-s - Search all open files

2. Open related files

3. Use navigation history (M-/M-) to move between locations

4. Use breadcrumbs to see context

✅ Precision Jumping

For maximum precision:

1. scimax.jump.gotoChar2 - Two characters gives fewer matches

2. scimax.jump.gotoSubword - Jump within camelCase names

3. scimax.jump.gotoWord with starting character - Filter words

✅ Source Block Workflows

When working with literate programming:

1. scimax.ob.jumpToBlock - Find block by name/language

2. scimax.ob.nextBlock/previousBlock - Navigate between blocks

3. scimax.ob.jumpToResults - Check execution results

4. Execute block (C-c C-c)

5. Jump to results to verify output

✅ Enable/Disable Features

{
  // Enable speed commands (single-key navigation at heading start)
  "scimax.speedCommandsEnabled": true,

  // Maximum number of items in fuzzy search (performance)
  "scimax.fuzzySearch.maxResults": 1000
}

✅ Custom Keybindings

Add custom keybindings in keybindings.json:

[
  // Custom jump to character binding
  {
    "key": "ctrl+;",
    "command": "scimax.jump.gotoChar",
    "when": "editorTextFocus"
  },

  // Custom next source block binding
  {
    "key": "ctrl+shift+n",
    "command": "scimax.ob.nextBlock",
    "when": "editorTextFocus && editorLangId == 'org'"
  }
]

✅ Fuzzy Search Not Working

If fuzzy search doesn't show results:

1. Check that the file has non-empty lines

2. Try searching with simpler terms

3. Check if file is too large (increase maxResults setting)

✅ Speed Commands Not Triggering

Speed commands require:

1. scimax.speedCommandsEnabled set to true

2. Cursor at column 0 (start of line)

3. Cursor on a heading line (starts with * in org, # in markdown)

Move cursor to beginning of heading with Home key, then try speed command.

✅ Jump Labels Not Appearing

If jump commands don't show labels:

1. Make sure there are visible matches in the viewport

2. Check that the editor has focus

3. Try scrolling to ensure matches are visible

✅ Navigation History Not Working

VS Code's navigation history works best when:

1. You make explicit jumps (jump commands, follow links)

2. You move between files

3. You use go to definition

Cursor movement with arrow keys doesn't create history entries.