Terminal markdown pager with syntax highlighting
A terminal markdown pager with syntax highlighting, search, and vim-style navigation.
This project is an experiment in building a complete tool using AI coding agents with minimal manual code intervention.
pmd or pmd <dir> to browse and open markdown filesT/ and jump between matches with n/N$EDITOR at the current line with e, with a notice when the file changes on diskpmd works in scriptsbrew tap aliou/toolbox
brew install aliou/toolbox/pmd
Download the binary for your platform from the releases page:
pmd-darwin-arm64 - macOS Apple Siliconpmd-linux-arm64 - Linux ARM64Then install it somewhere in your $PATH:
# Example for macOS
curl -L https://github.com/aliou/preview-markdown/releases/latest/download/pmd-darwin-arm64 -o pmd
chmod +x pmd
sudo mv pmd /usr/local/bin/
Add to your flake inputs:
{
inputs.pmd.url = "github:aliou/preview-markdown";
}
Then either run directly:
nix run github:aliou/preview-markdown -- README.md
Or add to your system/home-manager packages:
# In your configuration
{ inputs, ... }:
{
environment.systemPackages = [ inputs.pmd.packages.${system}.default ];
}
A home-manager module is also available:
{ inputs, ... }:
{
imports = [ inputs.pmd.homeManagerModules.default ];
programs.pmd.enable = true;
}
pmd # Browse markdown files in the current directory
pmd docs/ --depth 3 # Browse up to three levels deep
pmd README.md # Open a file in the pager
cat CHANGELOG.md | pmd # Read from stdin (or: pmd -)
pmd README.md | less # Print plain text when stdout is not a terminal
pmd --help lists the flags and commands, and pmd help <command> shows the details of one command. Press ? inside pmd, or run pmd help keys, for the keyboard shortcuts.
pmd exits with 0 on success, 1 when something fails (for example a missing file), and 2 for a usage error such as an unknown flag.
Load completion in the current shell:
source <(pmd completion zsh) # zsh
source <(pmd completion bash) # bash
pmd completion fish | source # fish
Install it permanently:
pmd completion zsh > "${fpath[1]}/_pmd"
pmd completion bash > ~/.local/share/bash-completion/completions/pmd
pmd completion fish > ~/.config/fish/completions/pmd.fish
pmd config init writes the default config to ~/.config/pmd/config.json (or $XDG_CONFIG_HOME/pmd/config.json). A .pmd.json in the current directory takes precedence over it; pmd config path prints the file pmd reads. The config is validated against schema.json, and .pmd.json in this repository is an example.
theme names a bundled theme (senzu-dark, senzu-light) or a TextMate theme file in ~/.config/pmd/themes/<name>.json, either for both modes or as a { "dark": ..., "light": ... } pair.
When viewing a file in a Git worktree, pmd shows a Git status gutter. It compares the working tree with HEAD; green marks additions, yellow modifications, red deletion boundaries, and blue moved lines.
MIT