Converter Options
The ConverterOptions interface provides configuration options to customize the conversion behavior.
Interface Definition
typescript
interface ConverterOptions {
fileName?: string;
forceExtension?: string;
url?: string;
ocr?: boolean | OCROptions;
}1
2
3
4
5
6
2
3
4
5
6
Options
fileName
- Type:
string(optional) - Description: Specifies the file name, which is particularly useful when converting from Buffer or base64 data. Helps with automatic format detection.
Example:
typescript
const buffer = readFileSync('./document.pdf');
const markdown = await convertToMarkdown(buffer, {
fileName: 'document.pdf'
});1
2
3
4
2
3
4
forceExtension
- Type:
string(optional) - Description: Forces the converter to treat the input as a specific file type, bypassing automatic detection.
Example:
typescript
// Force treat as PDF even if detection fails
const markdown = await convertToMarkdown(buffer, {
forceExtension: '.pdf'
});1
2
3
4
2
3
4
Supported Extensions:
.pdf- PDF documents.docx- Word documents.html,.htm- HTML files.xlsx,.xls- Excel spreadsheets.csv- CSV files.ipynb- Jupyter notebooks.pptx- PowerPoint presentations.xml,.rss,.atom- XML/Feed formats.json- JSON documents.yaml,.yml- YAML documents.epub- EPUB e-books.msg- Outlook email messages.txt- Text files.zip- ZIP archives.jpg,.jpeg,.png,.gif- Images.mp3,.wav- Audio files
url
- Type:
string(optional) - Description: Original URL of the content, used for special handling of web content like YouTube videos or Bing search results.
Example:
typescript
// Convert YouTube page
const markdown = await convertToMarkdown(htmlBuffer, {
url: 'https://www.youtube.com/watch?v=...'
});
// Convert Bing search results
const markdown = await convertToMarkdown(htmlBuffer, {
url: 'https://www.bing.com/search?q=...'
});1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
ocr
- Type:
boolean | OCROptions(optional) - Description: Enables OCR for images and scanned PDFs. Opt-in — when omitted, no OCR is attempted. Pass
trueto use the defaults, or anOCROptionsobject to choose a provider, language, or PDF mode.
Example:
typescript
// Defaults: tesseract provider, 'eng', pdfMode 'auto'
const scanned = await convertToMarkdown('./scan.pdf', { ocr: true });
// Explicit options
const receipt = await convertToMarkdown('./receipt.png', {
ocr: { provider: 'tesseract', lang: 'eng' }
});1
2
3
4
5
6
7
2
3
4
5
6
7
The default tesseract provider requires the tesseract.js peer dependency. See the OCR guide for providers, PDF modes, and vision-model configuration.
Usage Examples
Combining Options
You can combine multiple options:
typescript
const markdown = await convertToMarkdown(buffer, {
fileName: 'document.pdf',
forceExtension: '.pdf',
});1
2
3
4
2
3
4
Buffer with Format Detection
When working with buffers without extension information:
typescript
const buffer = getSomeBuffer();
const markdown = await convertToMarkdown(buffer, {
fileName: 'unknown-file.pdf' // Helps detect it's a PDF
});1
2
3
4
2
3
4
Web Content Conversion
For web-scraped content:
typescript
const htmlContent = await fetchWebPage(url);
const markdown = await convertToMarkdown(htmlContent, {
url: url // Enables special handling for known sites
});1
2
3
4
2
3
4
Default Behavior
When no options are provided:
- File type is auto-detected from file path extension or buffer content
- If detection fails, content is treated as plain text
- No special URL-based processing is applied
- OCR is not attempted