Documentation
¶
Overview ¶
Package display provides Aether’s rich output-rendering subsystem.
This package is responsible for converting normalized Aether documents into human-readable, theme-aware representations such as:
- Markdown (primary output format)
- ANSI-colored terminal views
- Width-aware text tables
- Short previews for CLI / TUI interfaces
The Display subsystem supports four major features:
ANSI-aware color rendering • Safe fallback when color is not supported • Works in terminals, logs, and non-TTY environments
Theme profiles (Theme) • DefaultTheme • DarkTheme • MinimalTheme • PaperTheme (no ANSI, printer-style)
Adaptive width rendering • Detects terminal width at runtime • Falls back to 80–100 characters when unknown • Provides wrapping, truncation, and preview helpers
Markdown transformation • Heading styles • Code blocks • Lists, links, inline emphasis • Table rendering
Architecture:
theme.go → theme definitions + runtime feature detection color.go → ANSI color & style helpers (with fallbacks) width.go → terminal width detection + text wrapping markdown.go → generic Markdown formatting model_render.go → render model.Document into Markdown table.go → flexible Unicode/ASCII table renderer preview.go → short previews (title + excerpt)
The package is intentionally decoupled from:
- async fetcher
- plugins
- normalization
allowing it to be used not only for Aether.Search(), but also for rendering OpenAPI results, feed items, or user-generated documents.
Export policy:
Internal-only. Public rendering APIs live in aether/display.go in later stages.
Stage 18 establishes the foundation for fully themeable, terminal-aware output rendering for both human users and LLM pipelines.
Index ¶
- Constants
- func DetectTerminalWidth() (int, bool)
- func EffectiveWidth(t Theme) int
- func RenderBulletList(t Theme, items []string) string
- func RenderCodeBlock(code string) string
- func RenderHeading(t Theme, level int, text string) string
- func RenderInlineCode(t Theme, s string) string
- func RenderInlineEm(t Theme, s string) string
- func RenderInlineStrong(t Theme, s string) string
- func RenderParagraph(t Theme, text string) string
- func RenderTable(t Theme, tbl Table) string
- type ColorMode
- type EmphasisStyle
- type HeadingStyle
- type Preview
- type PreviewRenderer
- type Renderer
- type Table
- type TableStyle
- type Theme
Constants ¶
const DefaultWidth = 80
DefaultWidth is used when terminal size cannot be detected.
Variables ¶
This section is empty.
Functions ¶
func DetectTerminalWidth ¶
DetectTerminalWidth attempts to read terminal width using ioctl. Returns (width, ok).
This is a best-effort detection. If detection fails, ok=false.
func EffectiveWidth ¶
EffectiveWidth decides what width should ultimately be used for rendering under the given Theme.
Priority:
- If theme.MaxWidth > 0 → use that
- If terminal width detected → use min(terminalWidth, theme cap)
- Else → DefaultWidth
func RenderBulletList ¶
RenderBulletList formats a slice of bullet items using the theme’s Bullet marker. Each item is rendered as a wrapped paragraph prefixed by the bullet symbol.
func RenderCodeBlock ¶
RenderCodeBlock wraps code in a Markdown fenced block.
Example:
``` line1 line2 ```
func RenderHeading ¶
RenderHeading renders a Markdown heading (level 1–6) using the theme. It applies:
- optional ANSI styling (color.go)
- configurable heading style (prefix, underline, uppercase)
- safe trimming of whitespace
func RenderInlineCode ¶
RenderInlineCode renders inline code using Markdown backticks and applies subtle ANSI styling when enabled.
func RenderInlineEm ¶
RenderInlineEm applies Markdown emphasis formatting *...* and then uses ANSI styling when enabled by the theme.
func RenderInlineStrong ¶
RenderInlineStrong applies Markdown strong formatting **...** and then uses ANSI styling when enabled by the theme.
func RenderParagraph ¶
RenderParagraph formats a block of prose text. This includes:
- Normalizing whitespace
- Optional wrapping to the effective width (theme + terminal)
- Optional ANSI emphasis (e.g., strong/em) added later in pipeline
The function preserves paragraph structure but removes excessive internal spacing.
func RenderTable ¶
RenderTable renders a Table using theme-aware formatting.
Types ¶
type EmphasisStyle ¶
type HeadingStyle ¶
HeadingStyle describes how a given heading level should be rendered.
type Preview ¶
Preview represents a human-friendly short display representation of a normalized document.
type PreviewRenderer ¶
type PreviewRenderer struct {
Theme Theme
}
PreviewRenderer renders Preview structs using a Theme.
func NewPreviewRenderer ¶
func NewPreviewRenderer(t Theme) PreviewRenderer
NewPreviewRenderer constructs a preview renderer using the given Theme.
func (PreviewRenderer) MakePreview ¶
func (PreviewRenderer) MakePreview(doc *model.Document) Preview
MakePreview extracts a Preview struct from a normalized Document.
Rules:
- Title = doc.Title OR fallback to SourceURL.
- Summary = doc.Excerpt OR first non-empty paragraph from sections or content.
This struct-level function does not perform formatting; renderers do.
func (PreviewRenderer) RenderPreview ¶
func (r PreviewRenderer) RenderPreview(p Preview) string
RenderPreview produces a human-readable, theme-aware single-block preview suitable for CLI or UI list displays.
type Renderer ¶
type Renderer struct {
Theme Theme
}
Renderer renders normalized documents according to a Theme.
func NewRenderer ¶
NewRenderer constructs a Renderer using the provided Theme.
The Theme is sanitized to ensure it has sensible defaults (indent, bullet, code fence, table padding, etc.).
func (Renderer) RenderDocument ¶
RenderDocument renders a normalized Document into a theme-aware, human-readable string. The result is suitable for terminals, logs, and Markdown-capable viewers.
type TableStyle ¶
type TableStyle struct {
Bold bool // apply strong/bold styling
Faint bool // apply faint/metadata styling
Colorize bool // colorize (theme-aware)
}
TableStyle controls optional styling for a table row.
type Theme ¶
type Theme struct {
Name string
Color ColorMode
MaxWidth int
Indent string
Bullet string
CodeFence string
HeadingStyles map[int]HeadingStyle
Emphasis EmphasisStyle
ShowSectionRoles bool
// ─── Table rendering extensions ────────────────────────────────
TablePadding int
TableHeaderStyle TableStyle
TableBodyStyle TableStyle
AsciiOnly bool
}
Theme defines how Aether should render Markdown, tables, and text.
func PaperTheme ¶
func PaperTheme() Theme
PaperTheme — printable output, limited width, clear headers.
func (Theme) EffectiveWidth ¶
EffectiveWidth resolves usable width.
func (Theme) HeadingForLevel ¶
func (t Theme) HeadingForLevel(level int) HeadingStyle
HeadingForLevel resolves heading style for a given level.
Source Files