treemd

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.

Table of Contents

• 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

Overview

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

Features

Interactive TUI

CLI Mode

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

Installation

From crates.io

cargo install treemd

From source

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

Package managers

Homebrew (macOS/Linux):

brew install treemd

Arch Linux (extra repo):

pacman -S treemd

NetBSD:

pkgin install treemd

Usage

TUI Mode (Interactive)

Launch the interactive interface by running treemd with a file:

treemd README.md        # Open specific file
treemd .                # Open file picker in current directory
treemd docs/            # Open file picker in specified directory
treemd *.md             # Open file picker with matched files

Keyboard Shortcuts

Navigation

Tree Operations

Search

Link Following

Interactive Mode

Table Navigation (within interactive mode)

Commands & System

Selecting and copying text

treemd captures the mouse for scroll-wheel navigation, which by default suppresses your terminal's native click-drag selection. To grab an arbitrary substring:

• Hold Shift while dragging — most terminals (iTerm2, kitty, GNOME Terminal, Konsole, Windows Terminal) bypass application mouse capture and select natively.
• Press M to release mouse capture entirely, then select and copy as usual; press M again to restore scroll-wheel navigation.

For whole sections, y copies the current section straight to the clipboard without leaving treemd.

CLI Mode (Non-Interactive)

List headings

treemd -l README.md

Show heading tree

treemd --tree README.md

Extract a section

treemd -s "Installation" README.md

Filter and level options

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

Count and JSON output

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

Query Language

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

Element Selectors

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

Filters and Indexing

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

Pipes and Functions

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

Hierarchy Operators

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

Aggregation

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

Output Formats

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

Stdin Support

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.

Releases

Pre-built Binaries

Download from the releases page:

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

Building from Source

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

Artifacts are output to target/release-artifacts/.

Configuration

treemd stores configuration in a TOML file:

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

Basic Configuration

[ui]
theme = "Nord"                  # OceanDark, Nord, Dracula, Solarized, Monokai, Gruvbox, TokyoNight, CatppuccinMocha
outline_width = 30              # 20, 30, or 40
tree_style = "spaced"           # "spaced" (default) or "compact" (gapless box characters)
outline_heading_markers = true  # Show #/##/### level markers in outline sidebar

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

[content]
hide_frontmatter = true  # Hide YAML frontmatter (---\n...\n---) in content view
hide_latex = true        # Hide LaTeX math expressions ($...$, $$...$$, \begin{...})

Custom Keybindings

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.

Custom Theme Colors

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)

```toml [ui] theme = "Nord"

[theme] background = { rgb = [25, 25, 3