Apex 0.1.100 - image rendering in terminal

Apex can render Markdown to the terminal (-t terminal or -t terminal256) with ANSI colors and themes. As of 0.1.100, it can also draw images inline when stdout is a real TTY: your ![alt](path-or-url) images show up as actual graphics instead of only link-style text.

What actually draws the image

Apex does not embed a rasterizer. It looks for an external viewer on your PATH, in this order:

1. imgcat (iTerm2-style inline images)
2. chafa
3. viu
4. catimg

The first one that exists wins. If none are found, or something fails, or you are piping output (not a TTY), you get the same link-style fallback as a normal terminal link: styled alt text plus the URL in parentheses.

Remote http:// and https:// images are downloaded with curl (temp file under TMPDIR or /tmp, then deleted). There is a size cap and timeout so runaway downloads do not blow up your session.

Flags and metadata

• --no-terminal-images turns inline rendering off entirely (always link-style).
• --terminal-image-width N sets the maximum width in character cells (default 50). This is separate from --width , which wraps prose.

You can also set terminal.inline_images / terminal_inline_images and terminal.image_width / terminal_image_width in metadata or config.

Installing the viewers (macOS)

iTerm2 ships imgcat on your PATH when you use its utilities, so you may already have the first choice. The others are a quick Homebrew install:

# Optional: pick one or more (Apex uses the first available on PATH) brew install chafa viu catimg

On Linux, use your distro packages or the projects’ install notes; the same binary names apply.

Other stuff

Since 0.1.95 , this line of releases also landed a bunch of other work. Highlights:

• CSV/TSV includes with custom delimiters ({delimiter=X} or {;}) across iA Writer, Marked, and MultiMarkdown include styles.
• Metadata handling improved: mode-aware extraction, better MultiMarkdown / Unified / Kramdown behavior, and standalone HTML now emits generic metadata as proper <meta name="..."> tags.
• MultiMarkdown includes and transclusions accept embedded delimiter overrides without breaking on braces in paths.
• Swift tooling: ApexC exposes the C API for SwiftPM, collision fixes for apex_* symbols, and NSString.defaultApexOptions() for plugins that need low-level options.
• HTML output shape: --to xhtml serializes void elements in XML style (<br />, self-closing meta/link, and so on). --to strict-xhtml goes further for full documents: with --standalone it adds polyglot XHTML scaffolding (XML declaration, XHTML namespace, application/xhtml+xml metadata). Use one or the other; they target different strictness levels.
• Homebrew formula updates for recent releases.

If you want the full blow-by-blow, see the project changelog on GitHub.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.