# Welcome to cli-html
[](https://www.npmjs.com/package/cli-html)
[](https://www.npmjs.com/package/cli-html)
[](https://nodejs.org)
[](https://github.com/grigorii-horos/cli-html#readme)
[](https://github.com/grigorii-horos/cli-html/graphs/commit-activity)
[](https://github.com/grigorii-horos/cli-html/blob/master/LICENSE)
> Renderer HTML and Markdown in the Terminal.
> Supports pretty tables, syntax highlighting, and GitHub Flavored Markdown
## Features
- 🎨 **Full HTML rendering** — headings, lists, tables, forms, figures, and 80+ tags
- 📝 **GitHub Flavored Markdown** — alerts, task lists, tables, footnotes, strikethrough, and more
- ⚛️ **JSX / React** — render React elements straight to the terminal
- 🌈 **Syntax highlighting** — automatic, for dozens of languages
- 📐 **Pretty tables** — borders, alignment, zebra striping, responsive narrow-terminal mode
- 🎭 **Deep theming** — every element themeable via `config.yaml`, a theme object, or per-element `data-cli-*` attributes
- 🔌 **CLI + library** — use the `html` / `markdown` / `md` / `jsx` commands, or import `renderHTML` / `renderMarkdown` / `renderJSX`
- ⌨️ **Reads stdin** — pipe HTML or Markdown straight in (`echo '
hi
' | html`)
Table of Contents
- [Install](#install)
- [Example](#example)
- [HTML Rendering](#html-rendering)
- [Markdown Rendering](#markdown-rendering)
- [JSX Rendering](#jsx-rendering)
- [Usage as module](#usage-as-module)
- [Library Examples](#library-examples)
- [API Reference](#api-reference)
- [Common Use Cases](#common-use-cases)
- [Inline Style Customization](#inline-style-customization)
- [Documentation](#-documentation)
- [Customizing Styles](#customizing-styles)
- [Syntax Highlighting](#syntax-highlighting)
- [Author](#author)
- [Contributing](#contributing)
- [License](#license)
## Install
Requires **Node.js >= 18**.
```sh
npm i -g cli-html
```
## Example
### HTML Rendering
```sh
# Render a full HTML document
html examples/html/full/demo.html
# Render individual tag examples
html examples/html/tags/table.html
# Pipe HTML from stdin
echo 'Hello
from stdin
' | html
curl -s https://example.com | html
```
This will produce the following:

### Markdown Rendering
Render Markdown files with full GitHub Flavored Markdown support:
```sh
# Render GFM alerts
markdown examples/markdown/features/alerts.md
# Render full GFM document
md examples/markdown/full/gfm-features.md
# Pipe Markdown from stdin
echo '# Title\n\n> [!NOTE]\n> Piped markdown' | md
cat CHANGELOG.md | md
```
**Supported GFM Features:**
- ✓ **Alerts** - `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, `[!CAUTION]` with colors
- ✓ **Task Lists** - `- [x]` and `- [ ]` with checkboxes
- ✓ **Tables** - Full table support with borders
- ✓ **Strikethrough** - `~~text~~`
- ✓ **Autolinks** - Automatic URL linking
- ✓ **Footnotes** - `[^1]` references
- ✓ **Definition Lists** - Term and definition pairs
- ✓ **Subscript/Superscript** - `H~2~O` and `x^2^`
- ✓ **Insert/Mark** - `++inserted++` and `==marked==` text
- ✓ **Abbreviations** - `*[HTML]: Hyper Text Markup Language`
### JSX Rendering
Render React/JSX files straight to the terminal. JSX is transpiled, rendered to
HTML via `react-dom`, then drawn by the same renderer used for HTML and Markdown:
```sh
# Render a JSX file
jsx examples/jsx/full/demo.jsx
# With a custom theme config
jsx examples/jsx/full/demo.jsx --config ./theme.yaml
```
The file's `default` export may be a React element (`export default `) or a
component (`export default App`). Neighbouring modules resolve relative to the
file.
JSX support uses optional peer dependencies that are not installed with `cli-html`
by default. Install them next to it to use the `jsx` command:
```sh
npm install -g cli-html @babel/core @babel/preset-env @babel/preset-react react react-dom
```
More examples (components, data-driven tables, dashboards, boxed layouts) live in
[examples/jsx](examples/jsx).
## Usage as module
```sh
npm i cli-html
```
### Library Examples
For practical, runnable examples of using `cli-html` and `cli-markdown` as libraries, check out the [examples/library-usage](examples/library-usage) directory:
- **[html-basic.js](examples/library-usage/html-basic.js)** - Basic HTML rendering (headings, lists, tables, code blocks)
- **[markdown-basic.js](examples/library-usage/markdown-basic.js)** - GitHub Flavored Markdown features (alerts, task lists, tables)
- **[custom-theme.js](examples/library-usage/custom-theme.js)** - Custom theming examples (dark, light, vibrant themes)
- **[dynamic-content.js](examples/library-usage/dynamic-content.js)** - Generating content from data (reports, dashboards, changelogs)
- **[file-reader.js](examples/library-usage/file-reader.js)** - Reading and rendering files from disk
- **[jsx-basic.js](examples/library-usage/jsx-basic.js)** - Rendering React/JSX with `renderJSX`
Run any example:
```bash
node examples/library-usage/.js
```
See the [Library Examples README](examples/library-usage/README.md) for detailed documentation.
### API Reference
#### `renderHTML(html, theme?)`
Renders HTML content to formatted terminal output.
**Parameters:**
- `html` (string) - HTML content to render
- `theme` (object, optional) - Custom theme configuration (see [Customizing Styles](#customizing-styles))
**Returns:** `string` - Formatted terminal output
**Example:**
```js
import { renderHTML } from 'cli-html';
const html = `
Hello World
This is a bold paragraph with code.
`;
console.log(renderHTML(html));
```
**With custom theme:**
```js
import { renderHTML } from 'cli-html';
const customTheme = {
h1: "magenta bold", // shorthand for h1: { color: "magenta bold" }
code: { color: "bgBlack yellow" } // inline code
};
const html = 'Styled Title
';
console.log(renderHTML(html, customTheme));
```
#### `renderMarkdown(markdown, theme?)`
Renders Markdown content to formatted terminal output with full GitHub Flavored Markdown support.
**Parameters:**
- `markdown` (string) - Markdown content to render
- `theme` (object, optional) - Custom theme configuration (see [Customizing Styles](#customizing-styles))
**Returns:** `string` - Formatted terminal output
**Example:**
```js
import { renderMarkdown } from 'cli-html';
const markdown = `
# Hello World
> [!NOTE]
> This is a note with **bold** text
- [x] Task 1
- [ ] Task 2
## Code Example
\`\`\`javascript
function greet(name) {
return \`Hello, \${name}!\`;
}
\`\`\`
`;
console.log(renderMarkdown(markdown));
```
**With custom theme:**
```js
import { renderMarkdown } from 'cli-html';
const customTheme = {
h1: "cyan bold",
h2: "blue bold",
code: {
color: "yellowBright",
inline: "bgBlack yellow"
}
};
const markdown = '# Title\n\nParagraph with `code`.';
console.log(renderMarkdown(markdown, customTheme));
```
#### `renderJSX(jsx, theme?)`
Renders a React/JSX element or component to formatted terminal output.
`react` and `react-dom` are optional peer dependencies (`npm install react react-dom`),
loaded lazily, so plain HTML/Markdown rendering never needs them.
**Parameters:**
- `jsx` (React element | component) - e.g. `` or `App`
- `theme` (object, optional) - Custom theme configuration (see [Customizing Styles](#customizing-styles))
**Returns:** `Promise` - Formatted terminal output (async)
**Example:**
```jsx
import { renderJSX } from 'cli-html';
const App = () => (
<>
Hello from JSX
Rendered with cli-html
>
);
console.log(await renderJSX());
```
#### Default Export: `cliHtml(html, theme?)`
Alias for `renderHTML()`. Use this for backward compatibility or shorter imports.
```js
import cliHtml from 'cli-html';
const html = 'Hello World
';
console.log(cliHtml(html));
```
### Common Use Cases
**Reading HTML from file:**
```js
import { renderHTML } from 'cli-html';
import { readFileSync } from 'fs';
const html = readFileSync('document.html', 'utf8');
console.log(renderHTML(html));
```
**Reading Markdown from file:**
```js
import { renderMarkdown } from 'cli-html';
import { readFileSync } from 'fs';
const markdown = readFileSync('README.md', 'utf8');
console.log(renderMarkdown(markdown));
```
**Rendering dynamic content:**
```js
import { renderHTML } from 'cli-html';
const data = {
title: 'User Report',
items: ['Item 1', 'Item 2', 'Item 3']
};
const html = `
${data.title}
${data.items.map(item => `- ${item}
`).join('\n')}
`;
console.log(renderHTML(html));
```
**Converting Markdown to HTML then to Terminal:**
```js
import { renderMarkdown } from 'cli-html';
// renderMarkdown handles the conversion internally
const markdown = '# Title\n\n**Bold** and *italic*';
console.log(renderMarkdown(markdown));
```
## Inline Style Customization
You can customize individual elements using `data-cli-*` attributes without modifying the global theme.
### Using data-cli-* Attributes
```html
Magenta Bold Header
Cyan Underlined Italic Header
Triangle Marker
Triple Dot Marker
Warning Header
White bold on red
- Item with green text and red bold marker with ) separator
- Another item
- Item with yellow text and cyan star marker
- Another item
Centered paragraph
```
**Available Attributes:**
- **`data-cli-color`**: Full chalk-string specification (color + styles), e.g., `"red bold italic"`, `"bgBlue white"`
- For `ol`/`ul`: applies to list item text
- **`data-cli-indicator-marker`**: Custom marker symbol
- For headers/blockquotes: e.g., `"►"`, `"▌ "`, `"•••"`
- For `ul`: custom bullet marker, e.g., `"★"`, `"►"`, `"•"`
- **`data-cli-indicator-color`**: Marker color (headers, blockquotes, `ol`/`ul`), e.g., `"red bold"`, `"cyan"`
- **`data-cli-decimal`**: Decimal separator for `ol`, e.g., `")"`, `":"`, `"-"`
- **`data-cli-title-*`** (abbr/dfn):
- `data-cli-title-color`: Title color
- `data-cli-title-prefix-marker` / `data-cli-title-prefix-color`: Opening marker + color
- `data-cli-title-suffix-marker` / `data-cli-title-suffix-color`: Closing marker + color
**Available Colors:**
- Basic: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `gray`
- Bright: `redBright`, `greenBright`, `yellowBright`, `blueBright`, `magentaBright`, `cyanBright`, `whiteBright`
- Background: `bgRed`, `bgGreen`, `bgBlue`, `bgYellow`, `bgMagenta`, `bgCyan`, `bgWhite`, etc.
**Available Styles:**
- `bold`, `italic`, `underline`, `dim`, `inverse`, `strikethrough`
**Examples:**
- Color only: `data-cli-color="red"`
- Color + style: `data-cli-color="blue bold"`
- Multiple styles: `data-cli-color="green bold italic underline"`
- Background: `data-cli-color="bgYellow black"`
- Background + styles: `data-cli-color="bgMagenta white bold"`
**Supported Tags:**
- Headers (color, indicator-marker, indicator-color): `h1`, `h2`, `h3`, `h4`, `h5`, `h6`
- Block (color, indicator-marker, indicator-color): `blockquote`
- Lists (color for text, indicator-color, indicator-marker, decimal): `ol`, `ul`
- Inline (color): `span`, `strong`, `b`, `em`, `i`, `u`, `del`, `ins`, `mark`, `code`, `kbd`, `samp`, `var`, `cite`, `time`
See [examples/html/tags/](examples/html/tags/) for complete examples with `data-cli-*` attributes.
## 📚 Documentation
Comprehensive documentation is available in the `examples/` directory:
- **[Examples Overview](examples/README.md)** - Main documentation hub
- **[HTML Examples](examples/html/README.md)** - Complete HTML rendering guide with examples
- **[Markdown Examples](examples/markdown/README.md)** - Markdown rendering guide
- **[Data Attributes](DATA_ATTRIBUTES.md)** - Complete reference for all `data-cli-*` attributes
- **[Theme Configuration](examples/THEMES.md)** - Guide to customizing the default theme via `config.yaml`
- **[Library Usage](examples/library-usage/README.md)** - Programmatic API examples and patterns
## Customizing Styles
Every element's default style lives in [`config.yaml`](config.yaml) — the single source of truth. Override it three ways, in increasing precedence:
1. **Globally** — a `config.yaml` in the config directory, or an explicit file via [`--config`](#--config-path) (CLI)
2. **Per render** — a theme object passed to `renderHTML()` / `renderMarkdown()` / `renderJSX()` (library)
3. **Per element** — `data-cli-*` attributes on individual tags (see [Inline Style Customization](#inline-style-customization))
Full reference:
- **[Theme Configuration](examples/THEMES.md)** — every theme key with examples
- **[Data Attributes](DATA_ATTRIBUTES.md)** — every `data-cli-*` attribute
### For CLI Usage
Each command loads [`config.yaml`](config.yaml) defaults, then merges your overrides from a per-command config directory:
| Command | Linux | macOS | Windows |
|---------|-------|-------|---------|
| `html` | `~/.config/cli-html/config.yaml` | `~/Library/Preferences/cli-html/config.yaml` | `%LOCALAPPDATA%\cli-html\Config\config.yaml` |
| `markdown` / `md` | `~/.config/cli-markdown/config.yaml` | `~/Library/Preferences/cli-markdown/config.yaml` | `%LOCALAPPDATA%\cli-markdown\Config\config.yaml` |
Print the exact path for a command:
```sh
# html
node -e "import('env-paths').then(({default:e})=>console.log(e('cli-html',{suffix:''}).config))"
# markdown / md
node -e "import('env-paths').then(({default:e})=>console.log(e('cli-markdown',{suffix:''}).config))"
```
#### `--config `
To load a specific config file instead of the one in the config directory, pass `--config`. Supported by every command (`html`, `markdown`, `md`, `jsx`) and works with stdin too:
```sh
html demo.html --config ./theme.yaml
md README.md --config ./theme.yaml
jsx demo.jsx --config ./theme.yaml
# with stdin
cat page.html | html --config ./theme.yaml
```
#### `--width `
Wrap output at `n` columns instead of the terminal width (overrides `lineWidth` from the config):
```sh
md README.md --width 80
cat page.html | html --width 60
```
#### `--help`
Show usage information and available options for the command.
```sh
html --help
```
Without a file argument (or with `-`), every command reads from stdin.
#### Per-document settings
An HTML document can override the line width and ASCII mode for itself:
```html
```
Values are [chalk-string](https://www.npmjs.com/package/chalk-string) compatible (`"red bold"`, `"bgBlue white underline"`). Example `config.yaml`:
```yml
theme:
h1: "magenta bold"
a: "cyan underline"
blockquote: "gray italic"
code:
color: "yellowBright bgBlack" # inline code
block:
numbers:
color: "blackBright dim" # line numbers in code blocks
th: "red bold" # table header cells
td: "" # table data cells
caption: "blue bold" # table caption
var: "blue italic"
mark: "bgYellow black"
hr: "gray"
progress:
filled: { color: "bgWhite cyan", marker: "█" }
empty: { color: "bgBlack gray", marker: "░" }
```
See [THEMES.md](examples/THEMES.md) for the complete key list (headings, lists, borders, forms, and more).
### For Library Usage
Pass a theme object as the second argument to any renderer. It uses the same keys as `config.yaml`:
```js
import { renderHTML, renderMarkdown } from 'cli-html';
const theme = {
h1: "magenta bold",
a: "blue underline",
blockquote: "gray italic",
code: { color: "yellowBright bgBlack" },
th: "red bold",
td: "",
caption: "blue bold",
ul: {
indicators: {
disc: { color: "green", marker: "•" },
square: { color: "yellow", marker: "▪" },
circle: { color: "cyan", marker: "◦" },
},
},
progress: {
filled: { color: "bgWhite cyan", marker: "█" },
empty: { color: "bgBlack gray", marker: "░" },
},
};
console.log(renderHTML('Hello
This is inline code
', theme));
console.log(renderMarkdown('# Hello\n\nThis is `inline code`', theme));
```
Omit the theme argument to use the defaults from `config.yaml`. For the full set of keys, see [THEMES.md](examples/THEMES.md).
## Syntax Highlighting
Code blocks support automatic syntax highlighting using [cli-highlight](https://www.npmjs.com/package/cli-highlight). To enable syntax highlighting for a code block, add a `language-*` or `lang-*` class to the `` element:
```html
function hello() {
console.log("Hello, World!");
return true;
}
```
Supported languages include: `javascript`, `typescript`, `python`, `java`, `sql`, `bash`, `json`, `yaml`, `nginx`, `go`, `rust`, and many more.
**Example:**
```html
const user = await User.findById(id);
def hello():
print("Hello, World!")
SELECT * FROM users WHERE email = 'user@example.com';
npm install express
```
Code blocks without a language class will still be displayed but without syntax highlighting.
See the comprehensive examples in `examples/html/full/documentation.html`, `examples/html/full/blog.html`, and `examples/html/full/tutorial.html` for more syntax highlighting examples.
## Author
👤**Grigorii Horos**
* Github: [@grigorii-horos](https://github.com/grigorii-horos)
## Contributing
Contributions, issues and feature requests are welcome!
Feel free to check the [issues page](https://github.com/grigorii-horos/cli-html/issues). Run the test suite with:
```sh
npm test
```
## Show your support
Give a ⭐️ if this project helped you!
## License
Copyright © 2019–2026 [Grigorii Horos](https://github.com/grigorii-horos).
This project is [GPL-3.0-or-later](https://github.com/grigorii-horos/cli-html/blob/master/LICENSE) licensed.