tviewmd

README

tviewmd

Native markdown rendering for tview TextViews.

tviewmd parses markdown (CommonMark + GFM) into a renderer-neutral block/segment model, then emits tview color tags directly — no ANSI round-trip, no glamour/TranslateANSI double translation.

Why

tview apps today render markdown via glamour, which produces ANSI that must be re-parsed into tview tags with tview.TranslateANSI. That hop is lossy, wasteful, and glamour's block backgrounds clash with tview widgets. tviewmd emits tview tags natively so a TextView.SetWrap(true) just works.

Quick start

import "github.com/buchenberg/tviewmd"

tv := tview.NewTextView().SetWrap(true)
fmt.Fprint(tv, tviewmd.Render("# Hello\n\nSome **bold** and `code`.", tviewmd.Options{}))

Design

• Parser: goldmark (CommonMark + GFM) — correct parsing for free.
• Code highlighting: chroma terminal256 formatter, translated to tview tags.
• Layered core: Parse → []Block (renderer-neutral) → RenderTView. A future RenderANSI / plain backend can reuse the same []Block.

The []Block / Segment model is the real deliverable: a curated terminal-oriented markdown vocabulary, smaller and friendlier than goldmark's full AST.

Status

In-tree development under the yaah repository (md/), extracted via a Go workspace. When the test bar is met it lifts to its own repo with zero import rewrites (the module path is already github.com/buchenberg/tviewmd).

License

MIT.

Documentation

Overview

Package tviewmd renders markdown to tview color-tagged text.

It parses CommonMark + GFM markdown (via goldmark) into a renderer-neutral block/segment model, then emits tview color tags directly — suitable for a tview.TextView with SetWrap(true). No ANSI round-trip is required.

The primary entry points are Render (parse + render) and RenderTView (render pre-parsed blocks). Callers that want to inspect or transform the document can use Parse to obtain the intermediate []Block representation.

Index

• func Render(src string, opts Options) string
• func RenderTView(blocks []Block, opts Options) string
• type Block
  • func Parse(src string) ([]Block, error)
• type BlockKind
• type CodeBlock
• type ListItem
• type Options
• type Segment
• type Style
• type TableCell
• type TableData
• type TextAlign
• type Theme
  • func DefaultTheme() Theme

Functions

func Render

func Render(src string, opts Options) string

Render parses src and renders it to tview color-tagged text. It is the convenience entry point for callers that do not need the intermediate []Block.

func RenderTView

func RenderTView(blocks []Block, opts Options) string

RenderTView renders parsed blocks to tview color-tagged text suitable for a tview.TextView configured with SetWrap(true). The output contains tview color tags ([fg:bg:flags] ... [-:-:-]); the TextView performs word-wrapping.

Types

type Block

type Block struct {
	Kind     BlockKind
	Level    int        // heading level 1-6 (BlockHeading only)
	Segments []Segment  // paragraph, heading, blockquote inline content
	Code     CodeBlock  // BlockCodeBlock only
	Items    []ListItem // BlockList only
	Table    TableData  // BlockTable only
}

Block is one block-level element. The field matching Kind is populated; the others are zero-valued.

func Parse

func Parse(src string) ([]Block, error)

Parse converts markdown source into a slice of renderer-neutral Blocks. Parse never returns an error for goldmark (markdown is permissive), but the error result is retained for API symmetry with future parser backends.

type BlockKind

type BlockKind int

BlockKind enumerates block-level markdown elements.

const (
	// BlockParagraph is a run of inline content (text + emphasis + code + links).
	BlockParagraph BlockKind = iota
	// BlockHeading is a level 1-6 heading. Level holds the depth.
	BlockHeading
	// BlockCodeBlock is a fenced or indented code block. Code holds language+source.
	BlockCodeBlock
	// BlockList is an ordered or unordered list. Items holds the entries.
	BlockList
	// BlockBlockquote is a quoted block. Segments holds the flattened inline content.
	BlockBlockquote
	// BlockTable is a GFM table. Table holds header, rows, and column alignments.
	BlockTable
	// BlockThematicBreak is a horizontal rule.
	BlockThematicBreak
)

type CodeBlock

type CodeBlock struct {
	Lang   string // language hint from the info string (may be empty)
	Source string
}

CodeBlock holds a fenced or indented code block.

type ListItem

type ListItem struct {
	Segments []Segment
	Children []ListItem // nested list items
	Ordered  bool
	// Index is the 1-based ordinal for ordered items.
	Index int
}

ListItem is one entry in a List block.

type Options

type Options struct {
	// Width is used for horizontal-rule length and table column sizing. 0 = 80.
	Width int

	// NoHighlight disables chroma syntax highlighting for fenced code blocks.
	NoHighlight bool

	// Theme is the color theme. The zero value uses DefaultTheme().
	Theme Theme
}

Options configure rendering. The zero value renders with the default theme, syntax highlighting enabled, and an 80-column width for rules and tables.

type Segment

type Segment struct {
	Text  string
	Style Style

	// Link, when non-empty, marks Text as the link label and Link as the URL.
	Link string

	// Code marks the segment as inline code. Renderers may use a distinct
	// background/foreground for code spans.
	Code bool
}

Segment is a single styled inline run of text. Exactly one rendering hint applies: Code, Link, or a plain Style.

type Style

type Style struct {
	FG string
	BG string

	Bold          bool
	Italic        bool
	Underline     bool
	Strikethrough bool
	Dim           bool
}

Style is renderer-neutral inline formatting. Empty color fields mean "inherit the surrounding style"; the renderer maps the flags to its native emphasis syntax.

type TableCell

type TableCell struct {
	Segments []Segment
	Align    TextAlign
}

TableCell is one cell of a table row.

type TableData

type TableData struct {
	Header []TableCell
	Rows   [][]TableCell
	// Aligns is the per-column alignment declared in the delimiter row.
	Aligns []TextAlign
}

TableData holds a parsed GFM table.

type TextAlign

type TextAlign int

TextAlign controls table column alignment.

const (
	// AlignDefault left-aligns (the CommonMark default rendering).
	AlignDefault TextAlign = iota
	AlignLeft
	AlignCenter
	AlignRight
)

type Theme

type Theme struct {
	// Heading colors per level (index 0 = H1). Used by the tview backend.
	Heading [6]string

	Link         string
	InlineCodeFG string
	InlineCodeBG string
	CodeBlockFG  string
	QuoteFG      string
	Hr           string
}

Theme holds the color scheme used by renderers. Colors are expressed in any form the target backend understands (tview accepts named colors like "red", hex like "#ff8c42", and "default").

func DefaultTheme

func DefaultTheme() Theme

DefaultTheme returns a dark-terminal-friendly theme tuned for readability on a black/default background.