treemd 0.2.2

A markdown navigator with tree-based structural navigation and syntax highlighting
Documentation

treemd

Crates.io Documentation License: MIT Build Status

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

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 just reading comfortably in your terminal, treemd provides both CLI tools for scripting and a beautiful TUI for interactive exploration.

Features

Interactive TUI

  • Dual-pane interface - Navigate outline while viewing content
  • Live editing - Edit files in default editor with auto-reload (respects $VISUAL/$EDITOR)
  • Link following - Follow markdown links with visual popup, supports anchor/file/wikilink/external URLs
  • Navigation history - Back/forward between files with full state preservation
  • Syntax highlighting - 50+ languages with full syntect integration
  • Vim-style navigation - j/k, g/G, d/u, p (parent) for efficient browsing
  • Search & filter - Press / to filter headings in real-time
  • Collapsible tree - Expand/collapse sections with Space/Enter
  • Bookmarks - Mark positions (m) and jump back (')
  • Adjustable layout - Toggle outline visibility, resize panes
  • Rich rendering - Bold, italic, inline code, lists, blockquotes, code blocks

CLI Mode

  • List headings - Quick overview of document structure
  • Tree visualization - Hierarchical display with box-drawing
  • Section extraction - Extract specific sections by heading name
  • Smart filtering - Filter by text or heading level
  • Multiple formats - Plain text, JSON output
  • Statistics - Count headings by level

treemd is incredibly powerful as a CLI utility. Using the --tree visualizations with --section enables rapid piecewise consumption of even the largest .md files.

Installation

From crates.io

cargo install treemd

From source

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

Usage

TUI Mode (Interactive - Default)

Simply run treemd without flags to launch the interactive interface:

treemd README.md

Keyboard Shortcuts:

Navigation:

  • j/k or ↓/↑ - Navigate up/down
  • g/G - Jump to top/bottom
  • p - Jump to parent heading
  • d/u - Page down/up (in content)
  • Tab - Switch between outline and content
  • 1-9 - Jump to heading 1-9 (instant access)

Tree Operations:

  • Enter/Space - Toggle expand/collapse
  • h/l or ←/→ - Collapse/expand heading

UX Features:

  • w - Toggle outline visibility (full-width content)
  • [ ] - Decrease/increase outline width (20%, 30%, 40%)
  • m - Set bookmark at current position
  • ' - Jump to bookmarked position

Link Following:

  • f - Enter link follow mode (shows popup with all links)
  • Tab/Shift+Tab - Navigate through links
  • j/k or ↓/↑ - Navigate links (in link mode)
  • 1-9 - Jump directly to link by number
  • p - Jump to parent heading's links (stays in link mode)
  • Enter - Follow selected link (opens browser, loads file, or jumps to anchor)
  • b/Backspace - Go back to previous file
  • Shift+F - Go forward in navigation history
  • Esc - Exit link follow mode

Editing & System:

  • e - Edit current file in default editor (respects $VISUAL or $EDITOR)
  • t - Cycle color theme
  • y - Copy current section content to clipboard
  • Y - Copy anchor link to clipboard

Search & Help:

  • / - Search/filter headings (type to filter, Esc to clear)
  • ? - Toggle help overlay
  • q/Esc - Quit

Interface Features:

  • Live editing - Edit files in your default editor and auto-reload (press e)
  • Link following popup - Visual navigator shows all links with highlighting (press f)
  • Multi-file navigation - Load files via links with full history (back/forward)
  • External URL opening - Opens links in default browser automatically
  • Syntax-highlighted code blocks - 50+ languages supported
  • Inline formatting - Bold, italic, inline code with colors
  • Real-time search - Filter headings as you type (press /)
  • Toggle outline - Hide for full-width reading (press w)
  • Adjustable layout - Resize outline 20%/30%/40% (press [ ])
  • Quick navigation - Jump to any heading 1-9 instantly, parent with p
  • Bookmarks - Mark and return to positions (press m and ')
  • Color-coded headings - 5 distinct levels
  • Scrollbars - Position indicators on both panes
  • Smart status bar - Shows position, link details, navigation history
  • Help overlay - Always available (press ?)

CLI Mode (Non-Interactive)

List all headings

treemd -l README.md

Output:

# treemd
## Features
### Phase 1: CLI Mode
### Phase 2: TUI Mode
## Installation
...

Show heading tree

treemd --tree README.md

Output:

└─ # treemd
    ├─ ## Features
    │   ├─ ### Phase 1: CLI Mode
    │   └─ ### Phase 2: TUI Mode
    ├─ ## Installation
    ...

Extract a section

treemd -s "Installation" README.md

Output:

## Installation

cargo install --path .
...

Filter headings

treemd -l --filter "usage" README.md

Show only specific heading level

treemd -l -L 2 README.md  # Only ## headings

Count headings

treemd --count README.md

Output:

Heading counts:
  #: 1
  ##: 5
  ###: 6

Total: 12

JSON output

treemd -l -o json README.md

Releases

Cross-Platform Binaries

Pre-built binaries for multiple platforms are available on the releases page. Supported platforms:

  • Linux x86_64 - treemd-x86_64-unknown-linux-gnu
  • Linux ARM64 - treemd-aarch64-unknown-linux-gnu
  • macOS x86_64 - treemd-x86_64-apple-darwin
  • macOS ARM64 (Apple Silicon) - treemd-aarch64-apple-darwin
  • Windows x86_64 - treemd-x86_64-pc-windows-msvc.exe

Building from Source

To build binaries locally for all platforms (requires cross for Linux ARM targets):

# Install cross for Linux ARM support
cargo install cross

# Build all platforms
./scripts/build-all.sh

Artifacts will be in target/release-artifacts/.

Code Signing

macOS: Pre-built binaries are signed with Developer ID and notarized by Apple, so you won't see any Gatekeeper warnings.

Linux & Windows: Binaries are provided as-is. These are standard CLI tools that work on all systems.

Contributing

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

Roadmap

Future enhancements planned:

  • Obsidian Flavored Markdown (callouts, wikilinks)
  • Multiple color themes (Nord, Dracula, Solarized)
  • Configuration file support
  • Fuzzy search
  • Multiple file tabs
  • Link following
  • Watch mode (auto-reload on file change)

Why treemd?

  • Tree-based navigation: Unlike less or cat, treemd understands document structure and lets you explore it like a file tree
  • Expandable outline: Drill down into sections by collapsing/expanding headings—just like tree command
  • Interactive TUI: Beautiful dual-pane interface with vim-style navigation and synchronized scrolling
  • CLI and TUI modes: Use interactively for reading or in scripts for extraction/filtering
  • Fast: Built in Rust, optimized binary with syntax highlighting
  • Rich rendering: Color-coded headings, syntax-highlighted code blocks (50+ languages), styled inline formatting
  • User-friendly: Scrollbars, help overlays, bookmarks, and fuzzy search

Similar Tools

  • tree - File tree explorer (inspiration for outline navigation)
  • glow - Beautiful markdown rendering (presentation-focused, not interactive)
  • mdcat - Markdown rendering to terminal (no navigation)
  • bat - Syntax highlighting pager (not markdown-aware)
  • less - Classic pager (no structure awareness)

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

License

MIT