henriklovhaug/md-tui
henriklovhaug/md-tui has 563 GitHub stars and 33 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 21:08 UTC. Last push 2026-11-14.
What you can do
- Keyboard-driven navigation
- Internal and external links
- File tree for browsing Markdown files
- Search and link selection modes
Measured star growth
- in 24h
- 0
- in 7 days
- Update delayed
- in 15 days
- Update delayed
- in 1 month
- Update delayed
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
Markdown renderer in the terminal
Developer ToolsREADME.md
OriginalMD-TUI
MD-TUI is a terminal-based application for viewing and navigating Markdown
files. It focuses on keyboard navigation and functional link navigation.
Capabilities
- Keyboard-driven navigation
- Internal and external links
- File tree for browsing Markdown files
- Search and link selection modes
- Optional image rendering, depending on terminal support
Installation
Prebuilt binaries with install script can be found on the release page.
| Target | Method |
|---|---|
| Arch | pacman -S md-tui |
| Cargo | cargo install md-tui --locked |
| Conda-Forge | pixi global install md-tui |
| Homebrew | brew install md-tui |
| Nix | There is a flake |
Requirements
- A terminal
- Nerd font
Usage
Start the program running mdt <file.md> or just mdt. The latter will search
recursively from where it was invoked for Markdown files and present them in a
file tree.
You can also pipe the content into the program. Example: cat README.md | mdt.
Key Binds
These are the default settings. See keyboard configuration for configuration options.
| Key | Action |
|---|---|
j or <Down> |
Scroll down |
k or <Up> |
Scroll up |
h |
Go up half a page |
l |
Go down half a page |
d or <Right> |
Scroll one page down |
u or <Left> |
Scroll one page up |
f or / |
Search |
n or N |
Jump to next or previous search result |
s or S |
Enter select link mode. Different selection strategy |
D |
Enter select details mode. Cycle through <details> blocks |
K |
Hover. Preview link targets without following them |
<Enter> |
Select. Open link, search, or toggle fold on selected <details> |
Esc |
Go back to normal mode |
t |
Go back to files |
b |
Go back to previous file (file tree if no previous file) |
g |
Go to top of file |
G |
Go to bottom of the file |
e |
Edit file in $EDITOR |
o |
Sort files in file tree |
q |
Quit the application |
Syntax Highlighting
MD-TUI supports syntax highlighting in code blocks for the following
languages:
- Bash/sh
- C/C++
- CSS
- Elixir
- Go
- HTML
- Java
- JavaScript
- JSON
- Lua
- Luau
- OCaml
- PHP
- Python
- Rust
- Scala
- TypeScript
- YAML
Configuration
The program checks for the file ~/.config/mdt/config.toml at startup. The
following parameters and their defaults are written below.
Keyboard Actions
Some key actions are not configurable, including:
- Enter
- Arrow keys
- Escape
- Question mark for help menu
- 'q' to quit the application
- '/' for search
If you override another default key, it's undefined behavior if that key does not get reassigned.
Actions can only be assigned to single characters. Space, fn keys, ctrl+key, backspace etc., will not take effect and the default will be in use.
# Keyboard actions
up = 'k'
down = 'j'
page_up = 'u'
page_down = 'd'
half_page_down = 'l'
half_page_up = 'h'
top = 'g'
bottom = 'G'
search = 'f'
search_next = 'n'
search_previous = 'N'
# This will search downwards until it finds one or select the last link in document.
select_link = 's'
# Finds the link 2/3 up the page. It will search then for closest in both direction.
select_link_alt = 'S'
# Enter select-details mode. Press <Enter> on a selected <details> to fold/unfold it.
select_details = 'D'
# Select CriticMarkup annotations. Press <Enter> to read the selected comment.
select_annotation = 'c'
headings = 'H' # open the document heading navigator
theme = 'T' # open the theme chooser
edit = 'e'
hover = 'K'
back = 'b'
file_tree = 't'
sort = 'o'
Colors and Misc
Press T in the file tree or document view to choose a color theme. Custom
uses the colors in ~/.config/mdt/config.toml; Match terminal resets colors
to the terminal's palette. Light, Dark, Warm light, and High contrast
provide accent palettes (they do not change the terminal background).
In the chooser, use j/k or arrow keys and Enter to apply, s to save the
current palette under a name, and x to delete a saved palette (with confirmation).
Edit custom colors in config.toml or saved palettes in
~/.config/mdt/themes/<name>.json. The selected theme is remembered across runs.
Setting color to "" will not remove it, but leave it as its default. To remove
colors, set it to reset.
The code_hl_* keys color the highlighting inside fenced code blocks.
# General settings
width = 100 # Set to 0 for full terminal width
gitignore = false
alignment = "left" # "center" | "right"
help_menu = true # false hides it
document_header = false # true shows the current document path
file_tree_details = false # true shows each file's modified time and size in the file tree
file_tree_directory_header = false # true shows the browsing directory in the file tree
document_header_full_path = false # true shows the absolute document path, with or without document_header
heading_style = "hashes" # "bars" renders H2-H6 with indented accent bars
scrollbar = true # false hides the document position indicator
image_max_height = 20 # maximum terminal rows used by an inline image
remember_position = true # restore recently viewed documents at their last position
position_cache_ttl_minutes = 60 # ignore older positions; 0 means never expire
escape_quits = false # true makes Escape quit once nothing is selected or searched
# Environment variable MDT_ESCAPE_QUITS=true does the same for one launch, e.g. inside a tmux popup
# Inline styling
bold_color = "reset"
bold_italic_color = "reset"
code_bg_color = "#2A2A2A"
code_fg_color = "red"
italic_color = "reset"
link_color = "blue"
link_selected_bg_color = "darkgrey"
link_selected_fg_color = "green"
scrollbar_color = "lightgreen"
critic_highlight_bg_color = "darkgrey"
critic_highlight_fg_color = "reset"
strikethrough_color = "reset"
# Block styling
code_block_bg_color = "#2A2A2A"
quote_bg_color = "reset"
table_header_bg_color = "reset"
table_header_fg_color = "yellow"
# Code block syntax highlighting
code_hl_attribute = "yellow"
code_hl_constant = "yellow"
code_hl_function = "green"
code_hl_function_builtin = "green"
code_hl_keyword = "red"
code_hl_operator = "red"
code_hl_property = "blue"
code_hl_punctuation = "blue"
code_hl_punctuation_bracket = "blue"
code_hl_punctuation_delimiter = "blue"
code_hl_string = "magenta"
code_hl_string_special = "magenta"
code_hl_tag = "cyan"
code_hl_type = "cyan"
code_hl_type_builtin = "cyan"
code_hl_variable = "reset"
code_hl_variable_builtin = "reset"
code_hl_variable_parameter = "reset"
# File tree
file_tree_name_color = "blue"
file_tree_page_count_color = "lightgreen"
file_tree_path_color = "gray"
file_tree_selected_fg_color = "lightgreen"
# Quote bar
quote_caution = "lightmagenta"
quote_default = "white"
quote_important = "lightred"
quote_note = "lightblue"
quote_tip = "lightgreen"
quote_warning = "lightYellow"
# Heading
h_bg_color = "blue"
h_fg_color = "black"
h2_fg_color = "green"
h3_fg_color = "magenta"
h4_fg_color = "cyan"
h5_fg_color = "yellow"
h6_fg_color = "lightred"
# Help box
help_bg_color = "black"
help_fg_color = "lightgreen"
help_title_color = "lightgreen"
CriticMarkup comments
MD-TUI renders CriticMarkup highlight/comment pairs without their delimiters:
{==Text under review==}{>>Comment about that text.<<}
Press c to select an annotation, use j/k, the arrow keys, or n/N to
move between annotations, and press Enter to read its comment. Enter, Escape,
or q closes the comment popup and stays in annotation mode. With the popup
closed, Escape or q exits annotation mode.
Links
MD-TUI supports the following link formats:
[text](url)[[link]][[link|Some title]]
Neovim Plugin
This application also exists as a plugin for Neovim called Preview.
[!NOTE]
This version does not support images regardless of your terminal capabilities.
Contributions
Both PRs and issues are appreciated!
Use as Library
It's possible to use this as a library. It's not well documented for that use, but the feature is there. There is one default feature attached, which is the whole highlighting of code blocks.