name: charm-glamour description: "Render markdown to styled ANSI terminal output in Go with glamour v2. Use when rendering markdown programmatically in Go, glamour, terminal markdown rendering, or styled markdown output. NOT for viewing markdown files in terminal (use glow)."

glamour - Terminal Markdown Rendering

charm.land/glamour/v2 renders markdown to styled ANSI output. Built on goldmark, supports GFM (tables, task lists, strikethrough), syntax highlighting via Chroma, emoji, and fully customizable stylesheets.

Quick Start

go get charm.land/glamour/v2@latest

One-liner

import "charm.land/glamour/v2"

out, err := glamour.Render("# Hello\n\nSome **bold** text.", "dark")
fmt.Print(out)

With renderer (reusable)

r, err := glamour.NewTermRenderer(
    glamour.WithStandardStyle("dark"),
    glamour.WithWordWrap(80),
)
if err != nil {
    log.Fatal(err)
}

out, err := r.Render(markdown)
fmt.Print(out)

Core API

Package-level functions

Function	Description
`Render(in, stylePath string) (string, error)`	One-shot render with a style name or file path
`RenderBytes(in []byte, stylePath string) ([]byte, error)`	Same but bytes in/out
`RenderWithEnvironmentConfig(in string) (string, error)`	Uses `GLAMOUR_STYLE` env var, defaults to `"dark"`

TermRenderer

Created via NewTermRenderer(options ...TermRendererOption). Reusable for multiple renders.

Methods:

Method	Description
`Render(in string) (string, error)`	Render markdown string
`RenderBytes(in []byte) ([]byte, error)`	Render markdown bytes
`Write(b []byte) (int, error)`	Implements `io.Writer`, buffer markdown input
`Close() error`	Flush buffered input, call before `Read`
`Read(b []byte) (int, error)`	Implements `io.Reader`, read rendered output

io.ReadWriter pattern (streaming):

r, _ := glamour.NewTermRenderer(glamour.WithWordWrap(80))
r.Write([]byte("# Streamed\n\nContent here."))
r.Close()

rendered, _ := io.ReadAll(r)
fmt.Print(string(rendered))

Options

Option	Description
`WithStandardStyle(name string)`	Use a built-in style by name
`WithStylePath(path string)`	Style name OR path to JSON file
`WithStyles(cfg ansi.StyleConfig)`	Programmatic style struct
`WithStylesFromJSONBytes(b []byte)`	Parse style from JSON bytes
`WithStylesFromJSONFile(path string)`	Load style from JSON file
`WithEnvironmentConfig()`	Use `GLAMOUR_STYLE` env var
`WithWordWrap(width int)`	Word wrap width (default: 80)
`WithTableWrap(wrap bool)`	Wrap table content (default: true). False truncates with ellipsis
`WithInlineTableLinks(inline bool)`	Render links inline in tables instead of footer list
`WithPreservedNewLines()`	Keep newlines instead of reflowing
`WithEmoji()`	Enable `:emoji_code:` rendering
`WithBaseURL(url string)`	Resolve relative URLs against this base
`WithChromaFormatter(fmt string)`	Set Chroma formatter for code blocks
`WithOptions(opts ...TermRendererOption)`	Combine multiple options

Built-in styles

Constant	String	Use case
`styles.DarkStyle`	`"dark"`	Dark terminal backgrounds (default)
`styles.LightStyle`	`"light"`	Light terminal backgrounds
`styles.DraculaStyle`	`"dracula"`	Dracula color scheme
`styles.TokyoNightStyle`	`"tokyo-night"`	Tokyo Night color scheme
`styles.PinkStyle`	`"pink"`	Pink accent theme
`styles.AsciiStyle`	`"ascii"`	ASCII-only, no unicode box chars
`styles.NoTTYStyle`	`"notty"`	No ANSI codes at all, plain text

Each has a corresponding StyleConfig variable: styles.DarkStyleConfig, styles.LightStyleConfig, etc.

Common Patterns

Custom style (programmatic)

Start from a built-in config and modify fields. Style fields use pointers for optional values.

import (
    "charm.land/glamour/v2"
    "charm.land/glamour/v2/ansi"
    "charm.land/glamour/v2/styles"
)

func boolPtr(b bool) *bool    { return &b }
func strPtr(s string) *string { return &s }
func uintPtr(u uint) *uint    { return &u }

func customRenderer() (*glamour.TermRenderer, error) {
    style := styles.DarkStyleConfig

    // Custom H1: green text, no background
    style.H1 = ansi.StyleBlock{
        StylePrimitive: ansi.StylePrimitive{
            Color:  strPtr("34"),
            Bold:   boolPtr(true),
            Prefix: "# ",
        },
    }

    // Wider margins
    style.Document.Margin = uintPtr(4)

    // Custom code block theme
    style.CodeBlock.Theme = "monokai"

    return glamour.NewTermRenderer(
        glamour.WithStyles(style),
        glamour.WithWordWrap(100),
    )
}

Custom style (JSON file)

{
    "document": {
        "color": "252",
        "margin": 2,
        "block_prefix": "\n",
        "block_suffix": "\n"
    },
    "heading": {
        "color": "39",
        "bold": true,
        "block_suffix": "\n"
    },
    "h1": {
        "color": "228",
        "background_color": "63",
        "bold": true,
        "prefix": " ",
        "suffix": " "
    },
    "h2": {
        "prefix": "## "
    },
    "code_block": {
        "theme": "dracula",
        "margin": 2
    },
    "link": {
        "color": "123",
        "underline": true
    },
    "strong": {
        "bold": true
    },
    "emph": {
        "italic": true
    }
}

r, err := glamour.NewTermRenderer(
    glamour.WithStylesFromJSONFile("./my-style.json"),
    glamour.WithWordWrap(80),
)

StyleConfig structure reference

StyleConfig
  Document, BlockQuote, Paragraph     -> StyleBlock
  List                                -> StyleList (StyleBlock + LevelIndent)
  Heading, H1-H6                     -> StyleBlock
  Text, Emph, Strong, Strikethrough  -> StylePrimitive
  HorizontalRule                     -> StylePrimitive (use Format for custom rule)
  Item, Enumeration                  -> StylePrimitive (BlockPrefix for bullet char)
  Task                               -> StyleTask (Ticked/Unticked strings)
  Link, LinkText                     -> StylePrimitive
  Image, ImageText                   -> StylePrimitive
  Code                               -> StyleBlock (inline code)
  CodeBlock                          -> StyleCodeBlock (Theme + Chroma)
  Table                              -> StyleTable (separators)
  DefinitionList/Term/Description    -> StyleBlock/StylePrimitive
  HTMLBlock, HTMLSpan                 -> StyleBlock

StyleBlock
  Indent *uint, IndentToken *string, Margin *uint
  + StylePrimitive (all fields below)

StylePrimitive
  Color, BackgroundColor  *string    // ANSI color number or hex "#RRGGBB"
  Bold, Italic, Underline *bool
  CrossedOut, Faint       *bool
  Inverse, Conceal, Blink *bool
  Upper, Lower, Title     *bool      // text transform
  Prefix, Suffix          string     // per-line prefix/suffix
  BlockPrefix, BlockSuffix string    // before/after entire block
  Format                  string     // Go template, e.g. link format

Color downsampling with lipgloss (v2)

Glamour v2 is "pure" - same input always gives same output. It does NOT auto-detect terminal color capabilities. Use lipgloss to downsample colors for the actual terminal.

import (
    "charm.land/glamour/v2"
    "charm.land/lipgloss/v2"
)

r, _ := glamour.NewTermRenderer(glamour.WithWordWrap(80))
out, _ := r.Render(markdown)

// lipgloss detects terminal capabilities and downsamples
lipgloss.Print(out)

Alternative with colorprofile for explicit control:

import "github.com/charmbracelet/colorprofile"

w := colorprofile.NewWriter(os.Stdout, os.Environ())
fmt.Fprintf(w, "%s", out)

Detect terminal background for style selection

import "charm.land/lipgloss/v2"

style := "dark"
if !lipgloss.HasDarkBackground() {
    style = "light"
}
r, _ := glamour.NewTermRenderer(glamour.WithStandardStyle(style))

Environment-based style

export GLAMOUR_STYLE=dracula
# or a file path:
export GLAMOUR_STYLE=/path/to/custom.json

// Picks up GLAMOUR_STYLE, falls back to "dark"
out, err := glamour.RenderWithEnvironmentConfig(markdown)

// Or with a renderer:
r, err := glamour.NewTermRenderer(glamour.WithEnvironmentConfig())

Integration

Bubbletea viewport (scrollable markdown)

import (
    "charm.land/glamour/v2"
    tea "charm.land/bubbletea/v2"
    "charm.land/bubbles/v2/viewport"
)

type model struct {
    viewport viewport.Model
    content  string
}

func initialModel(markdown string) model {
    r, _ := glamour.NewTermRenderer(
        glamour.WithStandardStyle("dark"),
        glamour.WithWordWrap(78), // viewport width minus padding
    )
    rendered, _ := r.Render(markdown)

    vp := viewport.New(viewport.WithWidth(80), viewport.WithHeight(24))
    vp.SetContent(rendered)

    return model{viewport: vp, content: rendered}
}

func (m model) Init() tea.Cmd {
    return nil
}

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    var cmd tea.Cmd
    m.viewport, cmd = m.viewport.Update(msg)
    return m, cmd
}

func (m model) View() string {
    return m.viewport.View()
}

Key point: set WithWordWrap to viewport width minus any horizontal padding/margin. Re-render when terminal resizes.

Re-render on resize

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.WindowSizeMsg:
        m.viewport.SetWidth(msg.Width)
        m.viewport.SetHeight(msg.Height)

        r, _ := glamour.NewTermRenderer(
            glamour.WithStandardStyle("dark"),
            glamour.WithWordWrap(msg.Width - 2),
        )
        rendered, _ := r.Render(m.rawMarkdown)
        m.viewport.SetContent(rendered)
    }

    var cmd tea.Cmd
    m.viewport, cmd = m.viewport.Update(msg)
    return m, cmd
}

Lipgloss styled container around rendered markdown

import "charm.land/lipgloss/v2"

border := lipgloss.NewStyle().
    Border(lipgloss.RoundedBorder()).
    Padding(1, 2)

r, _ := glamour.NewTermRenderer(
    glamour.WithStandardStyle("dark"),
    glamour.WithWordWrap(76), // account for border + padding (2 border + 4 padding = 6)
)
rendered, _ := r.Render(markdown)

fmt.Println(border.Render(rendered))

Common Mistakes

Using WithAutoStyle() or WithColorProfile() - Removed in v2. Use WithStandardStyle("dark") and lipgloss.Print() for color handling.

Not accounting for margin/padding in word wrap - If you wrap a glamour-rendered block in a lipgloss container with padding/border, subtract that width from the word wrap value or text will overflow.

Creating a new renderer per render when unnecessary - TermRenderer is reusable. Create once, call Render() many times.

Using fmt.Print instead of lipgloss.Print - If colors look wrong on some terminals, you need color downsampling. Use lipgloss.Print(out) instead of fmt.Print(out).

Forgetting Close() when using Write/Read pattern - After writing markdown via r.Write(), you must call r.Close() before reading with r.Read() or io.ReadAll(r).

Import path still on v1 - v2 uses charm.land/glamour/v2, not github.com/charmbracelet/glamour.

Setting style fields directly instead of via pointer - Color, Bold, Italic, etc. are pointer types. Use helper functions like func boolPtr(b bool) *bool { return &b }.

Using WithStandardStyle with a file path - WithStandardStyle only accepts built-in style names. For file paths, use WithStylePath or WithStylesFromJSONFile.

Checklist

Import charm.land/glamour/v2 (not the old github path)
Pick a style: built-in name, JSON file, or programmatic StyleConfig
Set WithWordWrap to match your output width minus borders/padding
Use lipgloss.Print() for proper color downsampling on real terminals
For bubbletea: re-render on WindowSizeMsg with updated wrap width
Handle errors from NewTermRenderer and Render (malformed styles, etc.)
For env-based config: use WithEnvironmentConfig() or RenderWithEnvironmentConfig()
Test with "notty" style for CI/non-terminal environments

SKILL.md