0
# HTML to Markdown Conversion
1

2
Core conversion functionality providing both static methods for single-use conversions and instance methods for better performance when processing multiple documents.
3

4
## Capabilities
5

6
### NodeHtmlMarkdown Class
7

8
The main converter class that provides both static and instance methods for HTML to Markdown conversion.
9

10
```typescript { .api }
11
/**
12
 * Main HTML to Markdown converter class
13
 */
14
class NodeHtmlMarkdown {
15
  /**
16
   * Create a new converter instance with optional configuration
17
   * @param options - Conversion options and formatting settings
18
   * @param customTranslators - Custom element translators
19
   * @param customCodeBlockTranslators - Custom code block element translators
20
   */
21
  constructor(
22
    options?: Partial<NodeHtmlMarkdownOptions>,
23
    customTranslators?: TranslatorConfigObject,
24
    customCodeBlockTranslators?: TranslatorConfigObject
25
  );
26

27
  /** Main element translators collection */
28
  translators: TranslatorCollection;
29
  /** Anchor tag specific translators */
30
  aTagTranslators: TranslatorCollection;
31
  /** Code block translators collection */
32
  codeBlockTranslators: TranslatorCollection;
33
  /** Table translators collection */
34
  tableTranslators: TranslatorCollection;
35
  /** Table row translators collection */
36
  tableRowTranslators: TranslatorCollection;
37
  /** Table cell translators collection */
38
  tableCellTranslators: TranslatorCollection;
39
  /** Configuration options (read-only) */
40
  readonly options: NodeHtmlMarkdownOptions;
41
}
42
```
43

44
### Static Translation Methods
45

46
Single-use conversion methods ideal for one-off HTML to Markdown translations.
47

48
```typescript { .api }
49
/**
50
 * Translate HTML string to markdown (static method for single use)
51
 * @param html - HTML string to convert
52
 * @param options - Optional conversion options
53
 * @param customTranslators - Optional custom element translators
54
 * @param customCodeBlockTranslators - Optional custom code block translators
55
 * @returns Converted markdown string
56
 */
57
static translate(
58
  html: string,
59
  options?: Partial<NodeHtmlMarkdownOptions>,
60
  customTranslators?: TranslatorConfigObject,
61
  customCodeBlockTranslators?: TranslatorConfigObject
62
): string;
63

64
/**
65
 * Translate collection of HTML files to markdown (static method for single use)
66
 * @param files - Object mapping filenames to HTML content
67
 * @param options - Optional conversion options
68
 * @param customTranslators - Optional custom element translators
69
 * @param customCodeBlockTranslators - Optional custom code block translators
70
 * @returns Object mapping filenames to converted markdown content
71
 */
72
static translate(
73
  files: FileCollection,
74
  options?: Partial<NodeHtmlMarkdownOptions>,
75
  customTranslators?: TranslatorConfigObject,
76
  customCodeBlockTranslators?: TranslatorConfigObject
77
): FileCollection;
78
```
79

80
**Usage Examples:**
81

82
```typescript
83
import { NodeHtmlMarkdown } from "node-html-markdown";
84

85
// Basic single file conversion
86
const markdown = NodeHtmlMarkdown.translate("<strong>Bold text</strong>");
87
console.log(markdown); // "**Bold text**"
88

89
// Multiple files conversion
90
const files = {
91
  "page1.html": "<h1>Title</h1><p>Content</p>",
92
  "page2.html": "<ul><li>Item 1</li><li>Item 2</li></ul>"
93
};
94

95
const converted = NodeHtmlMarkdown.translate(files);
96
console.log(converted["page1.html"]); // "# Title\n\nContent"
97
console.log(converted["page2.html"]); // "* Item 1\n* Item 2"
98

99
// With custom options
100
const customMarkdown = NodeHtmlMarkdown.translate(
101
  "<strong>Bold</strong>",
102
  { strongDelimiter: "__" }
103
);
104
console.log(customMarkdown); // "__Bold__"
105
```
106

107
### Instance Translation Methods
108

109
Instance methods providing better performance for multiple conversions by reusing the configured converter.
110

111
```typescript { .api }
112
/**
113
 * Translate HTML string to markdown (instance method)
114
 * @param html - HTML string to convert
115
 * @returns Converted markdown string
116
 */
117
translate(html: string): string;
118

119
/**
120
 * Translate collection of HTML files to markdown (instance method)
121
 * @param files - Object mapping filenames to HTML content
122
 * @returns Object mapping filenames to converted markdown content
123
 */
124
translate(files: FileCollection): FileCollection;
125
```
126

127
**Usage Examples:**
128

129
```typescript
130
import { NodeHtmlMarkdown } from "node-html-markdown";
131

132
// Create reusable instance
133
const nhm = new NodeHtmlMarkdown({
134
  bulletMarker: "-",
135
  strongDelimiter: "__"
136
});
137

138
// Convert multiple documents efficiently
139
const doc1 = nhm.translate("<strong>First document</strong>");
140
const doc2 = nhm.translate("<ul><li>List item</li></ul>");
141
const doc3 = nhm.translate("<em>Emphasized text</em>");
142

143
console.log(doc1); // "__First document__"
144
console.log(doc2); // "- List item"
145
console.log(doc3); // "_Emphasized text_"
146

147
// Batch conversion
148
const batch = nhm.translate({
149
  "article1.html": "<h2>Article Title</h2><p>Content here</p>",
150
  "article2.html": "<blockquote>Quote text</blockquote>"
151
});
152
```
153

154
### File Collection Type
155

156
Type definition for batch processing multiple HTML files.
157

158
```typescript { .api }
159
/**
160
 * Collection of HTML files for batch processing
161
 * Maps filename to HTML content string
162
 */
163
type FileCollection = { [fileName: string]: string };
164
```
165

166
**Usage Examples:**
167

168
```typescript
169
// Define file collection
170
const htmlFiles: FileCollection = {
171
  "home.html": "<h1>Welcome</h1><p>Homepage content</p>",
172
  "about.html": "<h1>About Us</h1><p>Company information</p>",
173
  "contact.html": "<h1>Contact</h1><p>Get in touch</p>"
174
};
175

176
// Convert all files
177
const markdownFiles = NodeHtmlMarkdown.translate(htmlFiles);
178

179
// Access converted content
180
Object.entries(markdownFiles).forEach(([filename, markdown]) => {
181
  console.log(`${filename}:`);
182
  console.log(markdown);
183
  console.log("---");
184
});
185
```
186

187
### Performance Considerations
188

189
**Static Methods:**
190
- Best for single conversions or infrequent use
191
- Creates new instance for each call
192
- No setup overhead for one-time conversions
193

194
**Instance Methods:**
195
- Best for multiple conversions
196
- Reuses configured translators and options
197
- Significant performance improvement for batch processing
198
- Recommended when processing many documents
199

200
```typescript
201
// Performance comparison example
202
import { NodeHtmlMarkdown } from "node-html-markdown";
203

204
const htmlContent = "<h1>Title</h1><p>Content</p>";
205
const iterations = 1000;
206

207
// Slower: Creates new instance each time
208
console.time("Static Method");
209
for (let i = 0; i < iterations; i++) {
210
  NodeHtmlMarkdown.translate(htmlContent);
211
}
212
console.timeEnd("Static Method");
213

214
// Faster: Reuses instance
215
console.time("Instance Method");
216
const nhm = new NodeHtmlMarkdown();
217
for (let i = 0; i < iterations; i++) {
218
  nhm.translate(htmlContent);
219
}
220
console.timeEnd("Instance Method");
221
```