herald

HTML-inspired typography for terminal UIs in Go.

Herald maps familiar HTML elements (H1–H6, P, Blockquote, UL, OL, Code, HR, and inline styles) to styled terminal output, built on lipgloss v2. It ships with a Rose Pine-inspired default theme and supports full style customization via functional options.

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())

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.

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"))

Definition lists

DL accepts a slice of [2]string pairs (term, description). DT and DD are available for individual rendering.

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

// Or individually:
fmt.Println(ty.DT("Term"))
fmt.Println(ty.DD("The description for that term."))

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:

Custom theme

Replace the entire theme by constructing a Theme struct and passing it with WithTheme.

import (
    "github.com/indaco/herald"
    "charm.land/lipgloss/v2"
)

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))

DefaultTheme() is exported and can serve as a starting point: call it, modify the fields you need, then pass the result to WithTheme.

Examples

Runnable examples are in the examples/ directory:

The catppuccin-theme example has its own go.mod to keep github.com/catppuccin/go out of herald's core dependencies.

License

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