# ink

> A terminal markdown reader that actually looks good.

ink is a command-line tool that renders markdown files in the terminal with rich formatting. Built in Rust as a single binary with no runtime dependencies.

## What it does

- Renders markdown with syntax highlighting, tables (with column alignment), blockquotes, lists, task lists, footnotes, definition lists, HTML superscript (<sup>) and subscript (<sub>), and horizontal rules
- Displays inline images using terminal graphics protocols (Kitty, iTerm2, Sixel) where supported, falling back to Unicode half-block characters (any true-color terminal); --image-protocol selects the renderer
- Renders mermaid diagrams as text art: flowcharts (laid out with boxes and routed edges, all directions), state, class and ER diagrams, sequence diagrams, pie charts, Gantt charts and mindmaps
- Supports GitHub-style admonitions (NOTE, TIP, IMPORTANT, WARNING, CAUTION) with custom titles, and Obsidian callouts
- YAML and TOML frontmatter: hidden by default, shown as a key/value box with --frontmatter (JSON frontmatter is never hidden; with --frontmatter it gets the box when markdown follows it)
- Supports wikilink syntax: [[page]] and [[page|display text]]
- Renders inline/block math ($...$, $$...$$, ```math) as Unicode text (Greek, operators, super/subscripts, fractions, roots, matrices, cases) and resolves :emoji: shortcodes
- Interactive TUI with multi-tab support, in-document search (n/N to cycle matches), keyboard link opening (press f), a help overlay (?), and a table of contents sidebar
- Text selection and clipboard copy: v/V for character- and line-wise visual selection (y copies), mouse drag with double-click word and triple-click line, c to copy a code block's raw source, Y to copy the current section's markdown; delivered over OSC 52 (works across SSH/tmux) and a native helper (pbcopy/wl-copy/xclip/xsel/clip.exe)
- File browser mode for exploring directories of markdown files
- 9 built-in color themes (including terminal, which follows your terminal's palette) with auto dark/light detection, live theme picker that saves to config, plus custom TOML themes
- Presentation mode (split on --- separators), navigate with arrows/space
- Watch mode for live-reloading on file changes
- Pager mode: `ink --plain` on a TTY pages long output through $PAGER (like bat); --line-range START:END renders only those source lines
- Honors NO_COLOR and downgrades to 256-color on non-truecolor terminals
- Document statistics, outline view, and a real (Myers) markdown diff
- Vim-style keybindings (j/k/G/Ctrl+f/Ctrl+b), also emacs preset, fully customizable
- Reads from files, URLs, or stdin
- Plain output mode for piping (ANSI-colored, no TUI)
- Shell completions (bash/zsh/fish/PowerShell/elvish) and a man page

## Security

- Sanitizes terminal control/escape bytes out of untrusted markdown before rendering (both TUI and --plain), preventing ANSI/OSC escape-sequence and hyperlink injection
- Remote (http/https) images are not fetched by default; --remote-images opts in, and private/loopback/cloud-metadata addresses stay blocked
- URL fetches are timeout- and size-capped; relative file/link paths are contained to the document's directory
- install.sh / install.ps1 verify a published SHA256SUMS manifest before installing; release assets carry signed build provenance (gh attestation verify)

## Install

curl -fsSL https://raw.githubusercontent.com/borghei/ink/main/install.sh | sh    # macOS / Linux (picks glibc or static musl build)
irm https://raw.githubusercontent.com/borghei/ink/main/install.ps1 | iex         # Windows PowerShell (x64 / ARM64)
cargo install ink-md                                                             # from source (Rust 1.90+)
INK_VERSION=v0.11.1 sh install.sh                                                # pin a version

Prebuilt: Linux amd64/arm64 (glibc 2.35+), static musl Linux amd64/arm64/armv7 (any distro), macOS amd64/arm64, Windows amd64/arm64; .deb/.rpm and tar.gz/zip archives include the man page and completions. Verify with SHA256SUMS or `gh attestation verify <file> --repo borghei/ink`.

## Usage

ink README.md            # read a file
ink .                    # browse markdown files in current directory
ink --plain file.md      # pipe-friendly output (pages via $PAGER on a TTY; no escapes in a pipe unless --color=always)
ink --slides deck.md     # presentation mode
ink --watch draft.md     # auto-reload on changes
ink --remote-images x.md # allow remote images (off by default)
ink --list-themes        # list available themes
ink outline file.md      # show heading structure
ink stats file.md        # word count, reading time
ink diff a.md b.md       # compare two files (Myers diff)
ink completions zsh      # shell completions
ink man                  # man page

## Docs

- Install: https://github.com/borghei/ink/blob/main/docs/install.md
- Features: https://github.com/borghei/ink/blob/main/docs/features.md
- Themes and color: https://github.com/borghei/ink/blob/main/docs/themes.md
- Configuration and keybindings: https://github.com/borghei/ink/blob/main/docs/configuration.md
- Command line: https://github.com/borghei/ink/blob/main/docs/cli.md
- Troubleshooting: https://github.com/borghei/ink/blob/main/docs/troubleshooting.md
- Full feature dump for LLMs: https://borghei.github.io/ink/llms-full.txt

## Links

- Source: https://github.com/borghei/ink
- Website: https://borghei.github.io/ink/
- Author: Amin Borghei (https://github.com/borghei)
- License: Free to use, cannot be sold (see LICENSE)