termimad 0.6.4

Markdown Renderer for the Terminal
Documentation

MIT Latest Version docs Chat on Miaou

A simple tool to display static or dynamic Markdown snippets in the terminal, with skin isolation.

Based on crossterm so works on most terminals (even on windows).

text

The goal isn't to display any markdown text with its various extensions (a terminal isn't really fit for that). The goal is rather to improve the display of texts in a terminal application when we want both the text and the skin to be easily configured.

Termimad also includes a few utilities helping efficient managing of events and user input in a multithread application.

Wrapping, table balancing, and scrolling are essential features of Termimad.

A text or a table can be displayed in an a priori unknown part of the screen, scrollable if desired, with a dynamically discovered width.

For example this markdown:

|:-:|:-:|-
|**feature**|**supported**|**details**|
|-:|:-:|-
| tables | yes | pipe based, with or without alignments
| italic, bold | yes | star based |
| inline code | yes | `with backquotes` (it works in tables too)
| code bloc | yes |with tabs; fences *not* supported
| syntax coloring | no |
| crossed text |  ~~not yet~~ | wait... now it works `~~like this~~`
| horizontal rule | yes | Use 3 or more dashes (`---`)
| lists | yes|* unordered lists supported
|  | |* ordered lists *not* supported
| quotes |  yes |> What a wonderful time to be alive!
| links | no | (but your terminal already handles raw URLs)
|-

will give different results depending on the width:

table

table

table

Usage

[dependencies]
termimad = "0.5"

With the default skin:

termimad::print_inline("**some** *nested **style*** and `some(code)`");

or

print!("{}", termimad::inline("**some** *nested **style*** and `some(code)`"));

Result:

simple example

Inline snippets with a custom skin:

Inline snippets are one line or less.

let mut skin = MadSkin::default();
skin.bold.set_fg(Yellow);
skin.print_inline("*Hey* **World!** Here's `some(code)`");
skin.paragraph.set_fgbg(Magenta, rgb(30, 30, 40));
skin.italic.add_attr(Underlined);
println!("\nand now {}\n", skin.inline("a little *too much* **style!** (and `some(code)` too)"));

Result:

too much style

Texts

Texts can be several lines. Tables and code blocks are automatically aligned, justified and consistently wrapped.

skin.print_text("# title\n* a list item\n* another item");

Scrollable TextView in a raw terminal:

scrollable

The code for this example is in examples/scrollable. To read the whole text just do

cargo run --example scrollable

Advices to get started

  • Start by reading the examples (in /examples): they cover the whole API and especially all the skin definition functions. They also show how you can use the alternate screen and scroll a page.
  • If you want to see how some file would look with Termimad, you may try the cli Clima.
  • Be careful that some colors aren't displayable on all terminals. The default color set of your application should not include arbitrary RGB colors.
  • If a feature is missing, or you don't know how to use some part, come and ping me on my chat during West European hours.

broot is a real application using Termimad to handle its help screen (if you're the author of another one, please tell me), you might want to see how it does it.