@aiquants/html-to-markdown 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (26) hide show
  1. package/README.md +123 -4
  2. package/dist/{core-CouDTni-.js → core-DJV8t_Qj.js} +8 -4
  3. package/dist/core-Dq4LfiYy.cjs +1 -0
  4. package/dist/index.cjs +1 -1
  5. package/dist/index.js +3 -3
  6. package/dist/main.cjs +1 -1
  7. package/dist/main.js +30 -13
  8. package/dist/mcp-server-CMBUHOmc.cjs +1 -0
  9. package/dist/{mcp-server-BAmy7d8r.js → mcp-server-DD8CqdNw.js} +59 -2
  10. package/dist/{mcp-server-streamable-CVDJHcWu.js → mcp-server-streamable-DODolSbj.js} +127 -3
  11. package/dist/{mcp-server-streamable-mF26pg3E.cjs → mcp-server-streamable-IQlimU2H.cjs} +1 -1
  12. package/dist/mcp-streamable.cjs +1 -1
  13. package/dist/mcp-streamable.js +1 -1
  14. package/dist/mcp.cjs +1 -1
  15. package/dist/mcp.js +1 -1
  16. package/dist/src/index.d.ts +1 -1
  17. package/dist/src/mcp-common.d.ts +57 -0
  18. package/dist/src/mcp-server-streamable.d.ts +15 -2
  19. package/dist/src/mcp-server.d.ts +79 -2
  20. package/dist/src/types.d.ts +6 -6
  21. package/dist/{version-Cg6D6H9g.cjs → version-BkgGdAYt.cjs} +1 -1
  22. package/dist/{version-BF9-U8Ef.js → version-CTdrYd1G.js} +81 -7
  23. package/mcp.json +2 -2
  24. package/package.json +1 -1
  25. package/dist/core-D2dlEt1l.cjs +0 -1
  26. package/dist/mcp-server-CCu0Pcm3.cjs +0 -1
package/README.md CHANGED
@@ -30,10 +30,17 @@ You can run the tool directly using `npx` without installation. By default, the
30
30
  npx @aiquants/html-to-markdown <URL> [--locale <locale>] [--output <path>]
31
31
  ```
32
32
 
33
+ Or convert HTML content directly:
34
+
35
+ ```bash
36
+ npx @aiquants/html-to-markdown --html-content <HTML_TEXT> [--locale <locale>] [--output <path>]
37
+ ```
38
+
33
39
  **Options:**
34
40
 
35
41
  - `--locale <locale>`: Set the locale for the browser context and console messages (`en-US` or `ja-JP`). Defaults to `en-US`.
36
42
  - `--output <path>`, `-o <path>`: Specify the output file path. If not specified, the file will be saved in the `.outputs/raw` directory with an auto-generated filename.
43
+ - `--html-content <HTML_TEXT>`, `-h <HTML_TEXT>`: Convert HTML content directly instead of fetching from a URL.
37
44
 
38
45
  **Examples:**
39
46
 
@@ -49,6 +56,12 @@ npx @aiquants/html-to-markdown https://en.wikipedia.org/wiki/Node.js --output ./
49
56
 
50
57
  # Use short option for output
51
58
  npx @aiquants/html-to-markdown https://ja.wikipedia.org/wiki/Node.js --locale ja-JP -o ./nodejs-ja.md
59
+
60
+ # Convert HTML content directly
61
+ npx @aiquants/html-to-markdown --html-content '<html><body><h1>Sample Title</h1><p>This is a sample paragraph.</p></body></html>' --output ./sample.md
62
+
63
+ # Convert HTML content with Japanese locale
64
+ npx @aiquants/html-to-markdown --html-content '<html><body><h1>サンプルタイトル</h1><p>これはサンプルの段落です。</p></body></html>' --locale ja-JP -o ./sample-ja.md
52
65
  ```
53
66
 
54
67
  ### As a Library
@@ -58,6 +71,7 @@ import { htmlToMarkdown } from '@aiquants/html-to-markdown';
58
71
  import fs from 'fs';
59
72
 
60
73
  async function main() {
74
+ // Example 1: Convert from URL
61
75
  const url = 'https://en.wikipedia.org/wiki/Node.js';
62
76
  const options = {
63
77
  locale: 'en-US', // 'en-US' (default) or 'ja-JP'
@@ -70,6 +84,31 @@ async function main() {
70
84
  } catch (error) {
71
85
  console.error('Error converting HTML to Markdown:', error);
72
86
  }
87
+
88
+ // Example 2: Convert HTML content directly
89
+ const htmlContent = `
90
+ <html>
91
+ <body>
92
+ <h1>Sample Title</h1>
93
+ <p>This is a sample paragraph.</p>
94
+ <ul>
95
+ <li>Item 1</li>
96
+ <li>Item 2</li>
97
+ </ul>
98
+ </body>
99
+ </html>
100
+ `;
101
+
102
+ try {
103
+ const { markdown } = await htmlToMarkdown('', {
104
+ locale: 'en-US',
105
+ htmlContent: htmlContent
106
+ });
107
+ fs.writeFileSync('output-from-html.md', markdown);
108
+ console.log('Markdown file has been saved as output-from-html.md');
109
+ } catch (error) {
110
+ console.error('Error converting HTML to Markdown:', error);
111
+ }
73
112
  }
74
113
 
75
114
  main();
@@ -145,6 +184,22 @@ npx --package=@aiquants/html-to-markdown aiq-html2md-mcp-stream
145
184
  - `save_directory` (optional): Directory path to save content with auto-generated filename
146
185
  - `filename` (optional): Base filename to use when save_directory is specified (extension .md will be added automatically)
147
186
 
187
+ - **url_to_markdown_file**: Convert web pages or HTML strings directly to Markdown files (combines conversion and file saving)
188
+ - `url` (required*): The URL of the web page to convert and save
189
+ - `html_content` (required*): HTML content as a string to convert and save (alternative to URL)
190
+ - `locale` (optional): Browser locale (`en-US` or `ja-JP`, defaults to `en-US`)
191
+ - `save_path` (optional): Complete file path including filename to save the converted content
192
+ - `save_directory` (optional): Directory path to save the converted content with auto-generated filename
193
+ - `filename` (optional): Base filename to use when save_directory is specified (extension .md will be added automatically)
194
+
195
+ *Either `url` or `html_content` is required, and either `save_path` or `save_directory` is required
196
+
197
+ **Streamable MCP Tools (for real-time progress updates):**
198
+
199
+ - **html_to_markdown_streamable**: Same as `html_to_markdown` but with real-time progress updates
200
+ - **save_content_to_file**: Same file saving functionality as in standard MCP
201
+ - **url_to_markdown_file_streamable**: Same as `url_to_markdown_file` but with real-time progress updates and streaming support
202
+
148
203
  **File Saving Options:**
149
204
 
150
205
  - **`save_path`**: Specify the complete file path including filename and extension where you want to save the content.
@@ -165,7 +220,70 @@ npx --package=@aiquants/html-to-markdown aiq-html2md-mcp-stream
165
220
  - With `save_path`: File is saved to the exact specified path
166
221
  - With `save_directory`: File is saved with auto-generated filename based on the URL or custom filename if provided
167
222
 
168
- - **html_to_markdown_streamable**: Same as above but with streamable MCP support for progress updates
223
+ #### MCP Usage Examples
224
+
225
+ ##### Example 1: Basic HTML to Markdown conversion
226
+
227
+ ```json
228
+ {
229
+ "method": "tools/call",
230
+ "params": {
231
+ "name": "html_to_markdown",
232
+ "arguments": {
233
+ "url": "https://example.com",
234
+ "locale": "en-US"
235
+ }
236
+ }
237
+ }
238
+ ```
239
+
240
+ ##### Example 2: Save content to a specific file
241
+
242
+ ```json
243
+ {
244
+ "method": "tools/call",
245
+ "params": {
246
+ "name": "save_content_to_file",
247
+ "arguments": {
248
+ "content": "# My Content\n\nThis is my markdown content.",
249
+ "save_path": "/path/to/my-file.md"
250
+ }
251
+ }
252
+ }
253
+ ```
254
+
255
+ ##### Example 3: Convert URL directly to Markdown file (One-step operation)
256
+
257
+ ```json
258
+ {
259
+ "method": "tools/call",
260
+ "params": {
261
+ "name": "url_to_markdown_file",
262
+ "arguments": {
263
+ "url": "https://example.com/article",
264
+ "save_directory": "/path/to/output/",
265
+ "filename": "my-article",
266
+ "locale": "en-US"
267
+ }
268
+ }
269
+ }
270
+ ```
271
+
272
+ ##### Example 4: Streamable conversion with real-time progress
273
+
274
+ ```json
275
+ {
276
+ "method": "tools/call",
277
+ "params": {
278
+ "name": "url_to_markdown_file_streamable",
279
+ "arguments": {
280
+ "url": "https://example.com/large-page",
281
+ "save_path": "/path/to/large-page.md",
282
+ "locale": "ja-JP"
283
+ }
284
+ }
285
+ }
286
+ ```
169
287
 
170
288
  ### Using MCP Server Programmatically
171
289
 
@@ -183,11 +301,11 @@ await streamableMcpServer.start(8000); // Port 8000
183
301
 
184
302
  ## API
185
303
 
186
- ### `htmlToMarkdown(url, options?)`
304
+ ### `htmlToMarkdown(urlOrHtml, options?)`
187
305
 
188
- Converts the HTML content of a given URL to Markdown.
306
+ Converts the HTML content of a given URL or HTML string to Markdown.
189
307
 
190
- - `url` (`string`, **required**): The URL of the web page to convert.
308
+ - `urlOrHtml` (`string`, **required**): The URL of the web page to convert, or when using `htmlContent` option, this can be any string (commonly used as identifier).
191
309
  - `options` (`object`, optional): Options for the conversion process.
192
310
 
193
311
  #### `options` object
@@ -195,6 +313,7 @@ Converts the HTML content of a given URL to Markdown.
195
313
  - `locale` (`string`, optional): Specifies the locale to use for the browser context and console messages.
196
314
  - `'en-US'` (default)
197
315
  - `'ja-JP'`
316
+ - `htmlContent` (`string`, optional): HTML content as a string instead of fetching from URL. When provided, the function will convert this HTML content directly instead of fetching content from the `urlOrHtml` parameter.
198
317
 
199
318
  ## How It Works
200
319
 
package/dist/{core-CouDTni-.js → core-DJV8t_Qj.js} RENAMED
@@ -9,10 +9,12 @@ import { chromium } from "playwright";
9
9
  const messages = {
10
10
  "ja-JP": {
11
11
  error_url_required: "エラー: 変換対象のURLを引数で指定してください。",
12
- usage: "使用法: node dist/main.js <URL> [--output <ファイルパス>] [--locale <ロケール>]",
13
- example: "例: node dist/main.js https://ja.wikipedia.org/wiki/Node.js -o output.md --locale ja-JP",
12
+ error_url_or_html_required: "エラー: URLまたはHTMLコンテンツのいずれかを指定してください。",
13
+ usage: "使用法: node dist/main.js <URL> [--output <ファイルパス>] [--locale <ロケール>] [--html-content <HTMLテキスト>]",
14
+ example: "例: node dist/main.js https://ja.wikipedia.org/wiki/Node.js -o output.md --locale ja-JP\n または: node dist/main.js --html-content '<html><body><h1>タイトル</h1></body></html>' -o output.md",
14
15
  cli_start: "🚀 コマンドラインから処理を開始します...",
15
16
  cli_url: " - URL: {url}",
17
+ cli_html_content: " - HTML Content: {length} 文字",
16
18
  cli_locale: " - Locale: {locale}",
17
19
  cli_output: " - Output: {path}",
18
20
  success_save: "✅ Markdownファイルが正常に保存されました。",
@@ -29,10 +31,12 @@ const messages = {
29
31
  },
30
32
  "en-US": {
31
33
  error_url_required: "Error: Please specify the URL to convert as an argument.",
32
- usage: "Usage: node dist/main.js <URL> [--output <file path>] [--locale <locale>]",
33
- example: "Example: node dist/main.js https://en.wikipedia.org/wiki/Node.js -o output.md --locale en-US",
34
+ error_url_or_html_required: "Error: Please specify either a URL or HTML content.",
35
+ usage: "Usage: node dist/main.js <URL> [--output <file path>] [--locale <locale>] [--html-content <HTML text>]",
36
+ example: "Example: node dist/main.js https://en.wikipedia.org/wiki/Node.js -o output.md --locale en-US\n or: node dist/main.js --html-content '<html><body><h1>Title</h1></body></html>' -o output.md",
34
37
  cli_start: "🚀 Starting process from command line...",
35
38
  cli_url: " - URL: {url}",
39
+ cli_html_content: " - HTML Content: {length} characters",
36
40
  cli_locale: " - Locale: {locale}",
37
41
  cli_output: " - Output: {path}",
38
42
  success_save: "✅ Markdown file saved successfully.",