Problem
Documentation cleanup and terminal rendering interpret Markdown separately, making link-formatting changes difficult to apply consistently without changing existing output. The discussion in #107 raises this concern for the link-navigation work.
Significance
Terminal readers, scripts, and AI agents depend on the current output. Removing link syntax can expose a heading or emphasis that the terminal renderer then interprets, so preserving the visible text alone does not preserve behavior.
Cost of inaction
Each formatting feature must reconcile the cleanup rules with the terminal renderer, increasing the risk of changes to code examples and Markdown consumed by other tools.
Desired state
Share Markdown handling while preserving current stdout and stderr in TTY, non-TTY, NO_COLOR, and --pager modes, including their combinations. Preserve ANSI styling, whitespace, wrapping, code fences and language labels, tables, links, images, and Hugo cleanup.
For example, keep fenced js code in piped output; replacing it with indented text or dropping its language label is unacceptable. Current heading and emphasis interpretation must also remain unchanged, and output compatibility takes priority over reducing parsing passes.
Goal: Zero behavior changes after this refactoring.
Problem
Documentation cleanup and terminal rendering interpret Markdown separately, making link-formatting changes difficult to apply consistently without changing existing output. The discussion in #107 raises this concern for the link-navigation work.
Significance
Terminal readers, scripts, and AI agents depend on the current output. Removing link syntax can expose a heading or emphasis that the terminal renderer then interprets, so preserving the visible text alone does not preserve behavior.
Cost of inaction
Each formatting feature must reconcile the cleanup rules with the terminal renderer, increasing the risk of changes to code examples and Markdown consumed by other tools.
Desired state
Share Markdown handling while preserving current stdout and stderr in TTY, non-TTY,
NO_COLOR, and--pagermodes, including their combinations. Preserve ANSI styling, whitespace, wrapping, code fences and language labels, tables, links, images, and Hugo cleanup.For example, keep fenced
jscode in piped output; replacing it with indented text or dropping its language label is unacceptable. Current heading and emphasis interpretation must also remain unchanged, and output compatibility takes priority over reducing parsing passes.Goal: Zero behavior changes after this refactoring.