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: --tree -n shows each section's line range, so you can read just the lines you need from a large file, or pull one out whole with --section. 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

Shell completions & man page

treemd --setup-completions   # Interactive tab-completion setup (bash/zsh/fish)
treemd --man-page > treemd.1 # Generate the man page (for packagers)

Completions are context-aware: they only offer .md/.markdown files and directories.

Usage

TUI Mode (Interactive)

treemd README.md                  # Open a file
treemd github:rust-lang/rust      # Read a GitHub repo's README, whatever it is named
treemd https://example.com/doc.md # Open any markdown URL

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

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

Line ranges

treemd -l -n README.md                  # Each heading with its [start-end] line range
treemd --tree -n README.md              # Same, in tree form

Useful for LLM-driven workflows: read the heading list first, then fetch only the line range for the section that matters instead of the whole file.

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       # Text contains "Features" (any case)
treemd -q '.h2["Installation"]' doc.md # Whole text is "Installation" (any case)
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
treemd -q '.h2[Install] | .code' doc.md          # Code inside one section

Functions like count, first, sort_by and join see everything a selector returns at once, and a selector piped from a heading looks only inside that heading's section.

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 array
treemd -q '.h2' --query-output json-pretty doc.md # Pretty JSON array
treemd -q '.h2' --query-output jsonl doc.md       # JSON Lines

json and json-pretty always print an array, even for a single result, and [] when nothing matches.

Exit Status

A query that matches nothing exits 0, as jq does. Add -e to exit 1 instead, so a script can tell:

treemd -q '.h2[Install]' -e README.md || echo "no install section"

A query that does not parse exits 3, and one that fails while running (such as "a" - 1) exits 5, as in jq.

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

A piped document could come from anywhere, so in the TUI its links and images stay inside the working directory, and it loads no image by absolute path. A document opened by URL reaches nothing on this machine at all. To treat piped documents like local files:

[security]
trust_piped_documents = true

Run treemd --query-help for complete documentation.

Releases

Pre-built Binaries

Download from the releases page:

Each archive holds the binary, named as above without the extension, and LICENSE; the .tar.gz archives also hold the man page, treemd.1. SHA256SUMS lists the hash of every archive, and each treemd-<target>.sha256 is the hash of the binary inside it. The archives are reproducible: the same binaries, packaged by scripts/package-release.sh with the same versions of tar, gzip and zip, give byte-identical archives. Each archive also has signed build provenance, checkable with gh attestation verify <archive> --repo Epistates/treemd. The Linux glibc builds need glibc 2.28 or newer (RHEL 8, Debian 10, Ubuntu 18.10); the musl builds need no glibc at all.

Each archive also has a signed build provenance attestation, which shows it was built by this repository's release workflow from the tagged commit:

sha256sum --check --ignore-missing SHA256SUMS
gh attestation verify treemd-x86_64-unknown-linux-gnu.tar.gz --repo Epistates/treemd

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

Building from Source

cargo build --release --locked   # target/release/treemd

The release binaries for every platform are built by .github/workflows/release.yml, which is the reference for each target's build.

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 = "compact"          # "compact" (default, gapless box characters) or "spaced"; used by --tree
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{...})
code_fences = "full"     # "full", "label", or "none" (see below)
slug_style = "treemd"    # "treemd" or "github" (see below)

Heading Anchors

slug_style decides how a heading becomes an anchor: the one Y copies, the id and slug in -l -o json, and .slug and slugify in queries. treemd, the default, drops _ and gives repeated headings the same anchor. github makes them the way github.com does: snake_case keeps its _, and the second ## Setup is #setup-1. Following a link finds the heading with either kind of anchor, whichever is set.

Code Block Appearance

code_fences controls how a fenced code block is delimited in the content pane. The rows are removed rather than hidden, so they take no vertical space.

With label, a block with no language gets no label row either. The name sits on its own row rather than on the first line of code, so selecting the block with the mouse does not drag it in.

The code block background comes from the code theme by default, so it agrees with the syntax colors. Override or disable it:

[theme]
code_block_bg = { rgb = [40, 40, 50] }  # explicit color
# code_block_bg = "none"                # leave code on the terminal background

The background covers the full width of the block, including padding, so short lines do not leave a ragged edge.

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, FilePicker, FileSearch, ImageViewer

A binding that names an unknown key or action is skipped, and the rest of the file still applies; the status bar says which entries were skipped.

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)
• Obsidian and GitHub callouts

Planned:

• 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