Rendering Markdown In Terminal

Rendering Markdown in the Terminal

Apex can render Markdown to ANSI-colored output suitable for TTYs, terminal emulators, and terminal-based file manager previews (e.g. lf, yazi). This page describes the output formats, CLI flags, and configuration options.

Output formats: -t / --to

Use -t or --to to choose the output format. For terminal rendering, use one of:

Format	Aliases	Description
terminal	cli	8/16-color ANSI output (standard and bright colors). Best compatibility with basic terminals.
terminal256	—	256-color ANSI output (xterm-256 palette). Richer colors when your terminal supports it.

Examples:

# 16-color terminal output (default theme)
apex doc.md -t terminal

# Same as above (cli is an alias for terminal)
apex doc.md -t cli

# 256-color terminal output
apex doc.md -t terminal256

# Pipe from stdin
cat doc.md | apex -t terminal

Output is written to stdout. Redirect or pipe as needed:

apex doc.md -t terminal | less -R
apex doc.md -t terminal256 -o -

Options

--theme NAME

Load a terminal theme from:

• ~/.config/apex/terminal/themes/NAME.theme (when NAME is given)
• ~/.config/apex/terminal/themes/default.theme (when no theme is specified and a default file exists)

Themes are YAML files that map element types to colors and optional bold. See Theme file format below.

Examples:

apex doc.md -t terminal --theme brett
apex doc.md -t terminal256 --theme dark

--width N

Hard-wrap terminal (and terminal256) output at N visible columns. ANSI escape sequences are not counted toward the width, so colors and formatting are preserved while lines are wrapped. Useful when:

• Viewing in a narrow terminal or file manager preview pane
• Apex cannot detect the pane width (e.g. in lf or yazi preview)

N must be a positive integer. If omitted or set to 0, Apex does not add wrapping; the terminal controls line breaks.

Examples:

apex doc.md -t terminal --width 80
apex doc.md -t terminal256 --width 72

Configuration and metadata

Terminal behavior can be set via document metadata or a config file (e.g. --meta-file), so you don’t have to pass flags every time.

Precedence: CLI flags override metadata/config. For width: CLI --width > metadata/config terminal.width.

Metadata keys

Use a terminal: mapping in YAML front matter (or flattened keys in your metadata):

Key	Example	Description
terminal.theme or terminal_theme	brett	Default theme name for -t terminal / -t terminal256.
terminal.width or terminal_width	80	Default wrap width (positive integer).

Example in document front matter:

---
title: My Doc
terminal:
  theme: brett
  width: 80
---

Example in a shared config file (e.g. config.yml passed with --meta-file):

terminal:
  theme: dark
  width: 72

If you set --theme or --width on the command line, those values override the metadata/config.

Theme file format

Theme files live under ~/.config/apex/terminal/themes/ and use the .theme extension. They are plain YAML.

Location and naming

• Path: ~/.config/apex/terminal/themes/<NAME>.theme
• default.theme is used when no theme name is provided (and no --theme is given).

Element keys

Common top-level keys:

• h1 … h6 – Heading levels (each can have color and optional bold: true).
• link – Link text and optional link.url for the URL style.
• code_span – Inline code.
• code_block – Fenced code blocks.
• blockquote – Blockquote marker and text color (blockquote.character, blockquote.color).
• table – Table border/style (table.border, optional table.bold).
• list_marker – Style for bullet and numbered list markers (e.g. *, 1., 2.). When unset, markers use bold bright red.

For any element that has a color field, you can add bold: true to make that element bold in addition to its color.

Example theme (excerpt)

h1:
  color: "bright_white"
  bold: true

h2:
  color: "bright_blue"
  bold: true

list_marker: "b intense_red"

code_span:
  color: "b white on_intense_black"

code_block:
  color: "white on_black"
  bold: true

Color values can use names like red, bright_blue, intense_red, and 256-color forms like 38;5;nnn. The b prefix (or bold: true in structured keys) enables bold. See existing themes in the repo or in ~/.config/apex/terminal/themes/ for more examples.

Typical use cases

• Interactive reading: apex doc.md -t terminal | less -R
• File manager preview (lf, yazi, etc.): Use -t terminal or -t terminal256 and --width set to your preview pane width (e.g. --width 80), or set terminal.width in metadata/config.
• Consistent look: Create a .theme file and reference it with --theme or terminal.theme in metadata so all your terminal renders use the same colors and emphasis.

See also

• Command Line Options – Full list of CLI flags, including -t/--to, --theme, and --width.
• Configuration – Config file and metadata behavior.