herald

package module

v0.4.0 Latest Latest Go to latest Published: Mar 19, 2026 License: MIT Imports: 5 Imported by: 14

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/indaco/herald

Links

Open Source Insights

README ¶

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.

herald demo output

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

Preview

headings demo

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

Method	Decoration	Default character
`H1(text)`	underline	`═`
`H2(text)`	underline	`─`
`H3(text)`	underline	`·`
`H4(text)`	bar prefix	`▎`
`H5(text)`	bar prefix	`▎`
`H6(text)`	bar prefix	`▎`

Block elements

Preview

blocks demo

Method	Description
`P(text)`	Paragraph
`Blockquote(text)`	Indented block with a left bar; supports multi-line input
`CodeBlock(text, lang)`	Fenced code block with padding; optional line numbers and syntax highlighting
`HR()`	Horizontal rule, configurable width and character
`DL(pairs)`	Definition list from `[][2]string` pairs (term, description)
`DT(text)`	Definition term (standalone)
`DD(text)`	Definition description (standalone)

fmt.Println(ty.Blockquote("First line.\nSecond line."))
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

Preview

lists demo

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:

Function	Description
`Item(text)`	Leaf item (no children)
`Items(texts...)`	Batch-convert strings to leaf items
`ItemWithChildren(text, children...)`	Item with unordered sub-list
`ItemWithOLChildren(text, children...)`	Item with ordered sub-list

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

Preview

inline styles demo

Method	Renders as
`Code(text, lang)`	Inline code with background highlight; `lang` is optional, used when a CodeFormatter is set
`Bold(text)`	Bold
`Italic(text)`	Italic
`Underline(text)`	Underlined
`Strikethrough(text)`	Strikethrough
`Small(text)`	Faint
`Mark(text)`	Highlighted background
`Link(label, url)`	Styled link; `url` is optional — when both differ, renders as `label (url)`
`Kbd(text)`	Keyboard key indicator
`Abbr(abbr, desc)`	Abbreviation; `desc` is optional, appended in parentheses
`Sub(text)`	Subscript, prefixed with `_`
`Sup(text)`	Superscript, prefixed with `^`

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

Preview

alerts demo

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

Method	Icon	Color	Description
`Note(text)`	`○`	Blue	Useful information for the reader
`Tip(text)`	`▸`	Green	Helpful advice
`Important(text)`	`‼`	Purple	Key information
`Warning(text)`	`⚠`	Amber	Urgent attention needed
`Caution(text)`	`◇`	Red	Risk or negative outcomes

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:

Option	Targets
`WithH1Style` – `WithH6Style`	Heading levels 1–6
`WithParagraphStyle`	`P`
`WithBlockquoteStyle`	`Blockquote`
`WithCodeInlineStyle`	`Code`
`WithCodeBlockStyle`	`CodeBlock`
`WithCodeLineNumberStyle`	Code block line numbers
`WithHRStyle`	`HR`
`WithBoldStyle`	`Bold`
`WithItalicStyle`	`Italic`
`WithUnderlineStyle`	`Underline`
`WithStrikethroughStyle`	`Strikethrough`
`WithSmallStyle`	`Small`
`WithMarkStyle`	`Mark`
`WithLinkStyle`	`Link`
`WithKbdStyle`	`Kbd`
`WithAbbrStyle`	`Abbr`
`WithListBulletStyle`	Bullet/number marker
`WithListItemStyle`	List item text
`WithDTStyle`	Definition term
`WithDDStyle`	Definition description
`WithAlertStyle(type, style)`	Alert of given type

Token options — each accepts a string or int:

Option	Default	Description
`WithH1UnderlineChar(c)`	`═`	Underline character for H1
`WithH2UnderlineChar(c)`	`─`	Underline character for H2
`WithH3UnderlineChar(c)`	`·`	Underline character for H3
`WithHeadingBarChar(c)`	`▎`	Bar prefix character for H4–H6
`WithBulletChar(c)`	`•`	Bullet character for `UL`
`WithNestedBulletChars(chars)`	`•`, `◦`, `▪`, `▹`	Bullet characters cycling per depth for `NestUL`
`WithListIndent(n)`	`2`	Spaces per nesting level for `NestUL`/`NestOL`
`WithHierarchicalNumbers(b)`	`false`	Outline-style numbering for nested `OL` (e.g. `2.1.`)
`WithHRChar(c)`	`─`	Character repeated for `HR`
`WithHRWidth(w)`	`40`	Width of `HR` in characters
`WithBlockquoteBar(c)`	`│`	Left bar character for `Blockquote`
`WithCodeLineNumbers(b)`	`false`	Show line numbers in `CodeBlock`
`WithCodeLineNumberSep(c)`	`│`	Separator between line numbers and code
`WithAlertBar(c)`	`│`	Left bar character for alerts
`WithAlertIcon(type, icon)`	per-type	Override icon for a specific alert type
`WithAlertLabel(type, label)`	per-type	Override label for a specific alert type

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.

Line numbers in code blocks

Enable line numbers with WithCodeLineNumbers(true). Line numbers are right-aligned, styled with CodeLineNumber (defaults to the Muted palette color), and separated from code by CodeLineNumberSep (default │). Line numbers are added after the CodeFormatter runs, so they work with syntax highlighting.

ty := herald.New(
    herald.WithCodeLineNumbers(true),
)

fmt.Println(ty.CodeBlock("func main() {\n\tfmt.Println(\"hello\")\n}", "go"))

1│ func main() {
2│     fmt.Println("hello")
3│ }

Customize the separator and style:

ty := herald.New(
    herald.WithCodeLineNumbers(true),
    herald.WithCodeLineNumberSep(":"),
    herald.WithCodeLineNumberStyle(lipgloss.NewStyle().Foreground(lipgloss.Color("#888888"))),
)

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.

Field	Maps to
`Primary`	H1 headings
`Secondary`	H2, list bullets
`Tertiary`	H3, links
`Accent`	H4, mark background
`Highlight`	H5, `Abbr`
`Muted`	H6, blockquote, HR, sub/sup, `DD`, line numbers
`Text`	Body text, paragraphs, list items, inline code, `DT`
`Surface`	Background for `Kbd`
`Base`	Background for inline code, code blocks; mark fg

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.

`DraculaTheme()`	`CatppuccinTheme()`
`Base16Theme()`	`CharmTheme()`

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:

Example	Description	Run
00_default-theme	All elements with the default Rose Pine theme	`go run ./examples/00_default-theme/`
01_lists	Flat, nested, mixed, and hierarchical lists	`go run ./examples/01_lists/`
02_alerts	GitHub-style alert callouts (Note, Tip, Important, Warning, Caution)	`go run ./examples/02_alerts/`
03_custom-options	Override styles, decoration chars, and tokens via functional options	`go run ./examples/03_custom-options/`
04_palette	Generate a full theme from 9 colors using `ColorPalette`	`go run ./examples/04_palette/`
05_builtin-themes	Built-in themes (Dracula, Catppuccin, Base16, Charm) matching huh	`go run ./examples/05_builtin-themes/`
06_catppuccin-theme	Build a full theme from the Catppuccin palette (separate module)	`cd examples/06_catppuccin-theme && go run .`
07_syntax-highlighting	Plug in chroma for syntax-highlighted code blocks (separate module)	`cd examples/07_syntax-highlighting && go run .`
08_tree-sitter-highlighting	Plug in tree-sitter for AST-based syntax highlighting (separate module)	`cd examples/08_tree-sitter-highlighting && go run .`

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.

Documentation ¶

Overview ¶

Package herald provides a reusable TUI typography library inspired by CSS frameworks such as Tailwind Typography, Bootstrap, and Pico CSS.

It offers HTML-analogous rendering functions (H1-H6, P, Blockquote, lists, inline styles, etc.) that output styled strings via lipgloss v2.

Quick start:

ty := herald.New()                    // default theme
fmt.Println(ty.H1("Hello, World!"))
fmt.Println(ty.P("Some body text."))
fmt.Println(ty.UL("Apples", "Bananas", "Cherries"))

Customization via functional options:

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

Index ¶

Constants
Variables
func DefaultAlertConfigs(ap AlertPalette) map[AlertType]AlertConfig
type AlertConfig
type AlertPalette
type AlertType
type ColorPalette
type ListItem
type ListKind
type Option
type Theme
type Typography
- func New(opts ...Option) *Typography

Constants ¶

View Source

const (
	DefaultAlertNoteIcon      = "○"
	DefaultAlertTipIcon       = "▸"
	DefaultAlertImportantIcon = "‼"
	DefaultAlertWarningIcon   = "⚠"
	DefaultAlertCautionIcon   = "◇"
)

Default icon constants for each alert type. All are plain Unicode (no emoji) for broad terminal compatibility.

View Source

const (
	DefaultAlertNoteLabel      = "Note"
	DefaultAlertTipLabel       = "Tip"
	DefaultAlertImportantLabel = "Important"
	DefaultAlertWarningLabel   = "Warning"
	DefaultAlertCautionLabel   = "Caution"
)

Default label constants for each alert type.

View Source

const (
	DefaultH1UnderlineChar   = "═"
	DefaultH2UnderlineChar   = "─"
	DefaultH3UnderlineChar   = "·"
	DefaultHeadingBarChar    = "▎"
	DefaultBulletChar        = "•"
	DefaultListIndent        = 2
	DefaultHRChar            = "─"
	DefaultHRWidth           = 40
	DefaultBlockquoteBar     = "│"
	DefaultAlertBar          = "│"
	DefaultCodeLineNumberSep = "│"
)

Default token values used by DefaultTheme and ThemeFromPalette.

Variables ¶

View Source

var DefaultNestedBulletChars = []string{"•", "◦", "▪", "▹"}

DefaultNestedBulletChars is the default set of bullet characters that cycle through nesting levels in nested unordered lists.

Functions ¶

func DefaultAlertConfigs ¶ added in v0.3.0

func DefaultAlertConfigs(ap AlertPalette) map[AlertType]AlertConfig

DefaultAlertConfigs builds a full map[AlertType]AlertConfig from an AlertPalette, using default icons and labels and creating a lipgloss.Style with the palette color as foreground.

Types ¶

type AlertConfig ¶ added in v0.3.0

type AlertConfig struct {
	Icon  string         // Unicode icon for the header line
	Label string         // Text label (e.g. "Note")
	Style lipgloss.Style // Foreground color applied to bar, icon, label, and content
}

AlertConfig holds the display properties for a single alert type.

type AlertPalette ¶ added in v0.3.0

type AlertPalette struct {
	Note      color.Color // blue
	Tip       color.Color // green
	Important color.Color // purple
	Warning   color.Color // yellow/amber
	Caution   color.Color // red
}

AlertPalette defines the five colors used to derive alert styles. It is separate from ColorPalette because the existing 9-color palette does not cleanly map to 5 alert semantics.

type AlertType ¶ added in v0.3.0

type AlertType int

AlertType identifies a GitHub-style alert category.

const (
	// AlertNote renders a blue informational alert.
	AlertNote AlertType = iota
	// AlertTip renders a green helpful-hint alert.
	AlertTip
	// AlertImportant renders a purple important-information alert.
	AlertImportant
	// AlertWarning renders a yellow/amber warning alert.
	AlertWarning
	// AlertCaution renders a red caution/danger alert.
	AlertCaution
)

type ColorPalette ¶ added in v0.2.0

type ColorPalette struct {
	Primary   color.Color // main text, H1 headings
	Secondary color.Color // H2, list bullets, accents
	Tertiary  color.Color // H3, links
	Accent    color.Color // H4, marks/highlights
	Highlight color.Color // H5, abbreviations
	Muted     color.Color // H6, comments, sub/sup, blockquote, DD, HR
	Text      color.Color // default body text, paragraphs, list items, DT
	Surface   color.Color // background for kbd
	Base      color.Color // background for inline code, code blocks, mark foreground
}

ColorPalette defines a minimal set of colors from which a full Theme can be derived. This allows users to share a single color palette across herald and other Charm ecosystem libraries (e.g. huh).

type ListItem ¶ added in v0.2.0

type ListItem struct {
	Text     string
	Children []ListItem
	Kind     ListKind // how Children are rendered (UL vs OL)
}

ListItem represents a single entry in a nested list. It may contain children to create hierarchical lists.

func Item ¶ added in v0.2.0

func Item(text string) ListItem

Item creates a leaf ListItem with no children.

func ItemWithChildren ¶ added in v0.2.0

func ItemWithChildren(text string, children ...ListItem) ListItem

ItemWithChildren creates a ListItem whose children are rendered as an unordered sub-list.

func ItemWithOLChildren ¶ added in v0.2.0

func ItemWithOLChildren(text string, children ...ListItem) ListItem

ItemWithOLChildren creates a ListItem whose children are rendered as an ordered sub-list.

func Items ¶ added in v0.2.0

func Items(texts ...string) []ListItem

Items converts multiple strings into a slice of leaf ListItems.

type ListKind ¶ added in v0.2.0

type ListKind int

ListKind determines whether a list is rendered as unordered or ordered.

const (
	// Unordered renders list items with bullet characters.
	Unordered ListKind = iota
	// Ordered renders list items with sequential numbers.
	Ordered
)

type Option ¶

type Option func(*Typography)

Option is a functional option for configuring a Typography instance.

func WithAbbrStyle ¶

func WithAbbrStyle(s lipgloss.Style) Option

WithAbbrStyle overrides the abbreviation style.

func WithAlertBar ¶ added in v0.3.0

func WithAlertBar(c string) Option

WithAlertBar sets the left-bar character for alerts.

func WithAlertIcon ¶ added in v0.3.0

func WithAlertIcon(at AlertType, icon string) Option

WithAlertIcon overrides the icon for a specific alert type.

func WithAlertLabel ¶ added in v0.3.0

func WithAlertLabel(at AlertType, label string) Option

WithAlertLabel overrides the label for a specific alert type.

func WithAlertPalette ¶ added in v0.3.0

func WithAlertPalette(ap AlertPalette) Option

WithAlertPalette rebuilds all alert configs from the given AlertPalette, using default icons and labels.

func WithAlertStyle ¶ added in v0.3.0

func WithAlertStyle(at AlertType, s lipgloss.Style) Option

WithAlertStyle overrides the style for a specific alert type.

func WithBlockquoteBar ¶

func WithBlockquoteBar(c string) Option

WithBlockquoteBar sets the left-bar character for blockquotes.

func WithBlockquoteStyle ¶

func WithBlockquoteStyle(s lipgloss.Style) Option

WithBlockquoteStyle overrides the blockquote style.

func WithBoldStyle ¶

func WithBoldStyle(s lipgloss.Style) Option

WithBoldStyle overrides the bold style.

func WithBulletChar ¶

func WithBulletChar(c string) Option

WithBulletChar sets the bullet character for unordered lists.

func WithCodeBlockStyle ¶

func WithCodeBlockStyle(s lipgloss.Style) Option

WithCodeBlockStyle overrides the code block style.

func WithCodeFormatter ¶ added in v0.2.0

func WithCodeFormatter(fn func(code, language string) string) Option

WithCodeFormatter sets a callback that receives raw code and a language hint, returning syntax-highlighted text. The highlighted text is then wrapped in the CodeInline or CodeBlock style for consistent padding/margins.

func WithCodeInlineStyle ¶

func WithCodeInlineStyle(s lipgloss.Style) Option

WithCodeInlineStyle overrides the inline code style.

func WithCodeLineNumberSep ¶ added in v0.4.0

func WithCodeLineNumberSep(sep string) Option

WithCodeLineNumberSep sets the separator between line numbers and code content.

func WithCodeLineNumberStyle ¶ added in v0.4.0

func WithCodeLineNumberStyle(s lipgloss.Style) Option

WithCodeLineNumberStyle overrides the style for code block line numbers.

func WithCodeLineNumbers ¶ added in v0.4.0

func WithCodeLineNumbers(enabled bool) Option

WithCodeLineNumbers enables or disables line numbers in code blocks.

func WithDDStyle ¶

func WithDDStyle(s lipgloss.Style) Option

WithDDStyle overrides the definition description style.

func WithDTStyle ¶

func WithDTStyle(s lipgloss.Style) Option

WithDTStyle overrides the definition term style.

func WithH1Style ¶

func WithH1Style(s lipgloss.Style) Option

WithH1Style overrides the H1 heading style.

func WithH1UnderlineChar ¶

func WithH1UnderlineChar(c string) Option

WithH1UnderlineChar sets the character used for the H1 underline.

func WithH2Style ¶

func WithH2Style(s lipgloss.Style) Option

WithH2Style overrides the H2 heading style.

func WithH2UnderlineChar ¶

func WithH2UnderlineChar(c string) Option

WithH2UnderlineChar sets the character used for the H2 underline.

func WithH3Style ¶

func WithH3Style(s lipgloss.Style) Option

WithH3Style overrides the H3 heading style.

func WithH3UnderlineChar ¶

func WithH3UnderlineChar(c string) Option

WithH3UnderlineChar sets the character used for the H3 underline.

func WithH4Style ¶

func WithH4Style(s lipgloss.Style) Option

WithH4Style overrides the H4 heading style.

func WithH5Style ¶

func WithH5Style(s lipgloss.Style) Option

WithH5Style overrides the H5 heading style.

func WithH6Style ¶

func WithH6Style(s lipgloss.Style) Option

WithH6Style overrides the H6 heading style.

func WithHRChar ¶

func WithHRChar(c string) Option

WithHRChar sets the character used for horizontal rules.

func WithHRStyle ¶

func WithHRStyle(s lipgloss.Style) Option

WithHRStyle overrides the horizontal rule style.

func WithHRWidth ¶

func WithHRWidth(w int) Option

WithHRWidth sets the width of horizontal rules in characters.

func WithHeadingBarChar ¶

func WithHeadingBarChar(c string) Option

WithHeadingBarChar sets the bar prefix character for H4-H6.

func WithHierarchicalNumbers ¶ added in v0.2.0

func WithHierarchicalNumbers(enabled bool) Option

WithHierarchicalNumbers enables hierarchical numbering for nested ordered lists (e.g. 1., 1.1, 1.2, 2., 2.1). When false (default), each nested sub-list restarts numbering at 1.

func WithItalicStyle ¶

func WithItalicStyle(s lipgloss.Style) Option

WithItalicStyle overrides the italic style.

func WithKbdStyle ¶

func WithKbdStyle(s lipgloss.Style) Option

WithKbdStyle overrides the keyboard key style.

func WithLinkStyle ¶

func WithLinkStyle(s lipgloss.Style) Option

WithLinkStyle overrides the link style.

func WithListBulletStyle ¶

func WithListBulletStyle(s lipgloss.Style) Option

WithListBulletStyle overrides the bullet/number marker style.

func WithListIndent ¶ added in v0.2.0

func WithListIndent(n int) Option

WithListIndent sets the number of spaces per nesting level for nested lists.

func WithListItemStyle ¶

func WithListItemStyle(s lipgloss.Style) Option

WithListItemStyle overrides the list item text style.

func WithMarkStyle ¶

func WithMarkStyle(s lipgloss.Style) Option

WithMarkStyle overrides the highlight/mark style.

func WithNestedBulletChars ¶ added in v0.2.0

func WithNestedBulletChars(chars []string) Option

WithNestedBulletChars sets the bullet characters that cycle through nesting levels in nested unordered lists.

func WithPalette ¶ added in v0.2.0

func WithPalette(p ColorPalette) Option

WithPalette derives a complete theme from a ColorPalette and sets it. It is a convenience shortcut for WithTheme(ThemeFromPalette(p)).

func WithParagraphStyle ¶

func WithParagraphStyle(s lipgloss.Style) Option

WithParagraphStyle overrides the paragraph style.

func WithSmallStyle ¶

func WithSmallStyle(s lipgloss.Style) Option

WithSmallStyle overrides the small/faint style.

func WithStrikethroughStyle ¶

func WithStrikethroughStyle(s lipgloss.Style) Option

WithStrikethroughStyle overrides the strikethrough style.

func WithTheme ¶

func WithTheme(t Theme) Option

WithTheme sets the entire theme at once.

func WithUnderlineStyle ¶

func WithUnderlineStyle(s lipgloss.Style) Option

WithUnderlineStyle overrides the underline style.

type Theme ¶

type Theme struct {
	// Headings H1-H6
	H1 lipgloss.Style
	H2 lipgloss.Style
	H3 lipgloss.Style
	H4 lipgloss.Style
	H5 lipgloss.Style
	H6 lipgloss.Style

	// Text block elements
	Paragraph  lipgloss.Style
	Blockquote lipgloss.Style
	CodeInline lipgloss.Style
	CodeBlock  lipgloss.Style
	HR         lipgloss.Style

	// List elements
	ListBullet lipgloss.Style // style for the bullet/number marker
	ListItem   lipgloss.Style // style for list item text

	// Inline styles
	Bold          lipgloss.Style
	Italic        lipgloss.Style
	Underline     lipgloss.Style
	Strikethrough lipgloss.Style
	Small         lipgloss.Style
	Mark          lipgloss.Style
	Link          lipgloss.Style
	Kbd           lipgloss.Style
	Abbr          lipgloss.Style
	Sub           lipgloss.Style
	Sup           lipgloss.Style

	// Definition list
	DT lipgloss.Style // definition term
	DD lipgloss.Style // definition description

	// Callbacks
	CodeFormatter func(code, language string) string // optional syntax highlighter

	// Heading decoration
	H1UnderlineChar string // character repeated under H1 (e.g. "═")
	H2UnderlineChar string // character repeated under H2 (e.g. "─")
	H3UnderlineChar string // character repeated under H3 (e.g. "·")
	HeadingBarChar  string // left-bar prefix for H4-H6 (e.g. "▎")

	// Code block line numbers
	CodeLineNumber    lipgloss.Style // style for line number text
	CodeLineNumberSep string         // separator between line number and code (e.g. "│")
	ShowLineNumbers   bool           // whether to render line numbers in CodeBlock

	// Configurable tokens
	BulletChar          string   // character used for unordered list bullets
	NestedBulletChars   []string // bullet chars cycling per depth for nested lists
	ListIndent          int      // spaces per nesting level for nested lists
	HierarchicalNumbers bool     // use hierarchical numbering (e.g. 2.1, 2.2) for nested OL
	HRChar              string   // character repeated for horizontal rules
	HRWidth             int      // width of horizontal rule in characters
	BlockquoteBar       string   // left-bar character for blockquotes

	// Alert elements
	Alerts   map[AlertType]AlertConfig // per-type icon, label, and style
	AlertBar string                    // left-bar character for alerts
}

Theme holds all style definitions used by Typography to render elements. Each field corresponds to a visual element and is a lipgloss.Style.

func Base16Theme ¶ added in v0.2.0

func Base16Theme() Theme

Base16Theme returns a Theme based on ANSI base16 terminal colors. Colors match huh's ThemeBase16. Base16 uses standard ANSI color indices; adaptive colors are used for API consistency.

func CatppuccinTheme ¶ added in v0.2.0

func CatppuccinTheme() Theme

CatppuccinTheme returns a Theme based on the Catppuccin color palette. Adapts to the terminal background: Mocha on dark, Latte on light. Colors match huh's ThemeCatppuccin.

func CharmTheme ¶ added in v0.2.0

func CharmTheme() Theme

CharmTheme returns a Theme based on Charm's brand color palette. Auto-detects terminal background for light/dark variants. Colors match huh's ThemeCharm.

func DefaultTheme ¶

func DefaultTheme() Theme

DefaultTheme returns a Theme based on the Rose Pine color palette.

func DraculaTheme ¶ added in v0.2.0

func DraculaTheme() Theme

DraculaTheme returns a Theme based on the Dracula color palette. Colors match huh's ThemeDracula. Dracula is a dark-only palette; adaptive colors are used for API consistency.

func ThemeFromPalette ¶ added in v0.2.0

func ThemeFromPalette(p ColorPalette) Theme

ThemeFromPalette constructs a complete Theme by mapping palette colors to all style fields. Configurable tokens use the same defaults as DefaultTheme.

type Typography ¶

type Typography struct {
	// contains filtered or unexported fields
}

Typography is the central renderer. It holds a Theme and exposes methods for every supported typographic element.

func New ¶

func New(opts ...Option) *Typography

New creates a new Typography instance with the default theme, then applies any provided functional options.

func (*Typography) Abbr ¶

func (t *Typography) Abbr(abbr string, desc ...string) string

Abbr renders an abbreviation. If a description is provided it is shown in parentheses after the abbreviation.

func (*Typography) Alert ¶ added in v0.3.0

func (t *Typography) Alert(at AlertType, text string) string

Alert renders a GitHub-style alert callout. The header line (bar + icon + label) is bold + colored; content lines have a colored bar but unstyled text, matching GitHub's visual style. If the alert type is not configured, it falls back to blockquote rendering.

func (*Typography) Blockquote ¶

func (t *Typography) Blockquote(text string) string

Blockquote renders a blockquote with a left border bar. Multi-line text is handled by prepending the bar to every line.

func (*Typography) Bold ¶

func (t *Typography) Bold(text string) string

Bold renders bold text.

func (*Typography) Caution ¶ added in v0.3.0

func (t *Typography) Caution(text string) string

Caution renders a red caution/danger alert.

func (*Typography) Code ¶

func (t *Typography) Code(text string, lang ...string) string

Code renders inline code. If a language is provided and a CodeFormatter is set on the theme, the formatter is applied before wrapping in the style.

func (*Typography) CodeBlock ¶

func (t *Typography) CodeBlock(text string, lang ...string) string

CodeBlock renders a fenced code block. If a language is provided and a CodeFormatter is set on the theme, the formatter is applied before wrapping in the style. When ShowLineNumbers is true, line numbers are prepended to each line after formatting.

func (*Typography) DD ¶

func (t *Typography) DD(text string) string

DD renders a single definition description.

func (*Typography) DL ¶

func (t *Typography) DL(pairs [][2]string) string

DL renders a definition list from term-description pairs. Each pair is a two-element array: [term, description]. Odd-length slices ignore the last unpaired element.

func (*Typography) DT ¶

func (t *Typography) DT(text string) string

DT renders a single definition term.

func (*Typography) H1 ¶

func (t *Typography) H1(text string) string

H1 renders text as a level-1 heading with a double-line underline.

func (*Typography) H2 ¶

func (t *Typography) H2(text string) string

H2 renders text as a level-2 heading with a single-line underline.

func (*Typography) H3 ¶

func (t *Typography) H3(text string) string

H3 renders text as a level-3 heading with a dotted underline.

func (*Typography) H4 ¶

func (t *Typography) H4(text string) string

H4 renders text as a level-4 heading with a bar prefix.

func (*Typography) H5 ¶

func (t *Typography) H5(text string) string

H5 renders text as a level-5 heading with a bar prefix.

func (*Typography) H6 ¶

func (t *Typography) H6(text string) string

H6 renders text as a level-6 heading with a bar prefix.

func (*Typography) HR ¶

func (t *Typography) HR() string

HR renders a horizontal rule.

func (*Typography) Important ¶ added in v0.3.0

func (t *Typography) Important(text string) string

Important renders a purple important-information alert.

func (*Typography) Italic ¶

func (t *Typography) Italic(text string) string

Italic renders italic text.

func (*Typography) Kbd ¶

func (t *Typography) Kbd(text string) string

Kbd renders a keyboard key indicator.

func (*Typography) Link ¶

func (t *Typography) Link(label string, url ...string) string

Link renders a styled URL or link text. If both label and url are provided, it renders as "label (url)". If only one argument is given, it is treated as both the label and the URL.

func (*Typography) Mark ¶

func (t *Typography) Mark(text string) string

Mark renders highlighted text.

func (*Typography) NestOL ¶ added in v0.2.0

func (t *Typography) NestOL(items ...ListItem) string

NestOL renders a nested ordered list from the provided ListItems.

func (*Typography) NestUL ¶ added in v0.2.0

func (t *Typography) NestUL(items ...ListItem) string

NestUL renders a nested unordered list from the provided ListItems.

func (*Typography) Note ¶ added in v0.3.0

func (t *Typography) Note(text string) string

Note renders a blue informational alert.

func (*Typography) OL ¶

func (t *Typography) OL(items ...string) string

OL renders an ordered (numbered) list from the provided items.

func (*Typography) P ¶

func (t *Typography) P(text string) string

P renders a paragraph.

func (*Typography) Small ¶

func (t *Typography) Small(text string) string

Small renders small/faint text.

func (*Typography) Strikethrough ¶

func (t *Typography) Strikethrough(text string) string

Strikethrough renders strikethrough text.

func (*Typography) Sub ¶

func (t *Typography) Sub(text string) string

Sub renders a subscript marker. In a terminal we prefix with an underscore to visually indicate subscript.

func (*Typography) Sup ¶

func (t *Typography) Sup(text string) string

Sup renders a superscript marker. In a terminal we prefix with a caret to visually indicate superscript.

func (*Typography) Theme ¶

func (t *Typography) Theme() Theme

Theme returns a copy of the current theme.

func (*Typography) Tip ¶ added in v0.3.0

func (t *Typography) Tip(text string) string

Tip renders a green helpful-hint alert.

func (*Typography) UL ¶

func (t *Typography) UL(items ...string) string

UL renders an unordered (bulleted) list from the provided items.

func (*Typography) Underline ¶

func (t *Typography) Underline(text string) string

Underline renders underlined text.

func (*Typography) Warning ¶ added in v0.3.0

func (t *Typography) Warning(text string) string

Warning renders a yellow/amber warning alert.

Source Files ¶

View all Source files

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
examples
00_default-theme command herald with the default Rose Pine theme.	herald with the default Rose Pine theme.
01_lists command Demonstrates flat lists, nested lists, mixed nesting, and hierarchical numbering.	Demonstrates flat lists, nested lists, mixed nesting, and hierarchical numbering.
02_alerts command GitHub-style alerts demo with the default Rose Pine theme.	GitHub-style alerts demo with the default Rose Pine theme.
03_custom-options command Customizing herald with functional options: override individual styles, decoration characters, and tokens without replacing the entire theme.	Customizing herald with functional options: override individual styles, decoration characters, and tokens without replacing the entire theme.
04_palette command Using ColorPalette to create a consistent theme from just 8 colors.	Using ColorPalette to create a consistent theme from just 8 colors.
05_builtin-themes command Using herald's built-in named themes that match huh's color palettes.	Using herald's built-in named themes that match huh's color palettes.
demos/alerts command GitHub-style alerts: Note, Tip, Important, Warning, Caution.	GitHub-style alerts: Note, Tip, Important, Warning, Caution.
demos/blocks command Block-level elements: paragraph, blockquote, code block, HR, and definition list.	Block-level elements: paragraph, blockquote, code block, HR, and definition list.
demos/builtin-themes/base16 command Base16 theme showcase.	Base16 theme showcase.
demos/builtin-themes/catppuccin command Catppuccin theme showcase.	Catppuccin theme showcase.
demos/builtin-themes/charm command Charm theme showcase.	Charm theme showcase.
demos/builtin-themes/dracula command Dracula theme showcase.	Dracula theme showcase.
demos/headings command All six heading levels with the default Rose Pine theme.	All six heading levels with the default Rose Pine theme.
demos/hero command Compact highlight reel for the README hero image.	Compact highlight reel for the README hero image.
demos/inline command Inline styles, links, and abbreviations.	Inline styles, links, and abbreviations.
demos/lists command Flat and nested lists with mixed nesting.	Flat and nested lists with mixed nesting.