Format Support

@cognipeer/to-markdown supports a wide variety of file formats. Each format is handled by a specialized converter optimized for that format's structure.

Document Formats

PDF Documents (.pdf)

Converts PDF documents to Markdown, preserving text structure and formatting.

const markdown = await convertToMarkdown('./document.pdf');

Features:

• Text extraction
• Heading detection
• Paragraph formatting

Scanned PDFs carry no extractable text. Enable OCR to read those.

---

Word Documents (.docx)

Converts Microsoft Word documents to Markdown.

const markdown = await convertToMarkdown('./document.docx');

Features:

• Text formatting (bold, italic)
• Headings and lists
• Tables
• Inline styles

---

HTML/HTM (.html, .htm)

Converts HTML web pages to clean Markdown.

const markdown = await convertToMarkdown('./page.html');

Features:

• Semantic HTML to Markdown
• Table conversion
• List handling
• Link preservation
• Code block detection

---

EPUB (.epub)

Converts EPUB e-books to Markdown by reading the OPF manifest and walking the spine in reading order.

const markdown = await convertToMarkdown('./book.epub');

Features:

• Title, author, and description from the EPUB metadata
• Chapters emitted in spine (reading) order
• Each chapter's XHTML converted through the HTML converter

---

Spreadsheet Formats

Excel (.xlsx, .xls)

Converts Excel spreadsheets to Markdown tables.

const markdown = await convertToMarkdown('./data.xlsx');

Features:

• Multiple sheet support
• Table formatting
• Header detection

Output Example:

## Sheet1

| Name | Age | City |
| --- | --- | --- |
| John | 30 | NYC |
| Jane | 25 | LA |

---

CSV (.csv)

Converts CSV files to Markdown tables.

const markdown = await convertToMarkdown('./data.csv');

Features:

• Automatic delimiter detection
• Header row handling
• Clean table formatting

---

Notebook Formats

Jupyter Notebooks (.ipynb)

Converts Jupyter notebooks to Markdown, preserving code and markdown cells.

const markdown = await convertToMarkdown('./analysis.ipynb');

Features:

• Markdown cell preservation
• Code block formatting
• Cell order maintained
• Output omission (text only)

Output Example:

# Analysis Title

This is a markdown cell.

```python
import pandas as pd
df = pd.read_csv('data.csv')
```

## Results

The data shows...

---

Presentation Formats

PowerPoint (.pptx)

Extracts text content from PowerPoint presentations.

const markdown = await convertToMarkdown('./presentation.pptx');

Features:

• Slide text extraction
• Slide order preservation
• Comments included

---

Data Formats

XML/RSS/ATOM (.xml, .rss, .atom)

Converts XML feeds and documents to structured Markdown.

const markdown = await convertToMarkdown('./feed.rss');

Features:

• RSS feed parsing
• ATOM feed parsing
• Structured output
• Metadata preservation

RSS Output Example:

# Blog Title

## Latest Article
Published on: 2025-01-01

Article content here...

---

JSON and YAML (.json, .yaml, .yml)

Parses structured data and renders it as readable Markdown rather than a dumped code block.

const markdown = await convertToMarkdown('./config.yaml');

Features:

• Flat objects with up to ten keys become a key/value table
• Nested objects become sub-headings, one level per depth
• Arrays of scalars become bullet lists; arrays of objects become numbered sections
• Multi-line strings are preserved in fenced blocks

---

Mail Formats

Outlook Messages (.msg)

Extracts the headers, body, and attachment list from an Outlook .msg file.

const markdown = await convertToMarkdown('./message.msg');

Features:

• From, To, Cc, Subject, and Date headers
• Message body under a ## Content heading
• Attachment file names listed under ## Attachments

---

Media Formats

Images (.jpg, .jpeg, .png, .gif)

Extracts metadata from image files, and optionally the text inside them.

const markdown = await convertToMarkdown('./photo.jpg');

Features:

• Image dimensions
• Format information
• File size

Note: To extract the text inside an image, enable OCR.

---

Audio (.mp3, .wav)

Extracts metadata from audio files.

const markdown = await convertToMarkdown('./song.mp3');

Features:

• Title, artist, album
• Duration
• Bitrate

Note: Speech-to-text support planned for future releases.

---

Archive Formats

ZIP Archives (.zip)

Processes ZIP archives and converts contained files.

const markdown = await convertToMarkdown('./archive.zip');

Features:

• Recursive file processing
• Multiple file handling
• Content aggregation

---

Text Formats

Plain Text (.txt)

Processes plain text files with minimal transformation.

const markdown = await convertToMarkdown('./notes.txt');

Features:

• UTF-8 encoding support
• Whitespace preservation

---

Special Formats

YouTube Pages

Extracts information from YouTube video pages.

const markdown = await convertToMarkdown(htmlBuffer, {
  url: 'https://www.youtube.com/watch?v=...'
});

Features:

• Title extraction
• Description parsing

---

Bing Search Results

Converts Bing search results to structured Markdown.

const markdown = await convertToMarkdown(htmlBuffer, {
  url: 'https://www.bing.com/search?q=...'
});

Features:

• Search result extraction
• Clean formatting

---

Format Detection

The library automatically detects file formats using:

1. File extension (for file paths)
2. MIME type (for base64 data URLs)
3. Magic bytes (for buffers without extension)
4. Fallback to plain text if detection fails

You can force a specific format:

const markdown = await convertToMarkdown(buffer, {
  forceExtension: '.pdf'
});

See Also

• API Overview
• Converter Options
• OCR