TUI Mode

Interactive terminal user interface for browsing and reading markdown files

Overview

TUI (Terminal User Interface) mode is Glow’s interactive file browser that lets you discover, search, and read markdown files directly in your terminal. It provides a beautiful, keyboard-driven interface for navigating your documentation.

Launching TUI Mode

TUI mode is activated when you run Glow without specifying a file to render:

# Launch in current directory
glow

# Launch in a specific directory
glow ~/my-docs

# Launch with directory path
glow /path/to/markdown/files

When launched, Glow will scan the directory for markdown files and display them in an interactive list.

File Discovery

Glow’s TUI mode features intelligent file discovery:

Git Repository Awareness

When scanning for markdown files, Glow uses the gitcha package to:

• Detect if you’re in a Git repository
• Automatically respect .gitignore rules
• Only show files that aren’t ignored by Git

This ensures that build artifacts, dependencies in node_modules, and other ignored files won’t clutter your markdown browser.

Showing Hidden Files

By default, Glow respects .gitignore and hides system files. To show all files including hidden and ignored ones:

glow --all
# or
glow -a

You can also set this in your configuration file:

all: true

The --all flag switches between gitcha.FindFilesExcept() (respects .gitignore) and gitcha.FindAllFilesExcept() (shows everything) for file discovery.

Navigation Controls

File List Navigation

Moving Between Files

j, ↓         Move down
k, ↑         Move up
enter        Open selected file
h, l, ←, →   Navigate pages (when multiple pages)

Document Viewer Navigation

When viewing a markdown file in TUI mode:

Scrolling

j, ↓         Scroll down one line
k, ↑         Scroll up one line
d            Scroll down half page
u            Scroll up half page
f, pgdn      Page down
b, pgup      Page up

Searching and Filtering

Press / to activate the filter:

1. Start Filtering: Press / to show the search input
2. Type Your Query: Glow uses fuzzy search to filter files as you type
3. Navigate Results: Use ↑/↓ or ctrl+j/ctrl+k to browse matches
4. Select File: Press enter to open the selected file
5. Clear Filter: Press esc to cancel or clear the filter

The filter searches across file names and paths, making it easy to find documents quickly.

Mouse Support

Enable mouse support to scroll and interact with the TUI using your mouse:

glow --mouse
# or
glow -m

Or enable it in your config:

mouse: true

The --mouse flag is hidden in the help output but fully functional. When enabled, Glow calls tea.WithMouseCellMotion() to enable mouse wheel scrolling in the viewport.

Line Numbers

Show line numbers when viewing markdown files:

glow --line-numbers
# or
glow -l

This is especially useful when reading code-heavy documentation or when you need to reference specific lines.

File Watching

When viewing a file in TUI mode, Glow automatically watches for changes using fsnotify. If the file is modified externally, Glow will reload and re-render it automatically.

Example Workflow

Here’s a typical workflow using TUI mode:

# Navigate to your documentation directory
cd ~/projects/my-app

# Launch Glow in TUI mode
glow

# The interface shows:
# 1. Glow logo and status bar at top
# 2. List of markdown files found in the directory
# 3. Pagination at bottom (if many files)
# 4. Help hints at the very bottom

# Press '/' to search
# Type "api" to filter for API documentation
# Use arrow keys to select the right file
# Press 'enter' to open and read

# While reading:
# - Press 'e' to edit in your $EDITOR
# - Press 'c' to copy the full contents
# - Press 'esc' to return to the file list

Integration with Git

Since Glow is Git-aware, it works seamlessly in repositories:

# In a cloned repository
cd my-cloned-repo
glow

# Only committed and tracked markdown files appear
# Files in .gitignore are automatically hidden
# Draft files can be shown with --all

This makes Glow perfect for browsing documentation in open-source projects.

Related

CLI Mode

Learn about rendering markdown directly to stdout

Configuration

Customize TUI behavior with configuration options