mdfried renders markdown headers as genuinely larger text in your terminal

Why headers rendered as images are not the same as bold headers

The README opens with the pitch, and it is worth reading closely because the distinction is the whole project. mdfried is a markdown viewer for the terminal that renders headers as Bigger Text than the rest, if your terminal supports some graphics protocol. Not bold, not just styled, actually BIGGER, making markdown much more readable in a terminal.

The implementation is what makes the claim concrete. The feature list says headers are actually rendered as images, or with the Text Sizing Protocol, and the project links the kitty text sizing protocol specification directly. So there are two paths: draw the header text as an image and blit it into the terminal grid, or ask the terminal to scale the glyphs.

Neither of those is what a normal markdown renderer does. A typical renderer emits ANSI bold or a bright colour, which is a style change inside a single cell. mdfried instead produces something that occupies more vertical space, which is why the feature is branded Big Headers with a trademark symbol and why the repository topics list the terminals it targets: ghostty, iterm2 and kitty.

The practical consequence is that a document with a clear heading hierarchy becomes navigable by eye in a way that bold text alone does not achieve. That is the reader problem this tool solves, and it is a narrow, visual one.

The project is written in Rust, published on crates.io as mdfried, licensed GPL-3.0-or-later, and built on ratatui for the terminal user interface with ratatui-image for the graphics side.

Image previews with three graphics protocols and a chafa fallback

Image support is the second half of the visual argument, and the mechanism is the interesting part.

The README states that Sixel, Kitty and iTerm2 are supported in a long list of terminals, and that if no protocol is supported it falls back to chafa. The project points at the ratatui-image compatibility matrix to check whether a terminal has graphics support at all.

The fallback is what makes the tool usable in a plain terminal, and it is not a trivial choice. The README only says the tool falls back to chafa when no protocol is supported, so a terminal without graphics support still gets a rendering rather than an empty box.

That fallback also has a cost at build time, which the installation section is candid about. A cargo install needs a chafa package with development headers, usually called something like libchafa-dev, libchafa-devel, or just libchafa, or even just chafa. If chafa is not available at all, or you do not care about it because your terminal supports some graphics protocol, then you can build with --no-default-features.

One design detail in the feature list deserves attention because it affects how the viewer feels. The images are sliced in rows, so that images scroll in and out of the viewport naturally. That is a small implementation decision with a visible consequence: without row slicing, an image taller than the viewport would have to be scaled down or clipped, and the document would stop behaving like a scrolling text flow.

The Cargo.toml shows how the features map. The default set is chafa-dyn, svg and mermaid, where chafa-dyn pulls in ratatui-image's chafa-dyn feature for distribution, svg pulls in resvg, and mermaid pulls in svg plus the mermaid-rs-renderer crate.

Opening documents, remote URLs and GitHub repositories

mdfried is more than a local file viewer, and the URL handling is the part that changes how you use it.

The feature list covers four cases. It can directly open a URL that serves a markdown document. It can directly open github:<owner>/<repo>, if it contains a README.md on master or main. It can transform any URL before opening with a configurable command, and the README gives the example url_transform_command = "readable | html2text", which first transforms the webpage into something like FireFox's reader mode and then converts it to markdown.

That transform hook is the most flexible piece, because it means the tool is not limited to markdown sources. Any command that can produce markdown on stdout can be piped in, which covers documentation sites, dashboards, issue trackers and anything else with a text-mode API.

Local links are handled too. URLs are opened with xdg-open, or the equivalent on macOS and Windows, local .md links can be followed, and headers can be jumped to in their #kebab-case form. The kebab-case detail is the anchor convention that most markdown generators emit, so a heading link in a README lands on the right heading rather than failing to resolve.

Running it is a single argument:

mdfried ./path/to.md

The one setup step the README describes is font selection. If the font could not be autodetected, you may have to pick a font the first time, and you should pick the same font your terminal is using, although any font can be chosen. The font is rendered directly as a preview, and once confirmed the choice is written into the configuration file. Use --setup to force the font setup again if the font is not right any more.

That font requirement is worth understanding because it is a consequence of rendering headers as images. The image has to match the terminal's own glyph metrics, otherwise the text sits at the wrong baseline and the document looks broken.

Search, pager keys, syntax highlighting and mermaid

The remaining features make it a usable pager rather than a rendering demo.

There is a pager with basic unix-page and Vi-style keybindings, and the README says the keybindings should be the basics of general CLI pagers, with Vi-style keybindings prioritized but normal keys usable as well. The exact list is available by typing :help in the program, or in assets/docs/help.md. That is a sensible choice for a tool that replaces less, because a pager that does not respond to q and space is not a pager.

Search is built in, and links are handled as described above.

Syntax highlighting in code blocks comes from arborium, which is a syntax highlighting library with a broad language list, and the Cargo.toml enables its all-languages feature. Rendering code blocks is where a terminal markdown viewer either keeps up with the original or becomes unusable, so the choice of a highlighter with wide coverage matters more here than the theme does.

Mermaid diagram rendering is supported, and it has two paths. An internal renderer, described as fast, or an external mermaid-cli command, described as accurate. The Cargo.toml shows the internal path is the optional mermaid-rs-renderer crate at version 0.2.2, and the mermaid feature depends on the svg feature, so a diagram ends up as SVG and then goes through the same resvg path as other vector content.

There is also experimental PDF support. If enabled with the pdf feature, PDF files can be opened, and the README recommends it only for terminals that use the kitty protocol. The Cargo.toml confirms the shape: the pdf feature pulls in the optional mupdf crate at version 0.8.

Theme configuration is supported, and the configuration file at ~/.config/mdfried/config.toml is automatically created on first run. mdfried --print-config prints a full example config with a full theme, and typing :help configuration in the program gives a detailed explanation.

Installing from cargo, Nix or a release binary

Installation is offered three ways and the README is specific about each.

From cargo:

cargo install mdfried

With a from-source variant for working in the checkout, cargo install --path ., and the README notes that if cargo install fails, try it with --locked and report an issue. The Cargo.toml declares rust-version 1.86.0 and edition 2024, so a current stable toolchain is needed.

From Nix, the flake reference is github:benjajaja/mdfried, and the repository carries a flake.nix, flake.lock and a nix/ directory.

And from a release, the README points at the releases page for a .deb and binaries for Mac and Windows. There is also a repology packaging status badge, which covers the distribution packages, so on a mainstream Linux distribution the package may already exist and save you the cargo build.

The chafa dependency decision belongs at the front of this section rather than the end, because it changes the build. Building with the default features requires chafa development headers, and building with --no-default-features skips it entirely, which is the right choice if your terminal speaks kitty or iTerm2.

Two other details are worth knowing before you start. The Cargo.toml excludes assets/* from the published crate except !assets/docs and !assets/logo.png, which is why the in-program help and changelog are shipped as files rather than embedded. And the workspace has three members, the main package plus mdfrier, which is the markdown parsing library used at version 3.0.9 with the ratatui feature, and what-terminal-font, which handles the font autodetection at version 0.1.1.

Where mdfried is the wrong choice

There are real limits, and one of them is the central feature.

The Big Headers rendering depends on your terminal supporting a graphics protocol, and while the chafa fallback means the viewer still runs, the fallback is a block-character approximation, not larger text. A reader on a terminal with no graphics support gets a working markdown pager with the headline feature diminished, and a reader whose terminal supports the text sizing protocol but not graphics gets neither image nor scaled text.

The font selection requirement is the second limit. Because headers are rendered as images, the tool has to know the terminal's font metrics, and if autodetection fails you are picking a font by eye. That is a one-time cost, but it is a cost, and the README is honest that the choice is written into the configuration file and can be redone with --setup.

The third limit is the scope. mdfried is a markdown viewer, not a general terminal pager for arbitrary files, and the PDF support is explicitly experimental and recommended only for kitty terminals. The mermaid rendering also has an accuracy caveat, since the internal renderer is fast and the external mermaid-cli command is the accurate path, which means the best output requires a separate tool you install yourself.

For comparison, the alternatives differ in approach. Plain text markdown viewers and general pagers render headers as styled text and never need a font or a graphics protocol, which is exactly the trade-off mdfried rejects. A browser-based renderer gives you perfect typography and images but moves the document off your machine and off the terminal, and it cannot be used over a plain shell session.

mdfried is for the specific case of someone in a graphics-capable terminal who wants the document to look like a document. That is a real preference, and the tooling around it is unusually complete for a viewer of this size.

Editorial conclusion

Adopt mdfried if you read markdown in the terminal and want headers to be visibly larger rather than bold, and if your terminal supports the kitty, iTerm2 or sixel graphics protocol, since that is what makes the Big Headers feature work as intended. Do not adopt it expecting a general purpose pager, because the README positions it around markdown rendering and graphics, and the PDF support is experimental and only recommended for kitty terminals. Before you install, check the repology packaging status for your distribution and decide whether to keep chafa, since it needs development headers and you can build with --no-default-features if you would rather not have it. The licence is GPL-3.0-or-later, the crate is published as mdfried, the latest release is v0.22.8 from 2026-10-13, and the last push was on 2026-10-18.

Frequently asked questions

Official sources

1. benjajaja/mdfried on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases