herald

HTML-inspired typography for terminal UIs in Go.

Quick Start | Elements | Customization | Themes | Examples

Herald maps familiar HTML elements (H1–H6, P, Blockquote, UL, OL, Code, HR, Alerts, and inline styles) to styled terminal output, built on lipgloss v2.

It ships with a Rose Pine-inspired default theme, built-in themes matching the Charm ecosystem (Dracula, Catppuccin, Base16, Charm) for seamless pairing with huh and other Charm-based TUIs, and full style customization via functional options and ColorPalette.

Default Rose Pine theme (dark and light). Herald also ships with Dracula, Catppuccin, Base16, and Charm themes.

Installation

go get github.com/indaco/herald

Requires Go 1.25 or later.

Quick start

package main

import (
    "fmt"
    "github.com/indaco/herald"
)

func main() {
    ty := herald.New()

    fmt.Println(ty.H1("Getting Started"))
    fmt.Println(ty.P("Herald renders terminal typography using lipgloss styles."))
    fmt.Println(ty.UL("Headings", "Block elements", "Inline styles"))
}

Available elements

Headings

H1–H3 render with a repeated underline character beneath the text. H4–H6 render with a left bar prefix.

Block elements

fmt.Println(ty.Blockquote("First line.\nSecond line."))
fmt.Println(ty.Code("os.Exit(1)"))
fmt.Println(ty.CodeBlock("func main() {\n\tfmt.Println(\"hello\")\n}"))
fmt.Println(ty.HR())

fmt.Println(ty.DL([][2]string{
    {"Go", "A statically typed, compiled language"},
    {"Rust", "A systems programming language"},
}))

Lists

fmt.Println(ty.UL("Apples", "Bananas", "Cherries"))
fmt.Println(ty.OL("First", "Second", "Third"))

UL uses a bullet character (default •). OL uses 1., 2., 3. markers.

Nested lists

NestUL and NestOL render hierarchical lists with configurable indentation, bullet cycling, and mixed nesting.

Constructors:

// Nested unordered list with mixed sub-lists
fmt.Println(ty.NestUL(
    herald.Item("Fruits"),
    herald.ItemWithChildren("Vegetables",
        herald.Item("Carrots"),
        herald.Item("Peas"),
    ),
    herald.ItemWithOLChildren("Ranked Desserts",
        herald.Item("Ice cream"),
        herald.Item("Cake"),
    ),
))

• Fruits
• Vegetables
  ◦ Carrots
  ◦ Peas
• Ranked Desserts
  1. Ice cream
  2. Cake

// Nested ordered list
fmt.Println(ty.NestOL(
    herald.Item("Introduction"),
    herald.ItemWithOLChildren("Main Topics",
        herald.Item("Architecture"),
        herald.Item("Design"),
    ),
    herald.Item("Conclusion"),
))

1. Introduction
2. Main Topics
  1. Architecture
  2. Design
3. Conclusion

Enable WithHierarchicalNumbers(true) for outline-style numbering (2.1., 2.2.):

ty := herald.New(herald.WithHierarchicalNumbers(true))

fmt.Println(ty.NestOL(
    herald.Item("Introduction"),
    herald.ItemWithOLChildren("Main Topics",
        herald.Item("Architecture"),
        herald.Item("Design"),
    ),
    herald.Item("Conclusion"),
))

1. Introduction
2. Main Topics
  2.1. Architecture
  2.2. Design
3. Conclusion

Inline styles

fmt.Println(ty.Bold("important") + " and " + ty.Italic("nuanced"))
fmt.Println(ty.Kbd("Ctrl") + " + " + ty.Kbd("C"))
fmt.Println(ty.Link("Go website", "https://go.dev"))
fmt.Println(ty.Abbr("CSS", "Cascading Style Sheets"))
fmt.Println(ty.Sub("2") + "O" + ty.Sup("n"))

Alerts

GitHub-style alert callouts with colored bars, icons, and labels. Five types are supported: Note, Tip, Important, Warning, and Caution.

fmt.Println(ty.Note("Useful information that users should know."))
fmt.Println(ty.Tip("Helpful advice for doing things better."))
fmt.Println(ty.Important("Key information users need to know."))
fmt.Println(ty.Warning("Urgent info that needs immediate attention."))
fmt.Println(ty.Caution("Advises about risks or negative outcomes."))

│ ○ Note
│ Useful information that users should know.

│ ⚠ Warning
│ Urgent info that needs immediate attention.

You can also use the generic Alert method with an AlertType:

fmt.Println(ty.Alert(herald.AlertNote, "Generic alert call."))

Customization

Functional options

Pass options to herald.New() to override individual styles or tokens.

ty := herald.New(
    herald.WithHRWidth(60),
    herald.WithBulletChar("-"),
    herald.WithH1Style(
        lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("#FF0000")),
    ),
)

Style options — each accepts a lipgloss.Style:

Token options — each accepts a string or int:

Code formatting

WithCodeFormatter accepts a func(code, language string) string callback. When set, Code() and CodeBlock() pass the raw text and language string to the formatter before applying the lipgloss style. When not set (the default), behavior is unchanged.

import (
    "strings"

    "github.com/alecthomas/chroma/v2/quick"
    "github.com/indaco/herald"
)

func chromaFormatter(style string) func(code, language string) string {
    return func(code, language string) string {
        var buf strings.Builder
        err := quick.Highlight(&buf, code, language, "terminal256", style)
        if err != nil {
            return code
        }
        return strings.TrimRight(buf.String(), "\n")
    }
}

ty := herald.New(
    herald.WithCodeFormatter(chromaFormatter("catppuccin-mocha")),
)

fmt.Println(ty.CodeBlock(`func main() { fmt.Println("hello") }`, "go"))

See examples/07_syntax-highlighting/ for a chroma-based example, or examples/08_tree-sitter-highlighting/ for a tree-sitter-based alternative.

Color palette

ColorPalette lets you define 9 colors and derive a complete theme from them. All style fields map from this palette; configurable tokens use the same defaults as DefaultTheme.

Pass the palette to New() via WithPalette, or call ThemeFromPalette to construct a Theme value directly.

// Dracula-inspired palette
palette := herald.ColorPalette{
    Primary:   lipgloss.Color("#bd93f9"), // purple
    Secondary: lipgloss.Color("#ff79c6"), // pink
    Tertiary:  lipgloss.Color("#8be9fd"), // cyan
    Accent:    lipgloss.Color("#ffb86c"), // orange
    Highlight: lipgloss.Color("#ff5555"), // red
    Muted:     lipgloss.Color("#6272a4"), // comment gray
    Text:      lipgloss.Color("#f8f8f2"), // foreground
    Surface:   lipgloss.Color("#44475a"), // current line
    Base:      lipgloss.Color("#282a36"), // background
}

ty := herald.New(herald.WithPalette(palette))

Alert palette

AlertPalette lets you override the 5 alert colors independently from the main ColorPalette:

ty := herald.New(
    herald.WithAlertPalette(herald.AlertPalette{
        Note:      lipgloss.Color("#0969DA"),
        Tip:       lipgloss.Color("#1A7F37"),
        Important: lipgloss.Color("#8250DF"),
        Warning:   lipgloss.Color("#9A6700"),
        Caution:   lipgloss.Color("#CF222E"),
    }),
)

Individual alert icons and labels can also be customized:

ty := herald.New(
    herald.WithAlertIcon(herald.AlertTip, "💡"),
    herald.WithAlertLabel(herald.AlertNote, "Info"),
)

You can combine WithPalette with other options to override specific fields after the palette is applied:

ty := herald.New(
    herald.WithPalette(palette),
    herald.WithHRWidth(60),
    herald.WithBulletChar("-"),
)

Built-in themes

Herald ships with named themes that match huh's built-in color palettes. Colors auto-adapt to light/dark terminal backgrounds using lipgloss.HasDarkBackground.

ty := herald.New(herald.WithTheme(herald.DraculaTheme()))

Pair with the corresponding huh theme for consistent styling across forms and typography:

form := huh.NewForm(...).WithTheme(huh.ThemeDracula())
ty := herald.New(herald.WithTheme(herald.DraculaTheme()))

Custom theme

The easiest way to customize is to start from an existing theme and modify specific fields:

custom := herald.DefaultTheme()
custom.H1 = lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("#FF0000")).MarginBottom(1)
custom.BulletChar = "-"

ty := herald.New(herald.WithTheme(custom))

For a fully custom theme, construct a Theme struct directly:

custom := herald.Theme{
    H1:        lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("#FFFFFF")),
    H2:        lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("#AAAAAA")),
    Paragraph: lipgloss.NewStyle().MarginBottom(1),
    // set remaining Theme fields as needed...

    H1UnderlineChar: "=",
    H2UnderlineChar: "-",
    H3UnderlineChar: ".",
    HeadingBarChar:  ">",
    BulletChar:      "*",
    HRChar:          "-",
    HRWidth:         40,
    BlockquoteBar:   "|",
}

ty := herald.New(herald.WithTheme(custom))

Examples

Runnable examples are in the examples/ directory:

The 06_catppuccin-theme, 07_syntax-highlighting, and 08_tree-sitter-highlighting examples each have their own go.mod to keep external dependencies out of herald's core module.

License

This project is licensed under the MIT License - see the LICENSE file for details.