tui-markdown feature showcase

This document exercises the Markdown constructs supported by tui-markdown and provides a useful manual test for mdr. Read it with:

cargo run -p markdown-reader -- markdown-reader/TEST.md

Each section shows its Markdown source first, followed by the live example rendered by mdr.

Metadata blocks

Metadata must be the first construct in a document, so the opening lines of this file are the live example. They use this syntax:

---
document: tui-markdown feature showcase
tags:
  - markdown
  - ratatui
  - terminal
---

Headings and attributes

### Heading with attributes {#heading .showcase audience=maintainers}
#### Level four
##### Level five
###### Level six

Heading with attributes {#heading .showcase audience=maintainers}

Level four

Level five

Level six

Paragraphs and inline formatting

Plain text can contain *emphasis*, **strong emphasis**, ***both at once***,
~~strikethrough~~, and `inline code`.

Formatting can be nested: **strong text with *emphasis* and `code`**.

Superscript: $2^{10}$^. Subscript: H~2~O.

Plain text can contain emphasis, strong emphasis, both at once, strikethrough, and inline code.

Formatting can be nested: strong text with emphasis and code.

Superscript: $2^{10}$^. Subscript: H2O.

Line breaks

A soft
line break becomes a space.

A hard break keeps the backslash\
and starts a new terminal line.

A soft line break becomes a space.

A hard break keeps the backslash
and starts a new terminal line.

Links and images

Visit the [Ratatui website](https://ratatui.rs) or its
[GitHub repository][ratatui-repository].

![Ferris holding a terminal](https://rustacean.net/assets/rustacean-flat-happy.png)

[ratatui-repository]: https://github.com/ratatui/ratatui

Visit the Ratatui website or its GitHub repository. Link labels may contain formatting.

Images use a terminal-friendly text fallback instead of loading image data:

Blockquotes

> A blockquote can contain **formatted text** and `inline code`.
>
> A second paragraph stays inside the same quote.

> An outer quote can contain another quote.
>
>> The nested quote has an additional `>` prefix.

Multiple paragraphs

A blockquote can contain formatted text and inline code.

A second paragraph stays inside the same quote.

Nested quote

An outer quote can contain another quote.

The nested quote has an additional > prefix.

Text after a blockquote returns to the ordinary paragraph style.

GitHub-style alerts

> [!NOTE]
> Notes add useful context.

> [!TIP]
> Tips suggest a more convenient approach.

> [!IMPORTANT]
> Important information is necessary to complete the task.

> [!WARNING]
> Warnings describe a risk that deserves attention.

> [!CAUTION]
> Cautions call out a likely negative consequence.

Note alert

Tip alert

Important alert

Warning alert

Caution alert

Lists

- Renderer
  - Styles spans
  - Preserves block layout
- Reader
  - Opens Markdown files
  - Scrolls terminal output

1. Parse Markdown events
2. Render Ratatui lines
3. Draw the result

- [x] Parse the document
- [x] Render supported constructs
- [ ] Add the next feature

An unordered list can contain nested items:

• Renderer
  • Styles spans
  • Preserves block layout
• Reader
  • Opens Markdown files
  • Scrolls terminal output

Ordered lists preserve their numbering:

1. Parse Markdown events
2. Render Ratatui lines
3. Draw the result

Task lists show completed and pending work:

• Parse the document
• Render supported constructs
• Add the next feature

Code

The outer four-backtick fence below displays the three-backtick code-fence syntax.

```rust
use tui_markdown::from_str;

let text = from_str("**Hello**, terminal!");
println!("{text}");
```

```made-up-language
widget -> buffer -> terminal
```

Recognized fenced languages use syntax highlighting when the highlight-code feature is enabled:

use tui_markdown::from_str;

let text = from_str("**Hello**, terminal!");
println!("{text}");

An unrecognized language still renders as a code block using the configured fallback style:

widget -> buffer -> terminal

Tables

| Construct   | Example                       | Status |
| :---------- | :---------------------------: | -----: |
| Strong      | **bold**                      |  Ready |
| Inline code | `Text<'a>`                    |  Ready |
| Link        | [Ratatui](https://ratatui.rs) |  Ready |
| Wide text   | 東京                          |  Ready |
| Emoji       | 🦀                            |  Ready |

Tables honor left, center, and right alignment. Wide CJK text and emoji use terminal display width, and inline Markdown stays inside its cell.

Construct	Example	Status
Strong	bold	Ready
Inline code	Text<'a>	Ready
Link	Ratatui	Ready
Wide text	東京	Ready
Emoji	🦀	Ready

Math

Inline math remains in its sentence: $E = mc^2$.

$$
f(x) = x^2 + 2x + 1
     = (x + 1)^2
$$

Inline math remains in its sentence: $E = mc^2$.

Display math preserves its delimiters and physical lines:

$$f(x) = x^2 + 2x + 1 = (x + 1)^2$$

HTML

Inline HTML remains visible.<br>

<details>
<summary>Block HTML also remains visible</summary>
Each source line remains visible.
</details>

Inline HTML remains visible rather than being interpreted.
The tag itself appears in the rendered text.

Block HTML also remains visible

Each source line is rendered on its own terminal line.

Definition lists

Terminal user interface
: A text-based interface drawn in a terminal.

Ratatui
: A Rust library for building terminal user interfaces.
: The rendering library used by `tui-markdown`.

Terminal user interface : A text-based interface drawn in a terminal.

Ratatui : A Rust library for building terminal user interfaces. : The rendering library used by tui-markdown.

Footnotes

Footnote references stay inline.[^renderer] More than one may appear.[^reader]

[^renderer]: `tui-markdown` converts Markdown into styled Ratatui text.

    A definition may contain a second paragraph.

[^reader]: `mdr` displays the rendered text in the terminal.

Footnote references stay inline.¹ More than one may appear.²

Thematic break

Text before the rule.

---

Text after the rule.

Text before the rule.

---

Text after the rule should not inherit styles or indentation from any earlier construct.

Footnotes

1. tui-markdown converts Markdown into styled Ratatui text.

   A definition may contain a second paragraph. ↩

2. mdr displays the rendered text in the terminal. ↩