any-markdown

A simple, lightweight wrapper for markitdown-ts with SSRF protection, path traversal prevention and batch processing.

Features

• Polymorphic Input: Accepts file paths, URLs, Buffers, YouTube links, plain text strings, or arrays of mixed inputs
• SSRF Protection: Blocks requests to private/internal IP ranges
• Path Traversal Prevention: Restricts file access to allowed directories
• Size Limits: Default 25MB cap to prevent memory exhaustion attacks
• Batch Processing: Convert multiple inputs in parallel with a single call
• Output Sanitization: XSS prevention with configurable markdown/HTML sanitization
• Structured Output: Returns markdown, text, ext, type, and base64 Data URI
• Graceful Errors: Never crashes — returns structured error objects

Installation

npm install any-markdown

Quick Start

import { markitdown } from "any-markdown";

// Single file
const result = await markitdown("./document.pdf");

// URL
const result = await markitdown("https://example.com/file.docx");

// Buffer with language hint
const result = await markitdown(buffer, "txt");

// Plain text string (auto-detected)
const result = await markitdown("This is plain text content");

// YouTube transcript
const result = await markitdown("https://www.youtube.com/watch?v=VIDEO_ID", "en");

// Array of mixed inputs (parallel processing)
const results = await markitdown([
  "./file.pdf",
  "https://example.com/doc.docx",
  buffer,
]);

API

markitdown(input, lang?, options?)

| Parameter | Type | Description | |-----------|------|-------------| | input | string \| Buffer \| (string \| Buffer)[] | File path, URL, Buffer, YouTube link, plain text string, or array of inputs | | lang | string | Optional language/extension hint (e.g., "txt", "pdf") | | options | MarkitdownOptions | Configuration options |

Returns: Promise<ConversionOutput> or Promise<ConversionOutput[]> for array input

ConversionOutput

interface ConversionResult {
  markdown: string;   // Sanitized markdown content
  text: string;       // Plain text (markdown stripped)
  ext: string;        // Verified file extension without dot (e.g., "pdf")
  type: "image" | "text";  // Content type classification
  base64: string;     // Data URI (e.g., "data:image/jpeg;base64,...")
}

interface ConversionError {
  error: true;
  message: string;
  code: string;       // Error code (e.g., "SSRF_BLOCKED", "FETCH_ERROR")
  markdown: "";
  text: "";
  ext: "";
  type: "text";
  base64: "";
}

Options

interface MarkitdownOptions {
  maxFileSize?: number;            // Max file size in bytes (default: 25MB)
  timeout?: number;                // Fetch timeout in ms (default: 10000)
  allowedDirs?: string[];          // Allowed directories for file access
  sanitizeOutput?: boolean;        // Sanitize XSS in output (default: true)
  enableYoutubeTranscript?: boolean;
  youtubeTranscriptLanguage?: string;
  suppressExiftoolWarning?: boolean; // Suppress exiftool stderr noise (default: true)
}

Input Types

File Path

const result = await markitdown("./reports/quarterly.xlsx");

// Restrict to specific directories
const result = await markitdown("/data/uploads/file.docx", undefined, {
  allowedDirs: ["/data/uploads"],
});

URL

const result = await markitdown("https://arxiv.org/pdf/2308.08155.pdf", undefined, {
  timeout: 15000,
});

URLs are validated against SSRF attacks — private IPs, localhost, and internal domains are blocked automatically.

Buffer

import fs from "fs";

const buffer = fs.readFileSync("./image.jpg");
const result = await markitdown(buffer);

// With language hint for untyped buffers
const result = await markitdown(abuffer);
const textBuffer = Buffer.from("Hello world", "utf-8");
const result = await markitdown(textBuffer, "txt");

Buffers are auto-detected using file-type. If detection fails, UTF-8 text is assumed before falling back to bin.

Plain Text

const result = await markitdown("This is plain text content");

Strings that are not URLs and don't match an existing file path are automatically detected as plain text and returned directly as markdown without transformation. This is useful when you have text content from user input, databases, or other sources that doesn't need conversion.

YouTube

const result = await markitdown("https://www.youtube.com/watch?v=VIDEO_ID", "en");

Array (Batch)

const results = await markitdown([
  "./document.pdf",
  "https://example.com/image.jpg",
  Buffer.from("plain text content"),
  "This is plain text, auto-detected!",
  "https://www.youtube.com/watch?v=VIDEO_ID",
]);

for (const result of results) {
  if (result.error) {
    console.error(`Failed: ${result.code} - ${result.message}`);
  } else {
    console.log(`Converted: ${result.ext} (${result.type}) - ${result.markdown.length} chars`);
  }
}

All inputs are processed in parallel using Promise.all.

Security

SSRF Protection

Blocks requests to:

• Private IP ranges: 10.x.x.x, 172.16-31.x.x, 192.168.x.x
• Loopback: 127.x.x.x, ::1
• Link-local: 169.254.x.x
• Reserved: 0.x.x.x, fe80:, fc00:, fd00:
• Blocked hostnames: localhost, metadata.google.internal, *.internal, *.local

Path Traversal Prevention

const result = await markitdown("../../etc/passwd", undefined, {
  allowedDirs: ["/data/uploads"],
});
// Returns error: PATH_TRAVERSAL_BLOCKED

Size Limits

const result = await markitdown("./large-file.zip", null, {
  maxFileSize: 10 * 1024 * 1024, // 10MB
});

Output Sanitization

By default, <script>, <iframe>, event handlers, javascript:, and data: URIs are stripped from output.

const result = await markitdown("./risky.html", null, {
  sanitizeOutput: true, // default
});

Error Handling

The function never throws. Errors are returned as structured objects:

const result = await markitdown("http://192.168.1.1/secret.pdf");

if (result.error) {
  console.error(`[${result.code}] ${result.message}`);
  // [SSRF_BLOCKED] SSRF blocked: private/internal IP '192.168.1.1'
}

Error Codes

| Code | Description | |------|-------------| | SSRF_BLOCKED | URL targets private/internal network | | PATH_TRAVERSAL_BLOCKED | File path escapes allowed directories | | SIZE_LIMIT_EXCEEDED | Input exceeds maxFileSize | | FETCH_ERROR | HTTP request failed | | FILE_READ_ERROR | Unable to read local file | | CONVERSION_ERROR | markitdown-ts conversion failed | | YOUTUBE_ERROR | Transcript extraction failed | | EMPTY_RESULT | No content extracted | | UNKNOWN_INPUT | Input type not recognized |

Supported Formats

| Format | Extension | Notes | |--------|-----------|-------| | PDF | pdf | Full text extraction | | Word | docx | Tables, lists, images | | Excel | xlsx, xls | Spreadsheets | | Images | jpg, jpeg, png, gif, bmp, webp, svg, ico, tiff | EXIF metadata (requires exiftool), base64 output | | HTML | html, htm | Converted to markdown | | Text | txt, csv, xml | Direct pass-through | | Jupyter | ipynb | Code + markdown cells | | YouTube | URL | Transcript extraction | | ZIP | zip | Recursive content extraction |

Output Contract

Every successful conversion returns:

{
  markdown: "# Document Title\n\nContent here...",
  text: "Document Title\n\nContent here...",
  ext: "pdf",
  type: "text",
  base64: "data:application/pdf;base64,JVBERi0xLjQK..."
}

• markdown: Sanitized markdown string
• text: Plain text with markdown syntax stripped (safe for indexing/search)
• ext: Verified file extension without dot
• type: "image" for image formats, "text" for all others
• base64: Standardized Data URI for embedding

TypeScript

Full type exports:

import {
  markitdown,
  ConversionOutput,
  ConversionResult,
  ConversionError,
  ArrayConversionOutput,
  MarkitdownOptions,
  DEFAULT_MAX_SIZE,
} from "any-markdown";

Type guards:

function isError(output: ConversionOutput): output is ConversionError {
  return "error" in output && output.error === true;
}

Examples

See the examples/ directory:

| File | Description | |------|-------------| | 01-file-path.mjs | Convert local files | | 02-url.mjs | URL-based conversion | | 03-buffer.mjs | Buffer with auto MIME detection | | 04-youtube.mjs | YouTube transcript extraction | | 05-security.mjs | SSRF and path traversal demos | | 06-error-handling.mjs | Graceful error patterns | | 07-options.mjs | Custom configuration | | 08-typescript.mts | Type-safe usage | | 09-docx.mjs | Word document conversion | | 10-excel.mjs | Excel spreadsheet conversion | | 11-plain-text.mjs | Plain text buffer conversion | | 12-image.mjs | Image to base64 conversion | | 13-array.mjs | Batch parallel processing |

Dependencies

| Package | Purpose | |---------|---------| | markitdown-ts | Core conversion engine | | axios | Secure URL fetching | | file-type | MIME type detection for buffers | | mime-types | Extension-to-MIME mapping | | is-ip | IP address validation |

License

MIT

Known Upstream Issues

xlsx (SheetJS) — Fixed

The abandoned xlsx npm package had two vulnerabilities (CVE-2023-30533, GHSA-5pgg-2g8v-p4x9). This package resolves them by overriding xlsx with the maintained community fork @e965/xlsx@^0.20.3:

"overrides": {
  "xlsx": "npm:@e965/xlsx@^0.20.3"
}