styledown

Documentation

Overview

Styledown is a simple markup language for representing styled text.

In the most basic form, Styledown markup consists of alternating text lines and style lines, where each character in the style line specifies the style of the character directly above it. For example:

foobar
***###
lorem
_____

represents two lines:

1. "foo" in bold, followed immediately by "bar" in reverse video
2. "lorem" in underline

Note the following:

• Style characters like "*" are defined in BuiltinStyleChars.
• A trailing newline after the last line is assumed.

Both aspects can be altered by the configuration stanza (see below).

This package can be used as a Go library or via Elvish's render-styledown command (https://elv.sh/ref/builtin.html#render-styledown).

Double-width characters

Characters in text and style lines are matched up using their visual width, as calculated by src.elv.sh/pkg/wcwidth.OfRune. This means that double-width characters need to have their style character doubled:

好 foo
** ###

The two style characters must be the same.

Configuration stanza

The alternating text and style lines constitute the "content stanza". It can be followed by an optional configuration stanza, separated by a single newline.

The configuration stanza can define additional style characters like this:

foobar
rrrGGG

r fg-red
G inverse fg-green

Each line consists of the style character and one or more stylings as recognized by src.elv.sh/pkg/ui.ParseStyling, separated by whitespaces. The character must be a single Unicode codepoint and have a visual width of 1.

The configuration stanza can also contain additional options, and there's currently just one:

• no-eol: suppress the newline after the last line

Rationale

Styledown is suitable for authoring large chunks of styled text. Its main advantage is that it preserves the alignment of text. Compare the following Styledown code:

foo:    100
###
foobar: 200
###___

With the following hypothetical HTML-like format:

<i>foo</i>:    100
<i>foo</i><u>bar</u>: 200

The Styledown example makes it clear that "100" and "200" are aligned. This property makes Styledown particularly suited for terminal mockups.

Styldown is also used in Elvish's tests that need to represent styled text in a visual pure-text format.

Index

• Variables
• func Derender(t ui.Text, styleDefs string) (string, error)
• func Render(s string) (ui.Text, error)

Variables

var BuiltinStyleChars = map[rune]ui.Styling{
	' ': ui.Reset,
	'*': ui.Bold,
	'_': ui.Underlined,
	'#': ui.Inverse,
}

BuiltinStyleChars defines the styling characters that are recognized by default.

Functions

func Derender

func Derender(t ui.Text, styleDefs string) (string, error)

Derender converts a Text to Styledown markup.

The styleDefs string is used to supply style characters in addition to BuiltinStyleChars; it uses the same syntax as configuration lines in Styledown. Only those that are actually used will appear in the markup's configuration stanza, sorted by first use.

This function returns an error if any of the following is true:

• styleDefs is invalid
• styleDefs contains two characters for the same style
• t contains segments with a style not covered by the map merged from BuiltinStyleChars and styleDefs

func Render

func Render(s string) (ui.Text, error)

Render renders Styledown markup. If the markup has parse errors, the error will start with "line x", where x is a 1-based line number.