Render HTML and Markdown to Terminal
npm install cli-html!Version



!Downloads
> Renderer HTML and Markdown in the Terminal.
> Supports pretty tables, syntax highlighting, and GitHub Flavored Markdown
``sh`
npm i -g cli-html
`shRender a full HTML document
html examples/html/full/demo.html
This will produce the following:
$3
Render Markdown files with full GitHub Flavored Markdown support:
`sh
Render GFM alerts
markdown examples/markdown/features/alerts.mdRender full GFM document
md examples/markdown/full/gfm-features.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 LanguageUsage as module
`sh
npm i cli-html
`$3
For practical, runnable examples of using
cli-html and cli-markdown as libraries, check out the examples/library-usage directory:- html-basic.js - Basic HTML rendering (headings, lists, tables, code blocks)
- markdown-basic.js - GitHub Flavored Markdown features (alerts, task lists, tables)
- custom-theme.js - Custom theming examples (dark, light, vibrant themes)
- dynamic-content.js - Generating content from data (reports, dashboards, changelogs)
- file-reader.js - Reading and rendering files from disk
Run any example:
`bash
node examples/library-usage/.js
`See the Library Examples README for detailed documentation.
$3
####
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)Returns:
string - Formatted terminal outputExample:
`js
import { renderHTML } from 'cli-html';const html =
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",
code: { inline: "bgBlack yellow" }
};
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)Returns:
string - Formatted terminal outputExample:
`js
import { renderMarkdown } from 'cli-html';const markdown =
> [!NOTE]
> This is a note with bold text
- [x] Task 1
- [ ] Task 2
\\\javascriptHello, \${name}!\
function greet(name) {
return \;\
}
\\;
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));
#### Default Export: cliHtml(html, theme?)
Alias for renderHTML(). Use this for backward compatibility or shorter imports.
`js
import cliHtml from 'cli-html';
const html = '
$3
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 =
- ${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\nBold and italic';
console.log(renderMarkdown(markdown));
`Inline Style Customization
You can customize individual elements using
data-cli-* attributes without modifying the global theme.$3
`html
Magenta Bold Header
Cyan Underlined Italic Header
Triangle Marker
Triple Dot Marker
data-cli-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
`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-marker: Custom marker symbol
- For headers/blockquotes: e.g., "►", "▌ ", "•••"
- For ul: custom bullet marker, e.g., "★", "►", "•"
- data-cli-marker-color: Marker color (for 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 + colorAvailable 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, strikethroughExamples:
- 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, marker):
h1, h2, h3, h4, h5, h6
- Block (color, marker): blockquote
- Lists (color for text, marker-color, marker, decimal): ol, ul
- Inline (color): span, strong, b, em, i, u, del, ins, mark, code, kbd, samp, var, cite, timeSee examples/html/tags-custom/ for complete examples with
data-cli-* attributes.📚 Documentation
Comprehensive documentation is available in the
examples/ directory:- Examples Overview - Main documentation hub
- HTML Examples - Complete HTML rendering guide with examples
- Markdown Examples - Markdown rendering guide
- Customization Guide - Complete reference for all
data-cli-* attributes
- Theme Configuration - Guide to customizing the default theme via config.yaml
- Library Usage - Programmatic API examples and patternsCustomizing Styles
$3
config.yaml in this repository. CLI loads them, then applies your overrides from config.yaml in the config directory.Important: Different commands use different configuration directories.
For
html command:
- Linux: ~/.config/cli-html/config.yaml
- macOS: ~/Library/Preferences/cli-html/config.yaml
- Windows: %LOCALAPPDATA%\cli-html\Config\config.yamlFor
markdown and md commands:
- Linux: ~/.config/cli-markdown/config.yaml
- macOS: ~/Library/Preferences/cli-markdown/config.yaml
- Windows: %LOCALAPPDATA%\cli-markdown\Config\config.yamlTo see the exact path for each command, run:
`sh
For html command
node -e "import('env-paths').then(({ default: envPaths }) => console.log(envPaths('cli-html', { suffix: '' }).config))"For markdown/md commands
node -e "import('env-paths').then(({ default: envPaths }) => console.log(envPaths('cli-markdown', { suffix: '' }).config))"
`1. Create the config directory if it does not exist:
For
html command:
- Linux: mkdir -p ~/.config/cli-html
- macOS: mkdir -p ~/Library/Preferences/cli-html
- Windows: Create %LOCALAPPDATA%\cli-html\Config directory For
markdown/md commands:
- Linux: mkdir -p ~/.config/cli-markdown
- macOS: mkdir -p ~/Library/Preferences/cli-markdown
- Windows: Create %LOCALAPPDATA%\cli-markdown\Config directory
2. Add a config.yaml file with styles written as chalk-string values (colors/modifiers separated by spaces). For objects, only color is passed to chalk-string; other keys are used as extra config for components. Available style keys:
h1–h6, span, a, figure.border.color, figure.border.style, figcaption, fieldset.border.color, fieldset.border.style, fieldset.title.color, details.border.color, details.border.style, blockquote, address, code.color, code.inline, code.numbers, table.header, table.caption, table.cell, dt, dd, dl, del, ins, strikethrough, underline, bold, samp, kbd, variableTag (for ), mark, time, italic, i, em, cite, abbr.color, abbr.title.color, abbr.title.prefix.marker, abbr.title.prefix.color, abbr.title.suffix.marker, abbr.title.suffix.color, dfn, ol.color, ol.markers, ul.color, ul.markers, hr, progress.filled, progress.empty. Extra config:
-
figure.border supports color and style (e.g., 'single', 'double', 'round', 'bold') for configuring the border around figure elements.
- fieldset.border supports color and style, and fieldset.title.color configures the legend text color.
- details.border supports color and style for configuring the summary/details box border.
- ol.markers (array) defines the numbering styles that rotate for nested ordered lists. Valid values: '1' (decimal), 'A' (uppercase letters), 'a' (lowercase letters), 'I' (uppercase Roman), 'i' (lowercase Roman). Default: ['1', 'I', 'A', 'i', 'a']. HTML type attribute on tag overrides this setting.
- ul.markers (array or object) controls markers for UL depth 1–3 (disc, square, circle). Example: markers: ["+", "-", ">"] or markers: { disc: "+", square: "-", circle: ">" }.
- code can be configured as a string (applies to color) or an object with color, inline, and numbers properties. Supports fallback: code.color ← code, code.inline ← inlineCode (legacy), code.numbers ← codeNumbers (legacy).
- table can be configured as nested object with header, caption, and cell properties. Supports fallback from legacy tableHeader, tableCaption, tableCell.
- abbr can be configured as a string (applies to color) or an object with color, title (with color, prefix.marker/color, suffix.marker/color). Supports fallback from legacy abbr, abbrTitle, abbrParens.
- progress supports flexible fallback configuration:
- For filled: checks progress.filled.color → progress.filled (if string) → progress.color → progress (if string) → base theme
- For empty: checks progress.empty.color → progress.empty (if string) → base theme
- Both support symbol property to customize the progress bar character (default: █)
- Legacy: config.yml or theme.yml will also be read if present.Example config file (paths vary by OS and command, see above):
`yml
theme:
h1: "magenta bold"
a: "cyan underline"
figure:
border:
color: "blue"
style: "double"
fieldset:
border:
color: "cyan"
style: "bold"
title:
color: "magenta"
details:
border:
color: "green"
style: "round"
blockquote: "gray"
code:
color: "yellowBright"
inline: "bgBlack yellow"
numbers: "blackBright dim"
table:
header: "red bold"
caption: "bold blue"
cell: ""
variableTag: "blue italic"
mark: "bgYellow black"
abbr:
color: "underline"
title: "cyan"
parens: "gray"
ol:
color: "" # Text color for list items (empty = no color)
markers: # Marker configuration by type
"1":
color: "blueBright" # Marker color
marker: "1" # Marker type
decimal: "." # Decimal separator
I:
color: "cyanBright"
marker: "I"
decimal: "."
A:
color: "magentaBright"
marker: "A"
decimal: "."
i:
color: "blueBright"
marker: "i"
decimal: "."
a:
color: "cyanBright"
marker: "a"
decimal: "."
indent: " " # Indentation for nested items
ul:
color: "" # Text color for list items (empty = no color)
markers: # Marker configuration by type
disc:
color: "redBright" # Marker color
marker: "•" # Marker symbol
square:
color: "yellowBright"
marker: "▪"
circle:
color: "cyanBright"
marker: "⚬"
indent: " " # Indentation for nested items
hr: "gray"
progress:
filled:
color: "bgGreen white"
symbol: "█"
empty:
color: "bgBlack gray"
symbol: "█"
`You can also use shorter forms for
progress:`yml
Simple string (applies to filled only)
progress: "green"Object with shared color for filled
progress:
color: "blue"
filled: "green" # String override
empty:
color: "gray"
symbol: "░"
`3. Run the appropriate command — the custom styles will be applied automatically:
-
html your-file.html loads config from the cli-html directory
- markdown your-file.md or md your-file.md loads config from the cli-markdown directory$3
When using
cli-html as a library, you can pass a custom theme object as the second parameter to both cliHtml() and renderMarkdown():`js
import cliHtml, { renderMarkdown } from 'cli-html';const customTheme = {
h1: "magenta bold",
h2: "cyan bold",
a: "blue underline",
blockquote: "gray italic",
code: {
color: "yellowBright",
inline: "bgBlack yellow",
numbers: "dim"
},
table: {
header: "red bold",
caption: "bold blue",
cell: ""
},
ul: {
color: "", // Text color for list items
markers: {
disc: { color: "green", marker: "•" },
square: { color: "yellow", marker: "▪" },
circle: { color: "cyan", marker: "⚬" }
},
indent: " "
},
ol: {
color: "", // Text color for list items
markers: {
"1": { color: "blueBright", marker: "1", decimal: "." },
I: { color: "cyanBright", marker: "I", decimal: "." },
A: { color: "magentaBright", marker: "A", decimal: "." },
i: { color: "blueBright", marker: "i", decimal: "." },
a: { color: "cyanBright", marker: "a", decimal: "." }
},
indent: " "
},
progress: {
filled: {
color: "bgGreen white",
symbol: "█"
},
empty: {
color: "bgBlack gray",
symbol: "░"
}
}
};
// HTML rendering with custom theme
const html = '
Hello
This is inline code
';
console.log(cliHtml(html, customTheme));// Markdown rendering with custom theme
const markdown = '# Hello\n\nThis is
inline code';
console.log(renderMarkdown(markdown, customTheme));
`The theme object uses the same structure and keys as the CLI
config.yaml file. Values should be chalk-string compatible strings (e.g., "red bold", "bgBlue white underline").Available theme keys:
- Headings:
h1, h2, h3, h4, h5, h6
- Text styles: bold, italic, i, em, underline, strikethrough, del, ins, mark, cite, samp, kbd, variableTag, abbr, dfn, time
- Links: a, span
- Block elements: blockquote, address, hr
- Code: code (string or object with color, inline, numbers)
- Lists: ul (with color for text, markers array with marker.color and marker.marker, indent), ol (with color for text, markers array with marker.color, marker.marker, and marker.decimal, indent), dl, dt, dd
- Tables: table (object with header, caption, cell)
- Borders: figure (with border.color, border.style), fieldset (with border.color, border.style, title.color), details (with border.color, border.style)
- Progress bars: progress (object with filled and empty, each having color and symbol)If you don't provide a theme object, the default theme from
config.yaml will be used.Syntax Highlighting
Code blocks support automatic syntax highlighting using 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.Run tests
`sh
npm run test
``Author
👤Grigorii Horos
* Github: @grigorii-horos
Contributing
Contributions, issues and feature requests are welcome!
Feel free to check issues page.
Show your support
Give a ⭐️ if this project helped you!
License
Copyright © 2019 Grigorii Horos.
This project is GPL-3.0-or-later licensed.