Skip to content

PyModel/pythinker-code / .agents/skills/opentui

opentui

Verified

Build terminal UIs with OpenTUI. Covers core, components, audio, keymaps, React, Solid, plugins, testing, standalone executables, QR encoding, SSH, and Three.js WebGPU.

FileKindSize
SKILL.mdskill md5.4 KB
docs/bindings/react.mdxmarkdown11.0 KB
docs/bindings/solid.mdxmarkdown15.0 KB
docs/components/ascii-font.mdxmarkdown4.3 KB
docs/components/box.mdxmarkdown5.5 KB
docs/components/code.mdxmarkdown10.2 KB
docs/components/diff.mdxmarkdown4.2 KB
docs/components/frame-buffer.mdxmarkdown6.7 KB
docs/components/input.mdxmarkdown5.6 KB
docs/components/line-number.mdxmarkdown4.0 KB
docs/components/markdown.mdxmarkdown10.6 KB
docs/components/qr-code.mdxmarkdown4.3 KB
docs/components/scrollbar.mdxmarkdown2.3 KB
docs/components/scrollbox.mdxmarkdown7.5 KB
docs/components/select.mdxmarkdown6.2 KB
docs/components/slider.mdxmarkdown2.2 KB
docs/components/tab-select.mdxmarkdown6.0 KB
docs/components/text-table.mdxmarkdown9.0 KB
docs/components/text.mdxmarkdown4.5 KB
docs/components/textarea.mdxmarkdown7.7 KB
docs/components/time-to-first-draw.mdxmarkdown4.7 KB
docs/core-concepts/audio.mdxmarkdown32.2 KB
docs/core-concepts/colors.mdxmarkdown7.8 KB
docs/core-concepts/console.mdxmarkdown3.2 KB
docs/core-concepts/constructs.mdxmarkdown5.8 KB
docs/core-concepts/keyboard.mdxmarkdown10.4 KB
docs/core-concepts/layout.mdxmarkdown4.0 KB
docs/core-concepts/lifecycle.mdxmarkdown4.4 KB
docs/core-concepts/notifications.mdxmarkdown2.3 KB
docs/core-concepts/renderables-vs-constructs.mdxmarkdown4.5 KB
docs/core-concepts/renderables.mdxmarkdown9.9 KB
docs/core-concepts/renderer.mdxmarkdown30.9 KB
docs/core-concepts/testing.mdxmarkdown14.6 KB
docs/getting-started.mdxmarkdown3.2 KB
docs/keymap/addons.mdxmarkdown15.6 KB
docs/keymap/core.mdxmarkdown38.9 KB
docs/keymap/custom-addons.mdxmarkdown26.7 KB
docs/keymap/hosts.mdxmarkdown15.7 KB
docs/keymap/overview.mdxmarkdown18.1 KB
docs/keymap/react.mdxmarkdown4.9 KB
docs/keymap/solid.mdxmarkdown5.1 KB
docs/plugins/core.mdxmarkdown12.6 KB
docs/plugins/react.mdxmarkdown6.5 KB
docs/plugins/slots.mdxmarkdown12.7 KB
docs/plugins/solid.mdxmarkdown7.0 KB
docs/reference/color-matrix.mdxmarkdown3.8 KB
docs/reference/env-vars.mdxmarkdown6.5 KB
docs/reference/native-span-feed.mdxmarkdown6.0 KB
docs/reference/package-entrypoints.mdxmarkdown9.6 KB
docs/reference/qr-encoder.mdxmarkdown12.3 KB
docs/reference/ssh.mdxmarkdown14.8 KB
docs/reference/standalone-executables.mdxmarkdown7.1 KB
docs/reference/three.mdxmarkdown14.8 KB
docs/reference/tree-sitter.mdxmarkdown4.6 KB

docs/components/markdown.mdx

View on GitHub
---
title: Markdown
description: Render markdown with syntax-aware styling
order: 11
---

# Markdown

Render markdown content with syntax-aware styling and optional Tree-sitter highlighting for code blocks.

## Basic usage

### Renderable API

````typescript
import { MarkdownRenderable, SyntaxStyle, RGBA, createCliRenderer } from "@opentui/core"

const renderer = await createCliRenderer()

const syntaxStyle = SyntaxStyle.fromStyles({
  "markup.heading.1": { fg: RGBA.fromHex("#58A6FF"), bold: true },
  "markup.list": { fg: RGBA.fromHex("#FF7B72") },
  "markup.raw": { fg: RGBA.fromHex("#A5D6FF") },
  default: { fg: RGBA.fromHex("#E6EDF3") },
})

const markdown = new MarkdownRenderable(renderer, {
  id: "readme",
  width: 60,
  content: "# Hello\n\n- One\n- Two\n\n```ts\nconst x = 1\n```",
  syntaxStyle,
})

renderer.root.add(markdown)
````

## Fenced language normalization

Code fence info strings are normalized before Tree-sitter highlighting.

- `tsx` -> `typescriptreact`
- `.jsx` -> `javascriptreact`
- `TSX title=Button.tsx` -> `typescriptreact`
- `Dockerfile` -> `dockerfile`

Normalization uses `infoStringToFiletype()`. You can extend or override mappings at runtime:

```typescript
import { extensionToFiletype, basenameToFiletype } from "@opentui/core"

extensionToFiletype.set("templ", "html")
basenameToFiletype.set("mytoolrc", "yaml")
```

## Concealment

Hide markdown markers (backticks, emphasis markers, etc.) when `conceal` is true:

```typescript
const markdown = new MarkdownRenderable(renderer, {
  content: "**bold** and `code`",
  syntaxStyle,
  conceal: true,
})
```

Use `concealCode` to control concealment inside fenced code blocks independently (`false` by default).

## Streaming updates

Enable streaming mode for incremental updates. Keep it `true` while appending chunks, then set `markdown.streaming = false` when complete to finalize trailing block parsing. Tables include trailing partial rows, with missing cells rendered empty.

```typescript
const markdown = new MarkdownRenderable(renderer, {
  content: "",
  syntaxStyle,
  streaming: true,
})

markdown.content += "# Live log\n"
markdown.content += "- line 1\n"
markdown.streaming = false
```

### Stable block prefix

`parseMarkdownIncremental` reports how many parsed tokens at the head of the stream are stable — that is, unlikely to change if you append more content. The renderable surfaces this as a count of **top-level render blocks** you can safely commit elsewhere while the unstable tail keeps updating.

To use it, render with `internalBlockMode: "top-level"`. The renderable keeps each top-level markdown block (heading, paragraph, list, table, fenced code) as its own child renderable, and exposes `markdown._stableBlockCount` — the number of blocks at the head of the tree that are stable right now. This matches the shape [`ScrollbackSurface`](/docs/core-concepts/renderer#writing-to-scrollback) expects when you commit streamed output row-by-row.

```typescript
import { MarkdownRenderable, RGBA, SyntaxStyle } from "@opentui/core"

const syntaxStyle = SyntaxStyle.fromStyles({
  default: { fg: RGBA.fromHex("#E6EDF3") },
})

const md = new MarkdownRenderable(renderer, {
  content: "",
  syntaxStyle,
  streaming: true,
  internalBlockMode: "top-level",
})

md.content = "# Title\n\nPara 1"
// md._stableBlockCount might be 1 here — "# Title" is settled, "Para 1" could still grow

md.content = "# Title\n\nPara 1\n\nPara 2"
// md._stableBlockCount rises as earlier blocks are sealed by a blank line
```

`internalBlockMode` is an experimental, opt-in flag that powers the built-in scrollback streaming demo. For non-streaming rendering, leave it at the default (`"coalesced"`), which folds sibling blocks together and matches the historical layout.

## Markdown tables

Markdown tables support `tableOptions` for style, sizing, wrapping, borders, and selection.

```typescript
const markdown = new MarkdownRenderable(renderer, {
  content: "| Service | Status |\n| --- | --- |\n| api | ok |",
  syntaxStyle,
  tableOptions: {
    style: "grid",
    widthMode: "full",
    columnFitter: "balanced",
    wrapMode: "word",
    cellPadding: 1,
    borders: true,
    outerBorder: true,
    borderStyle: "rounded",
    borderColor: "#6b7280",
    selectable: true,
  },
})
```

### `tableOptions`

| Option         | Type                           | Default                 | Description                                       |
| -------------- | ------------------------------ | ----------------------- | ------------------------------------------------- |
| `style`        | `"grid" \| "columns"`          | depends on block mode   | Visual preset (see [Table styles](#table-styles)) |
| `widthMode`    | `"content" \| "full"`          | depends on style        | `"full"` expands columns to fill available width  |
| `columnFitter` | `"proportional" \| "balanced"` | `"proportional"`        | How columns shrink when space is constrained      |
| `wrapMode`     | `"none" \| "char" \| "word"`   | `"word"`                | Wrapping mode inside each table cell              |
| `cellPadding`  | `number`                       | `0`                     | Padding on all sides of each cell                 |
| `borders`      | `boolean`                      | depends on style        | Enable inner and outer borders                    |
| `outerBorder`  | `boolean`                      | `borders`               | Override outer border visibility                  |
| `borderStyle`  | `BorderStyle`                  | `"single"`              | Table border character set                        |
| `borderColor`  | `ColorInput`                   | conceal fg or `#888888` | Border color for markdown tables                  |
| `selectable`   | `boolean`                      | `true`                  | Enable table cell text selection                  |

### Table styles

`tableOptions.style` picks a preset that tunes the defaults for `borders`, `outerBorder`, and `widthMode` together:

- **`"grid"`**: boxed table with visible borders. Defaults to `borders: true`, `widthMode: "full"`. This is the normal markdown-in-a-box rendering.
- **`"columns"`**: borderless columns with a 2-column gap, defaults to `widthMode: "content"`. Useful for append-only output where a full-width grid feels heavy.

If you do not pass `style`, it defaults to `"columns"` when `internalBlockMode` is `"top-level"`, and `"grid"` otherwise. You can still override individual fields (for example, `borders: true`) to pull toward a different look.

## Custom node rendering

Override rendering for a token and fall back to default rendering:

```typescript
const markdown = new MarkdownRenderable(renderer, {
  content: "# Title\n\nHello",
  syntaxStyle,
  renderNode: (token, context) => {
    if (token.type === "heading") {
      return context.defaultRender()
    }
    return undefined
  },
})
```

### Custom fenced-code languages

Use `createMarkdownCodeBlockRenderer` when you only want to replace specific fenced-code languages. The language key is matched against the normalized fence info string, so a `tsx` fence maps to `typescriptreact`, and custom DSL names like `taskflow` can be matched directly.

````typescript
import {
  BoxRenderable,
  MarkdownRenderable,
  SyntaxStyle,
  TextRenderable,
  createMarkdownCodeBlockRenderer,
  type CliRenderer,
  type MarkdownCodeBlockRenderer,
} from "@opentui/core"

const syntaxStyle = SyntaxStyle.fromStyles({ default: {} })

const renderTaskFlow =
  (renderer: CliRenderer): MarkdownCodeBlockRenderer =>
  (token) => {
    const steps = token.text
      .split("\n")
      .filter((line) => line.startsWith("step "))
      .map((line) => line.slice("step ".length))

    const card = new BoxRenderable(renderer, {
      border: true,
      borderStyle: "rounded",
      borderColor: "#38BDF8",
      paddingX: 1,
      flexDirection: "column",
      width: "100%",
    })

    for (const step of steps) {
      card.add(new TextRenderable(renderer, { content: `- ${step}`, width: "100%" }))
    }

    return card
  }

const markdown = new MarkdownRenderable(renderer, {
  content: "```taskflow\nstep Parse markdown done\nstep Render widget active\n```",
  syntaxStyle,
  renderNode: createMarkdownCodeBlockRenderer({
    taskflow: renderTaskFlow(renderer),
  }),
})
````

## Construct API

> Not available yet. Use `MarkdownRenderable` for now.

## Properties

| Property            | Type                                                                            | Default       | Description                                                   |
| ------------------- | ------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------- |
| `content`           | `string`                                                                        | `""`          | Markdown source                                               |
| `syntaxStyle`       | `SyntaxStyle`                                                                   | required      | Style definitions for tokens                                  |
| `fg`                | `ColorInput`                                                                    | -             | Base foreground color (flows into inner code blocks)          |
| `bg`                | `ColorInput`                                                                    | -             | Base background color (flows into inner code blocks)          |
| `conceal`           | `boolean`                                                                       | `true`        | Hide markdown markers in markdown text                        |
| `concealCode`       | `boolean`                                                                       | `false`       | Hide markers inside fenced code blocks                        |
| `streaming`         | `boolean`                                                                       | `false`       | Incremental mode; set `false` to finalize                     |
| `tableOptions`      | `MarkdownTableOptions`                                                          | -             | Options for markdown table rendering                          |
| `internalBlockMode` | `"coalesced" \| "top-level"`                                                    | `"coalesced"` | Experimental: expose top-level blocks as separate renderables |
| `treeSitterClient`  | `TreeSitterClient`                                                              | -             | Custom Tree-sitter client for code blocks                     |
| `renderNode`        | `(token: Token, context: RenderNodeContext) => Renderable \| null \| undefined` | -             | Custom render hook per markdown block                         |
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall