Apex as Terminal Markdown Renderer

This is the first of two Apex posts today. In my opinion, the two things I’ve been working on deserve their own headlins. So here’s part one: terminal rendering.

If you’ve ever wanted to read Markdown in the terminal with syntax highlighting and nice formatting, you’ve probably reached for mdless or glow. They’re great tools. But what if you want all of that plus Apex’s extensions, filters, and plugins—tables with captions, footnotes, callouts, file includes, and whatever your custom filters do?

That’s where Apex’s new built-in terminal output comes in.

Triggering Terminal Output

Apex can now render Markdown directly to your terminal instead of HTML. You use the --output flag with a special target:

apex README.md --output cli

or using the short form:

apex README.md -o terminal

Both produce colored, formatted output suitable for reading in an interactive terminal. No piping to mdless required—Apex handles it natively.

For terminals that support 256 colors, use:

apex README.md --output terminal256

This gives you a richer color palette for headings, code blocks, links, and other elements. If your terminal supports it, the difference is noticeable.

What You Get

Because this is Apex doing the rendering, you get the full pipeline:

• Extensions: Tables, footnotes, definition lists, task lists, callouts, wiki links, and all the rest
• Filters: Any filters in your config run before render, so your title filter, delink filter, or custom Lua scripts all apply
• Plugins: Pre-parse and post-render plugins run as usual — kbd for <kbd> tags, md-fixup, or whatever you’ve installed

So when you apex doc.md -o terminal, you’re seeing the same processed document you’d get as HTML, just rendered for the terminal instead.

It’s not perfect for handling all elements yet, but the foundation is there and I’ll tweak it as needed.

Theming: mdless Compatibility

Apex’s terminal theming is compatible with mdless theme files. If you already use mdless, you can point Apex at your existing theme:

apex doc.md -o terminal256 --theme ~/.config/mdless/mdless.theme

Or set a default in your Apex config. The theme format matches mdless, so your ~/.config/mdless/mdless.theme (or any *.theme file) works out of the box.

Apex adds a few extra keys for elements mdless doesn’t have—callouts, definition lists, table captions, and the like. If you don’t define them, sensible defaults are used. You can override them in your theme file when you want finer control.

JSON Output: Build Your Own Renderer

Apex can also output a Pandoc-compatible JSON representation of the document:

apex doc.md --output json

This emits the full AST, including blocks, inlines, metadata, to stdout. From there you can pipe it into your own script to generate whatever you want: custom terminal formatting, a different HTML structure, plain text, or something else entirely.

The JSON format is the same one filters use. So if you’ve written a filter, you already know the structure. A simple Python script can read it, walk the tree, and emit your own output format. No need to reimplement the parser.

Quick Reference

So next time you’re browsing docs in the terminal, skip the Apex &rarr mdless/glow pipeline and let Apex do it all in one shot.