GemReader/docs/navigation.md

TUI Navigation and Controls

This document provides a comprehensive guide to navigating and interacting with GemReader's terminal user interface.

Basic Navigation

Key	Action
↑ or k	Move up one line
↓ or j	Move down one line
PgUp or Ctrl+U	Move up one page
PgDn or Ctrl+D	Move down one page
g or Home	Go to top of document
G or End	Go to end of document

Dual Pane Interface

GemReader features a split-screen interface with two panes:

Content Pane (Right)

• Main area for viewing and scrolling through the markdown document
• This is the default active pane when the application starts

Table of Contents Pane (Left)

• Displays a hierarchy of document headings automatically generated from markdown headers
• Shows headers with proper indentation based on header level (#, ##, ###, etc.)

Pane Navigation

• Use Tab to switch between TOC and content panes
• When in TOC pane, use ↑ or ↓ to navigate between table of contents entries
• Press Enter while in TOC pane to jump to the selected header in the content pane
• Header indentation reflects the header level (#, ##, ###, etc.)
• Selected entries in the TOC are marked with a > character

Help System

• Press h or ? to toggle help visibility
• The help information shows available navigation commands
• Help is displayed at the bottom of the screen
• The help text has a subtle gray color to distinguish it from content

Visual Elements

Border Indicators

• Active pane has a yellow border
• Inactive pane has a blue border

Advanced Navigation Tips

1. Quick Navigation: Use g to jump to the beginning and G to jump to the end of the document.

2. Page Navigation: Use Page Up and Page Down keys to quickly move through longer documents.

3. TOC Navigation: Use Tab to switch to the TOC pane, navigate with arrow keys, and press Enter to jump to specific sections.

4. Toggle Help: Press h or ? to hide help text if you need more screen space for reading.

Screen Layout

The terminal interface is organized as follows:

1. Table of Contents Pane (left): Shows document structure with clickable headers
2. Content Pane (right): Main content area with the rendered markdown
3. Help Text (bottom): Shows navigation keys (when visible)

Troubleshooting Navigation Issues

Keys Not Responding

• Some terminals may not recognize certain key combinations
• Try using the alternative keys listed in the table above
• Ensure your terminal is not intercepting the key combinations

Scrolling Issues with Large Documents

• Use Page Up/Page Down for faster navigation
• Use the table of contents (switch with Tab and navigate with arrows) to jump to specific sections
• Navigate to top (g) or bottom (G) for quick positioning