MD-TUI

• MD-TUI
  • Installation
    • Requirements
  • Usage
  • Key binds
  • Syntax highlighting
  • Configuration
    • Keyboard actions
    • Colors and misc
  • Links
  • Neovim plugin
  • Contributions
  • Use as library

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.

Requirements

1. A terminal
2. 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.

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'
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_directory_header = false # true shows the browsing directory in the file tree
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

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