A markdown navigator with tree-based structural navigation. Like the tree command, but interactive—navigate markdown documents using an expandable/collapsible heading tree with a synchronized content view.

• Overview
• Features
  • Interactive TUI
  • CLI Mode
• Installation
• Usage
  • TUI Mode
  • CLI Mode
  • Query Language
• Releases
• Configuration
  • Basic Settings
  • Custom Keybindings
  • Custom Theme Colors
• Contributing
• Roadmap
• Why treemd?
• Similar Tools
• License

treemd is a modern markdown viewer that combines the structural clarity of the tree command with powerful interactive navigation. Whether you're exploring large documentation files, analyzing markdown structure, or reading comfortably in your terminal, treemd provides both CLI tools for scripting and a beautiful TUI for interactive exploration.

Use it to:

• Navigate large documents by collapsing/expanding heading sections
• Search headings or full document content with highlighted matches
• Edit tables, toggle checkboxes, and follow links—all without leaving the terminal
• Extract specific sections or query markdown elements with a jq-like syntax
• Pipe markdown from stdin for shell-scripted workflows

Pro tip: Combine --tree with --section for rapid navigation of large files. The query language brings jq-like power to markdown extraction.

cargo install treemd

git clone https://github.com/epistates/treemd
cd treemd
cargo install --path .

Homebrew (macOS/Linux):

brew install treemd

Arch Linux (extra repo):

pacman -S treemd

NetBSD:

pkgin install treemd

Launch the interactive interface by running treemd with a file:

treemd README.md

treemd -l README.md

treemd --tree README.md

treemd -s "Installation" README.md

treemd -l --filter "usage" README.md    # Filter by text
treemd -l -L 2 README.md                # Only ## headings

treemd --count README.md                # Count by level
treemd -l -o json README.md             # JSON output

treemd includes a powerful jq-like query language for extracting markdown elements. Use -q to execute queries and --query-help for full documentation.

treemd -q '.h' doc.md         # All headings
treemd -q '.h2' doc.md        # Level 2 headings
treemd -q '.code' doc.md      # Code blocks
treemd -q '.link' doc.md      # Links
treemd -q '.img' doc.md       # Images
treemd -q '.table' doc.md     # Tables

treemd -q '.h2[Features]' doc.md       # Fuzzy match
treemd -q '.h2["Installation"]' doc.md # Exact match
treemd -q '.h2[0]' doc.md              # First h2
treemd -q '.h2[-1]' doc.md             # Last h2
treemd -q '.h2[1:3]' doc.md            # Slice
treemd -q '.code[rust]' doc.md         # By language

treemd -q '.h2 | text' doc.md                    # Get text (strips ##)
treemd -q '[.h2] | count' doc.md                 # Count elements
treemd -q '[.h] | limit(5)' doc.md               # First 5
treemd -q '.h | select(contains("API"))' doc.md  # Filter
treemd -q '.h2 | text | slugify' doc.md          # URL slug
treemd -q '.link | url' doc.md                   # Extract URLs

treemd -q '.h1 > .h2' doc.md           # Direct children
treemd -q '.h1 >> .code' doc.md        # All descendants
treemd -q '.h1[Features] > .h2' doc.md # Combined

treemd -q '. | stats' doc.md           # Document statistics
treemd -q '. | levels' doc.md          # Heading counts by level
treemd -q '. | langs' doc.md           # Code blocks by language

treemd -q '.h2' --query-output json doc.md        # JSON
treemd -q '.h2' --query-output json-pretty doc.md # Pretty JSON
treemd -q '.h2' --query-output jsonl doc.md       # JSON Lines

cat doc.md | treemd -q '.h2'
curl -s https://raw.githubusercontent.com/.../README.md | treemd -q '.h'
tree | treemd                          # Pipe tree output to TUI

Run treemd --query-help for complete documentation.

Download from the releases page:

macOS binaries are signed with Developer ID and notarized by Apple.

cargo install cross              # For ARM cross-compilation
./scripts/build-all.sh           # Build all platforms

Artifacts are output to target/release-artifacts/.

treemd stores configuration in a TOML file:

The file is created automatically when you change settings (theme with t, outline width with [/]).

[ui]
theme = "Nord"         # OceanDark, Nord, Dracula, Solarized, Monokai, Gruvbox, TokyoNight, CatppuccinMocha
outline_width = 30     # 20, 30, or 40

[terminal]
color_mode = "auto"    # "auto", "rgb", or "256"

Remap any key for any mode using intuitive TOML syntax. Multi-key sequences are supported.

[keybindings.Normal]
"j" = "Next"
"k" = "Previous"
"Ctrl+c" = "Quit"
"g g" = "First"          # Multi-key sequence

[keybindings.Interactive]
"Escape" = "ExitInteractiveMode"
"Tab" = "InteractiveNext"

[keybindings.Search]
"Ctrl+n" = "NextMatch"
"Ctrl+p" = "PrevMatch"

Available modes: Normal, Help, ThemePicker, Interactive, InteractiveTable, LinkFollow, LinkSearch, Search, DocSearch, CommandPalette, ConfirmDialog, CellEdit

See the built-in defaults in src/keybindings/defaults.rs for all available actions.

Override any color from your base theme. Colors can be specified as:

• Named: "Red", "Cyan", "White", "DarkGray"
• RGB: { rgb = [255, 128, 0] }
• Indexed: { indexed = 235 } (256-color palette)

[ui]
theme = "Nord"

[theme]
background = { rgb = [25, 25, 35] }
heading_1 = { rgb = [120, 200, 255] }
heading_2 = "LightBlue"
border_focused = "Cyan"
search_match_bg = { rgb = [100, 100, 50] }
search_match_fg = "White"

[theme]
# Background and text
background = { rgb = [25, 25, 35] }
foreground = { rgb = [220, 220, 230] }

# Headings (5 levels)
heading_1 = { rgb = [120, 200, 255] }
heading_2 = "LightBlue"
heading_3 = { indexed = 114 }
heading_4 = "Yellow"
heading_5 = "Gray"

# Borders and UI
border_focused = "Cyan"
border_unfocused = "DarkGray"
selection_bg = { rgb = [45, 45, 60] }
selection_fg = "White"

# Status bar
status_bar_bg = { rgb = [30, 30, 45] }
status_bar_fg = { rgb = [200, 200, 210] }

# Code
inline_code_fg = { rgb = [255, 200, 100] }
inline_code_bg = { rgb = [40, 40, 50] }
code_fence = { rgb = [150, 180, 200] }

# Text formatting
bold_fg = "White"
italic_fg = { rgb = [180, 140, 200] }
list_bullet = "Cyan"

# Blockquotes
blockquote_border = { rgb = [100, 100, 120] }
blockquote_fg = { rgb = [150, 150, 170] }

# Search highlighting
search_match_bg = { rgb = [100, 100, 50] }
search_match_fg = "White"
search_current_bg = "Yellow"
search_current_fg = "Black"

Override settings for a single session:

treemd --theme Dracula README.md
treemd --color-mode 256 README.md
treemd --color-mode rgb README.md

Contributions are welcome! Please feel free to submit a Pull Request.

Completed:

• Query language (jq-like syntax)
• Stdin/pipe support
• 8 color themes
• Configuration file
• Link following with history
• WikiLinks support
• Customizable keybindings
• Live file watching (auto-reload)

Planned:

• Obsidian Flavored Markdown (callouts)
• Fuzzy search improvements
• Multiple file tabs
• Custom query language plugins

treemd understands markdown structure. Navigate documents like a file tree, drill into sections, search content, edit tables, and follow links—all from your terminal.

• tree — File tree explorer (inspiration for outline navigation)
• glow — Beautiful markdown rendering (presentation-focused)
• mdcat — Markdown rendering to terminal
• bat — Syntax highlighting pager
• less — Classic pager

treemd combines the best of these: tree-based exploration + interactive navigation + comfortable reading + CLI scriptability.

MIT