Glamour

Glamour is a Go library from Charm that renders Markdown documents and templates as beautifully styled output on ANSI-compatible terminals. Instead of hard-coding formatting logic, it separates presentation from parsing: a JSON stylesheet controls how headings, lists, code blocks, tables, links, and emphasis are drawn, and a set of built-in styles (dark, light, dracula, tokyo-night, pink, notty, ascii) cover common terminal themes out of the box.

Under the hood, Glamour wraps the goldmark Markdown parser with a custom ANSI-emitting renderer, so it gets GitHub-flavored Markdown, definition lists, emoji, and auto-generated heading IDs for free while controlling exactly how each node type is drawn to the terminal. Syntax highlighting for fenced code blocks is powered by Chroma, and raw HTML in Markdown source is sanitized with bluemonday before being dropped from output.

Glamour is best known as the rendering engine behind Glow, Charm’s terminal Markdown reader, and it’s also used by the GitHub CLI, GitLab CLI, and Gitea’s tea CLI to render README and issue content directly in the terminal. It ships as a pure, side-effect-free renderer — the same input always produces the same output — so callers who want color downsampling based on actual terminal capabilities are expected to pipe Glamour’s output through Lip Gloss.

What You Get

• A Render/RenderBytes one-shot API plus a configurable TermRenderer for streaming or repeated rendering
• Seven built-in styles (dark, light, dracula, tokyo-night, pink, notty, ascii) selectable by name or via the GLAMOUR_STYLE environment variable
• A full custom-stylesheet system (ansi.StyleConfig) covering headings, lists, tables, code blocks, links, emphasis, and block margins/indentation
• Built-in syntax highlighting for fenced code blocks via Chroma, with a configurable formatter
• GitHub-flavored Markdown support (tables, task lists, strikethrough, definition lists, emoji) via goldmark extensions
• HTML sanitization of embedded raw HTML via bluemonday before rendering
• Word-wrap control and preserve-newlines options for fitting output to a fixed terminal width

Common Use Cases

• Rendering README files or help text inside a terminal Markdown viewer (Glamour is the engine behind Glow)
• Formatting GitHub/GitLab/Gitea issue and PR descriptions inline in a CLI tool (used by gh, glab, and tea)
• Printing changelogs, release notes, or documentation pages with headings and code blocks inside a Bubble Tea TUI
• Building a custom --style flag for a CLI so users can pick or author their own terminal theme

Under The Hood

Architecture Glamour wraps goldmark’s AST-based Markdown parser with a custom node renderer (ansi.ANSIRenderer in ansi/renderer.go) that registers a handler for each goldmark AST node kind (heading, blockquote, code block, list, table, and more) and walks the tree emitting ANSI-styled text through a block-stack/render-context model (ansi/blockstack.go, ansi/context.go) that tracks nested indentation and margins. The public glamour.go facade exposes TermRenderer configured via functional options (TermRendererOption) that populate an ansi.Options struct before the goldmark renderer pipeline is constructed, keeping parsing (goldmark) cleanly separated from terminal emission (the ansi package). Swapping an ansi.StyleConfig changes the entire visual theme without touching either layer.

Tech Stack The module (charm.land/glamour/v2, Go 1.25) builds on the goldmark Markdown parser plus its GFM/definition-list/emoji extensions, Chroma (alecthomas/chroma) for fenced-code syntax highlighting, bluemonday for HTML sanitization, and sibling Charm library Lip Gloss for downstream color downsampling. Styles are authored as Go structs paired with generated JSON files (styles/*.json, produced via a go:generate hook into internal/generate-style-json) rather than a templating engine. There’s no deploy target beyond go build/go test — the project is consumed as a library dependency.

Code Quality Testing relies on Go’s standard testing package with golden-file comparisons (charmbracelet/x/exp/golden) driving glamour_test.go and the ansi package’s renderer/margin tests against fixtures in testdata directories, plus a dedicated benchmark file. Errors are returned as explicit Go error values through the option chain rather than swallowed. Linting is enforced via an extensive .golangci.yml (bodyclose, gosec, nestif, wrapcheck, unparam, and more) with gofumpt/goimports formatting, and CI runs build, coverage via Coveralls, and semgrep/ruleguard checks on every push — a well-instrumented though modestly-sized test surface relative to the codebase.

API Design The functional-options constructor (NewTermRenderer(options...)) and single-call Render(in, style) convenience function make the common case a one-liner while still exposing full stylesheet customization for advanced callers. Its deliberate refusal to do terminal-capability detection or color downsampling itself — delegating that to Lip Gloss — keeps output deterministic and testable via golden files, at the cost of naive callers getting suboptimal colors if they skip that step. Compared to generic Markdown-to-HTML renderers, Glamour’s ANSI-specific stylesheet vocabulary (margins, indents, block/inline prefixes) is purpose-built for terminal rendering constraints rather than a generic templating layer bolted on afterward.