mat

cat for markdown. Render markdown files beautifully in the terminal.

Installation

cargo install --path .

Or with cargo from crates.io (coming soon):

cargo install mat

Usage

# Basic rendering
mat README.md

# With a theme
mat --theme dracula README.md

# Multiple files
mat *.md

# From URL
mat https://raw.githubusercontent.com/user/repo/main/README.md

# From stdin
curl -s https://example.com/doc.md | mat

Features

Themes

Six built-in themes with full syntax highlighting:

mat --theme default   # Balanced colors (default)
mat --theme light     # Light terminal friendly
mat --theme dark      # Dark terminal optimized
mat --theme dracula   # Dracula color scheme
mat --theme nord      # Nord color palette
mat --theme gruvbox   # Gruvbox colors

Create custom themes in ~/.config/mat/themes/.

Interactive Mode

Vim-like navigation for reading long documents:

mat -i README.md

Key	Action
j/k	Scroll down/up
d/u	Half page down/up
g/G	Top/bottom
/	Search
n/N	Next/previous match
t	Toggle TOC
q	Quit

Presentation Mode

Turn markdown into slides using --- or ## as separators:

mat --slides presentation.md

Search

Find and highlight patterns with regex support:

mat -s "TODO" README.md
mat -s "func.*\(" --ignore-case src.md
mat -s "error" -C 3 logs.md  # With context lines

Linting

Check markdown style against common rules:

mat --lint README.md

Checks for:

• Heading structure (MD001-MD003)
• Line length (MD013)
• Trailing whitespace (MD009)
• Consecutive blank lines (MD012)
• Missing alt text (MD045)
• Broken link syntax (MD039, MD042)
• Inconsistent list markers (MD004)
• Heading punctuation (MD026)
• Code fence languages (MD040)
• Duplicate headings (MD024)

JSON AST

Output the document as a JSON abstract syntax tree:

mat --json README.md
mat --json-pretty README.md | jq '.metadata'

Table of Contents

mat --toc README.md

Section Extraction

Extract specific sections by heading:

mat --section "Installation" README.md

Document Stats

mat --stats README.md
# Words: 1,234 | Headings: 12 | Links: 8 | Images: 3 | Code blocks: 15

Link Validation

Check all links in your markdown:

mat --check-links README.md

Watch Mode

Auto-refresh on file changes:

mat -W README.md

Diff

Compare two markdown files:

mat diff old.md new.md

HTML Export

mat --html README.md > output.html
mat --html-standalone README.md > standalone.html

Git Integration

View markdown at specific git refs:

mat show HEAD:README.md
mat show main~5:docs/guide.md

Concatenation

Merge multiple files with headers:

mat concat README.md CONTRIBUTING.md > combined.md

Shell Completions

# Bash
mat completions bash > ~/.local/share/bash-completion/completions/mat

# Zsh
mat completions zsh > ~/.zfunc/_mat

# Fish
mat completions fish > ~/.config/fish/completions/mat.fish

Configuration

Initialize config directory:

mat init

Edit ~/.config/mat/config.toml:

theme = "dracula"
width = 100
pager = true
line_numbers = false
file_headers = true

[code]
theme = "base16-ocean.dark"
background = true

All Options

Usage: mat [OPTIONS] [FILES]... [COMMAND]

Commands:
  init         Initialize config directory
  themes       List available themes
  config       Show current configuration
  diff         Compare two markdown files
  show         Show markdown from git ref
  concat       Concatenate files with headers
  completions  Generate shell completions

Options:
  -t, --theme <THEME>      Color theme
      --plain              Disable colors
  -w, --width <WIDTH>      Output width
  -n, --line-numbers       Show line numbers
  -p, --pager              Force pager
      --toc                Show table of contents
      --section <HEADING>  Extract section
      --check-links        Validate links
  -W, --watch              Watch for changes
      --stats              Show document stats
      --html               Export as HTML
      --html-standalone    Export as standalone HTML
      --frontmatter        Show YAML frontmatter
  -i, --interactive        Interactive viewer
      --slides             Presentation mode
  -s, --search <PATTERN>   Search pattern
      --ignore-case        Case insensitive search
  -C, --context <LINES>    Context lines for search
      --lint               Check markdown style
      --json               Output as JSON AST
      --json-pretty        Output as pretty JSON
  -h, --help               Print help
  -V, --version            Print version

License

MIT