›_ Codex Issues
Codex Issues / #1246

Improve Markdown rendering

Resolved 💬 3 comments Opened Jun 6, 2025 by bolinfest Closed Aug 7, 2025

Today, the Rust TUI uses https://github.com/joshka/tui-markdown for Markdown rendering while the TypeScript CLI uses https://www.npmjs.com/package/marked-terminal.

I would say that marked-terminal has more detailed styling that results in more attractive output, though it also has its share of issues, which is why we included a patched version of it in Codex CLI:

https://github.com/openai/codex/blob/029f39b9da894d27dcde81b8636ef89d8b652a9f/package.json#L32-L36

(See https://github.com/openai/codex/pull/916, which introduced the patches for details.)

Curiously, tui-markdown has some of the same issues that required patches to marked-terminal.

Nevertheless, things that I have noticed in the tui-markdown output:

  • If an item in a bulleted/numbered list includes styling, the item content starts on the next line (but it should not).
  • Hyperlinks are not formatted correctly (I discovered this when working on https://github.com/openai/codex/pull/957).
  • Output would benefit from style tweaks: I noticed marked-terminal uses yellow for inline code, which stands out quite a bit more than the white used by tui-markdown.
  • More generally, it would be good to support theming, as I expect there will be debates over the "best" Markdown styling, so we should let users play with it.
  • In some cases, I think it would be nice to strip some of the markdown characters around styled content. For example, for a fenced code block that is syntax highlighted, I'm not sure it makes sense to show the triple backticks. I also go back and forth on whether the heading text should be prefixed with #.

Admittedly, this is a lot of stuff to experiment with. Given that the implementation of tui-markdown is mostly a single file (https://github.com/joshka/tui-markdown/blob/main/tui-markdown/src/lib.rs) built on top of a handful of Markdown-related dependencies (ansi-to-tui, pulldown-cmark), I think we might want to have our own fork of tui-markdown in the Codex repo and contribute back upstream as experiments stabilize.

/cc @joshka

View original on GitHub ↗

3 Comments

joshka · 1 year ago

I'm pretty happy to iterate fast on tui-markdown with you (or feel free to fork + backport - the license is compatible).

There's an open PR you raised for theming in https://github.com/joshka/tui-markdown/pull/80. I'm waiting on some clarifications. I'm wondering if you'd throw codex at it to see if it can answer the questions and fix the nits etc (guessing this was at least partially codex generated?).

Hyperlinks are a bit more of a broad Ratatui problem that we haven't yet solved properly yet. I think this needs to be in our next version 0.30 though. The problem boils down to the Ratatui buffer isn't designed to store and write ANSI escape codes, it's designed around store Cells which have the styles (colors / modifiers). See the following for some background:

I'm guessing that the bullet / numbered list styling problem is probably a quick fix (one or two lines and a test).

Regarding the markdown characters (headings / code fences etc.), I like having these on by default as it makes copying the text from the terminal into other markdown apps work well. But I would add configuration to turn them off. This seems like a low complexity change also.

codex-maintainers · 1 year ago

Thank you for the detailed feedback on Markdown rendering! We're primarily focused on the native/Rust implementation of Codex CLI and would love to see if these issues persist on the latest version. If they do, please let us know, and we can explore improvements or contributions to the codex-rs/ implementation.

gueysito · 4 months ago

I’m still seeing a Markdown readability problem in Codex CLI on macOS with codex-cli 0.118.0.

What’s breaking for me is the combination of:

  1. Markdown tables rendering as wrapped plain text instead of a readable table
  2. file/path references becoming visually noisy in the output

In practice, structured answers that are easy to read in Claude become hard to scan in Codex. A simple 3-column table like:

  • File
  • What it says
  • What that means

turns into flattened wrapped text, and the result is not easy on the eyes.

I also tested a Codex-only config experiment:

file_opener = "none"

in ~/.codex/config.toml.

That did not materially improve the problem, so at least in my setup the issue does not seem to be solved by file_opener.

What would help:

  • better Markdown table rendering in the TUI
  • better handling of file/path references inside formatted answers
  • ideally, behavior closer to the cleaner rendering I see in Claude for the same kind of structured response

Environment:

  • macOS
  • codex-cli 0.118.0

I have screenshots showing the current output if that would help.