Command line

mido [OPTIONS] [PATH]
mido new <FILE>
mido completions <SHELL>

PATH is a Markdown file, a folder, - for stdin, docs for the bundled documentation, or themes to list the themes. With no path, mido opens the current folder. A Markdown file that does not exist yet opens in the editor and is created on the first save, and mido new <FILE> does the same for any name.

Options

Examples

mido README.md          # open one file
mido docs/              # browse a folder: files on the left, outline on the right
mido                    # the current folder
mido -                  # read Markdown from stdin
mido -p README.md       # print styled text to stdout, pipe it to less -R
mido -w 80 notes.md     # cap the width at 80 columns
mido -t nord notes.md   # read in the Nord theme
mido themes             # list the themes with a swatch of each
mido docs               # read this documentation offline
mido new notes.md       # start a new file in the editor
mido completions zsh    # print zsh completions

Shell completions

mido completions <SHELL> prints a completion script for bash, zsh, fish, elvish or powershell to stdout. Save it where your shell looks for completions:

mido completions bash > ~/.local/share/bash-completion/completions/mido
mido completions zsh > ~/.zfunc/_mido        # with fpath+=~/.zfunc before compinit
mido completions fish > ~/.config/fish/completions/mido.fish

For PowerShell, add mido completions powershell | Out-String | Invoke-Expression to your profile. As with docs and themes, a file or folder called completions in the current directory wins over the command.

Width

By default the text runs the full width of the terminal, with small gutters on each side. --width caps the measure and centers the column, for anyone who prefers a fixed reading width on a wide screen.

Themes and config

--theme picks one of the built-in themes, a theme from the user themes folder, or a theme file by path, for this run only. mido themes lists them all with their kind and a swatch of their colors, and marks the one the config selects. As with docs, a file or folder called themes in the current directory wins over the listing.

Settings that last live in the config file, and a .mido.toml in a project folder overrides it there. --config reads a different file, which is handy for trying a setup out. Flags always win over both files.

Images

Local images render without any flag. Remote ones, http and https URLs, are skipped unless --remote-images is given, because opening a document should never make a network request by surprise. Downloads are capped at 10 MB and cached, so a page opens quickly the second time. See What renders for the terminals that draw pictures. The same flag lets badges fetch their live values.

Print mode

-p renders the document once and writes it to stdout with ANSI styling, so it can go through a pager or into another tool:

mido -p README.md | less -R

Links in print mode are OSC 8 hyperlinks, so terminals that support them make the text clickable: web links open in the browser and relative links to files that exist open as file:// URLs. Anchors, wikilinks and footnotes stay plain text, and the plain output below has no hyperlinks.

Piping or redirecting without -p writes plain text with no escape codes, so this never leaks colors into a file:

mido README.md > out.txt

Bundled documentation

mido docs opens this documentation in project mode with no network, unpacked from the binary into a temporary folder. A file or folder called docs in the current directory always wins, so inside a project with its own docs folder mido docs opens that folder, exactly like mido docs/.

Man page

The man page is generated at build time from the command definition. mido --man writes it as roff, so it can be read directly or installed:

mido --man | man -l -
mido --man > ~/.local/share/man/man1/mido.1

Exit

q quits the viewer. If an overlay is open, Esc closes it first.