feat(cli): render --help output as markdown using glamour#326
feat(cli): render --help output as markdown using glamour#326NJX-njx wants to merge 1 commit intoinstill-ai:mainfrom
Conversation
Fixes instill-ai/instill-core#631 Use charmbracelet/glamour to render help messages with formatted markdown when output is a TTY. Improves readability and provides a nicer UI for help output. Falls back to plain text when piping or on render error. Made-with: Cursor
There was a problem hiding this comment.
Pull request overview
Adds markdown-based rendering for the root command --help output, using the existing pkg/markdown (glamour) utilities to improve readability in interactive terminals while keeping a plain-text fallback.
Changes:
- Introduces
buildHelpMarkdownto construct help content as markdown from structured help entries. - When stdout is a TTY, renders the markdown via glamour with terminal theme detection and wrapping.
- Falls back to the existing plain-text help output when not a TTY or when markdown rendering fails (and uses the pager on successful TTY rendering).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| // Build markdown for rendering | ||
| md := buildHelpMarkdown(entries) | ||
|
|
There was a problem hiding this comment.
entries is declared as []helpEntry from a function-local helpEntry type (declared earlier in rootHelpFunc), but buildHelpMarkdown expects the package-level helpEntry type. Because these are distinct types in Go, this call won’t compile. Remove the function-local type helpEntry (or rename it) so entries uses the package-level type.
| codeBlockSections := map[string]bool{ | ||
| "USAGE": true, "FLAGS": true, "INHERITED FLAGS": true, | ||
| "EXAMPLES": true, "ARGUMENTS": true, | ||
| "ENVIRONMENT VARIABLES": true, "LEARN MORE": true, "FEEDBACK": true, |
There was a problem hiding this comment.
The command list sections (e.g., CORE/ACTIONS/ADDITIONAL COMMANDS) build strings with padded spaces for alignment, but those sections are not treated as code blocks here. In markdown, consecutive spaces are collapsed outside code blocks, so the alignment (and possibly line formatting) will be lost in the glamour-rendered help. Consider adding those section titles to codeBlockSections or emitting them as a proper markdown list/table.
| "ENVIRONMENT VARIABLES": true, "LEARN MORE": true, "FEEDBACK": true, | |
| "ENVIRONMENT VARIABLES": true, "LEARN MORE": true, "FEEDBACK": true, | |
| // Sections that list commands with padded spaces for alignment | |
| "CORE": true, "ACTIONS": true, "ADDITIONAL COMMANDS": true, |
| if err == nil { | ||
| _ = io.StartPager() | ||
| defer io.StopPager() | ||
| fmt.Fprint(io.Out, rendered) |
There was a problem hiding this comment.
This starts the pager whenever stdout is a TTY and markdown rendering succeeds (subject to pager config), regardless of output length. The PR description says to use a pager for long help output; if that’s still the intent, add a length/height check before starting the pager (e.g., compare rendered line count to terminal height) and print directly when it’s short.
| // Build markdown for rendering | ||
| md := buildHelpMarkdown(entries) | ||
|
|
||
| // Render with glamour when output is TTY for better readability | ||
| if io.IsStdoutTTY() { | ||
| wrapWidth := io.TerminalWidth() | ||
| style := markdown.GetStyle(io.DetectTerminalTheme()) | ||
| rendered, err := markdown.RenderWithWrap(md, style, wrapWidth) | ||
| if err == nil { | ||
| _ = io.StartPager() | ||
| defer io.StopPager() | ||
| fmt.Fprint(io.Out, rendered) | ||
| return |
There was a problem hiding this comment.
New behavior is introduced here (markdown construction + TTY-only glamour rendering + plain-text fallback), but there are no tests covering the generated markdown or the TTY/non-TTY branching. Adding unit tests for buildHelpMarkdown and an integration-style test that asserts which renderer is used based on IOStreams.IsStdoutTTY() would help prevent regressions in help output formatting.
Summary
Use charmbracelet/glamour to render help messages with formatted markdown when output is a TTY, improving readability and providing a nicer UI.
Problem
Help output is plain text and could benefit from better formatting (as noted in instill-ai/instill-core#631).
Solution
Fixes instill-ai/instill-core#631
Made with Cursor