<div align="center">

<h1>fetch-html-to-md</h1>

Convert remote or local HTML resources to Markdown via CLI or Node.js API.

[![NodeJS][node-image]][node-url]
[![Version][npm-version-image]][npm-version-url]
[![NPM][npm-image]][npm-url]
[![License][license-image]][license-url]

English | [简体中文][zh-cn-url]

![Preview in Terminal](https://github.com/user-attachments/assets/7f094c27-1c19-4428-afa8-1d6d0e7c61cd)

</div>

## 📖 Introduction

**fetch-html-to-md** is a lightweight, high-performance Node.js solution
designed to bridge the gap between web content and structured Markdown. Built
with flexibility in mind, it operates seamlessly both as a developer-friendly
SDK and as an intuitive command-line utility.

**Quick Start**
```bash
npx @kabeep/fetch-html-to-md@latest https://example.com
```

**MCP Server**

```bash
npx @kabeep/fetch-html-to-md@latest mcp
```

## 📦 Installation

**As Node.js API**

```bash
npm install @kabeep/fetch-html-to-md
```

**As CLI**

```bash
npm install --global @kabeep/fetch-html-to-md
```

## ⚙️ Usage

**ESModule**

```typescript
import fetchHtml2md, {
    html2md,
    type Html2MdOptions
} from '@kabeep/fetch-html-to-md';

// 1. Facade Function: Automatically converts local file path or remote URL
const markdown = await fetchHtml2md('https://example.com', {
    // ...Html2MdOptions
});

// 2. Built-in html-to-md
const rawMarkdown = html2md('<h1>Hello World</h1>');
```

**CommonJS**

```typescript
const fetchHtml2md = require('@kabeep/fetch-html-to-md');
const { html2md } = require('@kabeep/fetch-html-to-md');

async function main() {
    // 1. Facade Function
    const markdown = await fetchHtml2md('./index.html');
    console.log(markdown);

    // 2. Built-in html-to-md
    const rawMarkdown = html2md('<h1>Hello World</h1>');
}
```

**CLI**

Convert a local file

```bash
fetch-html-to-md ./docs/index.html
```

Convert a remote URL

```bash
fetch-html-to-md https://example.com
```

Pass a raw HTML string to convert

```bash
fetch-html-to-md --raw "<strong><em>strong and italic</em></strong>"
```

Read from stdin

```bash
echo https://example.com | fetch-html-to-md
```

Use Options

```bash
fetch-html-to-md ./index.html --skip-tags div section --alias-tags "figure=p"
```

## 🔩 CLI Options

**Input Options**

> *Note: Input flags are mutually exclusive. Only one input source can be provided per execution.*

| Option       | Short |   Type    | Description                                                        |
|:-------------|:-----:|:---------:|:-------------------------------------------------------------------|
| `[uri]`      |   -   | `string`  | Positional argument. Path to a local HTML file or a remote URL.    |
| `--url`      |   -   | `string`  | Specify an HTML page URL.                                          |
| `--filepath` | `-f`  | `string`  | Specify a local HTML file path.                                    |
| `--raw`      |   -   | `boolean` | Pass a raw HTML string directly instead of `[uri]` for conversion. |

**Configuration Options**

> See more: https://github.com/stonehank/html-to-md/blob/HEAD/README-EN.md#configoptional

| Option                 |   Type    |  Default   | Description                                                                                        |
|:-----------------------|:---------:|:----------:|:---------------------------------------------------------------------------------------------------|
| `--skip-tags`          |  `array`  | *(native)* | Tags to skip rendering while keeping their inner content intact. *(space-separated list)*          |
| `--empty-tags`         |  `array`  |    `[]`    | Tags to skip along with all content inside them.                                                   |
| `--ignore-tags`        |  `array`  | *(native)* | Tags to completely ignore (both tag and content).                                                  |
| `--alias-tags`         |  `array`  |     -      | Rename HTML tags using `key=value` pairs. <br>*(e.g., `--alias-tags figure=p dd=p`)*               |
| `--render-custom-tags` |  `enum`   |  `'true'`  | Rule for non-standard HTML tags. <br>Choices: `'true'`, `'false'`, `'SKIP'`, `'EMPTY'`, `'IGNORE'` |
| `--force`              | `boolean` |  `false`   | Force custom configurations to overwrite native defaults.                                          |

**General Options**

| Option      | Short | Description                            |
|:------------|:-----:|:---------------------------------------|
| `--help`    | `-h`  | Display help menu and command options. |
| `--version` | `-v`  | Display package version.               |

## 🔌 MCP Server

The `fetch-html-to-md` CLI natively supports the Model Context Protocol (MCP).
This enables AI clients such as **Claude Desktop**, **Cursor**, and **Windsurf**
to seamlessly invoke it as a background tool for web scraping and local HTML
conversion.

### 1. Client Setup

Add the following snippet to your client configuration file (e.g.,
`claude_desktop_config.json` or `.cursor/mcp.json`):

```json
{
    "mcpServers": {
        "fetch-html-to-md": {
            "command": "npx",
            "args": [
                "-y",
                "@kabeep/fetch-html-to-md",
                "mcp"
            ]
        }
    }
}
```

### 2. Tool Schema

The MCP server exposes a default tool named `fetch_html_to_md` with the
following parameters:

| Parameter |   Type   | Required | Description                                                          |
|:----------|:--------:|:--------:|:---------------------------------------------------------------------|
| `uri`     | `string` | **Yes**  | Target webpage URL (`http://` or `https://`) or local HTML file path |

---

### 💬 Example Prompt

Once configured, you can simply ask your AI assistant:

> "Fetch https://example.com using fetch_html_to_md and summarize the key takeaways."

## 💐 Credits

- [html-to-md][html-to-md-url] - A JS library for convert HTML\<String\> to
  markdown\<String\>, gzip 10kb.

## 🤝 Contribution

Contributions via Pull Requests or [Issues][issues-url] are welcome.

## 📄 License

This project is licensed under the MIT License. See the [LICENSE][license-url]
file for details.

[en-us-url]: README.md
[zh-cn-url]: README.zh-CN.md

[node-image]: https://img.shields.io/node/v/%40kabeep%2Ffetch-html-to-md?color=lightseagreen "Node.js Version"
[node-url]: https://nodejs.org

[npm-version-image]: https://img.shields.io/npm/v/%40kabeep%2Ffetch-html-to-md.svg "NPM version"
[npm-version-url]: https://www.npmjs.com/package/%40kabeep%2Ffetch-html-to-md

[npm-image]: https://img.shields.io/npm/d18m/%40kabeep%2Ffetch-html-to-md?color=cornflowerblue "NPM Downloads"
[npm-url]: https://www.npmjs.com/package/@kabeep/fetch-html-to-md

[html-to-md-url]: https://github.com/stonehank/html-to-md

[issues-url]: https://github.com/kabeep/fetch-html-to-md/issues

[license-image]: https://img.shields.io/github/license/kabeep/fetch-html-to-md?color=slateblue "License"
[license-url]: LICENSE