@pawel-up/html.md

v0.2.0

Published

2 months ago

No-dependency, ESM, in browser HTML to markdown converter

0High
0Medium
0Low

jarrodek

markdown html

HTML.md 📝

No-dependency, ESM-based, in-browser HTML to Markdown converter.

A lightweight, zero-dependency library that takes an HTML string or a DOM Element and converts it into clean, well-formatted Markdown.

Perfect for modern web applications, rich text editors, and content migration tools. Designed to be highly readable for both developers and AI agents.

🚀 Key Features

📦 Zero Dependencies — Extremely lightweight and fast.
🌐 Native ESM — Built for modern JS bundles and browser environments.
🤖 Syntax Highlighting Detection — Infers programming languages from PrismJS/Highlight.js tags (e.g., class="language-js" or class="lang-typescript").
📊 Table Alignment Support — Parses column text alignments from inline CSS text-align styles.
☑️ Task Lists — Parses checkboxes (<input type="checkbox">) into markdown task lists (- [ ] and - [x]).
🧹 Robust Whitespace Processing — Avoids double-spacing issues and preserves correct multiline code indentation even when deeply nested inside container elements.
🔏 Clean Escaping — Smart line-start escaping prevents normal text symbols from accidentally breaking into markdown formatting.

💻 Environment Compatibility

[!IMPORTANT] This library is designed to work in browser environments only because it utilizes the browser's native DOMParser and DOM APIs. To use this in Node.js, you must shim/mock the global DOM environment using a library like jsdom.

🛠 Usage

Installation

npm install --save @pawel-up/html.md

Basic Example (HTML String)

import { HtmlMd } from '@pawel-up/html.md'

const parser = new HtmlMd()
const htmlInput = '<p>This is a <strong>strong</strong> text with <code>inline code</code>.</p>'

const markdown = parser.generate(htmlInput)
console.log(markdown)
// Output: This is a **strong** text with `inline code`.\n\n

DOM Element Example

You can pass a live browser DOM element. The outermost element is treated as a container wrapper and ignored; only its children are converted to markdown.

import { HtmlMd } from '@pawel-up/html.md'

const parser = new HtmlMd()
const containerElement = document.querySelector('#content-editor')

const markdown = parser.generate(containerElement)
console.log(markdown)

📋 Tag Conversion Map

⚙️ Configuration

The HtmlMd class constructor accepts an optional configuration object to customize the markdown output format and parsing rules.

import { HtmlMd } from '@pawel-up/html.md'
import type { HtmlMdOptions } from '@pawel-up/html.md'

const options: HtmlMdOptions = {
  flavor: 'gfm',
  keepHtml: false,
  rules: {
    'custom-badge': (node) => `[BADGE: ${node.textContent}]`,
  },
}

const parser = new HtmlMd(options)

Options API Reference

1. Markdown Flavors (`flavor`)

Configure the output flavor to target different markdown parsers/platforms:

GitHub Flavored Markdown (gfm): Supports full standard GFM features including tables, task lists, and strikethroughs (~~strikethrough~~).
CommonMark (commonmark): Strict standard CommonMark. Strikethroughs and task lists are disabled; tables are stripped/rendered as inline text content.
Slack mrkdwn (slack): Generates Slack-compatible syntax (e.g. bold as *text*, italic as _text_, strike as ~text~, headers as bold text, and lists starting with bullet points •).

2. HTML Fallback Mode (`keepHtml`)

Determines how tags that do not map to markdown (like <details>, <aside>, <iframe>) are processed:

false (default): Strips the HTML container tags but processes and outputs their text content and inline styles.
true: Retains the unhandled tags as raw HTML inside the generated markdown output.

3. Custom Rules (`rules`)

Allows defining custom transformer functions for specific HTML elements (by tag name in lowercase). If a custom rule matches, it completely overrides the default rendering behavior for that element and its children.

const parser = new HtmlMd({
  rules: {
    // Replace custom badges with a formatted text string
    'custom-badge': (node) => `[BADGE: ${node.textContent}]`,

    // Ignore specific tags (and their children) completely
    'tab-container': () => '',
  },
})

📖 API Reference

`class HtmlMd`

The main entry point for the library.

`constructor(options?: HtmlMdOptions)`

Initializes the parser instance with customizable config options.

`generate(input: string | Element): string`

Converts input HTML into a Markdown string.

Parameters:
- input: Either a raw HTML string or a DOM Element.
Returns: string - The formatted Markdown markup.
Throws:
- Error if the input is falsy or of an unsupported type.

🔧 Local Development

Clone & Install

git clone https://github.com/pawel-up/html.md.git
cd html.md
npm install

Launch Interactive Demo

Runs a local development server hosting the interactive testing UI:

npm start

Run Unit Tests

Runs the Lupa test runner across headless browsers:

npm test

Run Linters

npm run lint

📄 License

HTML.md by Pawel Uchida-Psztyc is licensed under the Creative Commons Attribution 4.0 International (CC BY 4.0) license.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme