spruce/markdown

Markdown to ANSI terminal rendering.

Rendering is driven by the mork parser (canonical home: https://git.liten.app/krig/mork) and walks its document AST directly rather than going through mork’s HTML output.

GFM support

The following GitHub Flavored Markdown extensions are supported:

Tables (rendered via spruce/table)
Task list items (- [x] / - [ ])
Strikethrough (~~text~~)
Extended autolinks for bare URLs and www. links

In addition, GitHub-style alerts (> [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], [!CAUTION]) and Astro/Starlight :::type[Title] container directives are rendered as colored callouts.

Known limitations

These are GitHub/Markdown features that are not rendered. Most stem from upstream mork (tracked in its TODO.md); a few are deliberate choices here.

Emoji shortcodes (:rocket:) are not expanded. mork only expands them in its HTML output path, not in the document AST this module renders, so enabling mork.emojis has no effect here.
Email autolinks (bare me@example.com) are not linked; extended email autolinking is unimplemented upstream (mork TODO: “autolink (email)”).
Footnotes: a [^1] reference renders as literal [^1] and the definition body is dropped. Footnote bodies are not yet implemented upstream, and inline footnotes (^[...]) are unsupported.
GFM table column alignment (:--, :-:, --:) is parsed by mork but ignored here: every cell is left-aligned, because spruce/table does not expose per-column alignment.
Heading ID attributes (## Title {#id}) are stripped from the rendered text (via mork.heading_ids), since a terminal has no anchors to link to. The id itself is parsed but not rendered.
Raw HTML is not sanitized. Inline and block HTML is passed through (rendered dimmed), not escaped or stripped. mork does not implement GFM’s tagfilter. This is harmless in a terminal, but do not rely on this module to neutralize untrusted HTML.

Types

Options

opaque </>

Markdown rendering options: the theme and an optional wrap width.

pub opaque type Options

Theme

opaque </>

A set of styles controlling how each Markdown element is rendered. Construct one with dark_theme, light_theme, or adaptive_theme.

pub opaque type Theme

Values

adaptive_theme

</>

pub fn adaptive_theme() -> Theme

A theme whose colors adapt to the terminal background (light vs dark), resolved per render from spruce.background. This is the default theme used by render and default_options. On Unknown backgrounds it renders as dark.

dark_theme

</>

pub fn dark_theme() -> Theme

Build a theme tuned for dark terminal backgrounds.

default_options

</>

pub fn default_options() -> Options

Default options: the adaptive theme and no width limit.

light_theme

</>

pub fn light_theme() -> Theme

Build a theme tuned for light terminal backgrounds.

print

</>

pub fn print(sp: spruce.Spruce, markdown: String) -> Nil

Render Markdown with the default options and print it to stdout.

render

</>

pub fn render(sp: spruce.Spruce, markdown: String) -> String

Render Markdown to styled terminal text using the default options.

render_with

</>

pub fn render_with(
  sp: spruce.Spruce,
  markdown: String,
  options: Options,
) -> String

Render Markdown to styled terminal text with explicit options.

with_theme

</>

pub fn with_theme(options: Options, theme: Theme) -> Options

Use a specific theme when rendering.

with_width

</>

pub fn with_width(options: Options, width: Int) -> Options

Wrap rendered output to a maximum visual width. Negative values clamp to 0.