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

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)

[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"

Custom Code Blocks Theme

Customize syntax highlighting in code blocks using Sublime Text .tmTheme files.

[ui]
code_theme = "base16-ocean.dark"  # Default theme

Built-in themes: base16-ocean.dark, base16-ocean.light, base16-eighties.dark, base16-mocha.dark, InspiredGitHub, Solarized (dark), Solarized (light)

Using custom themes:

1. Create the code-themes directory next to your config.toml file

2. Add your .tmTheme files to the directory

3. Reference the theme by name (filename without extension):

   [ui]
   code_theme = "MyCustomTheme"
   

CLI Overrides

Override settings for a single session:

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

Contributing

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

Roadmap

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

Why treemd?

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

Similar Tools

• 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.

Acknowledgements

License

MIT